feat(product-suite): add cmhub vision AI writing

docs/cmhub-integration-design.md

@@ -13,6 +13,7 @@
 > **v3.4 核对（2026-07-06，刷新别名 notfound）**：核对对接文档 §4.4 与 cmhub `ModelsView` 路由，确认 cmshopee `GET /api/v1/models` + Bearer 请求**已达标**；「notfound」为 404，根因是 Base URL 带多余 `/api(/v1)` 路径（双拼）或所连实例未部署 `/api/v1/models`（见 `docs/troubleshooting.md`）。**T-530 已落地**：保存/请求前规整 Base URL 到网关根，HTTP 404 映射为 `not_found` 并给出中文排障提示。
 > **v3.5 修订（2026-07-08，T-553 待实现）**：cmhub 生图稳定性口径调整为连接超时默认 66 秒、生图请求和 `image_url` 下载读取等待统一 900 秒，与线上 Nginx/Gunicorn 的长等待窗口对齐；生图读超时仍不自动重发，避免重复扣点。
 > **v3.6 修订（2026-07-08，T-564）**：cmhub 已新增异步生图任务接口，②批量生图改为 `POST /api/v1/generate/image/tasks` submit + `GET /api/v1/generate/image/tasks/{task_id}` poll；cmshopee 持久化 `tasks.image_task_id/image_task_key`，支持停止/超时/重启后续查，避免 900 秒同步长连接和读超时重复扣点。旧同步 `POST /api/v1/generate/image` 仅保留给单独 `gen_cover()` 兼容/回滚路径。
+> **v3.7 修订（2026-07-17，T-645）**：⑥「商品套图」的 AI帮写接入独立图片理解能力：使用 `vision_alias` 调 `POST /api/v1/analyze/images`，不复用标题接口或 `title_alias`。请求最多8张有序本地原图，单图不超过10MiB、总计不超过32MiB；读取等待120秒且读超时不自动重发，避免结果未确认时重复扣点。
 
 ## 1. 背景与目标
 
@@ -59,6 +60,7 @@
     "base_url": "https://<cmhub>",    // 网关根地址，请求时拼 /api/v1/...
     "title_alias": "title-standard",  // 生文能力别名
     "image_alias": "image-hd",        // 生图能力别名
+    "vision_alias": "vision-standard",// ⑥AI帮写图片理解能力别名
     "connect_timeout": 66,
     "check_balance_before_batch": false
   },
@@ -69,7 +71,7 @@
 
 - **cmhub API Key 不进 `data/config.json`**（避免与其它设置混放、避免误提交）。固定存到 `data/config/cmhub.json`，文件 schema 第一版为 `{ "api_key": "sk_cmhub_xxx" }`；新增 `CMHUB_CONFIG_PATH`、`load_cmhub_config()`、`save_cmhub_config()`、`get_cmhub_api_key(masked=False)` 等 helper；`data/config/cmhub.json` 必须加入 `.gitignore`。沿用现有"本地明文保存但 gitignore + UI 打码 + 日志脱敏"纪律（T-503）。
 - **`ai_models.json` 去留**：`direct` 模式继续用；`cmhub` 模式不读它。文件保留但标记 legacy。
-- **默认 backend 与配置不完整处理（T-529 后）**：`DEFAULT_CONFIG` / `default_config()` 造全新配置时写 `backend=cmhub`；⑤设置页隐藏 direct/cmhub 下拉并固定保存 `backend=cmhub`。允许先保存不完整 cmhub 配置，便于用户先保存其它路径/安全设置；②生成真正调用时如果 `base_url`/Key/别名缺失，必须抛**清晰的"请去⑤配置 cmhub"错误**（`CMHubError`/`AIError`），不得崩溃或静默回退 direct。显式手工配置 `backend=direct` 仍作为内部回滚路径保留，但普通 UI 不提供入口。
+- **默认 backend 与配置不完整处理（T-529/T-645 后）**：`DEFAULT_CONFIG` / `default_config()` 造全新配置时写 `backend=cmhub`，`vision_alias` 默认 `vision-standard`；⑤设置页隐藏 direct/cmhub 下拉并固定保存 `backend=cmhub`。允许先保存不完整 cmhub 配置，便于用户先保存其它路径/安全设置；②或⑥真正调用时如果 `base_url`/Key/对应别名缺失，必须抛**清晰的"请去⑤配置 cmhub"错误**（`CMHubError`/`AIError`），不得崩溃或静默回退 direct。显式手工配置 `backend=direct` 仍作为内部回滚路径保留，但⑥AI帮写不提供 direct 回退。
 - **Base URL 必须是网关根**：只填 `https://<cmhub-域名>`，**不带** `/api`、`/api/v1` 或任何路径。`cmhub_request_url()` 会自行拼 `/api/v1/...`；若 Base URL 已含 `/api/v1`，会双拼成 `.../api/v1/api/v1/...` → 404（正是「刷新别名 notfound」现象，见 `docs/troubleshooting.md`）。**当前请求本身已达标**（`GET /api/v1/models` + `Authorization: Bearer <key>`，对齐对接文档 §4.4 与 cmhub `ModelsView` 路由）；404 的根因是 Base URL 带多余路径或所连实例未部署 `/api/v1/models`。**T-530 已在保存/请求前规整 Base URL**，会去掉多余路径、查询串和片段，只保留 scheme+host(+port)；404 会给出明确中文提示。
 
 ### 4.2 `gen_title` 改造（cmhub 分支）
@@ -86,6 +88,13 @@
 - **响应**：解析 `titles`，取 `titles[0]`（当前一条任务要一个新标题）；空列表/空串按现有语义抛 `AIError("AI 返回为空标题")`。
 - 不复用现有 `_call_with_retry` 的一刀切重试逻辑；cmhub 分支新增专用 HTTP helper，优先使用项目已依赖的 `requests`，传 `timeout=(connect_timeout, read_timeout)` 以区分连接超时和读超时。`model_used`/`points_cost`/`points_balance`/`call_id` 不改变返回值，通过 `on_step`/事件回调上报给 `generate_batch` 与 GUI worker；T-526 只保证 metadata 事件完整传出，不直接要求写 GUI `run_logs`，T-528 再由 GUI worker 脱敏写 `run_logs` 和展示余额；不入 Excel。
 
+### 4.2a ⑥商品套图图片理解（T-645）
+
+- **请求**：仅 `backend=cmhub` 时由 `analyze_product_images()` 调 `POST {base_url}/api/v1/analyze/images`，头沿用 Bearer Key，体为 `{prompt, model: vision_alias, images:[{image_base64:data_url}], parameters:{temperature:0.2}}`。`images` 按⑥项目原图 `source_order` 顺序传入，数量1至8；单图超过10MiB、总计超过32MiB、路径缺失或无图时在本地阻断，不发请求。
+- **响应**：只接收可编辑文本和白名单元数据 `alias/model_used/points_cost/points_balance/call_id`；不保存 base64、完整提示词、图片路径、接口URL或 Provider 原始响应。成功由⑥状态栏显示“已理解N张商品原图、图片理解扣点、当前余额”。
+- **超时/取消**：连接等待沿用 `connect_timeout`，读取等待120秒；一次 `read_timeout`、连接中断的结果均视为未确认，不自动重发。取消只在发请求前或返回后协作生效，不强杀网络线程，也不声称未扣点。
+- **边界**：该能力不改 `gen_title()`、`gen_cover()`、②批量生成状态或⑥正式套图生图 job；已有卖点只作为补充要求，模型必须以图片可见信息为主，避免虚构不可确认的规格、认证、价格和物流信息。
+
 ### 4.3 `gen_cover` 改造（cmhub 分支）
 
 返回值不变（仍返回已存 JPEG 路径），现有调用保持兼容；允许新增可选事件回调参数承载计费元数据。内层：
@@ -139,9 +148,9 @@ cmhub 返回结构化 `{error:{code}}`。映射层**按 `code` 优先分支**（
 
 对接文档已把别名发现从"未来提供"落地为**真实接口**（第 4 个接口，鉴权同为 Bearer Key）：
 
-- 响应 `{models:[{alias, operation_type:"title"|"image", capabilities[], requires_image:bool, pricing_status:"priced"|"unpriced", prices:[{resolution, points_cost}]}]}`——只含别名侧信息，不含具体模型名/URL/密钥。
-- **⑤设置的别名由手填改为动态下拉**：新增 `app/appconfig.py`（或 `app/ai.py`）helper `fetch_cmhub_models(base_url, api_key)`，⑤按 `operation_type` 拆成「生文别名 / 生图别名」两个下拉；`requires_image` 供 UI 提示（cmshopee 生图恒传旧封面 base64，天然满足）；`pricing_status="unpriced"` 的别名**不放入下拉**（直接调用会 `no_pricing_rule`）；单价用 `prices` 展示。
-- 拉取时机：⑤ 打开或用户点「测试连接/刷新别名」时拉一次，选中的别名仍持久化到 `config.json` 的 `ai.cmhub.title_alias/image_alias`（网关临时不可达时用已存值）。
+- 响应 `{models:[{alias, operation_type:"title"|"image"|"vision", capabilities[], requires_image:bool, pricing_status:"priced"|"unpriced", prices:[{resolution, points_cost}]}]}`——只含别名侧信息，不含具体模型名/URL/密钥。
+- **⑤设置的别名由手填改为动态下拉**：新增 `app/appconfig.py`（或 `app/ai.py`）helper `fetch_cmhub_models(base_url, api_key)`，⑤按 `operation_type` 拆成「生文别名 / 生图别名 / 图片理解别名」三个下拉；图片理解下拉额外只接受 `requires_image=true` 且 `pricing_status="priced"` 的别名。已保存但本次模型列表不可用的值必须保留并标注，不可无声清空；`requires_image` 也供生图 UI 提示（cmshopee 生图恒传旧封面 base64，天然满足）；`pricing_status="unpriced"` 的别名**不放入下拉**（直接调用会 `no_pricing_rule`）；单价用 `prices` 展示。
+- 拉取时机：⑤打开或用户点「测试连接/刷新别名」时拉一次，选中的别名仍持久化到 `config.json` 的 `ai.cmhub.title_alias/image_alias/vision_alias`（网关临时不可达时用已存值）。
 - 这**关闭了原待确认 #1（别名清单）**——不再需部署方单独提供；仅 Base URL 仍待部署方给。
 
 ## 5. 各模块改动点
@@ -176,7 +185,7 @@ cmhub 返回结构化 `{error:{code}}`。映射层**按 `code` 优先分支**（
 
 ## 8. 迁移与回退
 
-- T-529 后普通配置默认 `backend=cmhub`；显式手工配置 `backend=direct` 仍可作为内部回滚路径。⑤普通 UI 不再提供后端切换，用户只需配好 `base_url + Key + 两个别名`。
+- T-529/T-645 后普通配置默认 `backend=cmhub`；显式手工配置 `backend=direct` 仍可作为内部回滚路径，但⑥AI帮写必须使用 cmhub 图片理解。⑤普通 UI 不再提供后端切换，用户只需配好 `base_url + Key + 三类别名`。
 - 回退：`backend=direct` 立即切回本地直连，`ai_models.json` 仍有效。
 - 灰度：可先在 ② 单条生成上验证 cmhub 联通与计费，再放批量。