kb-retriever

1# 本地知识库检索 Skill（kb-retriever）
2 
3## 知识库目录说明
4 
5- 知识库存放在一个根目录下，包含多种文件类型（如 `.md`/`.txt`、`.pdf`、`.xlsx` 等），通常按类型或业务用途拆分为多级子目录。
6- 采用**分层目录索引文件**：
7  - 根目录有一个 `data_structure.md`，说明主要的「领域目录」及其用途。
8  - 每个领域目录下可以有自己的 `data_structure.md`，说明该目录下有哪些子目录/文件，以及各自用途。
9  - 更深一层的子目录也可以继续有 `data_structure.md`，形成多级索引树。
10- 知识库根目录约定：
11  - 默认认为知识库位于当前项目根目录下的 `knowledge/` 目录。
12  - 如果用户在对话中明确指定了其他路径（例如“我的知识库在 /data/kb”或“用 ./docs 这个目录作为知识库”），则以用户指定的路径作为根目录。
13  - 当默认路径 `knowledge/` 不存在或访问失败时，应向用户确认实际的知识库根目录位置，而不是随意猜测。
14- 单个业务文件可能很大：
15  - 不要直接用 Read 读取整文件
16  - 对 PDF、Excel 使用对应 Skill 进行结构化处理后，再结合 grep/局部读取做精细检索
17 
18### 定位 `knowledge` 根目录
19 
20- 根目录优先听用户：如果用户给了路径（如 `./docs`、`./knowledge-personal`），直接用用户提供的路径。
21- 默认根目录：否则约定根目录为当前项目下的 `knowledge/`。
22  - 使用 shell 显式检查目录是否存在：优先使用 `test -d knowledge`，或退而求其次使用 `ls -d knowledge`。
23  - 注意：禁止使用 `Glob "knowledge" in .` 这类模式来判断目录是否存在，`Glob` 只返回文件路径，不返回目录本身，空结果并不能区分“目录不存在”和“目录存在但为空”。
24- 只有在根目录已通过 `test -d` 等方式确认存在时，才使用 Glob 在该目录下检索内容，并把目录作为 `path`，例如：
25  - 索引文件：`pattern="**/data_structure.md"`, `path="knowledge"`
26  - 所有 Markdown：`pattern="**/*.md"`, `path="knowledge"`
27- 如果默认 `knowledge/` 不存在（`test -d` 失败）：不要猜测其他目录，明确告诉用户未找到默认根目录，并让用户指定实际知识库路径。
28 
29## 关键原则：先学习，再处理
30 
31**遇到 PDF 或 Excel 文件时的强制检查清单**：
32 
33- [ ] ✅ 已读取对应的 references 文档学习处理方法
34- [ ] ✅ 已理解推荐的工具和命令
35- [ ] ✅ 已将文件处理（提取/转换）完成
36- [ ] ⏭️ 现在可以开始检索
37 
38**禁止行为**：
39- ❌ 在未读取 pdf_reading.md 的情况下直接尝试处理 PDF
40- ❌ 在未读取 excel_reading.md 的情况下直接尝试处理 Excel
41- ❌ 跳过文件处理步骤，直接对原始 PDF/Excel 进行检索
42 
43## 总体流程
44 
451. 理解用户需求
46   - 读用户问题，提取：
47     - 主题/领域关键词（如“销售报表”“系统架构”“接口文档”）
48…