Add V2 external service providers

ai_knowledge_base_v2/development_records/2026-07-06-decision-register.md

@@ -31,6 +31,8 @@
 | D-008 | 生产密钥不明文展示，不写入日志。 | 默认采用 | 降低模型 Key、飞书密钥、短信密钥泄露风险。 |
 | D-009 | 用户端 Markdown 渲染使用 `markdown-it`，不手写 Markdown 解析器。 | 默认采用 | 减少列表、代码块、表格等格式兼容问题，降低后续维护成本。 |
 | D-010 | 用户端停止生成先使用浏览器 `AbortController` 中断 SSE 读取，后端真实中断等接入真实模型时实现。 | 默认采用 | 当前后端仍是 mock 模型，前端先保证用户操作反馈真实有效。 |
+| D-011 | 阶段四外部服务默认保持 mock 开启，通过配置关闭 mock 后再走真实 provider。 | 默认采用 | 当前缺少真实飞书检索地址和模型凭证，默认 mock 可以保证开发、演示和测试连续。 |
+| D-012 | 大模型真实调用先按 OpenAI 兼容 `chat/completions` 非流式响应接入。 | 默认采用 | 先打通配置化真实模型调用和失败日志，后续再升级为模型原生流式透传。 |
 
 ## 待确认决策
 
@@ -41,6 +43,7 @@
 | Q-003 | 大模型供应商、API URL、模型名和鉴权方式是什么？ | 先按 OpenAI 兼容接口 | 接入真实模型前。 |
 | Q-004 | 飞书知识库实时检索 API 是否满足 SpaceID/NodeID 检索要求？ | 先做 mock + 技术验证 | 阶段二后端基础工程完成后尽快验证。 |
 | Q-005 | 模型 API Key 生产环境如何保存？ | 优先环境变量引用或加密存储 | 做模型管理功能前。 |
+| Q-006 | 飞书检索是否直接调飞书原生 API，还是先由独立适配服务封装？ | 当前先预留 `FEISHU_SEARCH_URL` 适配服务入口 | 飞书账号、权限和 API 返回结构确认后。 |
 
 ## 当前可进入阶段二的判断
 

ai_knowledge_base_v2/development_records/2026-07-06-phase4-rag-external-services.md

@@ -0,0 +1,55 @@
+# 阶段四记录：RAG 和外部服务接入骨架
+
+日期：2026-07-06
+
+## 本次目标
+
+把阶段四从纯 mock 推进到可替换的外部服务接入骨架：飞书检索、模型调用、外部异常、失败日志和配置开关都要有明确边界。
+
+## 已完成
+
+- 新增统一外部服务异常 `ExternalServiceError`。
+- 拆出 `FeishuKnowledgeService`：
+  - 默认 `FEISHU_MOCK_ENABLED=true`，继续使用本地 mock 文档。
+  - 关闭 mock 后通过 `FEISHU_SEARCH_URL` 调用远端检索适配服务。
+  - 支持 `FEISHU_TIMEOUT_SECONDS` 和 `FEISHU_RETRY_COUNT`。
+  - 远端返回统一解析为 `RetrievedChunk`。
+- 增强 `ModelClientService`：
+  - 默认 `MOCK_MODEL_ENABLED=true`，继续使用 mock 模型。
+  - 关闭 mock 且后台存在启用模型时，按 OpenAI 兼容 `chat/completions` 非流式格式调用。
+  - 支持读取模型表中的 `api_url`、`api_key`、`model_name`、`temperature`、`max_token` 和 `timeout_second`。
+- 增强 AI 请求日志：
+  - 成功时记录完整请求日志。
+  - 飞书或模型异常时记录失败日志。
+- 增强 `/chat/completions`：
+  - 外部服务异常会返回明确错误。
+  - 失败时不消耗用户每日额度。
+
+## 当前配置
+
+```env
+MOCK_RAG_ENABLED=true
+MOCK_MODEL_ENABLED=true
+FEISHU_MOCK_ENABLED=true
+FEISHU_SEARCH_URL=
+FEISHU_TIMEOUT_SECONDS=20
+FEISHU_RETRY_COUNT=2
+```
+
+## 当前边界
+
+- 真实飞书原生 API 尚未直接接入，因为还需要确认账号权限、SpaceID/NodeID 检索方式和返回结构。
+- 当前预留的是 `FEISHU_SEARCH_URL` 适配服务入口，后续可以选择直接接飞书原生 API，也可以由单独适配服务封装飞书复杂鉴权。
+- 真实模型当前先支持 OpenAI 兼容非流式响应；用户端仍通过后端 SSE 分块输出。
+- 模型原生流式透传和后端真实停止生成需要在模型供应商和 SDK/协议确认后继续补。
+
+## 阶段四判断
+
+阶段四的工程边界已经建立，可以支持后续真实接入：
+
+1. 权限过滤在检索前执行。
+2. 飞书检索 provider 可替换。
+3. Prompt 组装已独立。
+4. 模型 provider 可替换。
+5. 成功和失败 AI 请求日志都有记录路径。
+6. 无命中兜底规则已生效。

ai_knowledge_base_v2/development_records/README.md

@@ -30,3 +30,4 @@
 | `2026-07-06-phase2-dev-compose.md` | 阶段二本地开发编排记录。 |
 | `2026-07-06-phase2-rag-skeleton.md` | 阶段二 RAG 问答链路骨架记录。 |
 | `2026-07-06-phase3-user-client-completion.md` | 阶段三用户端 H5 主链路补齐记录。 |
+| `2026-07-06-phase4-rag-external-services.md` | 阶段四 RAG 和外部服务接入骨架记录。 |