kb-retriever

name	kb-retriever
description	面向本地素材库 / 知识库目录的检索和溯源助手。核心流程：(1)优先检索已构建的 KB unit index / canonical Markdown (2)遇到外部或搜索来的 PDF 时，不直接把 PDF 当 KB 检索，必须先按调用方摄取门完成 OCR/raw capture、修复为 repaired/canonical Markdown、再构建 units (3)答案必须带来源锚点。用户问题涉及"从素材库/知识库回答问题、检索信息、查资料、给某段内容找出处"时使用。当调用方需要"每条内容有来源"时，它是内容检索 + 溯源的运行时执行者。

本地素材库检索与溯源 Skill（kb-retriever）

知识库目录说明

• 素材库存放在一个根目录下，包含多种文件类型（如 .md/.txt、.tex、.pdf 等），通常按主题或来源拆分为多级子目录。
• KB 主输入是 repaired/canonical Markdown 或预构建的 unit index。原始 PDF、raw OCR、临时网页搜索结果只能作为证据层/候选层，不能直接作为正文 claim 的最终来源。
• 采用分层目录索引文件：
  • 根目录有一个 data_structure.md，说明主要的「主题目录 / 来源目录」及其用途。
  • 每个子目录下可以有自己的 data_structure.md，形成多级索引树。
  • 可选的单元索引：如果调用方（某个 domain 的流水线）预先产出了一份内容单元索引（每个可引用单元一个带 ID + 源锚点的条目），优先用它做精确检索与溯源，data_structure.md 只做粗粒度导航。
  • 单元索引必须记录 source_file、页锚/行锚、来源阶段（例如 repaired / canonical / native_md），这样 claim ledger 引用的是稳定文本，而不是搜索缓存。
• 素材库根目录约定（优先级从高到低）：
  • 用户/调用方显式指定的路径（对话里给的路径，或 domain 配置里声明的素材库根）——最高优先。
  • 常见默认：当前项目下的 sources/ 或 knowledge/（存在哪个用哪个）。
  • 当上述路径都不存在或访问失败时，应向用户确认实际的素材库根目录位置，而不是随意猜测。
• 单个源文件可能很大（如整本书 / 整篇长文导出的单文件上万行）：
  • 不要直接用 Read 读取整文件
  • 对 PDF 先完成调用方规定的摄取门，产出 repaired/canonical Markdown 或 unit index，再结合 grep / 局部读取做精细检索

定位素材库根目录

• 根目录优先听用户 / 调用方：如果给了路径（如 ./sources、./docs、./knowledge），直接用该路径。
• 默认根目录：未指定时，依次探测 sources/、knowledge/，存在哪个用哪个。
  • 使用 shell 显式检查目录是否存在：优先使用 test -d sources（或 test -d knowledge）。
  • 注意：禁止使用 Glob "sources" in . 这类模式来判断目录是否存在，Glob 只返回文件路径，不返回目录本身，空结果并不能区分“目录不存在”和“目录存在但为空”。
• 只有在根目录已通过 test -d 等方式确认存在时，才使用 Glob 在该目录下检索内容，并把目录作为 path，例如（下面以 <root> 代指确认存在的根目录）：
  • 单元索引 / 目录索引：pattern="**/data_structure.md", path="<root>"
  • 所有正文源文件：pattern="**/*.{md,tex,txt}", path="<root>"
• 如果默认根目录不存在（test -d 失败）：不要猜测其他目录，明确告诉用户未找到默认根目录，并让用户指定实际素材库路径。

关键原则：先 canonical，再检索

KB 检索强制检查清单：

• ✅ 已确认是否存在 kb_units.jsonl 或 repaired/canonical Markdown
• ✅ 若来源是搜索/外部 PDF，已完成 OCR raw capture
• ✅ 若来源是搜索/外部 PDF，已按 OCR repair guide 修复为 repaired/canonical Markdown
• ✅ 已从 repaired/canonical Markdown 构建 unit index，或明确这是 native Markdown source
• ⏭️ 现在可以开始检索和回填 source anchor

禁止行为：

• ❌ 跳过 OCR + repair，直接对搜索来的 PDF 建 KB / 做正文 claim 溯源
• ❌ 把 raw OCR Markdown 当成 canonical source 直接入库
• ❌ 把 web search snippet 当成正文 claim 的最终来源
• ❌ 对 .tex / .md / .txt 直接整文件 Read（应先 grep 定位再局部读）

总体流程

1. 理解用户需求

   • 读用户问题，提取：
     • 主题/领域关键词（如“销售报表”“系统架构”“接口文档”）
     • 时间或范围限定（如“2023 年 Q1”“最近版本”）
     • 需要的输出类型（解释、摘要、具体字段数值等）
   • 确定知识库根目录：
     • 优先检查用户是否在问题中指定了知识库路径。
     • 否则依次探测 sources/、knowledge/，使用第一个存在的目录。
     • 若默认根目录不存在或目录结构异常，应向用户询问确认，而不是自行假设。

2. 分层查看目录索引 data_structure.md

   • 使用一个「当前工作目录」的概念：
     • 默认从用户指定的知识库根目录开始；如果用户未指定，则使用当前目录。
   • 在当前工作目录下，如果存在 data_structure.md：
     • 使用 Read 读取该文件的前若干行（例如 limit=300），必要时分段继续读取。
     • 目标：
       • 了解当前目录下有哪些子目录和文件
       • 理解每个子目录/文件的用途说明
     • 基于用户问题，挑选最相关的若干个子目录或文件，构成候选集合。
   • 对于候选子目录：
     • 递归进入该子目录，将其作为新的「当前工作目录」，继续查找其中的 data_structure.md 并重复上述过程。
     • 在递归过程中，避免一次性深入所有分支，优先沿着与问题最相关的路径向下钻取。
   • 对于候选源文件（.tex / md / 文本、PDF 等）：
     • 在完成必要的目录层级探索后，收集这些文件为最终的检索目标列表。
   • 在优先级排序时：
     • 优先选择用途说明与问题主题高度匹配的领域目录和文件
     • 其次考虑时间/版本等约束（如果索引中有体现）
     • 通用说明类文档（如 README.md、总体设计类文档）放在较后优先级

3. 判断是否需要扩张 KB

   • 若本地 KB 找不到 claim 来源、事实需要核对、来源互相冲突、critic 标出疑似编造，且调用方明确允许扩张，才触发外部搜索。
   • 搜索结果先写入调用方约定的 research packet 或等价记录，记录 query、候选来源、入库决策。
   • 对搜索来的 PDF，必须先进入 OCR/repair 摄取链路；只有 repaired/canonical Markdown 和 unit index 完成后，才回到本 skill 检索。

4. 按文件类型执行处理和检索

   • 使用 canonical/repaired Markdown、unit index、native Markdown、LaTeX source 做检索。
   • PDF 只作为尚未入库的原始证据；如果还没完成 OCR + repair，先停在 ingestion 阶段，不输出 claim source。
   • 对每类候选文件，按照下面「Markdown/文本」「LaTeX」「PDF」策略执行
   • 总原则：
     • 优先从最相关、最精确的文件开始
     • 每个文件内都渐进式地局部检索，避免一次性加载全内容
     • 若当前文件得不到满意信息，切换到下一个候选文件

5. 迭代检索

   • 所有文件类型都使用统一的「多轮迭代检索机制」（见上文公共检索原则）

6. 答案组织与溯源

   • 汇总多轮检索得到的上下文，综合回答用户问题。
   • 尽量：
     • 给出清晰、直接的回答
     • 指出使用过的文件名（必要时包含大致位置，如章节或大概行数/页数）
   • 如果答案基于推断或信息不完全：
     • 明确标注假设与不确定性
     • 提示用户可以补充更具体的文件范围或关键词

公共检索原则

关键词选择策略

• 从用户问题提取 3-8 个关键词（含可能的英文缩写、同义词、上位/下位词）
• 可组合词组（如 "销售 报表"、"API 接口 超时"）
• 必要时包含业务词、技术术语、常见缩写（如 "uv"、"pv"、"GMV"）

grep 检索基本原则

• 始终指定尽量精准的 include 和 path，避免搜索整个目录
• pattern 优先尝试问题中的核心名词、术语，再尝试同义词
• 对于每个命中，只读取匹配附近的局部区域（上下若干行）
• 保存「文件名 + 位置信息 + 文本片段」

多轮迭代检索机制（最多 5 次）

所有文件类型都采用统一的迭代策略：

1. 迭代控制
   • 维护「已尝试检索次数」计数，最多 5 次
   • 每次检索后累加计数
2. 每轮迭代流程
   1. 基于问题生成/更新检索关键词（可包括同义词、扩展词）
   2. 选择尚未充分检索的文件或文件部分
   3. 执行检索（grep/局部读取/专用 Skill 调用）
   4. 分析获取的上下文片段
   5. 判断是否足够回答问题
3. 终止条件
   • 找到足够支撑回答的上下文；或
   • 已达到 5 次尝试仍未找到合适信息
4. 信息不足时的处理
   • 明确告知用户信息缺失或可能不在当前知识库中
   • 提供已找到的最接近信息，并说明不确定性
   • 提示用户可以如何缩小范围（更具体的文件名、关键词、时间范围等）

注意事项

• 禁止第一次就直接调用：Glob "knowledge" in . 或任何试图用 Glob 判定目录存在性的调用，目录存在性应通过 shell 命令（如 test -d）检查。
• 仅执行本地知识库查询时，禁止使用网络搜索等其他工具获取知识；外部扩张必须由调用方显式开启并记录 research packet。

针对不同文件类型的具体策略

1. Markdown / 文本类文件（.md, .txt, .log 等）

1. 候选文件选择

   • 根据 data_structure.md 和文件名、路径判断相关度
   • 优先检索标题和目录类文件（如汇总文档、设计总览）

2. grep 定位与局部读取

   • 使用 Grep 工具对指定候选文件，include 限定具体后缀（如 "*.md"）
   • 对于有匹配的文件，使用 Read 仅读取匹配附近的局部区域：
     • 通过行号偏移和 limit 控制读取（例如从匹配行附近往前后各读取几十行）
     • 避免整文件读取

3. 特殊处理

   • 如内容仅是目录/标题，根据链接或小节名继续定位深入内容
   • 应用「多轮迭代检索机制」（见上文公共检索原则）

2. PDF 文件摄取策略

PDF 不是可直接检索的 KB source。它只能处在以下状态之一：

pending_ocr      已登记 PDF,尚未 OCR
pending_repair   已有 raw OCR Markdown,尚未修复
promote_to_kb    已有 repaired/canonical Markdown 和 unit index
verification_only 只用于存在性核对,不进入正文 KB
discard          无关/重复/不可信

promote_to_kb 的最低条件：

• raw_path 或等价原始 PDF 记录存在。
• raw_ocr_md 存在。
• repaired_md 或 canonical_md 存在。
• 已从 repaired/canonical Markdown 构建 kb_units.jsonl。

只有达到 promote_to_kb 后，本 skill 才检索 PDF 派生出的 Markdown/unit。否则应返回“该 PDF 尚未完成摄取门”，并说明缺哪一步。

3. LaTeX 源文件（.tex）检索策略

书 / 论文 / 长文导出的 .tex 常是上万行的单文件。策略与 Markdown 类似，但注意：

1. 靠结构命令定位

   • 用 Grep 搜 \\(chapter|section|subsection)\{ 建立章节地图，再按用户问题跳到相关小节。
   • 定理 / 定义用环境定位：\\begin\{(theorem|definition|lemma|proof)\}。

2. 局部读取

   • 命中后用 Read 的 offset + limit 只读该环境 / 小节附近，不整文件加载。

3. 溯源锚点

   • 记录「文件 + 章节标题 + 大致行号」作为该条内容的 source，回填给调用方的溯源账本，实现"每条内容有出处"。
   • 应用「多轮迭代检索机制」（见上文公共检索原则）

与其他工具的协同

PDF 处理

• 通用 PDF 文本抽取方法可参考 references/pdf_reading.md，但如果调用方/domain 规定 OCR + repair 摄取门，则该门禁优先。
• 对搜索/外部 PDF，不直接 grep 原始 PDF 或临时抽取文本来支撑正文 claim；先产出 repaired/canonical Markdown 和 unit index。
• PDF 原文仍是最终裁判；OCR repair 有疑问时应回看原 PDF，但 claim ledger 引用 repaired/canonical source anchor。

工具使用原则

• Grep：用于按关键词在指定文件中查找行号与匹配片段，始终指定尽量精准的 include 和 path
• Read：只用于局部读取文件，始终设置合理的 limit（如 200-500 行）和合适的偏移
• 对于任何可能很大的文件：
  • 禁止直接从头读到尾
  • 始终先通过索引、目录、关键词等方式缩小范围后再读

回答风格与错误处理

• 回答风格
  • 尽量用用户提问的语言（中文/英文）作答。
  • 先给出结论，再给出简要依据。
  • 如需要，可在后面列出引用的文件和大致位置，例如：
    • 来源：design/api_gateway.md 第 100 行附近
    • 来源：sources/some-book.tex，某小节标题（约 4149 行）
• 信息缺失或不确定时
  • 明确说明在当前知识库中没有找到完全匹配的信息或只能部分回答。
  • 不臆造事实。
  • 提示用户可以如何帮助缩小范围：
    • 指定更具体的目录/文件
    • 提供更精确的关键词或字段名
    • 指定时间/版本范围