kb-retriever

name	kb_retriever
description	本地双层知识库检索与问答。用户要求从知识库、资料目录或本地文档中查信息、总结、核对来源时使用。先按 data_structure.md 分层导航，再渐进检索候选文件；遇到 PDF/Excel 时先读取本 Skill 的 references 处理指南。

本地知识库检索 (KB Retriever)

从用户级和全局级知识库中渐进检索信息，并给出可追溯答案。

插件路径

plugins/kb_retriever/

知识库层级

层级	路径	优先级	默认权限
用户级	users/<name>/knowledge/	高	读写
全局级	knowledge/	低	只读

检索时同时检查两层，同类结果以用户级为准。用户明确指定其他目录时，以用户路径为根目录。

核心流程

1. 从问题提取主题、时间、版本、字段和输出要求。
2. 使用已注入的根 data_structure.md 索引定位候选目录；需要时读取最近的子索引。
3. 选择最相关的少量候选文件，不遍历所有分支。
4. 文本文件先搜索关键词，再按行读取命中附近内容。
5. PDF/Excel 先读取对应 references，再转换或提取到临时文本后搜索。
6. 最多迭代 5 轮，调整同义词、英文缩写、范围和候选文件。
7. 先给结论，再列依据、文件路径和位置；信息不足时明确说明。

强制 references

文件类型	处理前必须读取
PDF	plugins/kb_retriever/references/pdf_reading.md
Excel	plugins/kb_retriever/references/excel_reading.md 和 excel_analysis.md

未读取指南前，不直接处理原始 PDF/Excel。

工具映射

目的	优先工具	说明
查看目录	list_dir / tree_dir	先看索引和相关分支
读取索引或小文件	read_file	索引文件通常可全文读取
搜索文件名/内容	search_files	优先于 shell grep/findstr
读取大文件局部	read_file_range	根据命中行读取上下文
文档转 Markdown	convert_to_markdown	对可用的 PDF/Office 转换工具
无专用工具时诊断	run_command	仅作备选，命令范围保持最小

文件类型策略

Markdown / 文本

• 根据索引和文件名筛选候选。
• 用 3-8 个关键词及同义词搜索。
• 对命中位置读取相邻行，不全量加载大文件。

PDF

• 先读 references/pdf_reading.md。
• 优先转换为 Markdown；必要时按指南使用 pdftotext 或其他提取方式。
• 检索转换稿，并保存文件名、页码或大致位置。

Excel

• 先读 references/excel_reading.md 和 excel_analysis.md。
• 先查看工作表、列名和少量样本，再筛选与聚合。
• 大表不要整表载入上下文，只返回相关记录和统计。

知识库写入规则

• 新增资料默认写入用户级知识库。
• 只有用户明确要求“写入全局知识库”时才修改全局级。
• 任何知识文件新增、修改、删除、移动或重命名后，必须同步更新最近的 data_structure.md，必要时再更新根索引。
• 二进制文件索引至少记录类型、主题、来源、建议读取工具和是否有 Markdown 转换稿。

结果说明

本 Skill 是指令型技能，不注册工具。回答应包含：

1. 直接结论；
2. 简要判断依据；
3. 来源文件和章节/行号/页码（能定位时）；
4. 不确定性与缺失信息。

常见规范

• 顶层索引已注入 system prompt 时不重复读取。
• 先索引导航，后内容搜索；先精确候选，后扩大范围。
• 本地知识库问答默认不混入网络搜索结果，除非用户另行要求。
• 不把用户私有资料复制到全局知识库。

常见处理办法

• 两层目录都不存在：告诉用户未找到知识库并请求实际路径。
• 首次搜索无结果：尝试同义词、英文缩写、上位词、时间或版本字段。
• 候选文件过多：利用子索引和文件用途说明进一步收窄。
• 信息相互冲突：用户级优先；同时注明冲突来源和更新时间。
• 达到 5 轮仍不足：停止扩大检索，报告已查范围和需要用户补充的信息。

常见教训

• 不先读索引就全库扫描会浪费时间并产生大量无关上下文。
• 不应直接用纯文本工具硬读 PDF/Office 二进制文件。
• 转换稿和原始文件不要混淆；回答中注明实际依据来源。
• 知识库变动不更新索引会产生失效入口，是必须避免的维护错误。