T-529 default to cmhub gateway

docs/03-tech-stack.md

@@ -17,13 +17,13 @@
 | 应用配置 | `config.json`（JSON，stdlib） | 已定 | 少量应用级设置：Chrome 路径、目录根、端口、DB 路径等 |
 | 业务数据 | SQLite（stdlib `sqlite3`，`cmshopee.db`） | 已定 | 账号、任务、结果：成行增长、要查询/统计/导出 |
 | Excel 读写 | `openpyxl` | 已定 | 导入任务、回写结果；stdlib 读不了 .xlsx |
-| AI 模型注册 | `config/ai_models.json` direct 模型清单 + `config/cmhub.json` 网关 Key | 已接入（后端） | direct 模式保留每模型 name/category/url/model/key/api_type；cmhub 模式用 `config.json` 的 Base URL/别名 + `config/cmhub.json` 单 Key；⑤ cmhub 面板待 T-527 |
-| AI 文本生成 | `app/ai.py` 支持 direct chat JSON 与 cmhub `POST /api/v1/generate/title` | 已接入 | 提示词+旧标题→新标题；返回值不变；cmhub 计费 metadata 通过事件回调上报 |
-| AI 图像生成 | `app/ai.py` 支持 direct chat/images_edits 与 cmhub `POST /api/v1/generate/image` | 已接入 | 提示词+旧封面→新封面；cmhub 拿 `image_url` 后安全下载并转本地 JPEG；生图读超时不自动重发 |
+| AI 模型注册 | `config/cmhub.json` 网关 Key + `config/ai_models.json` direct 兼容清单 | 已接入 | 普通产品默认 cmhub，使用 `config.json` 的 Base URL/别名 + `config/cmhub.json` 单 Key；direct 模型清单保留为内部兼容/手工回滚路径，普通⑤设置页不暴露后端切换 |
+| AI 文本生成 | `app/ai.py` 默认 cmhub `POST /api/v1/generate/title`，保留 direct chat JSON 兼容分支 | 已接入 | 提示词+旧标题→新标题；返回值不变；cmhub 计费 metadata 通过事件回调上报 |
+| AI 图像生成 | `app/ai.py` 默认 cmhub `POST /api/v1/generate/image`，保留 direct chat/images_edits 兼容分支 | 已接入 | 提示词+旧封面→新封面；cmhub 拿 `image_url` 后安全下载并转本地 JPEG；生图读超时不自动重发 |
 | 并发 | 标准库 `concurrent.futures.ThreadPoolExecutor` | 已定 | 标题/图片分别按并发数并行；③ 可按账号并行更新；可停止、可重试 |
 | 运行日志 | SQLite `run_logs` / `run_log_events` | 已定 | ③ dry-run 与真实更新都留痕；结构化内容走脱敏 |
 | 图片处理 | `requests`（下载）+ `Pillow`（按分辨率/jpg质量存盘） | 部分待定 | 下载旧封面；新封面按 resolution 生成、jpg_quality 存盘 |
-| 测试 | `python -m compileall app main.py` + `unittest` + 手动 CDP/AI 验证 | 已定（分层） | 配置/DB/Excel/prompts 用单测；CDP/Shopee 与真实 AI 属集成验证或 mock |
+| 测试 | `python -m compileall app main.py` + `unittest` + 手动 CDP/AI 验证 | 已定（分层） | 配置/DB/Excel/prompts 用单测；CDP/Shopee 与真实 AI 属集成验证或 mock |
 | 打包分发 | PyInstaller onedir（`cmshopee.spec`） | 已定 | 产出 Windows 免安装文件夹；不内置配置、DB、图片、日志、Chrome 登录态或提示词等本地数据 |
 
 ## 二、决策记录与演进
@@ -34,13 +34,13 @@
 - **Excel 用 openpyxl**：运营用真实 .xlsx；stdlib 无法读写 xlsx，引入一个轻依赖比改用 CSV 更贴合用户习惯。
 - **多账号隔离用独立 user-data-dir，不用 Chrome profile**：profile 共享同一 user-data-dir/进程/调试端口，无法每账号独立 CDP 与并行；独立 user-data-dir 才契合自动化。详见 [架构 3.0](04-architecture.md)。
 - **快捷方式生成用 PowerShell（无额外依赖）**：用 `WScript.Shell.CreateShortcut` 生成 `.lnk`，不引入 `pywin32` 等依赖。
-- **AI 服务商不写死在代码里**：T-301 已采用 `config/ai_models.json` 的 direct 通用 HTTP 接入，支持 OpenAI-compatible chat JSON 与 images_edits multipart；T-526 已新增 `backend=cmhub` 网关后端，cmhub 模式使用 Base URL + 生文/生图别名 + `config/cmhub.json` 单 Key，直连模型清单保留用于回退。
+- **AI 服务商收口到 cmhub 网关**：T-301 的 `config/ai_models.json` direct 通用 HTTP 接入仍保留为内部兼容/手工回滚路径；T-526~T-529 后普通产品默认 `backend=cmhub`，⑤设置页只展示 cmhub Base URL + 生文/生图别名 + `config/cmhub.json` 单 Key，不再暴露 AI 后端切换。
 - **AI 模型 category 是硬约束**：`config/ai_models.json` 每个模型必须有 `category=text` 或 `category=image`；启动时报 “AI 模型 category 必须是 text 或 image” 时，按 [常见问题排查](troubleshooting.md) 修复本地配置，不删除或提交含 Key 的配置文件。
 - **敏感信息不加密但强提示与脱敏**：密码与 AI Key 只在本机 SQLite / `config/ai_models.json` / `config/cmhub.json` 明文保存；保存/变更时弹窗提示，UI 打码，日志/导出必须脱敏，相关本地文件必须 gitignore。
 - **AI 产出无逐条审核**：生成的新标题/新封面经 ③ 批量确认后提交线上；无常驻提交开关，本地留档 + 回写 Excel 供追溯。
 - **T-504 更新执行增强**：③ 支持 dry-run 预览、运行日志和按账号并行；默认 dry-run 关闭、并行关闭，不引入新依赖。
 - **不引入数据库（指外部 DB）**：用 stdlib SQLite 足够；不引入 Postgres/MySQL 等。
-- **生产在 Windows 直跑**：开发期我们用过 WSL→Windows 的 `netsh portproxy`（9333→9222）连 CDP；但 GUI 与 Chrome 都在 Windows 时，直接连 `127.0.0.1:9222`，无需 portproxy。
+- **生产在 Windows 直跑**：开发期我们用过 WSL→Windows 的 `netsh portproxy`（9333→9222）连 CDP；但 GUI 与 Chrome 都在 Windows 时，直接连 `127.0.0.1:9222`，无需 portproxy。
 - **PyInstaller 使用 onedir 免安装包**：T-524 先做 `dist/cmshopee/cmshopee.exe` + `_internal/` 的文件夹分发，不做自动更新器；打包版启动时工作目录切到 exe 所在目录，用户本地配置、DB、图片、日志、登录态和提示词保留在程序目录，更新时只覆盖程序文件。
 
 ## 三、构建与运行命令
@@ -52,8 +52,8 @@
 | 语法检查 | `python -m compileall app main.py` |
 | 启动 GUI | `python main.py` / `python -m app` |
 | 单元测试（T-006 后） | `python -m unittest discover -s tests` |
-| CI 自动验证 | GitHub Actions `.github/workflows/tests.yml`（Windows + Python 3.11 + `QT_QPA_PLATFORM=offscreen`） |
-| 安装打包依赖 | `python -m pip install -r requirements-build.txt` |
+| CI 自动验证 | GitHub Actions `.github/workflows/tests.yml`（Windows + Python 3.11 + `QT_QPA_PLATFORM=offscreen`） |
+| 安装打包依赖 | `python -m pip install -r requirements-build.txt` |
 | 打包 exe | `powershell -ExecutionPolicy Bypass -File scripts\\build_exe.ps1` |
 | 跑单账号演示 | `python prototypes/demo.py`（分步）/ `set AUTO=1 && python prototypes/demo.py`（自动） |
 | 提交更新（真改线上） | `set UPDATE=1 && python prototypes/demo.py` |
@@ -74,7 +74,7 @@ set AUTO=1 && python prototypes/demo.py
 
 ## 四、依赖纪律
 
-- 运行时第三方依赖统一写入根目录 `requirements.txt` 并锁定版本；换机或 CI 使用 `python -m pip install -r requirements.txt` 安装。
+- 运行时第三方依赖统一写入根目录 `requirements.txt` 并锁定版本；换机或 CI 使用 `python -m pip install -r requirements.txt` 安装。
 - 打包依赖只写入 `requirements-build.txt`；PyInstaller 不属于运行时依赖，不写进 `requirements.txt`。
 - 当前直接依赖锁定：PySide6 6.5.3、openpyxl 3.1.3、requests 2.31.0、websocket-client 1.6.1、Pillow 9.5.0。
 - 新增第三方依赖前，先在本文说明用途、替代方案和维护成本，并同步更新 `requirements.txt`。
@@ -91,4 +91,4 @@ set AUTO=1 && python prototypes/demo.py
 | GUI 轻测 | PySide6 主窗口可创建、Tab 数量、worker signal 基本行为 | 可用 unittest 构造 `QApplication`，不连真实 Shopee |
 | CI | push / pull_request 自动跑语法 + 全量 unittest | `.github/workflows/tests.yml` 安装 `requirements.txt`，运行 `python -m compileall app main.py` 与 `python -m unittest discover -s tests`；不连真实 Shopee/AI |
 | 集成 | CDP/editor 操作 Shopee 测试商品 | 手动跑 `prototypes/demo.py` 或后续专用集成脚本 |
-| 外部 AI | 模型连接、文本/图像生成 | 默认 mock；真实调用只在手动验证时跑，避免成本和限流 |
+| 外部 AI | 模型连接、文本/图像生成 | 默认 mock；真实调用只在手动验证时跑，避免成本和限流 |

docs/04-architecture.md

@@ -27,7 +27,7 @@ GUI（PySide6 QTabWidget，5 Tab）
   └── ai         文本生成（提示词+旧标题→新标题）/ 图像生成（提示词+旧封面→新封面）
   |
   v
-Google Chrome（每账号独立 --user-data-dir + --remote-debugging-port） + AI 服务（direct 外部模型或 cmhub 网关）
+Google Chrome（每账号独立 --user-data-dir + --remote-debugging-port） + AI 服务（默认 cmhub 网关；direct 仅内部兼容/回滚）
   |
   v
 Shopee 卖家中心页面 / 本地图片目录
@@ -38,7 +38,7 @@ Shopee 卖家中心页面 / 本地图片目录
 - GUI 入口：根目录 `main.py` 调用 `app/gui/` 包（PySide6 + `QMainWindow` + `QTabWidget`，5 Tab）；包入口 `app/gui/__init__.py` 提供 `main()` 并兼容 `from app import gui` / `from app.gui import MainWindow`；也支持 `python -m app`。
 - 核心模块统一放在正式代码包 `app/`：`appconfig.py`、`db.py`、`excel.py`、`config.py`、`accounts.py`、`chrome.py`、`editor.py`、`workers.py`、`ai.py`、`prompts.py`；CDP 底座迁入 `app/cdp.py`（当前根目录 `cdp.py` 为已验证来源）。
 - 已验证脚本（重构进模块）：`prototypes/demo.py`、`prototypes/set_title.py`、`prototypes/set_cover.py`、`prototypes/get_title.py`、`prototypes/cookies.py`、`prototypes/inspect_images.py`、`prototypes/grab.py`。
-- 外部依赖：本机 Google Chrome；Shopee；AI 服务（文本+图像；direct 模式由 `config/ai_models.json` 配置，cmhub 模式由 `config.json` 的 `ai.cmhub` + `config/cmhub.json` 配置）；`openpyxl`。
+- 外部依赖：本机 Google Chrome；Shopee；AI 服务（文本+图像；普通产品默认 cmhub 网关，由 `config.json` 的 `ai.cmhub` + `config/cmhub.json` 配置；direct 直连模型清单仅作为内部兼容/手工回滚路径保留）；`openpyxl`。
 
 ## 二、流水线（核心）
 
@@ -71,12 +71,12 @@ imported  →  collected  →  generated  →  applied
 - `chrome`：拼接启动命令、启动、探测端口、（可选）生成快捷方式。
 - `cdp`：连接调试端口、找/开 tab、执行 JS、拖拽、注入文件。
 - `editor`：登录检测、**采集**（读旧标题、下载旧封面）、改标题、换封面、点更新。
-- `ai`：`gen_title(prompt, old_title)`、`gen_cover(prompt, old_cover_path)`（外部 AI；支持 `direct` 模型清单和 `cmhub` 网关 backend；返回值保持标题字符串/本地 JPEG 路径）。
+- `ai`：`gen_title(prompt, old_title)`、`gen_cover(prompt, old_cover_path)`（外部 AI；默认走 `cmhub` 网关，保留 `direct` 模型清单作为内部兼容/回滚 backend；返回值保持标题字符串/本地 JPEG 路径）。
 
 **存储（同一事实只存一处）**
 
 - 应用配置（模型选择、生成参数、目录、Chrome 路径）→ `config.json`。
-- AI 模型清单（direct 模式 url/模型/密钥/类型/连接超时）→ `config/ai_models.json`（API Key 本地明文保存，必须 gitignore，UI 打码显示）。
+- AI 模型清单（direct 内部兼容模式 url/模型/密钥/类型/连接超时）→ `config/ai_models.json`（API Key 本地明文保存，必须 gitignore，UI 打码显示；普通设置页不再暴露 direct 切换入口）。
 - cmhub 网关 Key → `config/cmhub.json`，schema `{ "api_key": "..." }`；`config.json` 只保存 Base URL、别名和超时，不保存 Key。
 - 业务数据（账号、任务、各阶段结果）→ SQLite `cmshopee.db`。
 - 图片（采集的旧封面、AI 生成的新封面）→ 本地图片目录（路径记在 DB）。
@@ -104,7 +104,7 @@ imported  →  collected  →  generated  →  applied
     "default_text_model": "GPT-5.5 文本",
     "default_image_model": "Nano Banana 2",
     "generate_cover": false,
-    "backend": "direct",
+    "backend": "cmhub",
     "cmhub": {
       "base_url": "",
       "title_alias": "",
@@ -134,14 +134,14 @@ imported  →  collected  →  generated  →  applied
 
 `ai` 段只放**选择 + 全局生成参数**：
 
-- `backend`：`direct` / `cmhub`。全新配置和旧配置缺字段时均为 `direct`，避免未配置 cmhub 时破坏既有直连生成；只有用户在⑤显式切换并配置完整后才走 cmhub。
+- `backend`：内部字段，取值仍支持 `cmhub` / `direct`；普通产品默认 `cmhub`，⑤设置页不再展示「AI 后端」label 或 direct/cmhub 下拉，保存设置固定写 `cmhub`。`direct` 仅保留为内部兼容/手工回滚路径。
 - `cmhub`：cmhub 网关配置，`base_url` 为网关根地址，`title_alias` / `image_alias` 为 `GET /api/v1/models` 发现的能力别名，`connect_timeout` 为连接超时；API Key 不在此处保存。
-- `default_text_model` / `default_image_model`：direct 模式下引用 `ai_models.json` 里的模型名（标题用文本模型、封面用图像模型）；cmhub 模式不读取这些模型定义。
+- `default_text_model` / `default_image_model`：仅 direct 内部兼容模式下引用 `ai_models.json` 里的模型名（标题用文本模型、封面用图像模型）；普通 cmhub 模式不读取这些模型定义，⑤设置页不再展示标题/图片模型角色下拉。
 - `generate_cover`：②「开始生成」时是否调用图片模型生成新封面；默认 `false`，避免用户无意产生图片生成成本。该字段只控制 AI 生成阶段，不等同于 ③ 的 `allow_cover_update`。
 - `resolution`：当前分辨率，下拉 `512 / 1k / 2k / 4k`。
 - `resolution_timeouts`：分辨率 → **等待大模型返回超时(秒)** 的映射；用户选分辨率即自动套用，不单独填。
-- direct 模式模型本身的定义（url/key/类型/连接超时…）在 `config/ai_models.json`，见 5.1b。
-- 密钥不在 `config.json`：direct 模式每个模型的 `api_key` 存于 `config/ai_models.json`；cmhub 模式 API Key 存于 `config/cmhub.json`。两者均本地明文保存、保存/变更时弹窗提示、UI 打码、gitignore、不入日志/导出。
+- direct 内部兼容模式模型本身的定义（url/key/类型/连接超时…）在 `config/ai_models.json`，见 5.1b。
+- 密钥不在 `config.json`：cmhub API Key 存于 `config/cmhub.json`；direct 内部兼容模式每个模型的 `api_key` 存于 `config/ai_models.json`。两者均本地明文保存、保存/变更时弹窗提示、UI 打码、gitignore、不入日志/导出。
 
 `shopee_update` 段放**真实更新前的安全开关**：
 
@@ -158,7 +158,7 @@ imported  →  collected  →  generated  →  applied
 
 ### 5.1b AI 模型清单 `config/ai_models.json`
 
-模型定义清单（"有哪些模型"），与 `config.json` 的 `ai` 段（"选了哪个 + 全局参数"）职责分开。该文件只用于 `backend=direct`；`backend=cmhub` 时生文/生图使用 cmhub 别名，不读取此文件。
+模型定义清单（"有哪些模型"），与 `config.json` 的 `ai` 段（"选了哪个 + 全局参数"）职责分开。该文件只用于内部兼容 `backend=direct`；普通用户默认 `backend=cmhub`，生文/生图使用 cmhub 别名，不读取此文件。
 
 ```json
 {
@@ -195,7 +195,7 @@ imported  →  collected  →  generated  →  applied
 ```
 
 - 文件必须 gitignore，不提交；UI 展示打码。
-- `appconfig.load_cmhub_config()` 缺文件时返回空 Key，不自动启用 cmhub。
+- `appconfig.load_cmhub_config()` 缺文件时返回空 Key；普通产品默认 backend 仍为 cmhub，但未配置 Key/Base URL/别名时生成阶段会给出清晰配置错误，不静默回退 direct。
 - `backend=cmhub` 但 Base URL、API Key 或别名缺失时，`app/ai.py` 抛 `CMHubError(code="cmhub_not_configured")`，提示去⑤设置配置，不静默回退 direct。
 
 ### 5.2 SQLite `cmshopee.db`
@@ -395,8 +395,8 @@ images/<batch_id>/<slug>/<task_id>_<item_id>_new.<ext>    # AI 生成的新封
 
 单个「开始生成」按钮，标题必生成，封面按本轮成本开关可选生成：
 
-1. **并发生成标题**：线程池大小 = `title_concurrency`，调 `gen_title(标题提示词, old_title)` → new_title。`backend=direct` 时使用 `default_text_model`；`backend=cmhub` 时调用 `POST /api/v1/generate/title` 并使用 `title_alias`。
-2. **若②勾选「生成封面图片（成本较高）」**：接着并发生成图片，线程池大小 = `image_concurrency`，调 `gen_cover(封面提示词, old_cover_path, resolution, jpg_quality)` → 新图存 `images/<batch_id>/<slug>/<task_id>_<item_id>_new.jpg`。`backend=direct` 时使用 `default_image_model`；`backend=cmhub` 时调用 `POST /api/v1/generate/image`，拿 `image_url` 后立即安全下载并转本地 JPEG。
+1. **并发生成标题**：线程池大小 = `title_concurrency`，调 `gen_title(标题提示词, old_title)` → new_title。默认 `backend=cmhub`，调用 `POST /api/v1/generate/title` 并使用 `title_alias`；`backend=direct` 仅内部兼容时使用 `default_text_model`。
+2. **若②勾选「生成封面图片（成本较高）」**：接着并发生成图片，线程池大小 = `image_concurrency`，调 `gen_cover(封面提示词, old_cover_path, resolution, jpg_quality)` → 新图存 `images/<batch_id>/<slug>/<task_id>_<item_id>_new.jpg`。默认 `backend=cmhub`，调用 `POST /api/v1/generate/image`，拿 `image_url` 后立即安全下载并转本地 JPEG；`backend=direct` 仅内部兼容时使用 `default_image_model`。
    - 连接超时取该模型 `connect_timeout_seconds`；**返回超时取 `resolution_timeouts[resolution]`**（512→180/1k→240/2k→360/4k→600）。
 3. **若未勾选生成封面**：标题成功后立即写 `new_title`，`new_cover_path=NULL`，不渲染封面提示词、不调用 `gen_cover()`、不创建本地新封面文件。
 

docs/06-tasks.md

@@ -124,9 +124,10 @@
 
 | ID | 任务 | 依赖 | 验收要点 | 状态 |
 | --- | --- | --- | --- | --- |
-| T-526 | `app/ai.py` + `appconfig` 接入 cmhub backend | T-301, T-303, T-520 | 依据 `docs/cmhub-integration-design.md` v3.2。`config.json` 的 `ai` 段加 `backend`（`cmhub`/`direct`）+ `cmhub` 子段（`base_url`/`title_alias`/`image_alias`/`connect_timeout` 等）；为保护既有用户，全新配置默认 `backend=direct`、加载既有配置缺 `backend` 时也补 `direct`，`cmhub` 一律由用户在⑤显式 opt-in；`backend=cmhub` 但 `base_url`/Key 缺失时须抛清晰「请去⑤配置 cmhub」错误（`CMHubError`/`AIError`），不崩溃、不静默直连。cmhub API Key 固定存 `config/cmhub.json`（schema `{ "api_key": "..." }`），新增读写/打码 helper 并把该文件加入 `.gitignore`；日志脱敏。`gen_title`/`gen_cover` **返回值不变**，内层按 backend 分流并保留 `direct`；计费元数据不塞进返回值，允许给二者**新增一个可选事件回调参数**（如 `on_meta`/`on_event`）承载，属向后兼容加参，`generate_batch` 显式传回调不受影响。cmhub 分支：生文 `POST /api/v1/generate/title` 体 `{prompt,model:别名,resolution?}`、取 `titles[0]`、空则 `AIError`；生图 `POST /api/v1/generate/image` 体 `{prompt,model:别名,image_base64:<旧封面>,resolution,aspect_ratio:"1:1"}`、拿 `image_url` 后**立即下载**再走 `_save_jpeg`；`resolution` 归一大写 `512/1K/2K/4K`。新增 `CMHubError(AIError)`，带 `code/status/retryable/retry_after`，错误按 `code` 优先分支（`insufficient_points`/`unauthorized`/`account_disabled`/`bad_request`/`model_not_allowed`/`no_pricing_rule`/`content_blocked`/`upstream_error`/`rate_limited`，未知 code 当不可重试）；cmhub HTTP helper 需区分 connect/read timeout（优先用 `requests timeout=(connect, read)`），只对 502/429/连接超时重试，生图读超时绝不自动重发，读超时按分辨率封顶 600s。`points_cost`/`points_balance`/`call_id` 不改返回值，通过 `on_step`/事件回调上报；T-526 只保证 metadata 事件完整传出，T-528 再由 GUI worker 脱敏写 run_logs 和余额展示。`image_url` 下载必须限制 http/https、拒绝内网/回环地址、校验域名解析后的 IP 仍不是内网/回环/本机地址，并设置超时和大小上限。新增 `fetch_cmhub_models(base_url, api_key)` helper 调 `GET /api/v1/models` 返回别名清单（`alias/operation_type/requires_image/pricing_status/prices`）供 T-527 渲染下拉，错误脱敏。不碰 editor/cdp/chrome/accounts/excel/db，也不改 ①③④流程。`tests/test_ai.py` 加 cmhub mock（titles 列表、image_url 下载、安全下载、错误码与重试、读超时不重发、metadata 事件）、`tests/test_appconfig.py` 加 schema 和 key 文件 helper，direct 用例保持绿 | DONE |
+| T-526 | `app/ai.py` + `appconfig` 接入 cmhub backend | T-301, T-303, T-520 | 依据 `docs/cmhub-integration-design.md` v3.2。`config.json` 的 `ai` 段加 `backend`（`cmhub`/`direct`）+ `cmhub` 子段（`base_url`/`title_alias`/`image_alias`/`connect_timeout` 等）；T-526 实现时保留 `direct` 兼容路径；T-529 后普通产品默认 `backend=cmhub`，⑤不再暴露后端切换；`backend=cmhub` 但 `base_url`/Key 缺失时须抛清晰「请去⑤配置 cmhub」错误（`CMHubError`/`AIError`），不崩溃、不静默直连。cmhub API Key 固定存 `config/cmhub.json`（schema `{ "api_key": "..." }`），新增读写/打码 helper 并把该文件加入 `.gitignore`；日志脱敏。`gen_title`/`gen_cover` **返回值不变**，内层按 backend 分流并保留 `direct`；计费元数据不塞进返回值，允许给二者**新增一个可选事件回调参数**（如 `on_meta`/`on_event`）承载，属向后兼容加参，`generate_batch` 显式传回调不受影响。cmhub 分支：生文 `POST /api/v1/generate/title` 体 `{prompt,model:别名,resolution?}`、取 `titles[0]`、空则 `AIError`；生图 `POST /api/v1/generate/image` 体 `{prompt,model:别名,image_base64:<旧封面>,resolution,aspect_ratio:"1:1"}`、拿 `image_url` 后**立即下载**再走 `_save_jpeg`；`resolution` 归一大写 `512/1K/2K/4K`。新增 `CMHubError(AIError)`，带 `code/status/retryable/retry_after`，错误按 `code` 优先分支（`insufficient_points`/`unauthorized`/`account_disabled`/`bad_request`/`model_not_allowed`/`no_pricing_rule`/`content_blocked`/`upstream_error`/`rate_limited`，未知 code 当不可重试）；cmhub HTTP helper 需区分 connect/read timeout（优先用 `requests timeout=(connect, read)`），只对 502/429/连接超时重试，生图读超时绝不自动重发，读超时按分辨率封顶 600s。`points_cost`/`points_balance`/`call_id` 不改返回值，通过 `on_step`/事件回调上报；T-526 只保证 metadata 事件完整传出，T-528 再由 GUI worker 脱敏写 run_logs 和余额展示。`image_url` 下载必须限制 http/https、拒绝内网/回环地址、校验域名解析后的 IP 仍不是内网/回环/本机地址，并设置超时和大小上限。新增 `fetch_cmhub_models(base_url, api_key)` helper 调 `GET /api/v1/models` 返回别名清单（`alias/operation_type/requires_image/pricing_status/prices`）供 T-527 渲染下拉，错误脱敏。不碰 editor/cdp/chrome/accounts/excel/db，也不改 ①③④流程。`tests/test_ai.py` 加 cmhub mock（titles 列表、image_url 下载、安全下载、错误码与重试、读超时不重发、metadata 事件）、`tests/test_appconfig.py` 加 schema 和 key 文件 helper，direct 用例保持绿 | DONE |
 | T-527 | ⑤设置 cmhub 网关面板 | T-526, T-517 | 依据 `docs/cmhub-integration-design.md` v3.2。⑤ AI 设置按 `backend` 切换：cmhub 模式显示「网关 Base URL + API Key（打码，提示从网页端复制、仅显示一次）+ 生文别名 + 生图别名 + 测试连接/查余额」；**别名从 `GET /api/v1/models`（T-526 的 `fetch_cmhub_models`）动态拉取渲染下拉**，按 `operation_type` 分生文/生图，过滤 `pricing_status="unpriced"` 的别名，可展示单价与 `requires_image` 提示，选中值持久化到 `ai.cmhub.title_alias/image_alias`（网关临时不可达时回退已存值）；不写死别名。direct 模式保留现有 AI 模型 master-detail。保存写 `config.json` 的 `ai` 段与 `config/cmhub.json`；切换 backend 时不删除 legacy `config/ai_models.json`。测试连接/查余额经后台 worker 调 cmhub（复用 `AIModelTestWorker` 思路或新增 worker），错误必须脱敏并给用户可读提示。同步 GUI 设置测试；不改 Shopee/CDP 流程 | DONE |
 | T-528 | ② 计费错误提示 + 余额展示 | T-526, T-527, T-303 | 依据 `docs/cmhub-integration-design.md` v3.2。② AI生成页把 cmhub 计费失败态显式化：通过 `CMHubError.code` 识别 `insufficient_points`，弹明确提示「点数不足，请先充值」并引导去网页端充值，本轮未开始任务可提前中止，不靠中文字符串匹配、不淹没在失败计数里；用 T-526 成功响应事件里的 `points_balance` 刷新②页剩余点数显示，`/balance` 仅作手动刷新/可选批量前预检；`points_cost`/`call_id` 记入脱敏 run_logs。只改② UI、`GenerateWorker` 事件处理/文案及 GUI 单测；不改 AI HTTP 协议、DB schema、Excel、Shopee/CDP 流程 | DONE |
+| T-529 | 默认 cmhub 网关并隐藏 AI 后端选择 | T-528, T-527 | 产品收口：后续普通用户只使用 cmhub 网关，不再在⑤设置页暴露「AI 后端」label 与 direct/cmhub 下拉框。方案：`DEFAULT_CONFIG.ai.backend` 改为 `cmhub`；⑤设置页默认直接展示 cmhub 网关配置（Base URL、API Key、生文/生图别名、刷新别名、测试连接/查余额），隐藏 direct 模型选择、模型详情、标题/图片模型角色下拉和「AI 后端」下拉；保存设置固定写 `ai.backend=cmhub`，允许先保存不完整 cmhub 配置，②生成时仍由 `app/ai.py` 对缺 Base URL/Key/别名给出「请去⑤配置 cmhub」错误。direct 代码、`config/ai_models.json` helper 与 direct 单测保留为内部兼容/手工回滚路径，但普通 UI 不提供切换入口。同步 `appconfig`、⑤设置页、②余额默认显示和 GUI/appconfig 单测；不改 AI HTTP 协议、DB schema、Excel、Shopee/CDP 流程 | DONE |
 
 ## Phase 8 · 工程基础设施后续（`docs/engineering-review.md`）
 

docs/api.md

@@ -29,13 +29,13 @@ cdp_ready_timeout(config=None) -> int
 ai_config(config=None) -> dict                # default_text_model/default_image_model/
                                              # title_concurrency/image_concurrency/retry/jpg_quality/
                                              # resolution/resolution_timeouts
-ai_backend(config=None) -> str                # direct / cmhub
+ai_backend(config=None) -> str                # 默认 cmhub；direct 仅内部兼容/手工回滚
 cmhub_config(config=None) -> dict             # base_url/title_alias/image_alias/connect_timeout
 cmhub_request_url(base_url, endpoint) -> str
 response_timeout(config=None) -> int           # = resolution_timeouts[resolution]（返回超时，随分辨率）
 ```
 
-`default_config()` / `load_config()` 包含 `shopee_update` 安全配置段：历史/调试兼容测试商品 ID、是否允许真实提交、是否允许更新封面、每批最大更新条数、成功后是否关闭本轮新开编辑页、内部兼容 `dry_run`、多账号并行、最大并行账号数。普通正式更新不再用测试商品 ID 阻断当前筛选结果。`config.json` 不保存 AI Key；写入 `api_key` / `*_key` / `token` / `*_token` / `password` / `*_password` 等敏感字段时抛 `ConfigError`。AI Key 留给 `config/ai_models.json`（direct）或 `config/cmhub.json`（cmhub）。
+`default_config()` / `load_config()` 包含 `shopee_update` 安全配置段：历史/调试兼容测试商品 ID、是否允许真实提交、是否允许更新封面、每批最大更新条数、成功后是否关闭本轮新开编辑页、内部兼容 `dry_run`、多账号并行、最大并行账号数。普通正式更新不再用测试商品 ID 阻断当前筛选结果。`config.json` 不保存 AI Key；写入 `api_key` / `*_key` / `token` / `*_token` / `password` / `*_password` 等敏感字段时抛 `ConfigError`。普通产品默认 cmhub，AI Key 存 `config/cmhub.json`；`config/ai_models.json` 仅为 direct 内部兼容路径。
 
 敏感信息展示/日志辅助：
 
@@ -50,12 +50,12 @@ cmhub Key 文件（`config/cmhub.json`，含本地明文密钥，T-526 已建；
 
 ```python
 default_cmhub_config() -> dict
-load_cmhub_config(path="config/cmhub.json") -> dict     # 缺文件返回空 key，不自动启用 cmhub
+load_cmhub_config(path="config/cmhub.json") -> dict     # 缺文件返回空 key；默认 cmhub 但生成时会提示补配置
 save_cmhub_config(config, path="config/cmhub.json") -> dict
 get_cmhub_api_key(path="config/cmhub.json", masked=False) -> str
 ```
 
-`config.json` 只保存 `ai.backend`、`ai.cmhub.base_url/title_alias/image_alias/connect_timeout` 等非密钥配置；`config/cmhub.json` 必须 gitignore，展示时打码，不写日志/导出。
+`config.json` 只保存 `ai.backend`、`ai.cmhub.base_url/title_alias/image_alias/connect_timeout` 等非密钥配置；T-529 后普通设置页固定保存 `ai.backend=cmhub`，不暴露后端切换；`config/cmhub.json` 必须 gitignore，展示时打码，不写日志/导出。
 AI 模型清单（`config/ai_models.json`，含本地明文密钥，已建；UI 由 ⑤ 设置复用）：
 
 ```python
@@ -303,9 +303,9 @@ fetch_cmhub_models(base_url, api_key, connect_timeout=10, read_timeout=30) -> li
 
 要点：
 
-- `backend=direct`：标题用 `default_text_model`、封面用 `default_image_model`（`appconfig.get_model` 取定义，含 url/key/api_type）。
-- `backend=cmhub`：标题调用 `POST /api/v1/generate/title`，封面调用 `POST /api/v1/generate/image`，模型字段使用 `ai.cmhub.title_alias/image_alias`，Key 来自 `config/cmhub.json`。
-- `fetch_cmhub_models()` 调 `GET /api/v1/models` 返回别名清单，供 T-527 设置页动态下拉使用。
+- `backend=direct`：内部兼容/手工回滚路径；标题用 `default_text_model`、封面用 `default_image_model`（`appconfig.get_model` 取定义，含 url/key/api_type）。
+- `backend=cmhub`：普通产品默认路径；标题调用 `POST /api/v1/generate/title`，封面调用 `POST /api/v1/generate/image`，模型字段使用 `ai.cmhub.title_alias/image_alias`，Key 来自 `config/cmhub.json`。
+- `fetch_cmhub_models()` 调 `GET /api/v1/models` 返回别名清单，供⑤设置页动态下拉使用。
 - `api_type=chat/auto` 走 OpenAI-compatible chat JSON；`api_type=images_edits` 走 multipart form。
 - direct 连接超时参考模型 `connect_timeout_seconds`；**返回超时 = 模型 `timeout_seconds` 或 `appconfig.response_timeout()`（随分辨率：512/1k/2k/4k → 180/240/360/600）**。cmhub 使用 `requests timeout=(connect, read)`，connect 来自 `ai.cmhub.connect_timeout`，read 随分辨率且封顶 600s。
 - 并发数/重试/分辨率/jpg 质量来自 `appconfig.ai_config()`；Key 本地明文存储，但不入日志、不导出。cmhub 响应的 `points_cost/points_balance/call_id` 不改变返回值，通过 `on_event` metadata 事件上报，GUI 余额/计费展示留给 T-528。

docs/cmhub-integration-design.md

@@ -6,8 +6,9 @@
 >
 > **v2 修订（2026-07-04，吸收对接文档）**：修正生图重试策略（非幂等，读超时不重发，避免重复扣点）；超时按分辨率细化到 600s 上限；余额直接用响应 `points_balance`；错误处理改为按 `code` 优先分支 + 未知 code 当不可重试，补 `content_blocked`；确认 `resolution`=`512/1K/2K/4K`（大写）、`aspect_ratio` 默认 `1:1`。
 > **v3 修订（2026-07-04，工程评审修正）**：补充既有配置迁移策略（缺 `backend` 先按 `direct` 处理，避免未配置 cmhub 时破坏现有生成）；固定 cmhub Key 文件为 `config/cmhub.json`；新增 `CMHubError` 结构化错误要求；明确 `points_balance/points_cost/call_id` 通过回调事件传播而不是改变 `gen_title`/`gen_cover` 返回值；要求 cmhub 分支用可区分 connect/read timeout 的 HTTP 调用；把 `image_url` 下载安全校验纳入 T-526 验收；T-525 顺延，Phase 7 成为当前业务优先任务。
-> **v3.1 修订（2026-07-04，实现前澄清）**：① 全新配置默认 backend 统一为 `direct`（cmhub 显式 opt-in），且 `backend=cmhub` 但未配置时须抛清晰"去⑤配置"错误而非崩溃（见 §4.1）；② 明确"返回值不变"≠"回调不变"——计费元数据须给 `gen_title`/`gen_cover` **新增可选事件回调参数**承载，是向后兼容加参（见 §4.2）。两点已同步 T-526 验收。
-> **v3.2 修订（2026-07-04，同步对接文档新增）**：cmhub 新增第 4 个接口 `GET /api/v1/models`（别名自助发现，见 §4.6），⑤设置别名由手填改为**动态下拉**（按 `operation_type` 分生文/生图、过滤 `unpriced`、展示单价、`requires_image` 提示），关闭原待确认 #1；仅 Base URL 仍待部署方提供。已同步 T-526（加 `fetch_cmhub_models` helper）与 T-527（别名下拉）。
+> **v3.1 修订（2026-07-04，实现前澄清）**：当时为保护既有直连流程，要求全新配置默认 backend 为 `direct`（cmhub 显式 opt-in），且 `backend=cmhub` 但未配置时须抛清晰"去⑤配置"错误而非崩溃（见 §4.1）；② 明确"返回值不变"≠"回调不变"——计费元数据须给 `gen_title`/`gen_cover` **新增可选事件回调参数**承载，是向后兼容加参（见 §4.2）。默认策略已被 v3.3/T-529 覆盖为普通产品默认 cmhub。
+> **v3.2 修订（2026-07-04，同步对接文档新增）**：cmhub 新增第 4 个接口 `GET /api/v1/models`（别名自助发现，见 §4.6），⑤设置别名由手填改为**动态下拉**（按 `operation_type` 分生文/生图、过滤 `unpriced`、展示单价、`requires_image` 提示），关闭原待确认 #1；仅 Base URL 仍待部署方提供。
+> **v3.3 修订（2026-07-04，产品收口）**：普通用户后续默认使用 `cmhub` 网关；⑤设置页去掉「AI 后端」label 和 direct/cmhub 下拉，直接展示 cmhub 网关配置。`direct` 代码和 `config/ai_models.json` 保留为内部兼容/手工回滚路径，但普通 UI 不提供切换入口；保存设置固定写 `ai.backend=cmhub`，允许先保存不完整 cmhub 配置，②生成时再提示去⑤补齐 Base URL/API Key/别名。已同步 T-529。
 
 ## 1. 背景与目标
 
@@ -39,7 +40,7 @@
 
 - **接缝最小化**：保持 `gen_title(...)` / `gen_cover(...)` 的**返回值与现有调用兼容**（`gen_title`→标题字符串、`gen_cover`→已存 JPEG 路径），允许向后兼容新增可选事件回调参数承载计费元数据，只改内层实现。这样 `generate_batch` 编排、并发、重试、DB 写入、诊断日志、JPEG 落盘、`images/<batch_id>/<slug>/...` 路径、T-520 封面开关**全部复用、零改动**；GUI `run_logs` 记录和余额展示放到 T-528。
 - **不碰高风险层**：`editor.py`/`cdp.py`/`chrome.py`/`accounts.py`/`excel.py`/`db.py`/`workers.py`，以及 ①采集/③更新/④账号全流程**完全不动**。这是本改动最重要的安全边界。
-- **适配器而非硬替换**：内层抽 `backend`（`cmhub` / `direct`），由配置选择。为保护既有用户，旧 `config.json` 缺 `ai.backend` 时先按 `direct` 迁移；用户在⑤设置明确切到 `cmhub` 并填好 Base URL / Key / 别名后才走网关。老 `ai_models.json` 不作废、测试易写、可灰度。
+- **产品默认 cmhub，direct 保留兼容**：内层仍抽 `backend`（`cmhub` / `direct`），但普通产品默认走 `cmhub`，⑤设置页不再展示后端切换。老 `ai_models.json` 和 direct 分支不删除，作为内部兼容/手工回滚路径；普通用户只配置 cmhub Base URL / Key / 别名。
 
 ## 4. 方案
 
@@ -49,7 +50,7 @@
 
 ```jsonc
 "ai": {
-  "backend": "direct",                // "cmhub" | "direct"；全新配置默认 direct，cmhub 为显式 opt-in
+  "backend": "cmhub",                // 普通产品默认 cmhub；direct 仅内部兼容/手工回滚
   "cmhub": {
     "base_url": "https://<cmhub>",    // 网关根地址，请求时拼 /api/v1/...
     "title_alias": "title-standard",  // 生文能力别名
@@ -64,10 +65,7 @@
 
 - **cmhub API Key 不进 `config.json`**（避免与其它设置混放、避免误提交）。固定存到 `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；`config/cmhub.json` 必须加入 `.gitignore`。沿用现有"本地明文保存但 gitignore + UI 打码 + 日志脱敏"纪律（T-503）。
 - **`ai_models.json` 去留**：`direct` 模式继续用；`cmhub` 模式不读它。文件保留但标记 legacy。
-- **默认 backend 的两条路径要分清（避免首启破坏）**：`appconfig` 里两条路径都必须落到"不破坏开箱"这一条统一规则——`backend` 默认 `direct`：
-  - **加载既有 `config.json`** 缺 `ai.backend` 时，补 `direct`（保护老用户，其 `ai_models.json` 仍有效）。
-  - **`DEFAULT_CONFIG` / `default_config()` 造全新配置** 同样写 `direct`，不写 `cmhub`——否则全新安装 `base_url`/Key 为空时首次生成直接报错。`cmhub` 一律由用户在 ⑤ 设置显式切换并填好 Base URL / Key / 别名后才生效。
-  - 兜底：即使 `backend=cmhub` 但 `base_url`/Key 缺失，也必须抛**清晰的"请去⑤配置 cmhub"错误**（`CMHubError`/`AIError`），不得崩溃或静默直连。
+- **默认 backend 与配置不完整处理（T-529 后）**：`DEFAULT_CONFIG` / `default_config()` 造全新配置时写 `backend=cmhub`；⑤设置页隐藏 direct/cmhub 下拉并固定保存 `backend=cmhub`。允许先保存不完整 cmhub 配置，便于用户先保存其它路径/安全设置；②生成真正调用时如果 `base_url`/Key/别名缺失，必须抛**清晰的"请去⑤配置 cmhub"错误**（`CMHubError`/`AIError`），不得崩溃或静默回退 direct。显式手工配置 `backend=direct` 仍作为内部回滚路径保留，但普通 UI 不提供入口。
 
 ### 4.2 `gen_title` 改造（cmhub 分支）
 
@@ -156,7 +154,7 @@ cmhub 返回结构化 `{error:{code}}`。映射层**按 `code` 优先分支**（
   - 生文：`titles` 多条取首条；空 `titles`/空串 → `AIError`。
   - 生图：`image_url` → mock 下载字节 → `_save_jpeg` 落盘校验分辨率/质量；覆盖 scheme、内网/回环字符串地址、域名解析到内网 IP 的拒绝路径。
   - 错误码矩阵：402/401/403/400 不重试且原因正确；502/429/连接超时按 attempts 重试；生图读超时不重发；未知 code 不重试。
-  - 配置：`backend=cmhub` 走 cmhub 分支、`direct` 走旧分支；旧配置缺 `backend` 时保持 direct；缺 `base_url`/Key 时明确报错。
+  - 配置：`backend=cmhub` 走 cmhub 分支、显式 `direct` 走旧分支；T-529 后缺 `backend` 的配置按 `DEFAULT_CONFIG` 补为 cmhub；缺 `base_url`/Key/别名时明确报错。
 - **GUI**：⑤ cmhub 面板读写、测试连接 worker、别名下拉；② 生成在 `insufficient_points` 时的提示路径。
 - **回归**：`direct` 模式现有 `test_ai.py` 用例保持绿。
 - 验证命令沿用 `python -m unittest discover -s tests`。
@@ -182,6 +180,7 @@ cmhub 返回结构化 `{error:{code}}`。映射层**按 `code` 优先分支**（
 - **第一步**：`app/ai.py` + `app/appconfig.py` 接入 cmhub backend（mock 联调），保留 direct。
 - **第二步**：⑤设置 UI cmhub 面板 + 测试连接/查余额。
 - **第三步**：② 计费错误提示（`insufficient_points` 引导充值）+ 可选余额展示。
+- **第四步（T-529）**：产品默认 cmhub，⑤去掉 AI 后端选择，保存固定 `backend=cmhub`。
 - 文档随每步同步。
 
 > 当前已在 `docs/06-tasks.md` 落成 T-526~T-528；下一步按 T-526 开始代码实现，仍遵守 `docs/05-coding-rules.md` 验证清单。

docs/routes.md

@@ -14,7 +14,7 @@
 | ② AI生成 | 左侧标题/封面**提示词**；右侧按批次/店铺/商品ID/状态筛选任务列表；AI 生成新标题，并按本轮开关可选生成新封面；已生成任务可本地微调新标题；双击看新旧封面 | 不触线上，中 |
 | ③ 更新shopee | 对**已生成**任务点击「开始更新」后弹窗确认；确认后打开编辑页换标题+封面并逐条点「更新」提交；结果回写 Excel | **写线上，高** |
 | ④ 账号管理 | Shopee 账号（账号名/别名/数据目录/端口/密码本地明文仅参考/登录状态）；启动登录、检测登录、生成快捷方式；检测登录遇到 `accounts.shopee.tw/seller/login` 必须显示未登录 | 中 |
-| ⑤ 设置 | AI 模型/API Key、本地图片目录、Chrome 路径、默认端口、Shopee 更新安全开关等 | — |
+| ⑤ 设置 | cmhub 网关/API Key、生文/生图别名、生成参数、本地图片目录、Chrome 路径、默认端口、Shopee 更新安全开关等 | — |
 
 任务的**阶段状态**贯穿各 Tab：`imported → collected → generated → applied`（或 `failed/skipped`）。② 不设逐条人工确认阶段；③ 无常驻提交开关，但点击「开始更新」后必须先通过 ⑤ 的 Shopee 更新安全开关，再弹窗确认当前筛选范围和任务数量。各 Tab 聚焦各自阶段的列与按钮，但操作同一批任务（同一 batch）。
 
@@ -87,7 +87,7 @@
 - 右上：按导入批次 / 店铺 / 商品ID / 状态筛选任务；商品ID输入框按包含匹配 `item_id`，清空表示全部。
 - 右下：任务列表（店铺名、商品id、旧标题、新标题、状态）+ AI生成运行日志；已生成、未提交线上、非运行中的任务可双击「新标题」列本地微调，写回 `tasks.new_title`，清空 `last_error` 并回到可更新；双击其他列弹窗展示旧封面 | 新封面（纯查看）。
 - 底部**单个「开始生成」+「停止」**，并增加「生成封面图片（成本较高）」复选框：默认不勾选，只生成标题；勾选后才在标题完成后按 `image_concurrency` 并发生成封面。该开关状态持久化到 `config.json` 的 `ai.generate_cover`，但入口放在②，便于用户在每轮生成前做成本判断。
-- 生成参数（标题/图片并发数、失败重试、分辨率、jpg 质量、模型/Key）在 **⑤ 设置**；②只暴露“本轮是否生成封面”的成本开关。
+- 生成参数（标题/图片并发数、失败重试、分辨率、jpg 质量、cmhub 网关/Key/别名）在 **⑤ 设置**；②只暴露“本轮是否生成封面”的成本开关。
 - 标题-only 模式标题成功即写库并进入 `generated`，`new_cover_path` 留空；标题+封面模式图片成功后写入本地新封面路径。两种模式都写 `run_type=generate` 的 `run_logs/run_log_events` 和用户可读滚动日志；未勾选生成封面时日志明确显示“本轮仅生成标题”。点击「开始生成」时先清空②界面可见日志并写入本轮开始摘要，运行中只追加本轮日志；不删除历史 `run_logs/run_log_events` 或本地 `logs/`。进入页面默认可显示“本轮日志会在开始运行后显示”，历史日志不自动混入当前运行界面。「停止」取消未开始项，可再次「开始生成」对剩余继续。
 - 「重置生成结果」仅作用当前选中单条，运行中禁用；确认后只改本地 DB，清空 `new_title/new_cover_path/last_error` 并退回 `collected/success` 供重新生成，默认不删除本地新封面文件。若该记录已提交过线上，必须在确认框提示本地重置不回滚 Shopee。
 - **无逐条人工审核环节**；新标题默认直接用 AI 输出，但允许对已生成且未提交线上的单行做本地微调；可选对单行 `重生成`。生成完即可进入 ③，③ 开始更新前会做批量确认。
@@ -143,15 +143,14 @@
 ## ⑤ 设置
 
 - 设置页整体布局：内容区居中，左右留白已从 T-506 初始实现缩短到约 40%；实现上用最大内容宽度 + 自适应 margin，而不是写死窗口像素。所有设置组默认响应式 3 列表单：短字段占 1 格，URL/API Key/路径等长字段跨 2 格或 3 格；窄窗口自动降为 2 列/1 列。点击「保存设置」成功后，状态栏显示“设置已保存”，并弹出轻量提示框。
-- AI 模型管理（T-501 已接入，待布局优化）：模型详情组件组改为 3 个组件一组；启用/类别/api_type/连接超时等短字段一格，服务商名/模型 ID 可一格或两格，URL 与 API Key 跨整行；AI 模型下拉 + 新增/删除仍在“模型详情”上方。
-  - 字段：启用、服务商名、类别（文本/图像）、api_type、模型ID、网址、密钥、连接超时。网址可填完整 endpoint，也可填 OpenAI-compatible base URL（如 `https://.../v1`），请求时按 `api_type` 自动补齐。
-  - 密钥存在 `config/ai_models.json`，本地明文保存；保存/变更时提示；UI 使用密码框打码显示，不进入日志/导出。
-  - 保存复用 `appconfig` 模型清单后端，保持 name 唯一、至少 text/image 各一个模型。
-  - 「测试连接」通过后台 worker 调 `appconfig.test_ai_model()`，不阻塞主线程。
-- AI 生成参数（T-501b 已接入，待布局优化）：角色与生成参数改为 3 个组件一组；标题模型、图片模型、分辨率、标题并发、图片并发、失败重试、jpg 质量等短字段按三列排列。
-  - 标题模型下拉只列 text 类模型；图片模型下拉只列 image 类模型。
+- cmhub 网关配置（T-529 后普通用户唯一 AI 入口）：⑤设置页不再显示「AI 后端」label 或 direct/cmhub 下拉，直接展示 cmhub 网关 Base URL、API Key、生文别名、生图别名、连接超时、刷新别名、测试连接/查余额。
+  - API Key 存在 `config/cmhub.json`，本地明文保存；保存/变更时提示；UI 使用密码框打码显示，不进入日志/导出。
+  - 生文/生图别名来自 `GET /api/v1/models` 动态下拉，过滤未定价别名并展示单价/需原图提示；网关临时不可达时保留已存别名。
+  - 保存设置固定写 `ai.backend=cmhub`。允许先保存不完整 cmhub 配置，②真正生成时如果缺 Base URL/API Key/别名，会提示去⑤补配置，不静默回退 direct。
+  - direct 模型清单和 `config/ai_models.json` 代码路径保留为内部兼容/手工回滚，不在普通 UI 暴露。
+- AI 生成参数：标题并发、图片并发、失败重试、分辨率、返回超时、jpg 质量等短字段按三列排列。
   - 分辨率为 `512 / 1k / 2k / 4k`；返回超时只读展示 `resolution_timeouts[resolution]`，不单独编辑。
-  - 保存写入 `config.json` 的 `ai` 段，供 ② AI生成复用。
+  - 保存写入 `config.json` 的 `ai` 段，供 ② AI生成复用；标题/图片模型角色下拉随 direct UI 一起隐藏。
 - 路径与端口（T-501b/T-506 已接入）：组件组改为 3 个组件一组；默认端口、端口起止、CDP 就绪超时等短字段三列排列；Chrome 路径、账号数据根目录、图片目录、DB 路径等长字段跨整行或跨 2/3 列。
 - Shopee 更新安全（T-501c/T-506 已接入）：组件组改为 3 个组件一组；允许真实提交、允许更新封面、每批最大更新条数、成功后关闭本次新开编辑页等短字段三列排列；「多账号并行更新」与「最大并行账号数」必须合并为同一个横向组件，最大并行账号数紧跟在多账号并行更新后面，不允许换到下一行；测试商品 ID 仅作为历史/调试兼容字段保留，不参与普通正式更新安全检查，普通设置页已隐藏该入口。
   - 默认关闭真实提交和封面更新，每批最大更新条数默认 1。