Document scoped real knowledge retrieval

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

@@ -52,6 +52,8 @@
 | D-027 | Agent 调试预览采用接近 DeepSeek 等聊天产品的显示方式。 | 用户确认 | 预览窗口以真实聊天体验为目标，支持连续对话、底部输入和生成中状态。 |
 | D-028 | 系统配置页面从占位 Key/Value 调整为中文分组配置表单。 | 用户确认 | 配置保存到 `sys_system_config`，默认每日额度接入学员新增和导入逻辑；其他配置作为后续运行时读取的统一入口。 |
 | D-029 | 系统配置页不保留高级配置入口。 | 用户确认 | 所有允许后台配置的项目必须显式列在配置页中，不允许管理员通过自由 Key/Value 临时增加配置项。 |
+| D-030 | 知识库检索不再使用 mock。 | 用户确认 | Agent 查找知识库内容时，要么调用真实搜索接口，要么飞书直读。 |
+| D-031 | 搜索接口必须限定在已开放知识库节点范围内。 | 用户确认 | 后端调用搜索接口时传入已开放知识库的 `spaceId/nodeId`，禁止搜索服务全局检索。 |
 
 ## 待确认决策
 

ai_knowledge_base_v2/development_records/2026-07-06-phase1-scope.md

@@ -53,8 +53,8 @@
 
 | 能力 | 一期要求 | 说明 |
 | --- | --- | --- |
-| 飞书知识库实时检索 | 必须 | 一期不做本地同步和向量库同步。 |
-| 多知识库开放过滤 | 必须 | 检索前先过滤出全部已开放、未禁用知识库。 |
+| 飞书知识库实时检索 | 必须 | 优先调用搜索接口；未配置或异常时回退飞书直读；一期不做本地同步和向量库同步。 |
+| 多知识库开放过滤 | 必须 | 检索前先过滤出全部已开放、未禁用知识库；调用搜索接口时必须把这些知识库的 `spaceId/nodeId` 作为检索范围传入，禁止全局搜索。 |
 | Prompt 组装 | 必须 | 系统 Prompt + 检索片段 + 历史上下文 + 当前问题。 |
 | 大模型调用 | 必须 | 从启用模型配置读取 API URL、Key、模型名和参数。 |
 | SSE 输出 | 必须 | 支持流式输出和结束标记。 |
@@ -97,7 +97,7 @@
 ## 一期验收重点
 
 1. 已在学员名单中的用户可以完成登录、提问、流式回答、停止生成、查看历史。
-2. AI 只使用已开放的知识库，知识库禁用或未开放时不能参与检索。
+2. AI 只使用已开放的知识库，知识库禁用或未开放时不能参与检索；搜索接口也必须限制在已开放知识库节点内。
 3. 无知识命中时不编造答案。
 4. 飞书异常、模型异常、AI 超时都有明确提示和日志。
 5. 后台可以维护用户、知识库、Prompt、模型、系统配置和聊天记录。

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

@@ -10,8 +10,10 @@
 
 - 新增统一外部服务异常 `ExternalServiceError`。
 - 拆出 `FeishuKnowledgeService`：
-  - 默认 `FEISHU_MOCK_ENABLED=true`，继续使用本地 mock 文档。
-  - 关闭 mock 后通过 `FEISHU_SEARCH_URL` 调用远端检索适配服务。
+  - 知识库检索不再使用 mock 文档。
+  - 优先通过 `FEISHU_SEARCH_URL` 调用远端检索适配服务。
+  - 未配置搜索接口或搜索接口异常时，回退为飞书直读。
+  - 调用搜索接口时必须传入当前已开放知识库的 `spaceId/nodeId` 范围，搜索服务只能在这些节点内检索，不允许全局知识库搜索。
   - 支持 `FEISHU_TIMEOUT_SECONDS` 和 `FEISHU_RETRY_COUNT`。
   - 远端返回统一解析为 `RetrievedChunk`。
 - 增强 `ModelClientService`：
@@ -28,9 +30,7 @@
 ## 当前配置
 
 ```env
-MOCK_RAG_ENABLED=true
 MOCK_MODEL_ENABLED=true
-FEISHU_MOCK_ENABLED=true
 FEISHU_SEARCH_URL=
 FEISHU_TIMEOUT_SECONDS=20
 FEISHU_RETRY_COUNT=2
@@ -38,8 +38,9 @@ FEISHU_RETRY_COUNT=2
 
 ## 当前边界
 
-- 真实飞书原生 API 尚未直接接入，因为还需要确认账号权限、SpaceID/NodeID 检索方式和返回结构。
-- 当前预留的是 `FEISHU_SEARCH_URL` 适配服务入口，后续可以选择直接接飞书原生 API，也可以由单独适配服务封装飞书复杂鉴权。
+- 搜索接口是优先方案，但必须支持按知识库节点范围检索。
+- 飞书直读是搜索接口未配置或异常时的兜底方案。
+- 不再允许使用本地 mock 知识库片段作为问答依据。
 - 真实模型当前先支持 OpenAI 兼容非流式响应；用户端仍通过后端 SSE 分块输出。
 - 模型原生流式透传和后端真实停止生成需要在模型供应商和 SDK/协议确认后继续补。