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

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

关联：

• 用法见 知识库的使用
• 产品规格.md §3.2.1（知识文档三层）
• 索引式文档与反馈闭环.md（两层索引方法论）
• AI重建知识索引规则.md（AI 生成索引规则）
• help/README.md（系统知识目录维护）
• 智能体对话编排.md（本轮如何选题再读正文）

1. 结论先说

Cadau 不会把整本知识目录原样塞进大模型。每次用户发一句话时，后端在服务端先判断本轮要不要检索知识（问数、做报表且已有数据连接时通常不检索）。应用完整操作表只在用户当前打开该应用，或正在消息里对工作区 应用助手 说话时展开；智能问数查数据连接（哪怕库也是人事数据）只带短桩，不凭「员工 / 部门 / 入职 / 人力资源」等用词去展开 Cadau 人力资源操作表。需要时再：

1. 读知识库的 两层索引（根目录与各主题下由 「用 AI 生成索引」 写成的索引），按这句话先选主题、再选篇，然后打开 Markdown 正文；
2. 原文档案（Word / PDF 等）按抽出的文字做关键词匹配，与说明文档一并进入对话；
3. 把带出处的片段拼进对话；总字数仍有上限（约 6000～8000 字）；
4. 按会话类型放进 用户消息 或 系统提示（运行时材料） 再调用模型。

说明文档改正文后请点 「用 AI 生成索引」，否则对话可能仍按旧目录选题。原文档案入库后抽出文字即可被关键词命中，不再生成向量。

知识库检索 不调用嵌入模型；rag.enable_vector 默认关闭。查询改写、BM25 加权仅在对应开关为真时生效。

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.AssemblePrompt 拼用户消息]
  C1 --> C2[系统角色 + 帮助文档片段 + 用户问题]
  F --> F1[composeLLMRuntimeContext 拼运行时材料]
  F1 --> F2[system 提示 + 历史 + 用户原文]

3.1 帮助智能体（help_mode: true）

• 前端：只提交用户问题，不传知识目录全文。
• 后端：先检索帮助文档切片（helpdocs.AssemblePrompt）；库空时再走 helpdocs.BuildPrompt（两级索引命中后切段）。片段与固定说明、快捷操作链接模板 整体替换本轮发给模型的 用户侧 内容，并截断至约 8000 字。
• 失败：索引或文件不可读时，接口返回「帮助文档未就绪」（help_docs_unavailable）。

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

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

• 用户消息：保持用户输入原文（可含附件元数据等，此处不展开）。
• 系统提示：由 buildAgentToolSystemPrompt / prepareLLMConversationWithRollingContext 组装。发话后先按用户原话分类本轮要哪些材料包（chat_prompt_packs.go），再拼 运行时材料（agentRuntimeContext → composeLLMRuntimeContext）：

1. 工作区知识（仅本轮判定需要知识时） 2. 智能体知识（同上） 3. 工作区技能（会话沉淀技能，按问题匹配，见 chat_workspace_skills.go） 4. 相关记忆（按问题选条目；长期记忆索引全文仅在本轮要改/查记忆时带上）

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

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. 取段落：按索引选篇后打开 Markdown 正文；原文档案另按抽出文字做关键词匹配。切段规则：整篇不超过约 5000 字则 整篇一段（适合「一张表一份数据字典」）；更长则按标题合并到约 1200 字再切，并尽量不从表格中间断开。
5. 截断：

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

默认只检索 现行 效力；问到以前/旧通知/归档时纳入归档件。知识库 不生成、不使用向量；说明文档靠两层索引选题，原文档案靠抽出的文字。用户在查过去对话原文（近几天聊过什么、问过哪些单词）时跳过知识文档检索，避免把无关制度说明塞进提示。

index.json 的标题/摘要/标签仍用于选篇与加分；paths 条件加载仍生效。

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 机制目标）。