系统知识文档与检索索引

给谁看：平台管理员（管理端 系统知识文档 工作区）。

维护什么

• 正文：help/ 下的 Markdown 说明（新手引导、产品能力、管理员操作等）。
• 索引：各层 index.json（根目录 + 各主题子文件夹），供帮助智能体 先选题、再读正文。

改完 Markdown 后，请点 「用 AI 生成索引」（或 强制重新生成）。未重建索引时，帮助智能体可能仍按旧摘要作答。

索引里有什么

每条文档在索引中通常包含：

两层结构：根 index.json 列 主题文件夹；每个主题文件夹内再有 index.json 列该主题下的各篇说明。

可选：按场景才加载（paths）

若某篇说明 只在特定场景才需要（例如「前端组件规范」仅在讨论 .tsx 文件时才有用），可在索引条目上增加可选字段 paths：

{
  "id": "frontend-rules",
  "title": "前端组件规范",
  "path": "guides/frontend-rules.md",
  "summary": "React 组件命名、Tailwind 用法",
  "tags": ["前端", "React"],
  "paths": ["**/*.tsx", "**/*.jsx"]
}

含义（用户侧）：

• 不填 paths：通用说明，对话时仍按问题关键词匹配，与以前一致。
• 填了 paths：仅当用户 消息里提到相关文件路径，或 附件文件名 命中 glob 时，才会把该篇注入对话；避免无关场景占满上下文。
• 新手导读、账号说明、三层知识分工 等 全员常读 材料 不要 填 paths。

用 「用 AI 生成索引」 时，模型会在合适时为条件类文档建议 paths；也可在生成后 手动编辑 对应主题的 index.json 微调。

管理端操作步骤

1. 登录管理端 → 系统知识文档（/system-knowledge）。
2. 左树选文件夹，中间列表选文件，右侧编辑 Markdown。
3. 改完一批正文后 → 用 AI 生成索引（需服务端已配置 LLM）。
4. 若索引摘要/标签明显不对，或刚升级了索引规则 → 强制重新生成。

写操作与重建索引会记入管理员审计日志。

常见问题

帮助智能体仍答旧内容？ 确认已重建索引，且部署配置里的帮助文档目录指向当前 help/。

某篇「前端规范」从不被引用？ 若该篇索引带了 paths，用户未附 .tsx 或未在消息里提到相关路径时 不会注入——这是预期行为；通用材料请去掉 paths。

与工作区 / 智能体知识的关系？ 本节仅 系统层（帮助智能体）。团队材料在工作区协作里维护；个人材料在「我的智能体 → 知识文档」里维护；三层分工见 知识文档的三层。

详情

• 索引生成规则（实现）：仓库 docs/core-mechanisms/AI重建知识索引规则.md
• 对话如何选用知识：仓库 docs/core-mechanisms/智能体调用知识文档的方式.md

---

发版或改 help 后检查清单

在 测试 / 生产 更新 help/ 正文或索引规则后，按顺序执行（约 5～10 分钟）：

前置

• [ ] 后端已配置 LLM（与主站对话相同，如 OPENAI_API_KEY）；管理端 用 AI 生成索引 按钮可用，而非提示「尚未配置 AI 服务」。
• [ ] 确认 help_docs.dir / HELP_DOCS_DIR 指向 当前部署 的 help/ 目录（改错目录会导致帮助智能体读旧文件）。

重建索引

• [ ] 登录 管理端 → 打开 系统知识文档（/system-knowledge）。
• [ ] （可选）点 用 AI 生成索引 前先浏览左树，确认新增的 .md 已在磁盘上可见。
• [ ] 点击 强制重新生成（或普通 用 AI 生成索引，若预览提示「文档有变化」）。
• [ ] 等待进度完成，页面上方出现 「已生成索引：…」；记录是否包含 index.json 及各主题子目录的 index.json。
• [ ] 若只改了某一主题文件夹（如 admin-ops/），至少应刷新 根 index.json 与该主题的 admin-ops/index.json（强制重建会一并处理）。

抽检索引内容

• [ ] 在编辑器中打开 admin-ops/index.json（或其他改动的主题子索引），确认新篇目在 documents 里且 summary / tags 非空。
• [ ] 若使用了 paths，确认 glob 写法正确（如 /*.tsx）；通用导读类条目 无** paths 字段。

验证帮助智能体

• [ ] 主站 未选工作区（或消息里选 帮助智能体），新开一场会话。
• [ ] 提问与刚更新内容相近的自然语言，例如：「系统知识索引 paths 是什么」「管理员怎么重建 help 索引」。
• [ ] 回答应引用 新摘要 中的要点；若仍像旧版，回到 强制重新生成 并确认 help_docs 目录。
• [ ] （可选）问一个带 .tsx 文件名 的问题，确认带 paths 的条件文档仅在相关场景被引用（无路径时不应硬塞前端规范全文）。

收尾

• [ ] 在管理端 审计 / 概览（若有）确认出现 admin.system_knowledge.reindex 类事件。
• [ ] 将本次发版说明发给运营：哪些 help 主题有变、是否涉及 paths 新规则。

何时用「强制」而非普通生成？ 刚合并代码、手动改过 index.json、或预览仍显示「文档未变化」但你知道摘要/标签过时 → 用 强制重新生成。