| name | kb_retriever |
| description | 本地双层知识库检索与问答。用户要求从知识库、资料目录或本地文档中查信息、总结、核对来源时使用。先按 data_structure.md 分层导航，再渐进检索候选文件；遇到 PDF/Excel 时先读取本 Skill 的 references 处理指南。 |
本地知识库检索 (KB Retriever)
从用户级和全局级知识库中渐进检索信息，并给出可追溯答案。
插件路径
plugins/kb_retriever/
知识库层级
| 层级 | 路径 | 优先级 | 默认权限 |
|---|
| 用户级 | users/<name>/knowledge/ | 高 | 读写 |
| 全局级 | knowledge/ | 低 | 只读 |
检索时同时检查两层，同类结果以用户级为准。用户明确指定其他目录时，以用户路径为根目录。
核心流程
- 从问题提取主题、时间、版本、字段和输出要求。
- 使用已注入的根
data_structure.md 索引定位候选目录；需要时读取最近的子索引。
- 选择最相关的少量候选文件，不遍历所有分支。
- 文本文件先搜索关键词，再按行读取命中附近内容。
- PDF/Excel 先读取对应 references，再转换或提取到临时文本后搜索。
- 最多迭代 5 轮，调整同义词、英文缩写、范围和候选文件。
- 先给结论，再列依据、文件路径和位置；信息不足时明确说明。
强制 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 是指令型技能，不注册工具。回答应包含：
- 直接结论；
- 简要判断依据；
- 来源文件和章节/行号/页码（能定位时）；
- 不确定性与缺失信息。
常见规范
- 顶层索引已注入 system prompt 时不重复读取。
- 先索引导航，后内容搜索；先精确候选，后扩大范围。
- 本地知识库问答默认不混入网络搜索结果，除非用户另行要求。
- 不把用户私有资料复制到全局知识库。
常见处理办法
- 两层目录都不存在：告诉用户未找到知识库并请求实际路径。
- 首次搜索无结果：尝试同义词、英文缩写、上位词、时间或版本字段。
- 候选文件过多：利用子索引和文件用途说明进一步收窄。
- 信息相互冲突：用户级优先；同时注明冲突来源和更新时间。
- 达到 5 轮仍不足：停止扩大检索，报告已查范围和需要用户补充的信息。
常见教训
- 不先读索引就全库扫描会浪费时间并产生大量无关上下文。
- 不应直接用纯文本工具硬读 PDF/Office 二进制文件。
- 转换稿和原始文件不要混淆；回答中注明实际依据来源。
- 知识库变动不更新索引会产生失效入口，是必须避免的维护错误。
