kb-retriever

Files (8)

• README.md
• README.zh-CN.md
• SKILL.md
• manifest.json
• excel_analysis.md · references/
• excel_reading.md · references/
• pdf_reading.md · references/
• convert_pdf_to_images.py · scripts/

SKILL.md (first lines)

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

## 知识库目录说明

- 知识库存放在一个根目录下，包含多种文件类型（如 `.md`/`.txt`、`.pdf`、`.xlsx` 等），通常按类型或业务用途拆分为多级子目录。
- 采用**分层目录索引文件**：
  - 根目录有一个 `data_structure.md`，说明主要的「领域目录」及其用途。
  - 每个领域目录下可以有自己的 `data_structure.md`，说明该目录下有哪些子目录/文件，以及各自用途。
  - 更深一层的子目录也可以继续有 `data_structure.md`，形成多级索引树。
- 知识库根目录约定：
  - 默认认为知识库位于当前项目根目录下的 `knowledge/` 目录。
  - 如果用户在对话中明确指定了其他路径（例如“我的知识库在 /data/kb”或“用 ./docs 这个目录作为知识库”），则以用户指定的路径作为根目录。
  - 当默认路径 `knowledge/` 不存在或访问失败时，应向用户确认实际的知识库根目录位置，而不是随意猜测。
- 单个业务文件可能很大：
  - 不要直接用 Read 读取整文件
  - 对 PDF、Excel 使用对应 Skill 进行结构化处理后，再结合 grep/局部读取做精细检索

### 定位 `knowledge` 根目录

- 根目录优先听用户：如果用户给了路径（如 `./docs`、`./knowledge-personal`），直接用用户提供的路径。
- 默认根目录：否则约定根目录为当前项目下的 `knowledge/`。
  - 使用 shell 显式检查目录是否存在：优先使用 `test -d knowledge`，或退而求其次使用 `ls -d knowledge`。
  - 注意：禁止使用 `Glob "knowledge" in .` 这类模式来判断目录是否存在，`Glob` 只返回文件路径，不返回目录本身，空结果并不能区分“目录不存在”和“目录存在但为空”。
- 只有在根目录已通过 `test -d` 等方式确认存在时，才使用 Glob 在该目录下检索内容，并把目录作为 `path`，例如：
  - 索引文件：`pattern="**/data_structure.md"`, `path="knowledge"`
  - 所有 Markdown：`pattern="**/*.md"`, `path="knowledge"`
- 如果默认 `knowledge/` 不存在（`test -d` 失败）：不要猜测其他目录，明确告诉用户未找到默认根目录，并让用户指定实际知识库路径。

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

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

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

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

## 总体流程

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

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

3. 学习文件处理方法（遇到 PDF/Excel 时强制执行）
   - **在处理 PDF 文件前**：
     - **必须先读取** [references/pdf_reading.md](references/pdf_reading.md)（注意这个目录位于 Skills 目录下，而不是 Knowledge 目录下）学习提取方法
     - 重点了解：pdftotext 命令、pdfplumber 用法、表格提取方法
   - **在处理 Excel 文件前**：
     - **必须先读取** [references/excel_reading.md](references/excel_reading.md)学习读取方法
     - **必须先读取** [references/excel_analysis.md](references/excel_analysis.md)学习分析方法
     - 重点了解：pandas 读取、列筛选、数据过滤
   - **目的**：确保使用正确的工具和方法，避免盲目检索

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

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

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

## 公共检索原则

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

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

### 多轮迭代检索机制（最多 5 次）
所有文件类型都采用统一的迭代策略：
1. **迭代控制**

From novolei/uclaw-new, Apache-2.0.

More from novolei/uclaw-new