AI 生成知识文档索引（规则）
「用 AI 重新生成索引」 指：在 当前智能体的知识文档目录 下，根据已有 Markdown 说明，自动生成或刷新 两层检索用的索引文件，让后续对话能 先锁定相关文档、再读原文 作答或执行。
来源 docs/core-mechanisms/AI重建知识索引规则.md
表述（产品侧）
「用 AI 重新生成索引」 指：在 当前智能体的知识文档目录 下，根据已有 Markdown 说明，自动生成或刷新 两层检索用的索引文件，让后续对话能 先锁定相关文档、再读原文 作答或执行。 用户侧不强调 index.json、knowledge/ 等实现名；运维与对接可见 § 实现对照。
机制目标
- 少漏召：索引里的主题、摘要与标签应能覆盖用户常见的说法，便于第一步就选对主题或文件。
- 路径可信：条目中的文档路径必须与磁盘上真实存在的
.md一致；禁止依赖模型「发明」不存在的路径。 - 细节在正文：索引只做 导航与粗匹配；具体条款、数字与操作步骤以 打开的 Markdown 正文 为准。
- 可演进：未来若增加 按块向量检索，文件级路径与索引结构应保持稳定，块级信息作为 增强层 挂载，而不破坏现有两层检索约定。
两层结构与文件约定
与「索引式说明/技能文档」方法论一致（见 索引式文档与反馈闭环.md），用户智能体知识目录 上采用：
| 层级 | 文件（实现名） | 作用（用户能理解的说法） |
|---|---|---|
| 第一层 | 知识根下的 index.json | 总览：根目录下的说明文档 + 有哪些主题文件夹，每项有简短说明与关键词。 |
| 第二层 | 每个一级主题文件夹 内的 index.json | 该主题下 各篇说明 的列表与摘要，用于精确到篇。 |
路径规则（实现契约）：
- 根索引里，直接在根下的 Markdown 在
documents中；path仅为文件名，不含/。 - 根索引里
themes的dir为 一级主题目录名（单层段、无/）。 - 子索引里
documents[].path为相对于 该一级目录 的路径（可含子文件夹），须与扫描结果 完全一致。
详细 JSON 字段与 Go 结构体见：backend/internal/skilldocs/index.go（Index、ThemeItem、DocItem）。
扫描与输入（生成前准备）
- 范围：从该智能体知识根目录 递归遍历 整棵树（
filepath.WalkDir语义）。 - 纳入：仅
*.md；路径与内容须为合法 UTF-8。 - 排除：名字以
.开头 的文件（与常见隐藏/配置约定一致）。 - 摘录：每文件进入模型前截取 前若干字符（按 rune 计），避免单次请求过大；子目录索引拼 prompt 时还可对单条摘录 再缩短（用于控制 token）。
- 分组：
- 根下一层的 .md → 参与 根索引 的 documents。 - 其余 .md 按 路径第一段（一级目录名）归入对应主题，用于 该主题的子索引 生成；根索引的 themes 仅针对这些 确实存在 Markdown 的一级目录。
模型调用顺序与职责
- 先根后子目录（按篇合并）：先生成并落盘根
index.json，再对每个一级目录 逐篇 调用模型生成DocItem，由程序合并写入{dir}/index.json（避免整目录一次 prompt 过长导致超时）。 - 根索引提示职责：根据根下
.md摘录 + 一级目录名单，产出version、themes、documents；themes中每个给定的一级目录 至多一条，且dir与名单一致。 - 子目录索引（单篇）：每篇只输出一个
DocItem对象；合并后themes固定为空数组；documents中path必须来自实现侧给出的闭合列表，摘要与标签服务检索。
温度等超参以实现为准（当前根与按篇生成均使用较低温度以稳定 JSON）。
输出与校验规则
- 只接受一个顶层 JSON 对象；若模型在 JSON 后追加自然语言说明，解析时 只取第一个平衡的
{ ... }对象（字符串内需正确处理引号与转义），避免解析失败。 - 根索引白名单：
- documents：仅保留 扫描到的根下 .md 文件名；丢弃含 ..、/ 或非 .md 的项。 - themes：仅保留 dir 在扫描到的一级目录集合中 的项；规范 index_file 等默认值。 - 若某应有的一级目录缺少主题项，实现可 按约定补默认主题项（避免检索链路断档）。
- 子索引白名单：
documents中的path必须在生成该文件时给定的列表中；否则丢弃或判失败（以实现为准）。 - 落盘：写入
index.json时应保证 读者不会读到半截文件（例如先写临时文件再替换；具体见实现）。
检索侧如何用它（与索引规则的一致性）
检索时 先读根索引 → 按问题匹配主题 → 读对应子目录索引 → 选中若干 documents → 再按路径打开 Markdown 原文 构建上下文（见 skilldocs.BuildContext 一类逻辑）。
因此索引中的 summary / tags 应优先服务 「这句话像哪篇文档」 的匹配，而不是复述全文。
可选 paths（条件加载）：documents / themes 可增 paths 字符串数组（glob，如 ["/*.tsx"]）。仅当用户消息或附件路径命中 glob 时才注入该篇；通用 onboarding/总则类文档不要填。无路径上下文时，带 paths 的条目 不会** 进入对话（见 skilldocs/itemMatchesScope）。
中文问句：检索会对连续汉字做单字/双字切分（避免无空格整句无法命中）；若无任何命中，会回退注入 导读.md、00-总则与功能导航.md 等优先篇（见 skilldocs/tokenize、fallbackDocs）。
演进（非当前必做）
- 超大主题目录：若单次提示仍过长，可按 子文件夹 分批生成再 合并（合并可以是确定性规则 + 可选轻量模型），不必强制「每叶目录一次调用」。
- 块级向量：未来可在每条索引或块元数据中增加
source_path与chunk_id；文件级索引仍可作为 第一层过滤。向量库选型（如 LanceDB 等）属部署与实现阶段决策，不改变 两层索引 + 读原文 的产品语义。
分步生成与进度（实现）
产品界面可按 扫描预览 → 根索引 → 各主题子索引 顺序多次请求，以便展示 当前步骤 / 总步骤：
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | .../knowledge/reindex/preview | 仅扫描磁盘；返回 steps_total、top_dirs、llm_configured（不调模型） |
| POST | .../knowledge/reindex/root | 只写根目录 index.json；响应含 progress.completed/total |
| POST | .../knowledge/reindex/sub | Body {"dir":"<单层主题文件夹名>"}；一次写完该主题下全部篇目的 index.json（内部仍按篇调用模型） |
| POST | .../knowledge/reindex/sub/doc | Body {"dir","path","clear_dir"?}；仅为该主题下 一篇 生成条目并合并进 index.json；clear_dir:true 表示本主题第一篇（清空该目录旧 documents 再写） |
| POST | .../knowledge/reindex | 一键完成上述流水线（与分步二选一即可） |
预览 GET .../reindex/preview 的 steps_total = 1（根）+ 各主题目录下 Markdown 篇数；top_dir_docs 给出各主题下待索引的相对路径列表。
实现对照（供工程与契约）
| 环节 | 代码入口（参考） |
|---|---|
| HTTP 触发 | 见上一节表；入口 RebuildKnowledgeIndexes、KnowledgeReindexPreview、KnowledgeReindexRoot、KnowledgeReindexSub |
| 扫描与摘录 | collectMarkdownForReindex、excerptSanitize 等 |
| 根/子 LLM 与解析 | generateRootKnowledgeIndexJSON、generateSingleDocKnowledgeIndexJSON、writeKnowledgeSubIndex、writeKnowledgeSubIndexDoc、stripLLMJSONObject |
| 校验与对齐 | sanitizeAndAlignRootIndex、sanitizeSubIndex |
| 检索消费 | skilldocs.BuildContext、Index 结构体 |
相关文档
- 索引式文档与反馈闭环.md（两层索引与闭环方法论）
- 智能体调用知识文档的方式.md（对话注入与三层知识）
- ../产品规格.md（「知识文档目录」产品与分层表述）