补齐外部契约版本策略与历史抠图模型口径
Project CI / Repository checks (pull_request) Failing after 8s
Project CI / Backend tests (pull_request) Failing after 10s
Project CI / Frontend tests (pull_request) Successful in 2m31s
Project CI / Native shell tests (pull_request) Successful in 12m16s

External v1 从四个生成响应移除原本 required 的 provider 时未升 info.version,属
breaking change 而非文档同步。接入方案新增「版本与兼容策略」,记录当前无外部存量调用方
的豁免前提、失效条件与今后的 breaking 判定;openapi info.description 补充面向集成方的
兼容性说明。API Key 由用户自助发放,「无调用方」不是受控状态,改契约前需先确认活跃密钥。

用户可见性过滤是标题精确匹配「处理模型」,不做语义识别,历史素材中标题为「抠图模型」的
字段会继续出现在图片信息弹窗与画布 ZIP。收敛 MVP 接入方案原有的全覆盖表述,明确该例外
属已知且接受的产品决策:历史素材不迁移、不回溯清理,约束只对新写入生效。

两条决策记入 decision-log,排查要点记入 pitfalls。本次均为文档变更,不修改响应结构、
请求 DTO、过滤实现或素材数据。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-31 07:49:13 +00:00
parent 2e0f1f41ad
commit 7b9433c23f
5 changed files with 76 additions and 2 deletions
@@ -3,7 +3,7 @@
"info": {
"title": "陶泥儿外部编辑器 OpenAPI",
"version": "1.0.0",
"description": "外部系统调用陶泥儿图片画布项目、画布布局、素材库,以及图片、视频、音效、音乐等编辑器素材生成/编辑能力的 v1 契约。新建 projectId 使用 proj- 前缀,新建 taskId / operationId 使用 task- 前缀;历史 editor-project-*、aitask_*、extgen-* ID 仍可作为既有资源标识传入。"
"description": "外部系统调用陶泥儿图片画布项目、画布布局、素材库,以及图片、视频、音效、音乐等编辑器素材生成/编辑能力的 v1 契约。新建 projectId 使用 proj- 前缀,新建 taskId / operationId 使用 task- 前缀;历史 editor-project-*、aitask_*、extgen-* ID 仍可作为既有资源标识传入。\n\n兼容性说明:v1 当前处于无外部存量调用方阶段,正式对外发放 API Key 之前,契约可能在不升 info.version、不设弃用期的情况下发生包含字段移除在内的破坏性变更。生成客户端时请勿假定本文档已冻结。"
},
"servers": [
{