feat: add diagnostic logs for generation flows

2026-06-29 17:49:45 +08:00
parent 588b352eac
commit cd1256bc5e
17 changed files with 1455 additions and 104 deletions
@@ -92,3 +92,53 @@ git status --short --ignored config/ai_models.json
 ```powershell
 python main.py
 ```
+
+## ⑤ 设置里测试连接提示 “HTTP 404”
+
+### 现象
+
+在⑤设置里填写文本大模型信息后，点击「测试连接」，结果显示：
+
+```text
+HTTP 404
+```
+
+### 原因
+
+HTTP 404 表示服务端已响应，但当前请求 URL 路径不存在。旧代码会把「网址」字段原样作为 POST 地址；如果只填 OpenAI-compatible base URL，例如：
+
+```text
+https://api.vectorengine.ai/v1
+```
+
+程序会直接 POST 到 `/v1`，部分服务商会返回 404。当前代码已兼容 base URL：
+
+- `api_type=chat` 或 `auto`：`/v1`、`/api/v1` 会自动补成 `/chat/completions`。
+- `api_type=images_edits`：`/v1`、`/api/v1` 会自动补成 `/images/edits`。
+- 已经填写完整 endpoint（如 `/v1/chat/completions`）时保持不变。
+
+### 推荐修复
+
+更新到包含该修复的代码后，保留当前配置即可；也可以手工把「网址」改成完整 endpoint：
+
+```text
+https://api.vectorengine.ai/v1/chat/completions
+```
+
+如果仍然 404，优先检查服务商文档要求的 endpoint 路径和 `api_type`，不要把 `config/ai_models.json` 或 API Key 贴到日志、文档或聊天里。
+
+### 非敏感检查
+
+只输出非密钥字段确认 URL 形态：
+
+```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', [])]"
+```
+## AI生成：标题成功但图片生成失败，且看不到原因
+
+当前代码会为 ② AI生成写两层日志：
+
+- 页面右下「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 发到聊天、文档或提交里。