# Kb Retriever

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

- Skill: `kesepain-ke/kb-retriever` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add kesepain-ke/kb-retriever`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kesepain-ke/kb-retriever/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: kesepain-ke (https://skillmd.com/u/kesepain-ke)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kesepain-ke/kb-retriever

---


# 本地知识库检索 (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 二进制文件。
- 转换稿和原始文件不要混淆；回答中注明实际依据来源。
- 知识库变动不更新索引会产生失效入口，是必须避免的维护错误。