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

## 执行记录

- 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`。