Merge remote-tracking branch 'origin/master' into codex/game-agent-resource-workbench

# Conflicts:
#	docs/project-memory/shared-memory/decision-log.md

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

@@ -7,6 +7,13 @@
 - 输出边界：资源查询和生成结果只投影相对路径、稳定 Canvas/resource/asset/task 身份、序列帧身份、pending 状态及脱敏告警；不返回完整 manifest、prompt、model、provider route、绝对路径、URL、Token、Cookie 或 API Key。角色动画及视频/音频新请求统一携带同名画布与素材目录上下文；已有冻结请求不迁移、不重写。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`apps/ai-game-creator-shell/src-tauri/resources/agc-skills/agc-client-projection/SKILL.md`。
 
+## 2026-08-23 External 去背景绑定权威静态来源与真实画布尺寸
+
+- 背景：External v1 去背景曾把调用方 `assetKind` 原样带入持久化，并允许 `sourceImageSrc=A + targetLayerId=B` 覆盖不同资源；Python helper 又为所有画布完成请求固定生成 `1024×1024` 占位，导致非方形透明结果按占位尺寸拉伸。
+- 决策：入队前从当前 owner 的项目资源或素材库解析来源权威语义类型，资产对象存储类型只参与非静态媒体门禁；显式项目资源 ID / 素材 ID 优先于 objectKey 回退，同一纯 objectKey 对应的候选权威元数据不一致时返回 `400` 并要求用 `sourceResourceId` 或业务 ID 消歧，禁止按列表首条决定类型。请求类型冲突或任一记录属于视频、音频、动画、图片序列时返回 `400`，队列只保存服务端解析出的静态语义类型。无 `canvasCompletion` 的原位替换优先比较双方 `assetObjectId`，任一缺失时回退 canonical `(bucket, objectKey)`，并要求默认类型一致；纯 objectKey 省略 `sourceResourceId` 时自动绑定目标图层资源并写入队列，由 Worker 复验同一绑定。helper 使用画布会话时必须取得真实源宽高或显式 `canvasWidth + canvasHeight`，不再猜测方形尺寸。
+- 影响范围：External v1 去背景入队与 worker 复验、OpenAPI、Python helper、外部编辑器 skill 和相关契约测试；不修改 SpacetimeDB schema、BgFilter 协议或去背景输出尺寸语义。
+- 验证方式：覆盖非静态类型与权威类型冲突、来源/目标不同对象拒绝及同对象通过、非方形 helper completion；运行 api-server 定向测试、helper self-test、OpenAPI 解析、编码与 diff 门禁。
+
 ## 2026-08-20 UI Editor LLM 递归输出与参考图单文件限制
 
 - 背景：结构识别、界面语义建议和多图合并直接把 LLM 工具 arguments 反序列化为递归树；结构识别与语义建议还在 async command 中同步读取并 base64 编码参考图。模型异常输出或过大图片可能造成不受控内存、栈和 async worker 占用。
@@ -6499,6 +6506,7 @@
 - Agent 发现：新增公开 `agent-integration.json`、`skill/SKILL.md` 和 `skill.zip`。manifest 同时声明 MCP、OpenAPI、完整 Skill archive、SHA-256 和包内清单；archive 必须包含 `SKILL.md`、上述四篇 references、stdlib Python helper 和 `agents/openai.yaml` 七个声明文件，不能只提供 OpenAPI JSON，也不能包含 API Key、本机路径或个人配置。完整 `skill.zip` 只供不支持 MCP 或需要本地文件上传编排的 Agent 使用，不作为 MCP resource。
 - 兼容边界：这是基于「截至 2026-07-31 尚无外部第三方存量调用方」接受的 v1 原地 breaking change；一旦出现外部活跃 Key、公开契约或联调方，后续破坏性变更必须保留兼容、经过弃用期或升级 `/api/external/v2`。
 - 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`.codex/skills/genarrative-external-editor-api/SKILL.md`。
+- 2026-08-23 补充：新增 `POST /api/external/v1/editor/images/background-removals` 后，External v1 生成 POST 由八类增至九类；该入口继续使用 `editor:image-generate` scope、稳定 `Idempotency-Key`、`202 + operationId` 与统一查询合同。外部请求只允许 OpenAPI 声明的去背景字段，拒绝内部 `taskId` 和其它未声明字段；入队前按当前 owner 解析稳定来源并规范化为权威 objectKey，同时预检、规范化项目与素材目录目标。提供 `targetLayerId` 时始终必须同时提供 `projectId`；没有 `canvasCompletion` 时目标图层必须存在并关联当前项目资源，存在 `canvasCompletion` 时沿用生成完成链路且不执行原位替换；目标无效、引用未登记或越权时不创建任务。未提供任一画布完成字段时不自动写入画布；任务 ID 仅由服务端队列生成。
 
 ## 2026-08-04 图片画布 BGM Prompt 采用唯一可见规范化文本与面板级同步提交锁
 
@@ -13571,6 +13579,7 @@
 - Agent 发现：新增公开 `agent-integration.json`、`skill/SKILL.md` 和 `skill.zip`。manifest 同时声明 MCP、OpenAPI、完整 Skill archive、SHA-256 和包内清单；archive 必须包含 `SKILL.md`、上述四篇 references、stdlib Python helper 和 `agents/openai.yaml` 七个声明文件，不能只提供 OpenAPI JSON，也不能包含 API Key、本机路径或个人配置。完整 `skill.zip` 只供不支持 MCP 或需要本地文件上传编排的 Agent 使用，不作为 MCP resource。
 - 兼容边界：这是基于「截至 2026-07-31 尚无外部第三方存量调用方」接受的 v1 原地 breaking change；一旦出现外部活跃 Key、公开契约或联调方，后续破坏性变更必须保留兼容、经过弃用期或升级 `/api/external/v2`。
 - 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`.codex/skills/genarrative-external-editor-api/SKILL.md`。
+- 2026-08-23 补充：新增 `POST /api/external/v1/editor/images/background-removals` 后，External v1 生成 POST 由八类增至九类；该入口继续使用 `editor:image-generate` scope、稳定 `Idempotency-Key`、`202 + operationId` 与统一查询合同。外部请求只允许 OpenAPI 声明的去背景字段，拒绝内部 `taskId` 和其它未声明字段；入队前按当前 owner 解析稳定来源并规范化为权威 objectKey，同时预检、规范化项目与素材目录目标，未登记、越权引用和无效目标不创建任务；任务 ID 仅由服务端队列生成。托管 MCP 不再维护异步生成 operation 的幂等硬编码名单，而是从 OpenAPI operation/path 的 required `Idempotency-Key` header 自动生成 `idempotencyKey` 工具参数并转发同名 HTTP 头，避免新增 operation 只出现在 `tools/list` 却无法实际提交。
 
 ## 2026-08-04 图片画布 BGM Prompt 采用唯一可见规范化文本与面板级同步提交锁
 
@@ -14444,3 +14453,7 @@
 - 严格图集崩溃收口：workflow 在严格图集调用前先持久化 `strictSpritesheetPending` 并冻结底层严格事务覆盖的九项旧合同身份；旧路径可精确冻结为缺失。Provider 完成结果先绑定原 retained stage ledger。恢复在同一项目锁内对账严格事务；只有新九项合同、规范图/背景图替换锚点与 retained spritesheet result 三者一致才补写 `completed`，旧九项合同才允许补偿。旧合同判定、写 `compensating`、恢复两项素材与登记、回读和清锚点必须在同一项目锁内，重启已有 `compensating` 也重新判定；第三种混合、漂移或 foreign result 状态进入 reconciliation。不能在主图集与四切片已整体提交后仍按两文件 rollback 制造混合包；若中断前阶段告警尚未进入 durable completed result，恢复结果追加“原阶段告警无法完整重放”的明确 warning，不静默清空。
 - Direct 对话恢复从新到旧扫描全部合法 User 回合，遇到较新已回答回合继续向前，不得丢失更早未回答回合。成功返回时 Rust 已先持久化 assistant，前端冗余 append 失败也不得重跑 Provider；普通错误终态的显式 append 失败后，恢复 claim 必须保持到 React fallback writer 对同一稳定 assistant messageId 的写入明确成功或失败，不能在 writer 尚在途时按旧 `/history` 快照重跑。fallback 成功后释放 claim；fallback 失败时跳过该 writer 的无界迟到重试并释放 claim，后续显式 `/history` 才可复用原稳定 `clientTurnId`。终态收敛后删除 claim，避免长会话无界增长。
 - 正式资源提交结算遵守同一顺序：阶段三 commit 成功后先持久化 `asset-commit-settlement-pending`，恢复器幂等补齐 `asset-durable-committed` 公开投影与 staging revision，再发布私有终态；公开投影已经存在时不得重复增加草稿 revision。恢复必须把私有回执与阶段三 commit ledger、transaction journal、manifest 资产和事件 payload 的完整身份绑定，任一错配都保留 pending 并失败关闭。回归同时覆盖三个 durable write cut，以及私有回执、commit ledger、journal 错配。
+## 2026-08-24 AGC Direct 抠图语义工具
+
+- 决策：将 External v1 `/api/external/v1/editor/images/background-removals` 通过 `agc_remove_background` 加入受控 `agc_tools`。工具只接受当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；客户端负责正式 resourceId、画布/素材目录、稳定 operation/idempotency 身份、权限和错误脱敏，不向 Codex 暴露内部 BgFilter worker、凭据或任意 API。
+- 约束：异步结果只投影有界队列状态，不允许模型自行构造源 URL 或在不确定提交后更换请求身份；External v1 负责 API Key、幂等接收与统一 operation 查询，客户端不得绕过该契约。