docs: 记录AI模型category启动报错排查

- 新增 troubleshooting 文档，说明 category 缺失导致启动失败的原因

- 补充安全修复步骤，避免泄露或提交 config/ai_models.json 中的 API Key

- 更新文档导航、技术栈、当前状态和进度记录

docs/troubleshooting.md

@@ -0,0 +1,94 @@
+# 常见问题排查
+
+> 本文只记录可复用的本地排障步骤。涉及 `config.json`、`config/ai_models.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/` 时，默认它们是本机敏感或业务数据，必须保持 gitignore，不把真实密码、API Key、Cookie、token 写入文档、日志或提交。
+
+## 启动时报 “AI 模型 category 必须是 text 或 image”
+
+### 现象
+
+运行 `python main.py` / `python -m app` 启动 GUI 时，弹出或输出：
+
+```text
+AI 模型 category 必须是 text 或 image
+```
+
+### 原因
+
+`config/ai_models.json` 是本地 AI 模型清单，里面每个模型都必须有合法的 `category`：
+
+- `text`：标题生成模型，会出现在“标题大模型”下拉。
+- `image`：封面生成模型，会出现在“图片大模型”下拉。
+
+早期或手工维护过的 `config/ai_models.json` 可能缺少 `category`，或者填了中文、空值、旧字段，导致 `appconfig.load_ai_models_config()` 严格校验失败，GUI 启动被阻断。
+
+### 不要这样做
+
+- 不要删除 `config/ai_models.json` 来“重置”，否则会丢失本地明文 API Key 和模型配置。
+- 不要把 `config/ai_models.json` 提交到 git。
+- 不要把完整文件内容贴到聊天、文档或日志里；该文件含本地明文 API Key。
+
+### 推荐修复
+
+先只查看非敏感字段，确认哪些模型缺少 `category`：
+
+```powershell
+python -c "import json; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); [print({'index': i+1, 'name': m.get('name'), 'category': m.get('category'), 'api_type': m.get('api_type'), 'enabled': m.get('enabled'), 'has_api_key': bool(m.get('api_key'))}) for i,m in enumerate(data.get('models', []))]"
+```
+
+然后手工编辑 `config/ai_models.json`，只补这些字段：
+
+```json
+{
+  "name": "示例文本模型",
+  "category": "text",
+  "enabled": true
+}
+```
+
+```json
+{
+  "name": "示例图片模型",
+  "category": "image",
+  "enabled": true
+}
+```
+
+如果要用脚本批量修复，只按模型名或 `api_type` 推断 `category`，并保留原有 `url`、`model`、`api_key`、`extra_body` 等字段。示例：
+
+```powershell
+python -c "import json; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); mapping={'你的文本模型名':'text','你的图片模型名':'image'}; changed=False
+for m in data.get('models', []):
+    name=m.get('name')
+    if not m.get('category') and name in mapping:
+        m['category']=mapping[name]; changed=True
+    if m.get('enabled') is None:
+        m['enabled']=True; changed=True
+open(p,'w',encoding='utf-8').write(json.dumps(data,ensure_ascii=False,indent=2)+'\n')
+print('updated' if changed else 'unchanged')"
+```
+
+### 验证
+
+验证时只输出模型名、类别、是否启用、是否存在 Key，不输出 Key 本身：
+
+```powershell
+python -c "import os,sys; sys.path.insert(0, os.getcwd()); from app import appconfig; print([(m['name'], m['category'], m['enabled'], m['api_key_set']) for m in appconfig.list_ai_models()])"
+```
+
+确认 `config/ai_models.json` 仍被忽略：
+
+```powershell
+git status --short --ignored config/ai_models.json
+```
+
+正常输出应包含：
+
+```text
+!! config/ai_models.json
+```
+
+最后重新启动：
+
+```powershell
+python main.py
+```