fix(storage): 强化外部图片导入与 Skill 异常引导

docs/architecture.md

@@ -78,4 +78,4 @@ flowchart LR
 
 平台管理员可在管理页保存和测试 COS 配置。SecretId/SecretKey 使用 `COS_CONFIG_ENCRYPTION_KEY` 派生的 AES-256-GCM 密钥加密，读取接口不返回明文。连接测试会上传、读取并删除临时对象。
 
-外部 API 图片统一归一到当前活动 COS：URL 与配置的 COS 公开域名或 CDN 域名同源时直接保存；其他公开 URL 经 SSRF 防护、图片类型和 20 MB 大小校验后下载，并按内容哈希转存到 COS。没有活动 COS 配置时拒绝 URL 导入。该规则适用于新作品和新验收轮次，不追溯迁移历史图片记录。
+外部 API 图片统一归一到当前活动 COS：所有 URL 会先拒绝本机、私有网段、局域网和保留地址；与配置的 COS 公开域名或 CDN 域名同源时直接保存，其他公开 URL 经 DNS SSRF 防护、图片类型和 20 MB 大小校验后下载，并按内容哈希转存到 COS。没有活动 COS 配置时拒绝 URL 导入；全部图片准备成功后才创建作品或新验收轮次。该规则不自动追溯迁移历史图片内容。

docs/handoff.md

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

docs/integration-guide.md

@@ -51,6 +51,7 @@ curl -X POST http://localhost:3010/api/projects \
 
 JSON 请求中的 `images` 为 1–30 个公开 HTTP/HTTPS URL，且平台必须已有活动 COS 配置。数组顺序就是展示顺序，第一张为封面。
 
+- 所有 URL 都会先拒绝 `localhost`、本机、私有网段、局域网和保留地址；即使域名与配置同源也不会绕过这项检查。
 - URL 与活动 COS 的公开域名或 CDN 域名同源时直接保存，不重复上传。
 - 其他域名的图片会由服务端下载并转存到活动 COS，最终入库 URL 来自该 COS。
 - 外部图片单张不得超过 20 MB，必须返回受支持的图片类型；本机、内网、保留地址和非标准端口会被拒绝。
@@ -68,7 +69,7 @@ curl -X POST http://localhost:3010/api/projects/1/works \
   }'
 ```
 
-相同 `projectId + externalId` 的重试不会重复创建，响应包含 `idempotent: true`。异源图片成功转存后不再依赖原地址长期可用。
+相同 `projectId + externalId` 的重试不会重复创建，响应包含 `idempotent: true`。异源图片成功转存后不再依赖原地址长期可用；任意图片校验或转存失败时不会创建作品记录。
 
 ## 创建新验收轮次
 

docs/operator-runbook.md

@@ -47,10 +47,12 @@ docker compose logs --tail=100 app
 
 连接测试会真实执行一次上传、读取和删除，因此密钥至少需要目标前缀的这三项权限。测试对象会尽力清理；请求中断时可检查 `<path-prefix>/.delivery-desk-check/` 是否残留临时文件。
 
-COS 使用公开 URL。必须关闭桶列表功能并使用不可枚举对象名；拿到 URL 的人可以直接访问文件。
+COS 使用公开 URL。公共访问域名和 CDN 域名必须能够解析到公网地址，本机、私有网段、局域网或保留地址会在保存配置时被拒绝。必须关闭桶列表功能并使用不可枚举对象名；拿到 URL 的人可以直接访问文件。
 
 JSON URL 导入依赖活动 COS 配置。同一 COS/CDN 域名的图片直接使用；其他域名会下载并按内容哈希写入 `<path-prefix>/imports/`。服务会拒绝内网地址、非图片响应和超过 20 MB 的文件，因此部署网络必须允许访问确需导入的公开图片源。
 
+使用 `pnpm server:prod` 运行本地 API 时不会监听源码变化；后端代码更新后必须重启进程。日常开发应使用 `pnpm server:dev` 或 `pnpm dev`。
+
 ## Agent 上传 Skill 维护
 
 Agent 通过 API 新建作品或提交验收轮次时，使用 `.agents/skills/upload-delivery-desk-work`。API Key 只通过 `DELIVERY_DESK_API_KEY` 环境变量注入，不写入计划文件、文档或 Git。