---
name: kb_retriever
description: 面向本地知识库目录的检索和问答助手。核心流程：(1)分层索引导航 (2)遇到PDF/Excel时必须先读取references学习处理方法 (3)处理文件后再检索。使用 read_file、list_dir、run_command(grep/findstr)、convert_to_markdown 进行渐进式检索，避免整文件加载。用户问题涉及"从知识库目录回答问题/检索信息/查资料"时使用。
---

# 本地知识库检索 Skill（kb-retriever）

## 知识库目录说明

- 知识库采用**双层架构**（用户级 + 全局级），每层包含多种文件类型（如 `.md`/`.txt`、`.pdf`、`.xlsx` 等），通常按类型或业务用途拆分为多级子目录。
- 顶层 `data_structure.md` 已由引擎注入 system prompt，AI 可直接使用索引地图，无需重复读取。
- 子目录内的 `data_structure.md` 需要时按需读取。
- 采用**分层目录索引文件**：
  - 根目录有一个 `data_structure.md`，说明主要的「领域目录」及其用途。
  - 每个领域目录下可以有自己的 `data_structure.md`，说明该目录下有哪些子目录/文件，以及各自用途。
  - 更深一层的子目录也可以继续有 `data_structure.md`，形成多级索引树。
- 知识库采用**双层架构**：
  - **用户级知识库**：`users/<当前用户名>/knowledge/` — 默认读写目标，用户上传/创建的文档放这里
  - **全局知识库**：项目根 `knowledge/` — 默认只读，所有用户共享的参考文档
  - 检索时**同时搜索两层**，用户级结果优先展示
  - 如果用户在对话中明确指定了其他路径（例如"我的知识库在 /data/kb"），则以用户指定的路径作为根目录
- **写入规则**：
  - 默认写入用户级知识库
  - 只有用户明确说"写入全局知识库""保存到全局"等类似表述时，才写入全局知识库
  - 禁止在未经用户明确指示的情况下修改全局知识库
- 单个业务文件可能很大：
  - 不要直接用 read_file 读取整文件
  - 对 PDF、Excel 优先用 convert_to_markdown 转换，再结合 grep/局部读取做精细检索

### 定位知识库根目录

- 两层知识库：
  - 用户级：`users/<当前用户名>/knowledge/`
  - 全局级：项目根 `knowledge/`
- 根目录优先听用户：如果用户给了路径，直接用用户提供的路径
- 检索时**同时搜索两层**：
  - 使用 `list_dir` 检查用户级目录是否存在
  - 同时检查全局 `knowledge/` 目录
  - 两层都存在时，合并检索结果，用户级优先
- 如果两层都不存在：明确告诉用户未找到知识库目录，让用户指定实际路径
- **重要**：除非用户明确指示，不要对全局知识库进行写入操作

## 关键原则：先学习，再处理

**遇到 PDF 或 Excel 文件时的强制检查清单**：

- [ ] ✅ 已读取对应的 references 文档学习处理方法
- [ ] ✅ 已理解推荐的工具和命令
- [ ] ✅ 已将文件处理（提取/转换）完成
- [ ] ⏭️ 现在可以开始检索

**禁止行为**：
- ❌ 在未读取 pdf_reading.md 的情况下直接尝试处理 PDF
- ❌ 在未读取 excel_reading.md 和 excel_analysis.md 的情况下直接尝试处理 Excel
- ❌ 跳过文件处理步骤，直接对原始 PDF/Excel 进行检索

## 总体流程

1. 理解用户需求
   - 读用户问题，提取：
     - 主题/领域关键词（如"销售报表""系统架构""接口文档"）
     - 时间或范围限定（如"2023 年 Q1""最近版本"）
     - 需要的输出类型（解释、摘要、具体字段数值等）
   - 确定知识库根目录：
     - 优先检查用户是否在问题中指定了知识库路径。
     - 否则同时使用两层：用户级 `users/<当前用户名>/knowledge/` + 全局 `knowledge/`。
     - 若两层都不存在或目录结构异常，应向用户询问确认，而不是自行假设。

2. 分层查看目录索引 `data_structure.md`
   - 顶层 `data_structure.md` 已注入 system prompt，直接使用其中信息定位文件。
   - 对于子目录：如果 system prompt 中的索引不够详细，进入子目录读取其中的 `data_structure.md`。
   - 在当前工作目录下，如果存在 `data_structure.md`：
     - 使用 read_file 读取该文件（索引文件通常较小，可全文读取）。
     - 目标：
       - 了解当前目录下有哪些子目录和文件
       - 理解每个子目录/文件的用途说明
     - 基于用户问题，挑选**最相关的若干个子目录或文件**，构成候选集合。
   - 对于候选子目录：
     - 递归进入该子目录，将其作为新的「当前工作目录」，继续查找其中的 `data_structure.md` 并重复上述过程。
     - 在递归过程中，避免一次性深入所有分支，优先沿着与问题最相关的路径向下钻取。
   - 对于候选业务文件（md/文本、PDF、Excel 等）：
     - 在完成必要的目录层级探索后，收集这些文件为最终的**检索目标列表**。
   - 在优先级排序时：
     - 优先选择用途说明与问题主题高度匹配的领域目录和文件
     - 其次考虑时间/版本等约束（如果索引中有体现）
     - 通用说明类文档（如 README.md、总体设计类文档）放在较后优先级

3. 学习文件处理方法（遇到 PDF/Excel 时强制执行）
   - **在处理 PDF 文件前**：
     - **必须先读取** `skills/kb-retriever/references/pdf_reading.md` 学习提取方法
     - 重点了解：convert_to_markdown 方法、pdftotext 命令、pdfplumber 用法、表格提取方法
   - **在处理 Excel 文件前**：
     - **必须先读取** `skills/kb-retriever/references/excel_reading.md` 学习读取方法
     - **必须先读取** `skills/kb-retriever/references/excel_analysis.md` 学习分析方法
     - 重点了解：convert_to_markdown 方法、pandas 读取、列筛选、数据过滤
   - **目的**：确保使用正确的工具和方法，避免盲目检索

4. 按文件类型执行处理和检索
   - 使用刚学到的方法处理文件（提取、转换、结构化）
   - 对每类候选文件，按照下面「Markdown/文本」「PDF」「Excel」策略执行
   - 总原则：
     - 优先从最相关、最精确的文件开始
     - 每个文件内都渐进式地局部检索，避免一次性加载全内容
     - 若当前文件得不到满意信息，切换到下一个候选文件

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

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

## 公共检索原则

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

### 渐进式检索原则
- 对文件先用关键词 grep 定位，再针对性 read_file
- 始终在尽可能小的范围内检索，避免全文加载
- pattern 优先尝试问题中的核心名词、术语，再尝试同义词
- 对于每个命中，读取匹配附近的局部区域
- 保存「文件名 + 位置信息 + 文本片段」

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

### 注意事项

- 检索前先确认两层知识库目录是否存在（system prompt 中已标明路径和索引）。
- 使用本 Skill 查询知识库时，禁止使用网络搜索等其他工具获取知识。
- read_file 不支持行号偏移和行数限制，对大文件先用 grep 定位再决定是否需要 read_file。
- 顶层 data_structure.md 已注入 system prompt，直接从注入内容中获取目录结构，无需重复 read_file。

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

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

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

2. **grep 定位与局部读取**
   - 使用 run_command 执行 grep 对指定候选文件搜索关键词：
     - Linux/WSL: `grep -n -i "关键词" 文件路径`
     - Windows: `findstr /n /i "关键词" 文件路径`
   - 对于有匹配的文件，使用 read_file 读取文件（通常 .md 索引文件不大，可全文读取）
   - 对于大文件，用 grep 的上下文参数获取局部内容：
     - `grep -n -i -C 10 "关键词" 文件路径`（前后各 10 行）

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

### 2. PDF 文件检索策略

**工作流**：

1. **首先：读取处理方法指南**
   - 在处理任何 PDF 之前，**必须先读取** `skills/kb-retriever/references/pdf_reading.md`
   - 重点了解：convert_to_markdown 方法、pdftotext 命令、pdfplumber 用法、表格提取方法

2. **选择候选 PDF**
   - 根据 `data_structure.md` 中的描述，选择最相关的 1-3 个文件
   - 如果用户指明具体 PDF 文件，则优先使用该文件

3. **应用学到的方法提取文本**
   - **首选方法**：使用 `convert_to_markdown` 工具将 PDF 转换为 Markdown 文本
     - 这会自动处理文本提取，结果可直接用 grep 检索
   - **备选方法**：使用 pdftotext 提取文本到文件
     - `pdftotext input.pdf output.txt`
     - 重要：输出到文件，不要输出到 stdout（避免占用大量 token）
   - 如需提取表格，使用 pdfplumber 的表格提取功能

4. **对提取结果执行检索**
   - 使用 grep 对提取的文本/Markdown 进行关键词搜索
   - 对于每个命中，提取命中附近范围的上下文
   - 保存「文件名 + 页码/大致位置 + 文本片段」
   - 应用「多轮迭代检索机制」（见上文公共检索原则）

### 3. Excel 文件检索策略

**工作流**：

1. **首先：读取处理方法指南**
   - 在处理任何 Excel 之前，**必须先读取**：
     - `skills/kb-retriever/references/excel_reading.md` - 学习如何读取工作表
     - `skills/kb-retriever/references/excel_analysis.md` - 学习如何分析数据
   - 重点了解：convert_to_markdown 方法、pandas 读取方法、列筛选、数据过滤、聚合操作

2. **选择候选 Excel**
   - 根据 `data_structure.md` 和文件/工作表命名，选择最相关的表
   - 优先选择包含「报表」「统计」「日志」「配置」「映射」等关键词的工作簿/工作表
   - 若用户指明具体 Excel 文件，优先使用该文件

3. **应用学到的方法探索结构**
   - **首选方法**：使用 `convert_to_markdown` 工具将 Excel 转换为 Markdown 表格
     - 快速预览数据结构，了解列名和内容
   - **备选方法**：使用 pandas 读取前 10-50 行（使用 `nrows` 参数限制）
   - 重点掌握：列名/字段名、数据类型（数值、日期、文本）、关键字段
   - 将列名与用户问题比对，识别潜在关键字段（如「收入」「销售额」「error_code」等）

4. **执行数据检索和分析**
   - 使用学到的 pandas 方法进行过滤和聚合（如 `df[df['column'] == value]`）
   - 每次只读取匹配行附近的数据，避免一次性读取整表
   - 如问题包含时间范围，在检索中加入时间过滤
   - 应用「多轮迭代检索机制」（见上文公共检索原则）

## 工具映射参考

本 Skill 适用的 votx-agent 工具：

| 目的 | 使用工具 | 说明 |
|------|----------|------|
| 列出目录 | `list_dir` | 查看目录结构 |
| 读取文件 | `read_file` | 读取小文件或索引文件 |
| 搜索文本 | `run_command` + grep/findstr | 在文件中定位关键词 |
| PDF/Excel转换 | `convert_to_markdown` | 将 PDF/Excel 转为 Markdown 文本 |
| 执行脚本 | `run_command` | 运行 Python 脚本处理数据 |

## 回答风格与错误处理

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