新增 External v1 去背景生成链路
新增外部去背景 API、MCP 工具与异步队列契约 补齐来源归属、媒体类型、幂等重放和画布原子持久化校验 修复 provenance 重建、assetKindOverride 门禁与 revision retry 竞态 同步 Python helper、Skill、OpenAPI 及项目文档
This commit is contained in:
@@ -1,5 +1,12 @@
|
||||
# 决策记录
|
||||
|
||||
## 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 占用。
|
||||
@@ -6492,6 +6499,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 采用唯一可见规范化文本与面板级同步提交锁
|
||||
|
||||
@@ -13564,6 +13572,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 采用唯一可见规范化文本与面板级同步提交锁
|
||||
|
||||
|
||||
Reference in New Issue
Block a user