feat(api): 添加安全上传 Skill 和 COS 图片归一化

docs/architecture.md

@@ -68,6 +68,14 @@ flowchart LR
 - 标题、正文和 Tag 批注保存 `start_offset`、`end_offset`、`selected_text` 及前后文，提交时校验选区仍与轮次快照一致。
 - `GET /api/works/:workId/annotations` 按轮次返回图片批注、文字批注、总体反馈和验收事件。
 
+## Agent 安全上传
+
+内置 Agent Skill 采用“发现目标 → 生成计划 → 人工确认 → 单次写入 → 读取核验”的两阶段流程。计划文件只保存目标 ID、待写内容和确认摘要，不保存 API Key，并写入已被 Git 忽略的 `tmp/` 目录。
+
+新建作品以 `externalId` 保证幂等；新增验收轮次没有幂等键。轮次写入超时或响应不明确时，必须先重新读取作品状态，不能直接重试，以免重复创建轮次。
+
 ## 存储
 
-平台管理员可在管理页保存和测试 COS 配置。SecretId/SecretKey 使用 `COS_CONFIG_ENCRYPTION_KEY` 派生的 AES-256-GCM 密钥加密，读取接口不返回明文。连接测试会上传、读取并删除临时对象。外部 API 提供的公开图片 URL 只保存地址，不下载、不转存 COS。
+平台管理员可在管理页保存和测试 COS 配置。SecretId/SecretKey 使用 `COS_CONFIG_ENCRYPTION_KEY` 派生的 AES-256-GCM 密钥加密，读取接口不返回明文。连接测试会上传、读取并删除临时对象。
+
+外部 API 图片统一归一到当前活动 COS：URL 与配置的 COS 公开域名或 CDN 域名同源时直接保存；其他公开 URL 经 SSRF 防护、图片类型和 20 MB 大小校验后下载，并按内容哈希转存到 COS。没有活动 COS 配置时拒绝 URL 导入。该规则适用于新作品和新验收轮次，不追溯迁移历史图片记录。

docs/handoff.md

@@ -9,7 +9,8 @@
 - 标题、正文和 Tag 选区批注、总体反馈、按作品聚合反馈和验收记录
 - 批注回复线程、只能撤回本人反馈并保留撤回记录
 - 客户项目链接、密码、姓名、访问期限和验收决定
-- API Key、审计日志、COS 前端配置及连接测试
+- API Key、审计日志、COS 前端配置、连接测试及外部 URL 安全转存
+- 内置 Agent 安全上传 Skill、双阶段确认脚本、回归测试和可分发 ZIP
 - SQLite/PostgreSQL 双运行时、迁移验证和 Docker 部署
 - 桌面端与移动端响应式页面
 

docs/integration-guide.md

@@ -10,6 +10,18 @@ Authorization: Bearer dd_live_xxx
 
 平台级 Key 可跨组创建和查询项目。项目级 Key 只能操作绑定项目，包括在该项目中新建作品和验收轮次。密钥明文只在创建时返回一次。
 
+## Agent 安全上传 Skill
+
+项目内置 `.agents/skills/upload-delivery-desk-work`，用于引导 Agent 精确定位运营组、项目和作品后创建作品或提交新验收轮次。它强制执行“发现 → 生成计划 → 操作者确认 → 单次提交 → 回读验证”，不允许根据名称猜测目标。
+
+更新 Skill 后重新生成分发包：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/package-upload-skill.ps1
+```
+
+压缩包输出到 `skill-packages/upload-delivery-desk-work.zip`。API Key 只能通过 `DELIVERY_DESK_API_KEY` 环境变量提供，不应写入 Skill、计划文件或命令参数。
+
 ## 发现资源
 
 ```bash
@@ -37,7 +49,11 @@ curl -X POST http://localhost:3010/api/projects \
 
 ## 创建作品
 
-JSON 请求中的 `images` 为 1–30 个公开 HTTP/HTTPS URL。服务只保存 URL，不下载也不转存 COS；数组顺序就是展示顺序，第一张为封面。
+JSON 请求中的 `images` 为 1–30 个公开 HTTP/HTTPS URL，且平台必须已有活动 COS 配置。数组顺序就是展示顺序，第一张为封面。
+
+- URL 与活动 COS 的公开域名或 CDN 域名同源时直接保存，不重复上传。
+- 其他域名的图片会由服务端下载并转存到活动 COS，最终入库 URL 来自该 COS。
+- 外部图片单张不得超过 20 MB，必须返回受支持的图片类型；本机、内网、保留地址和非标准端口会被拒绝。
 
 ```bash
 curl -X POST http://localhost:3010/api/projects/1/works \
@@ -52,7 +68,7 @@ curl -X POST http://localhost:3010/api/projects/1/works \
   }'
 ```
 
-相同 `projectId + externalId` 的重试不会重复创建，响应包含 `idempotent: true`。调用方负责保证外部图片 URL 长期公开可用。
+相同 `projectId + externalId` 的重试不会重复创建，响应包含 `idempotent: true`。异源图片成功转存后不再依赖原地址长期可用。
 
 ## 创建新验收轮次
 
@@ -125,4 +141,4 @@ curl -X POST http://localhost:3010/api/review/july-content/works/12/decision \
 
 旧的 `/api/notes`、`/api/notes/:id/versions`、`/api/notes/:id/review-rounds` 与 `/api/projects/:id/collections` 暂保留一个兼容周期。旧交付集 URL 会跳转到项目页；旧多候选稿请求会返回 `400`，不会再创建多方案轮次。新接入必须使用项目、作品和轮次接口。
 
-错误统一为 `{ "error": "错误说明" }`。常见状态码：`400` 输入无效、`401` 未认证、`403` 越权、`404` 不存在、`409` 状态冲突。
+错误响应均包含 `{ "error": "错误说明" }`。常见状态码：`400` 输入无效或地址被安全策略拒绝、`401` 未认证、`403` 越权、`404` 不存在、`409` 状态冲突或未启用 COS、`413` 图片超过 20 MB、`422` 外部图片无法下载或内容无效、`502` 转存 COS 失败。

docs/operator-runbook.md

@@ -49,6 +49,19 @@ docker compose logs --tail=100 app
 
 COS 使用公开 URL。必须关闭桶列表功能并使用不可枚举对象名；拿到 URL 的人可以直接访问文件。
 
+JSON URL 导入依赖活动 COS 配置。同一 COS/CDN 域名的图片直接使用；其他域名会下载并按内容哈希写入 `<path-prefix>/imports/`。服务会拒绝内网地址、非图片响应和超过 20 MB 的文件，因此部署网络必须允许访问确需导入的公开图片源。
+
+## Agent 上传 Skill 维护
+
+Agent 通过 API 新建作品或提交验收轮次时，使用 `.agents/skills/upload-delivery-desk-work`。API Key 只通过 `DELIVERY_DESK_API_KEY` 环境变量注入，不写入计划文件、文档或 Git。
+
+```powershell
+python tests/test_upload_skill.py
+powershell -ExecutionPolicy Bypass -File scripts/package-upload-skill.ps1
+```
+
+打包脚本会先运行回归测试，再生成 `skill-packages/upload-delivery-desk-work.zip`。计划文件写入已忽略的 `tmp/`；接口或层级变化后必须同步更新 Skill、测试和分发包。
+
 ## 数据备份与恢复
 
 - PostgreSQL 使用托管备份或定期 `pg_dump`，恢复流程需在预发布环境演练。
@@ -67,6 +80,7 @@ pnpm test:review-rounds
 pnpm test:collection-status
 pnpm test:postgres-runtime
 pnpm db:postgres:validate
+python tests/test_upload_skill.py
 ```
 
 正式切换前还应验证：管理员首次改密、客户访问门禁、COS 上传、客户批注与验收、数据库备份及 HTTPS Cookie。