docs: diagnose cmhub 刷新别名 notfound and add T-530

- troubleshooting.md: 新增「⑤ cmhub 刷新别名/测试连接 notfound(404)」排障节，确认请求达标，给 curl 隔离法（models vs balance）
- cmhub-integration-design.md: §4.1 补 Base URL 必须为网关根约束 + v3.4 核对记录
- 06-tasks.md: 新增 T-530（Base URL 规整 + 404 明确提示）

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/troubleshooting.md

@@ -134,6 +134,36 @@ https://api.vectorengine.ai/v1/chat/completions
 ```powershell
 python -c "import json; from urllib.parse import urlsplit,urlunsplit; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); [print({'name':m.get('name'),'category':m.get('category'),'api_type':m.get('api_type'),'url_without_query':urlunsplit((urlsplit(m.get('url','')).scheme,urlsplit(m.get('url','')).netloc,urlsplit(m.get('url','')).path,'','')),'has_api_key':bool(m.get('api_key'))}) for m in data.get('models', [])]"
 ```
+## ⑤ cmhub「刷新别名 / 测试连接」提示 notfound / 404
+
+### 现象
+
+在⑤设置切到 cmhub 后端，手动填入 Base URL、API Key，点「刷新别名」或「测试连接」，提示 `notfound`（即 HTTP 404）。
+
+### 原因
+
+先明确：**cmshopee 的请求本身是达标的**——`GET {Base URL}/api/v1/models`，头 `Authorization: Bearer <key>`，与对接文档《cmhub-接口对接文档-桌面端生文生图》§4.4 和 cmhub 服务端路由 `path("v1/models", ModelsView)` 完全一致。404 表示服务端已响应但该路径不存在，原因在请求之外，通常是两类：
+
+1. **Base URL 填了多余路径（手动填入最常见）**：Base URL 只能填**网关根**，例如 `https://cmhub.example.com`。当前 `appconfig.cmhub_request_url()` 是 `base_url.rstrip("/") + "/api/v1/models"`，**不会**替你去掉结尾的 `/api` 或 `/api/v1`；若你填成 `https://host/api/v1`，会拼成 `.../api/v1/api/v1/models` → 404。
+2. **连的那台 cmhub 实例没有该路由**：`ModelsView` 在 cmhub 仓库代码里有，但**运行中的实例**若未重新部署/重启，`/api/v1/models`（较新接口）会 404，而 `/api/v1/balance`（较老接口）可能正常。
+
+### 隔离方法（一条 curl 定位）
+
+```bash
+curl -i "https://<你的BaseURL>/api/v1/models"  -H "Authorization: Bearer sk_cmhub_xxx"
+curl -i "https://<你的BaseURL>/api/v1/balance" -H "Authorization: Bearer sk_cmhub_xxx"
+```
+
+- 两个都 404 → **Base URL 填错**，改成网关根（不带 `/api`、`/api/v1`）。
+- balance 通、models 404 → **cmhub 实例未更新**，让部署方重启/重部署带上 `ModelsView`。
+- models 通 → cmshopee 侧别的问题，回代码排查。
+
+> 不要把 API Key 贴进日志、文档或聊天；curl 里的 `sk_cmhub_xxx` 是占位。
+
+### 待改进（T-530）
+
+`cmhub_request_url()` 目前不规整带 `/api`/`/api/v1` 的 Base URL，且 404 落到 `unknown` 后透传生涩英文原文。跟进任务 T-530 将：保存/请求前规整 Base URL 去掉多余 `/api(/v1)` 尾部；给 404 一个明确中文提示（“cmhub 接口不存在，检查 Base URL 或该实例是否已部署 /api/v1/models”）。
+
 ## AI生成：标题成功但图片生成失败，且看不到原因
 
 当前代码会为 ② AI生成写两层日志：
@@ -141,4 +171,4 @@ python -c "import json; from urllib.parse import urlsplit,urlunsplit; p='config/
 - 页面右下「AI生成运行日志」显示最近一次 `run_type=generate` 的逐条事件，例如 `phase=cover step=cover_request result=failed detail=...`。
 - 本地 `logs/cmshopee.log` 保存脱敏后的 traceback、任务 id、alias、item_id、phase 和 step，用于判断卡在模型配置、封面请求、图片解析、保存文件还是写库。
 
-排查顺序：先看 ② 页面运行日志里的 `phase` / `step` / `detail`；如果只看到简短错误，再查看本地 `logs/cmshopee.log`。不要把 `config/ai_models.json` 或 API Key 发到聊天、文档或提交里。
+排查顺序：先看 ② 页面运行日志里的 `phase` / `step` / `detail`；如果只看到简短错误，再查看本地 `logs/cmshopee.log`。不要把 `config/ai_models.json` 或 API Key 发到聊天、文档或提交里。