From f7c9d761ee589c1ab01833f30b7567357f0b9525 Mon Sep 17 00:00:00 2001 From: chengma Date: Thu, 23 Jul 2026 10:08:03 +0800 Subject: [PATCH] docs(tasks): decouple suite ai writing gateway --- docs/tasks/T-695.md | 73 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/tasks/T-695.md diff --git a/docs/tasks/T-695.md b/docs/tasks/T-695.md new file mode 100644 index 0000000..f9be1ee --- /dev/null +++ b/docs/tasks/T-695.md @@ -0,0 +1,73 @@ +--- +id: T-695 +title: 商品套图AI帮写与生图网关解耦 +phase: 7 +deps: [T-679b, T-694] +status: TODO +created: 2026-07-23 +--- + +## 问题 / 背景 + +商品套图当前把“生成套图使用的网关”和“AI帮写使用的图片理解服务”绑定在同一个 `ai.backend` 上。用户选择自定义网关生成套图后，即使 cmhub Base URL、API Key 和 `vision_alias` 都已配置，`_apply_running_state()` 仍会把“AI帮写”按钮禁用并提示仅支持默认网关。 + +该限制同时存在于三层： + +- GUI `start_ai_write()` 通过 `_require_default_gateway()` 拒绝当前 `backend=direct`。 +- `ProductSuiteAiWriteWorker.execute()` 再次检查 backend 并拒绝执行。 +- `ai.analyze_product_images()` 作为专用 cmhub 图片理解函数，仍根据全局 backend 拒绝 direct 配置。 + +这不是能力冲突：自定义网关只负责套图生图，AI帮写本来就固定调用 cmhub `vision_alias` 的图片理解接口。二者可以同时保留各自配置并独立运行，不应要求用户为了使用AI帮写临时切换生图网关。 + +## 方案 + +### 1. 拆分能力判定 + +- “生成套图”继续按已保存的 `ai.backend` 选择默认 cmhub 异步生图或自定义 OpenAI 格式同步生图，现有模型校验、确认、计费文案和 job 来源不变。 +- “AI帮写”不再读取当前生图 backend 作为准入条件；始终使用 cmhub 图片理解能力，并独立检查：规范化 Base URL 非空、本地 cmhub API Key 非空、`vision_alias` 非空。 +- 配置完整只代表按钮可用，不在界面刷新时发网络请求；模型目录、预计扣点和服务可达性仍在用户点击后由现有后台 worker 检查。 +- 缺少任一配置时按钮禁用，tooltip 使用中文说明“请到⑤设置配置默认网关的地址、API Key 和图片理解模型”；点击入口和 worker 仍需重复执行配置预检，不能只依赖按钮状态。 + +### 2. 三层代码解耦 + +- `ProductSuiteTab._apply_running_state()` 的 AI帮写启用条件改为“cmhub 图片理解配置完整 + 未在AI帮写 + 未在套图生成”，不再要求 `_is_default_gateway()`。 +- `start_ai_write()` 移除 `_require_default_gateway()`，改为专用 cmhub 图片理解配置检查；订阅预检、原图筛选、确认弹窗、模型目录扣点查询、取消和结果保存保持不变。 +- `ProductSuiteAiWriteWorker` 保留 `freeze_runtime_config(... include_cmhub=True, include_direct_models=False)`，移除全局 backend 拒绝；worker 快照仍只包含本轮需要的 cmhub 配置，不读取或调用自定义生图模型。 +- `ai.analyze_product_images()` 移除对全局 backend 的判断，直接通过 `_cmhub_runtime(..., "vision")` 校验并调用 cmhub；Base URL、Key 或别名缺失时继续返回中文安全错误，不回退自定义网关。 + +### 3. 状态与文案 + +- 自定义网关启用且 cmhub 图片理解配置完整时，“生成套图”和“AI帮写”可同时正常启用；AI帮写 tooltip 不再显示“仅支持默认网关”。 +- 自定义网关配置不完整只影响生成套图，不影响已配置完整的AI帮写；cmhub 图片理解配置不完整只影响AI帮写，不影响自定义网关生图。 +- AI帮写确认框继续说明理解图片数量和 cmhub 预计扣点；实际扣点、余额、超时、日志脱敏和会员预检口径不变。 +- 所有用户文案继续使用中文，不展示 API Key、完整接口路径、图片本地路径或上游原始错误。 + +### 4. 回归测试 + +- `backend=direct` 且自定义图片模型与 cmhub 图片理解均配置完整：生成套图按钮和AI帮写按钮都启用；点击AI帮写仍创建 `ProductSuiteAiWriteWorker` 并调用 cmhub 图片理解，不读取 direct 图片模型。 +- `backend=direct` 且 cmhub Base URL、Key 或 `vision_alias` 任一缺失：生成套图按自定义配置保持可用，AI帮写禁用并显示对应中文引导。 +- `backend=cmhub` 的现有AI帮写、模型目录预计扣点、前8张原图顺序、取消、成功保存和错误脱敏回归保持通过。 +- 核心 `analyze_product_images()` 在全局 backend 为 direct 时仍只请求 cmhub vision；配置缺失时失败且不调用网络。 + +## 验收要点 + +- 用户选择“自定义网关”生成套图后，只要 cmhub 图片理解配置完整，“AI帮写”按钮保持可用。 +- 点击AI帮写后实际请求仍使用 cmhub Base URL、API Key 和 `vision_alias`，不会调用自定义生图网关。 +- 两套能力的配置错误互不连带禁用，运行中锁定、会员预检和取消行为不变。 +- 自动验证： + - `py -3.10 -m unittest tests.test_product_suite_gui tests.test_workers tests.test_ai` + - `py -3.10 -m unittest discover -s tests` + - `py -3.10 -m ruff check app tests main.py` + - `py -3.10 -m compileall app main.py` + - `git diff --check` + +## 边界（不改什么） + +- 不让AI帮写调用自定义网关，不新增AI帮写网关下拉、模型字段或独立 API Key。 +- 不改变默认/自定义生图 job、异步轮询、同步直连、重试、历史或导出逻辑。 +- 不改配置 schema；继续复用现有 `ai.cmhub` 与 `data/config/cmhub.json`，不复制或迁移密钥。 +- 不改订阅服务端最终授权、图片数量与大小限制、提示词结构或原图排序。 + +## 执行记录 + +- 待实现。