From 34c7a2e148332e9607ec38310d6172bc38775596 Mon Sep 17 00:00:00 2001 From: chengma Date: Mon, 20 Jul 2026 17:30:08 +0800 Subject: [PATCH] docs(tasks): close review gaps in custom gateway suite split MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 对 T-678 细化与 T-679a/b/c 拆分的全栈复核结果： T-678：修正背景中不准确的收敛理由。api_type 在 app/ai.py 只有 :348、 :350 两处使用且都在图片路径内，文字路径从不读取该字段；不能全局收敛 的真实原因是 appconfig.py:881 对所有模型统一校验，收窄取值集合会让 存量文字模型在载入与保存时抛 ConfigError。方案首条同步改为按校验口径 表述，避免实现时去找不存在的文字侧分支。 T-679a/b/c：三处补加发布门禁，说明三者未全部完成前不得发布。拆分只为 控制改动面，不构成可独立发布的中间态——重复计费的二次确认定义在 T-679c，若 a/b 先上线，用户已能创建并失败 direct 任务却在无提示情况下 重试，属资金口径缺口而非体验缺陷。 T-679a：补记本任务组有意放宽 T-677「不给商品套图新增自定义网关路径」 的边界及理由（套图是来源切换后唯一完全断链的模块，图片理解不在放宽 范围内），避免后续回看误判两者矛盾。 T-679a：比例近似映射改为同时记录用户选择的比例与实际输出尺寸。原方案 只存原始比例会让 DB 记 9:16 而文件实际为 1024x1536；当前 add_asset 的 aspect_ratio 只写入无消费者（app/image_studio.py:707-731）故暂不可见， 但历史展示或导出一旦信任该字段即出错。新增字段迁移须附加式且幂等。 Co-Authored-By: Claude Fable 5 --- docs/tasks/T-678.md | 6 ++++-- docs/tasks/T-679a.md | 8 +++++++- docs/tasks/T-679b.md | 2 ++ docs/tasks/T-679c.md | 2 ++ 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/tasks/T-678.md b/docs/tasks/T-678.md index 4b223d5..9fa0c14 100644 --- a/docs/tasks/T-678.md +++ b/docs/tasks/T-678.md @@ -11,7 +11,9 @@ created: 2026-07-20 ## 问题 / 背景 -T-677 恢复了⑤的自定义网关（`ai.backend=direct`）。当前 `api_type` 同时用于文字与图片模型：文字模型需要 `chat/completions`，而图片模型的 `chat` / `auto` 分支则依赖非标准聚合网关把图片塞进对话响应。将 `appconfig.API_TYPES` 全局收敛成单一值会直接破坏自定义网关生文，因此必须按模型类别收敛。 +T-677 恢复了⑤的自定义网关（`ai.backend=direct`）。图片模型的 `chat` / `auto` 分支依赖非标准聚合网关把生成图塞进对话响应，不符合 OpenAI 规范，需要收敛。 + +**但不能全局收敛 `appconfig.API_TYPES`。** 代码事实是：`api_type` 在 `app/ai.py` 全文只有 :348、:350 两处使用，都在图片路径内，**文字生成路径从不读取该字段**；然而 `appconfig.py:881` 的 `if normalized["api_type"] not in API_TYPES` 对**所有模型统一校验，不分 category**。因此收窄全局取值集合的后果不是文字请求走错接口，而是存量文字模型（`api_type: "chat"`）在载入与保存时直接抛 `ConfigError`，自定义网关生文全部不可用。收敛必须按模型类别做，不能动全局集合。 当前 direct 图片编辑也只能提交单张图：`_image_edit_body()` 的 `files` 是单键字典，`_multipart_body()` 不能表达重复字段。商品套图需要按顺序提交“主体图 + 参考图”，其前置能力应在本任务完成。 @@ -21,7 +23,7 @@ T-677 恢复了⑤的自定义网关（`ai.backend=direct`）。当前 `api_type ### 1. 按类别收敛模型接口 -- 保留全局 `API_TYPES = {"chat", "images_edits", "auto"}`，避免影响 `category=text` 的既有生文请求。 +- 保留全局 `API_TYPES = {"chat", "images_edits", "auto"}`，使 `category=text` 的既有模型配置仍能通过 `appconfig.py:881` 的校验正常载入与保存。 - 新增“图片编辑能力”校验：仅 `category=image` 且 `api_type=images_edits` 的模型可用于②生成封面与后续⑥商品套图；文字模型保持既有 `chat` / `auto` 行为。 - 图片模型的 `chat` / `auto` 存量配置原样保存、可查看，但在⑤显示“当前图片模型不支持 OpenAI 图片编辑接口”的中文状态，并在②、⑥预检中阻止提交。不得静默迁移、禁用或删除，避免触发“至少一个 image 模型启用”的既有校验冲突。 - ⑤根据模型类别展示接口类型：文字模型保留现有可选项；图片模型只允许选择并显示“OpenAI 图片编辑接口”。不再以全局文案宣称 `chat/completions` 永远不能生成图片，而是说明其不符合本项目锁定的图片编辑响应契约。 diff --git a/docs/tasks/T-679a.md b/docs/tasks/T-679a.md index 09bc83d..5554c93 100644 --- a/docs/tasks/T-679a.md +++ b/docs/tasks/T-679a.md @@ -11,6 +11,10 @@ created: 2026-07-20 ## 问题 / 背景 +**本任务组有意放宽 T-677 的既定边界。** T-677 明确写了「不给商品套图和图片理解新增自定义网关路径，本任务只做入口拦截与提示」。放宽的理由是：来源切换后，商品套图是唯一完全断链的模块——②生文生图在自定义网关下可用，只有⑥不可用，用户切走后套图功能整体消失。图片理解（AI 帮写）不在放宽范围内，继续保持默认网关独占。记录这一点是为了避免后续回看时误判 T-677 与本任务组互相矛盾。 + +**发布门禁：T-679a、T-679b、T-679c 未全部完成前不得发布。** 三者拆分只为控制单次改动面，不构成可独立发布的中间态。重复计费的二次确认提示定义在 T-679c，若 T-679a/T-679b 先上线，用户已能创建并失败 direct 任务，却会在没有"可能重复收费"提示的情况下重试——这是资金口径缺口，不是体验缺陷。 + `app/image_studio_generation.py` 当前把运行时、提交、轮询和 job 来源硬编码为 cmhub。自定义网关是无 task ID 的同步图片编辑请求，不能复用 cmhub 的异步恢复模型；若只在现有分支上打补丁，停止、超时或程序中断时会出现已扣费图片丢失、误轮询或重复生成。 ## 方案 @@ -37,7 +41,8 @@ created: 2026-07-20 ### 4. 比例与参考图 -- 套图比例固定映射：`1:1 -> 1024x1024`；`3:4`、`9:16 -> 1024x1536`；`4:3`、`16:9 -> 1536x1024`。后四种为近似映射，返回资产仍保存用户选择的原始比例。 +- 套图比例固定映射：`1:1 -> 1024x1024`；`3:4`、`9:16 -> 1024x1536`；`4:3`、`16:9 -> 1536x1024`。映射覆盖 `product_suite.RATIOS` 的全部五个取值；后四种为近似映射。 +- **资产必须同时记录用户选择的比例与实际输出尺寸。** 只保存原始比例会让 DB 记着 `9:16` 而文件实际是 1024×1536（2:3）。当前 `image_studio.add_asset()` 的 `aspect_ratio` 只写入、无下游消费者（`app/image_studio.py:707-731`），所以暂不产生可见故障；但一旦历史展示、导出或后续上传开始信任该字段就会出错。补充实际尺寸字段属于本任务范围，不留给以后修。 - 任务层向调用方返回“是否近似比例”的结构化结果，T-679b 负责在确认框中告知用户；不得静默伪造精确比例。 - 首图主体与其余参考图的规则必须使用已冻结、已持久化的 job prompt；不能在 HTTP 调用层临时拼接，避免确认预览、历史 prompt 与实际请求不一致。 @@ -48,6 +53,7 @@ created: 2026-07-20 - [ ] 已返回字节的 direct job 即使用户点击停止也会保存成功；未开始 job 才会取消。 - [ ] direct 不发生自动重试；遗留 `running` direct job 不会自动重发或进入继续查询。 - [ ] 比例映射、近似标记、`n=1`、多图顺序和 prompt 一致性有纯逻辑测试。 +- [ ] 生成资产同时记录用户选择的比例与实际输出尺寸；新增字段的迁移为附加式且幂等，存量资产缺该字段时不报错、不阻塞历史展示。 - [ ] 直连模型 URL、密钥与原始响应不进入 SQLite、事件日志或异常面向用户的文案。 ## 测试与文档 diff --git a/docs/tasks/T-679b.md b/docs/tasks/T-679b.md index 175733d..bdf2f94 100644 --- a/docs/tasks/T-679b.md +++ b/docs/tasks/T-679b.md @@ -11,6 +11,8 @@ created: 2026-07-20 ## 问题 / 背景 +**发布门禁：T-679a、T-679b、T-679c 未全部完成前不得发布**（理由见 T-679a 背景：重复计费提示定义在 T-679c，缺它会形成资金口径缺口）。 + T-677 按安全边界禁用了自定义网关下⑥的新建套图、重试和价格流程。T-679a 提供来源正确的同步执行能力后，GUI 必须只在配置可用时开放入口，并用清晰中文说明主体一致性、比例近似、费用和停止边界。 ## 方案 diff --git a/docs/tasks/T-679c.md b/docs/tasks/T-679c.md index 4fc5936..c20424a 100644 --- a/docs/tasks/T-679c.md +++ b/docs/tasks/T-679c.md @@ -11,6 +11,8 @@ created: 2026-07-20 ## 问题 / 背景 +**发布门禁：T-679a、T-679b、T-679c 未全部完成前不得发布。** 本任务承载 direct 重试的重复计费二次确认，是该门禁的主要原因——缺它则用户可在无提示的情况下重复付费重试（详见 T-679a 背景）。 + 默认网关异步任务可凭 `task_id` 继续查询；自定义网关同步请求无法在程序中断后确认远端状态。两类 job 在同一项目中并存时，错误的“恢复”或自动重试会造成重复计费、错误轮询或用户误判结果。 ## 方案