记录外部图片编辑字段原地升级决策

确认 2026-08-08 线上仍无外部调用方
明确豁免 sourceImageSrc 到 sourceReferenceId 的 v1 breaking change
修正 provider 容量说明并增加旧字段文案回归

docs/openapi/genarrative-external-v1.openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "陶泥儿外部编辑器 OpenAPI",
     "version": "1.0.0",
-    "description": "外部系统调用陶泥儿图片画布项目、画布布局、素材库，以及图片、视频、音效、音乐等编辑器素材生成/编辑能力的 v1 契约。全部生成 POST 都是异步提交：必须携带 Idempotency-Key，收到 202 后使用 operationId 查询统一生成状态。支持远程 MCP 的 Agent 可连接 /api/external/v1/mcp；不支持 MCP 的 Agent 可从 /api/external/v1/skill.zip 下载完整 Skill 包。新建 projectId 使用 proj- 前缀，新建 taskId / operationId 使用 task- 前缀；历史 editor-project-*、aitask_*、extgen-* ID 仍可作为既有资源标识传入。\n\n兼容性说明：v1 当前处于无外部存量调用方阶段，正式对外发放 API Key 之前，契约可能在不升 info.version、不设弃用期的情况下发生包含字段移除在内的破坏性变更。生成客户端时请勿假定本文档已冻结。"
+    "description": "外部系统调用陶泥儿图片画布项目、画布布局、素材库，以及图片、视频、音效、音乐等编辑器素材生成/编辑能力的 v1 契约。全部生成 POST 都是异步提交：必须携带 Idempotency-Key，收到 202 后使用 operationId 查询统一生成状态。支持远程 MCP 的 Agent 可连接 /api/external/v1/mcp；不支持 MCP 的 Agent 可从 /api/external/v1/skill.zip 下载完整 Skill 包。新建 projectId 使用 proj- 前缀，新建 taskId / operationId 使用 task- 前缀；历史 editor-project-*、aitask_*、extgen-* ID 仍可作为既有资源标识传入。\n\n兼容性说明：截至 2026-08-08，v1 经当前线上 API Key 与调用方状态确认仍无外部存量调用方；正式对外发放 API Key 之前，契约可能依据明确决策在不升 info.version、不设弃用期的情况下发生包含字段移除在内的破坏性变更。生成客户端时请勿假定本文档已冻结。"
   },
   "servers": [
     {
@@ -3532,7 +3532,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
+              "description": "当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。sourceReferenceId 对应的主来源原图占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
             },
             "maxItems": 8
           },

docs/project-memory/shared-memory/decision-log.md

@@ -1,5 +1,13 @@
 # 决策记录
 
+## 2026-08-08 External v1 图片编辑来源字段允许原地收紧
+
+- 背景：图片编辑主来源已经从可由客户端提交 objectKey 和类型提示的 `sourceImageSrc / sourceResourceId / assetKind`，收紧为服务端按项目资源 ID 或素材 ID 解析权威对象与类型的必填 `sourceReferenceId`。这会让严格 External v1 客户端立即失败，属于现役版本策略明确列出的 breaking change；2026-07-31 的历史豁免不能自动覆盖本次变更。
+- 决策：产品负责人于 2026-08-08 根据当前线上 API Key 与调用方状态确认仍无外部调用方，明确允许本次继续使用 `/api/external/v1` 与 `info.version = 1.0.0` 原地替换字段，不保留兼容字段、不新开 `/api/external/v2`、不设弃用期。该豁免仅覆盖本次图片编辑来源字段替换，后续 breaking change 必须重新确认当日线上状态并形成新决策。
+- 影响范围：`POST /api/external/v1/editor/images/edits` 只接受必填 `sourceReferenceId`；`sourceImageSrc / sourceResourceId / assetKind` 继续由 `additionalProperties: false` 拒绝。辅助 `referenceImageSrcs` 的 provider 容量说明按 `sourceReferenceId` 对应主来源原图计数。
+- 验证方式：External OpenAPI 契约测试精确断言 `sourceReferenceId` 必填、三个旧字段不存在，并断言图片编辑辅助参考图说明只引用 `sourceReferenceId` 而不再引用 `sourceImageSrc`。
+- 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/openapi/genarrative-external-v1.openapi.json`。
+
 ## 2026-08-07 game-chat 使用单主路径按需补齐美术
 
 - 背景：原 game-chat 把 Supervisor 的意图判断之后又硬接为 `design-director / code-director / art-* / code-prototype / preview-*` 固定图。`code-director` 代替程序主 Agent 判断素材缺口，会让“把现有美术资源应用到游戏中”被错误翻译成先生成美术，且美术回执无法天然回到同一个代码 Run 完成接入。

docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md

@@ -133,7 +133,7 @@ DELETE /api/profile/api-keys/{keyId}
 
 ### 当前状态：v1 尚无外部存量调用方
 
-截至 2026-07-31，`external_api_key` 表内没有属于外部第三方的存量调用方，v1 处于「已发布但无存量集成」阶段。本节记录的豁免只在该前提成立时有效。
+截至 2026-08-08，已按当前线上 API Key 与调用方状态再次确认没有外部第三方存量调用方，v1 仍处于「已发布但无存量集成」阶段。本节记录的豁免只在该前提成立时有效；本次确认不自动延续到今后的 breaking change，每次仍需重新取得当日线上状态并形成明确决策。
 
 ### 已接受的未版本化 breaking change
 
@@ -148,6 +148,8 @@ DELETE /api/profile/api-keys/{keyId}
 
 2026-07-31 同一豁免还覆盖了「八类生成从同步成功响应切换为 `202 + operationId`，新增统一查询接口」这一 breaking change。旧调用方若仍把生成 POST 响应当作媒体结果会立即失败；接受原地修改 v1 的唯一依据同样是上线前已确认没有外部第三方存量调用方。托管 MCP、集成 manifest 与 Skill archive 均为新增入口，不产生既有客户端兼容债务。
 
+2026-08-08「收紧图片编辑主来源契约」把 `POST /api/external/v1/editor/images/edits` 的既有必填 `sourceImageSrc` 替换为新的必填 `sourceReferenceId`，并移除可选 `sourceResourceId / assetKind`；`info.version` 继续为 `1.0.0`，路径继续为 `/api/external/v1`。严格客户端会因必填字段改名、旧字段被 `additionalProperties: false` 拒绝而立即失败，这属于本节定义的 breaking change。产品负责人已于 2026-08-08 根据当前线上 API Key 与调用方状态确认仍无外部调用方，因此明确接受本次不增加兼容字段、不新开 `/v2`、不设弃用期的原地变更。该豁免只覆盖本次字段替换，不得被后续 breaking change 自动引用。
+
 ### 豁免的失效条件
 
 API Key 由用户在个人中心自助发放，因此「无外部调用方」不是受控状态，可能在无人决策的情况下变为假。本节豁免在下列任一条件出现后立即失效：

server-rs/crates/api-server/src/external_editor_api.rs

@@ -2007,6 +2007,13 @@ mod tests {
                     && description.contains("未登记上传对象")
                     && description.contains("400"))
         );
+        let image_edit_references = &image_edit_schema["referenceImageSrcs"];
+        assert!(
+            image_edit_references["items"]["description"]
+                .as_str()
+                .is_some_and(|description| description.contains("sourceReferenceId")
+                    && !description.contains("sourceImageSrc"))
+        );
         assert_eq!(
             parsed["components"]["schemas"]["EditorImageEditRequest"]["additionalProperties"],
             json!(false)