fix(im_llm): 代理绕过Docker内部hostname

2026-07-31 08:51:15 +08:00
1 parent 96aabc31f6
commit 9a43ee244d
@@ -0,0 +1,109 @@
+# 能力路由规则文档 (CAPABILITY_ROUTING.md)
+
+> **谁敢改这些文件的任何一行前，必须通读本文档。**
+> 更新日期: 2026-07-28 | 维护人: Senior Developer
+
+---
+
+## 一、核心原则
+
+```
+✅ 所有路由路径最终汇聚到 capability_registry.resolve_auto_model
+✅ 文本/推理/视觉/工具能力必须指向有 "text" capabilities 的模型
+✅ 图像/视频/语音能力在有明确意图时才触发（不会误判普通对话）
+✅ 新增能力类型必须在 CAPABILITY_TYPES 注册，否则路由不可见
+```
+
+## 二、路由路径 (谁在什么时候决定用哪个模型)
+
+| 入口 | 文件 | 行号 | 决策逻辑 | 出错表现 |
+|------|------|------|----------|---------|
+| 前台用户对话 | chat_service.py | 2730 | `intent = detect_media_intent(req.content)` → 媒体意图 → 图像/视频/语音模型 | 普通对话被误判走图像 |
+| 前台 Auto 模式 | chat_service.py | 2750 | `ai_model = resolved or resolve_auto_model("text", db)` → 无意图时回退文本 | 无法对话 |
+| defensive guard | chat_service.py | 2898-2905 | 模型有 image/video 能力但用户无媒体意图 → 强制 resolve_auto_model("text") | 被 guard 修复后走 text |
+| 后台 "按能力默认模型" 页 | admin/models.py | 495 | `get_capability_defaults(db)` → 读 site_settings JSON → 填到 UI dropdown | 页面不显示默认模型 |
+| 后台 模型测试 (connect) | admin/models.py | 870-954 | `_detect_model_type(capabilities)` → 按 cap 分类测试 | 测试走错端点 |
+| 关键词检测 | chat_media.py | 97-157 | `detect_media_intent(text)` → 基于关键词白名单 | 词库不全导致误判/漏判 |
+| 模糊创作意图 | chat_media.py | 200-240 | `detect_ambiguous_creative_intent(text)` → 无媒体词但有创作动词 | 提示不准确 |
+| 前端能力下拉 | admin/Models.tsx | 534-559 | `lockedCapDefaults` → 动态锁定 is_default=true 模型到 text/thinking | 显示错误的锁定模型 |
+| 前端模型下拉 (前台) | ChatPage.tsx | 1486-1498 | `model.capabilities` → cap badge 显示 | 多显示/少显示 badge |
+| 模型变更 API | admin/models.py | 670-672 | `is_default` 切换 | 旧默认模型未解除锁定 |
+
+## 三、能力定义 (唯一真相源)
+
+```python
+# capability_registry.py lines 17-35
+CAPABILITY_TYPES = [
+    {"id": "text",       "label": "文本对话",  "desc": "文本生成与多轮对话"},
+    {"id": "thinking",   "label": "推理思考",  "desc": "深度推理 / 思维链"},
+    {"id": "vision",     "label": "视觉理解",  "desc": "图片 / 多模态理解"},
+    {"id": "tool",       "label": "工具调用",  "desc": "Function Calling"},
+    {"id": "image",      "label": "图像生成",  "desc": "文生图"},
+    {"id": "video",      "label": "视频生成",  "desc": "文生视频"},
+    {"id": "audio",      "label": "语音合成",  "desc": "TTS 文字转语音"},
+    {"id": "asr",        "label": "语音识别",  "desc": "ASR 语音转文字"},
+    {"id": "ocr",        "label": "OCR识别",   "desc": "图片文字识别"},
+    {"id": "embedding",  "label": "嵌入向量",  "desc": "文本向量化"},
+    {"id": "rerank",     "label": "重排序",    "desc": "语义重排"},
+]
+
+TEXT_FAMILY = {"text", "thinking", "vision", "tool"}  # 回退到 is_default 模型
+```
+
+## 四、媒体意图关键词白名单 (chat_media.py)
+
+### 图像触发词 (```image_kw```)
+
+```
+图片/图像/插画/海报/照片/头像/壁纸/漫画/表情包/logo/图标
+画一张/画张/画一只/画只/画个/画幅
+生成图片/生成一张/生成一幅/生成图/图像生成
+帮我画/给我画/请画/绘制/作画/ai绘画/ai画图
+画画/画一下/画出来/生成个图
+帮我生成图片/帮我生成图像/给我生成图片
+来一张图片/画一张图片/画一幅/画一副
+```
+
+### 视频触发词 (```video_kw```)
+
+```
+视频/短片/影片/动画视频
+做个视频/生成视频/视频生成
+生成一个视频/制作一个视频/帮我做视频/制作视频
+生成短片/做短片/制作短片/一段短片
+一段视频/来段视频/拍个视频/做段视频
+```
+
+### 语音触发词 (```audio_kw```)
+
+```
+语音/配音/朗读/播报/念一段/有声/tts/音频/生成语音
+读一下/念一下/语音合成
+```
+
+### 不触发的语句
+```
+疑问句（？结尾或含 吗/呢/怎么/如何/能否/可以吗/会不会）
+已有明确文本形式（文案/文章/诗/代码/总结/翻译/报告/PPT）
+```
+
+## 五、修改检查清单
+
+每次修改上述任何文件的代码，必须：
+
+- [ ] 重新跑 `tests/test_regression_r4.py` (30 条用例，含 detect_media_intent 19 个边界)
+- [ ] 调用 `GET /app/api/health/bug-audit` 确认 healthy=true (16 项检查)
+- [ ] 手动测试一条普通文字（如"你好"）→ 必须走 text 模型
+- [ ] 手动测试一条图像指令（如"画一只猫"）→ 必须走 image 模型
+- [ ] 修改关键词白名单 → 同步更新本文档 §四
+- [ ] 新增能力类型 → 同步更新本文档 §三 + capability_registry.py CAPABILITY_TYPES
+
+## 六、回归防护网
+
+| 层级 | 机制 | 触发时机 |
+|------|------|---------|
+| pre-commit | bug-audit API + Python syntax | git commit |
+| pre-push | bug-audit + pytest + vitest | git push |
+| unit test | test_regression_r4.py (30 cases) | pytest |
+| runtime guard | chat_service.py defensive guard | 每次用户请求 |
+| bug-audit API | /api/health/bug-audit (16 checks) | 手动/CI |