cmshoppe/docs/tasks/T-695.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-695	商品套图AI帮写与生图网关解耦	7	T-679b T-694	DONE	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，不复制或迁移密钥。
• 不改订阅服务端最终授权、图片数量与大小限制、提示词结构或原图排序。

执行记录

• 2026-07-23：完成商品套图生图网关与 AI帮写能力解耦。自定义网关继续只负责同步生图；AI帮写不再受全局 ai.backend 限制，始终独立校验并调用 cmhub Base URL、API Key 与 vision_alias。
• GUI 按两套配置分别控制生成套图与 AI帮写按钮；缺少 cmhub 图片理解配置时只禁用 AI帮写并显示中文引导。Worker 和核心 AI 调用层同步移除 backend 拒绝，设置页说明及架构/路由文档已更新。
• 新增并调整回归测试，覆盖 direct 生图下 AI帮写可用、两套配置错误互不影响、Worker 与核心图片理解仍只走 cmhub，以及既有前8张原图和临时草稿流程。
• 验证通过：py -3.10 -m unittest tests.test_product_suite_gui tests.test_workers tests.test_ai（147 项）、py -3.10 -m unittest discover -s tests（681 项）、py -3.10 -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check。