智能体调用知识文档的方式

文档版本：1.0 状态：与当前后端实现一致（backend/internal/api/handlers/chat.go、helpdocs、skilldocs） 表述：面向产品、运营与对接方，用用户能理解的用语说明「知识从哪来、怎么进对话」；实现名放在文末 实现对照。

关联：

• 产品规格.md §3.2.1（知识文档三层）
• 索引式文档与反馈闭环.md（两层索引方法论）
• AI重建知识索引规则.md（AI 生成索引规则）
• help/README.md（系统知识目录维护）

1. 结论先说

Cadau 不会把整本知识目录原样塞进大模型。每次用户发一句话时，后端在服务端：

1. 用 用户当前这句话 做关键词式匹配（读 index.json 里的标题、摘要、标签）；
2. 选出少量 主题 与 文档；
3. 从磁盘读取对应 Markdown 正文，拼成片段；
4. 按会话类型放进 用户消息 或 系统提示（运行时材料） 再调用模型。

因此：维护好两层索引 + 正文，比单纯堆长文档更重要；改正文后应 重新生成索引（管理端或工作区/智能体知识工作区内的「用 AI 重新生成索引」）。

当前知识检索 不依赖 RAG_ENABLE_* 环境变量（这些开关仅影响配置与日志，不参与本节注入逻辑）。

2. 知识文档三层与谁在用

此外，同一轮对话还可能拼入 工作区技能（会话沉淀的操作说明，存在数据库，不是 knowledge/ 目录）和 运行时记忆节选（MEMORY.md 等），见 §5。

与规范库：政府/行业法规、管理制度等 带版本与人审 的真源见 规范库.md（产品 §3.2.2）。实现上，已选工作区时 composeLLMRuntimeContext 会注入 已发布且生效 的规范库片段（workspaceStandardsBlock，按标题/标签/文号匹配）；不要把待审草稿或未启用版本注入普通成员答疑。工作区知识仍适合 Wiki/FAQ；二者勿混为一谈。

3. 会话分岔：帮助智能体 vs 工作区智能体

flowchart TD
  A[用户发送 POST /api/v1/chat] --> B{help_mode?}
  B -->|是| C[帮助路径]
  B -->|否| D{有 user_agent_id 且已选工作区?}
  D -->|否| E[一般不注入工作区/智能体知识]
  D -->|是| F[工作区智能体路径]
  C --> C1[helpdocs.BuildPrompt 拼用户消息]
  C1 --> C2[系统角色 + 帮助文档片段 + 用户问题]
  F --> F1[composeLLMRuntimeContext 拼运行时材料]
  F1 --> F2[system 提示 + 历史 + 用户原文]

3.1 帮助智能体（help_mode: true）

• 前端：只提交用户问题，不传知识目录全文。
• 后端：helpdocs.BuildPrompt 读取 系统知识 根目录（默认仓库 help/），两级索引命中后，把 1～3 篇文档片段与固定说明、快捷操作链接模板，整体替换本轮发给模型的 用户侧 内容（不是单独再挂一条 system 里的「知识块」）。
• 失败：索引或文件不可读时，接口返回「帮助文档未就绪」（help_docs_unavailable）。

帮助智能体 不会 同时注入工作区知识、智能体知识（composeLLMRuntimeContext 在 help_mode 下跳过知识块）。

3.2 工作区内的用户智能体（help_mode: false 且带 user_agent_id）

• 用户消息：保持用户输入原文（可含附件元数据等，此处不展开）。
• 系统提示：由 buildAgentToolSystemPrompt / prepareLLMConversationWithRollingContext 组装，其中 运行时材料 来自 agentRuntimeContext → composeLLMRuntimeContext：

1. 工作区知识（若有 workspace_id） 2. 智能体知识（若有 user_agent_id） 3. 工作区技能（会话沉淀技能，按问题匹配，见 chat_workspace_skills.go） 4. 近期会话记忆节选（运行时 MEMORY 尾部，最多约 2000 字符）

优先级（写在系统提示里）：工作区知识与智能体知识冲突时，以 智能体知识 中明确覆盖为准，否则以 工作区知识 为准；都未覆盖则说明不知道。

3.3 系统内置智能体（is_system）的特殊情况

若请求 未 开 help_mode，但当前智能体为 系统内置（user_agents.is_system），且已选工作区，则 injectHelpDocsForChat 为真，对用户消息走 与帮助智能体相同的 helpdocs.BuildPrompt（即用系统知识目录）。 典型场景：未选工作区时的帮助入口；具体以产品路由为准。

4. 两层索引检索（工作区 / 智能体 / 系统知识共用规则）

实现包：skilldocs（工作区、智能体知识）、helpdocs（系统知识，逻辑同构）。

4.1 目录约定

知识根/
  index.json          ← 第一层：主题 themes + 根下 documents
  某主题/
    index.json        ← 第二层：该主题下 documents
    某说明.md

4.2 检索步骤（每次用户提问执行一次）

1. 读根 index.json。
2. 第一层：用用户问题中的词，对 themes[] 的 title / summary / tags 打分，取 Top 2 个主题；若无命中则退回前 2 个主题。
3. 第二层：对每个命中主题，读 {dir}/index.json，对 documents[] 打分，每主题最多 2 篇（工作区/智能体路径下由 BuildContext(..., top=3) 控制总篇数上限，见下）。
4. 读正文：按条目中的 path 读 .md，拼为 ### 标题 + 正文，多篇之间用 --- 分隔。
5. 截断：

- 工作区知识块上限约 6000 字符（rune）； - 智能体知识块上限约 8000 字符（rune）； - 超出则尾部标注「节选已截断」。

匹配算法为 关键词 / 标签包含（中英文分词简单处理），不是 向量检索；index.json 的质量直接决定召回。

4.2.1 可选条件加载（paths）

documents[] / themes[] 可含可选 paths 字符串数组（glob，如 ["**/*.tsx"]）：

• 未填：与原先一致，按问题关键词参与匹配。
• 已填：还须用户 消息中的路径片段 或 附件文件名 与某一 glob 匹配，该条目才会进入候选；无路径上下文时不注入，避免大段「仅前端场景」文档占 token。
• 维护：「用 AI 生成索引」时模型可建议 paths；管理员可手改 index.json。用户说明见 help/admin-ops/system-knowledge-index.md、help/knowledge-layers/three-layers.md。

4.3 与工作区技能、技能中心的区别

技能逻辑契约与触发说明见 技能组成规范.md。

5. 一次对话的完整上下文结构（工作区智能体）

┌─────────────────────────────────────────┐
│ system（单条）                           │
│  - 角色与工具/诚实/试探等固定说明         │
│  - 【工作区知识…】                        │
│  - 【智能体知识库…】                      │
│  - 【与本工作区相关的技能说明】           │
│  - 【近期会话记忆节选】                   │
├─────────────────────────────────────────┤
│ 历史 user / assistant（滚动摘要控制体量） │
├─────────────────────────────────────────┤
│ user：用户本轮原文                         │
└─────────────────────────────────────────┘

流式与非流式接口（POST /chat、POST /chat/stream）共用上述组装逻辑。

启用 HTTP 工具（AGENT_HTTP_TOOL_ENABLED 且非帮助模式）时，system 仍带运行时材料；模型可在多轮中调用 http_request，与知识片段配合使用。

6. 维护者要做什么

1. 写 Markdown：操作步骤、边界条件写在正文，索引里只写「能搜到的」标题、摘要、标签。
2. 生成索引：新增主题文件夹或大量改标题后，在对应维护入口执行 用 AI 重新生成索引（规则见 AI重建知识索引规则.md）。仅在与文件类型/路径相关的规范上，可为索引条目加 paths（条件加载，见 §4.2.1）。
3. 系统知识：管理端 → 系统知识文档（help/）；工作区知识：工作区协作；智能体知识：我的智能体 → 知识文档。
4. 验证：用与文档标签相近的自然语言提问，看回答是否引用正确片段；帮助场景在未选工作区下测试。

7. 实现对照

8. 后续演进（未实现或仅配置预留）

• RAG_ENABLE_VECTOR、RAG_ENABLE_BM25 等：配置项存在，当前不参与 §4 的文件级索引注入。
• 块级向量、查询改写：若落地，宜作为 增强层，不破坏现有两层 index.json 与 path 约定（见 AI重建知识索引规则.md 机制目标）。