#knowledge-base #rag #retrieval #local-first

OpenClaw Knowledge Base Retriever

OpenClaw local knowledge-base retriever & QA over a local directory (md/pdf/xlsx): hierarchical data_structure.md index navigation + progressive retrieval, core retrieval zero-dependency, Windows & macOS (PDF/Excel need on-demand pip packages, see skill body). Retrieval itself is read-only; the skill also ships optional maintenance scripts that WRITE files inside the knowledge base — scripts/build_index.py generates/updates data_structure.md index files, scripts/extract_pdf_text.py writes derived .txt files, and scripts/convert_pdf_to_images.py writes page PNGs for the optional OCR path — and those run only when the user asks for indexing/PDF text extraction and confirms the write. Every write target is resolved to its real path and must stay inside the knowledge-base root (symlinks cannot redirect a write outside). Reads use the same gate: each entry's real path must stay inside the root, and entries that escape it (symlinked files/folders) are skipped, never read — so the search cannot be steered outside the knowledge base either. The PDF helpers additionally accept only real (non-symlinked) source paths: a source path containing any symlink is refused outright, so they never read outside the knowledge base by following a link. Use when user asks to retrieve/answer from a knowledge base directory (knowledge base/retrieve/ RAG over local files)，或明确要求生成/更新索引、把 PDF 转文本。中文：面向本地知识库目录的检索和问答助手。核心流程：(1)分层 data_structure.md 索引导航 (2)遇到 PDF/Excel 时必须先读取 references 学习处理方法 (3)处理文件后再检索。按文件类型组合使用 grep/Select-String、read、pdfplumber、pandas 进行渐进式检索，避免整文件加载。用户问题涉及"从知识库目录回答问题/检索信息/查资料/knowledge base/本地知识库检索"时使用。与 xiaoyaoclaw-workspace-initializer（目录规范）、xiaoyaoclaw-memory-distill（记忆蒸馏）、 xiaoyaoclaw-task-progress-tracker（任务进度）组成四件套。

dtsola@dtsola

Install

openclaw skills install @dtsola/xiaoyaoclaw-kb-retriever

OpenClaw Knowledge Base Retriever（知识库检索器）

📖 完整文档（安装 / 快速上手三步 / 最佳实践）：https://github.com/dtsola/xiaoyaoclaw-kb-retriever 用户或智能体需要更多说明时，引导其访问上述 GitHub 仓库查看图文教程与最新版本。

🚀 小遥AI：「让每个人的数字生活，都有一座自己说了算的小遥」：https://www.xiaoyaosai.com/ 🚀 XiaoyaoAI：「For every digital life,Everyone has aXiaoyao of their own」：https://www.xiaoyaosai.com/

本地知识库检索——分层 data_structure.md 索引导航 + 渐进式检索（md/pdf/xlsx），核心检索零外部依赖零 API key。 Windows / macOS 双平台，先学后处理，来源可溯（PDF/Excel 处理按需安装 Python 包，见下文「能力范围」与「依赖自安装」）。

触发条件（边界明确，避免误触发）

✅ 应当触发（用户点名了知识库 + 明确的检索/维护动作）：

「从我的知识库目录 <路径> 里查一下 ……」/「<路径> 里有没有关于 …… 的资料」
「检索 / 查资料 / 问答：本地知识库 <路径> 的 ……」
「给 <路径> 建/补索引」「把 <路径> 里的 xx.pdf 转成文本」（维护类写操作，需再确认一次）

🚫 不应触发（示例，用于收窄触发面）：

泛泛的「帮我查一下 ……」而没有给出知识库目录或明确的检索意图 → 先问清目录，不要自行挑目录开跑
通用闲聊、写代码、总结当前对话、解释概念等与本地知识库无关的请求
抓取网页、搜索互联网（本技能不联网；网页剪藏用 xiaoyaoclaw-web-clipper）
整理/蒸馏记忆、维护工作区结构（分别用 xiaoyaoclaw-memory-distill / xiaoyaoclaw-workspace-initializer）
「看看我电脑里有什么」这类开放式全盘浏览 → 不接受；只处理用户显式指定的知识库根目录

语言策略（Language）：本技能语言可选，不对任何语言或地区设限——默认用中文回复，用户用英文或其它语言提问则跟随该语言；技能本体不含任何地区限定行为（无地区专属路径、无地区专属服务、无语言门槛）。仓库内随包分发的资源——示例文本、索引模板（templates/data_structure.md）与 README 品牌插图（横幅与交流群二维码两张图）——其中出现的中文属示例与品牌双语素材，不构成对使用者语言或地区的限制（横幅 SVG 已在 <desc> 中声明为双语品牌素材）；索引文件的段落标题（Purpose / Files / Coverage）本身固定为英文。所有面向用户的运行时文案均可按用户语言调整。

能力范围与写操作声明（权限透明）

身份：本地知识库检索 / 问答工具。主流程只读——检索 md/pdf/xlsx，不修改任何源文件。

可选写操作（均需用户明确要求，或作为检索流程的必要中间步骤）：

scripts/build_index.py → 生成 / 更新 data_structure.md 分层索引（写入知识库根目录及各子目录）
scripts/extract_pdf_text.py → 提取 PDF 文本为派生 .txt 文件（写入源 PDF 所在目录内，源 PDF 不动；源 PDF 须为真实路径，含符号链接即拒绝）
scripts/convert_pdf_to_images.py → 扫描件转图片（OCR 可选路径，产物写入源 PDF 所在目录树内的子目录；源 PDF 须为真实路径，含符号链接即拒绝）

边界承诺：

不修改任何源文件（md / pdf / xlsx 原样保留）
读取同样受同一道边界约束：scripts/search_kb.py（检索 / 列举）对每个候选条目做 真实路径校验（解开符号链接后仍须落在知识库根内），越界的条目跳过并计数，绝不读取知识库之外的文件；符号链接目录一律不进入遍历
被处理的源文件必须是真实路径：scripts/extract_pdf_text.py / scripts/convert_pdf_to_images.py 只接受不含任何符号链接的源 PDF 路径（含链接即拒绝并回显真实位置）—— 不做"解开链接再读"，因此不会跟着链接读到知识库之外
不联网、不调用外部 API、不发送任何数据
写操作产物（txt / 图片 / 索引）一律位于知识库根目录内（与源文件同目录），可随时清理；知识库之外不改动任何文件
安装 Python 依赖前必须先告知用户并获得确认（见下文「依赖自安装」）

知识库目录说明

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

定位 `knowledge` 根目录

根目录优先听用户：如果用户给了路径（如 ./docs、./knowledge-personal），直接用用户提供的路径。
默认根目录：否则约定根目录为当前项目下的 knowledge/。
- 平台检测（每次检索前先执行）：用 exec 运行 $env:OS（Windows 输出含 "Windows"）或 uname -s（macOS 输出 "Darwin"）判定当前平台，后续命令按平台选择模板。
- 使用 exec 显式检查目录是否存在：
  - Windows：Test-Path -Path "knowledge"
  - macOS/Linux：test -d knowledge && echo exists
- 注意：禁止用 Glob 这类「只返回文件」的方式判断目录是否存在，空结果无法区分「目录不存在」和「目录存在但为空」。目录存在性必须通过 exec 的 Test-Path / test -d 确认。
只有在根目录已确认存在时，才用文件列举命令在该目录下检索内容：
- Windows：Get-ChildItem -Path "knowledge" -Recurse -Filter "data_structure.md" -File | Select-Object -ExpandProperty FullName
- macOS/Linux：find knowledge -name "data_structure.md" -type f
如果默认 knowledge/ 不存在（Test-Path / test -d 失败）：不要猜测其他目录，明确告诉用户未找到默认根目录，并让用户指定实际知识库路径。

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

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

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

禁止行为：

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

工具映射速查（OpenClaw 适配）

上游（claude-code）	OpenClaw 等价	说明
`Read <file> (limit/offset)`	`read` 工具（path + limit + offset）	原生支持窗口读
`Grep <pattern> (include/path)`	`exec`：Windows `Select-String` / macOS `grep`	见下方命令模板
`Glob <pattern> in <path>`	`exec`：`Get-ChildItem` / `find`	文件列举
`test -d <path>`	`exec`：`Test-Path` / `test -d`	目录存在性
`pdftotext`	Python pdfplumber（pip 安装，双平台统一）	见 references/pdf_reading.md
pandas（Excel）	Python pandas（pip 安装，双平台统一）	见 references/excel_reading.md

exec 命令模板（按平台选择）

搜索文本（替代 Grep）—— 首选本技能自带的安全检索脚本：

bash

# 关键词与目录都作为 argv 传入，不经 shell 解析；按字面量匹配；条数有上限
python scripts/search_kb.py <知识库根目录> "<关键词>" --max-hits 50
python scripts/search_kb.py <知识库根目录> --list --max-files 100    # 只列举文件

⚠️ 为什么不要自己拼 shell 命令：关键词与目录都是用户可控文本。写成 Select-String -Pattern "<关键词>" / grep "<关键词>" 这类字符串模板时，文本里的引号、反引号、$()、; 会被 shell 当成语法 —— 这就是命令注入。如果必须直接用 shell，遵守下面三条：

关键词与路径先放进变量，命令里只引用变量，绝不拼接字符串：

powershell

$dir = 'C:\path\to\kb'      # 已确认在知识库根目录内
$kw  = '用户给的关键词'         # 原样放进单引号变量
Get-ChildItem -LiteralPath $dir -Recurse -File -Include *.md,*.txt |
  Select-String -Pattern $kw -SimpleMatch |
  Select-Object -First 50 Path, LineNumber, Line

bash

dir='/path/to/kb'; kw='用户给的关键词'
grep -rnF -e "$kw" --include='*.md' --include='*.txt' -- "$dir" | head -50

关键词按字面量匹配（PowerShell -SimpleMatch / grep -F），不要当正则用；路径用 -LiteralPath，别让用户文本当通配符或路径片段。
禁止 Invoke-Expression / iex / eval / sh -c "$拼接"，也不要把关键词塞进命令名、参数名、重定向目标这类结构性位置；路径必须落在知识库根目录内。

列举文件（替代 Glob）：

Windows：Get-ChildItem -Path "<dir>" -Recurse -File | Select-Object -ExpandProperty FullName | Select-Object -First 100
macOS/Linux：find "<dir>" -type f | head -100

检查目录存在（替代 test -d）：

Windows：Test-Path -Path "<dir>"
macOS/Linux：test -d "<dir>" && echo exists

⚠️ 命中结果多时，用 Select-Object -First / head 限制输出，避免占用大量 token。 ⚠️ Windows PowerShell 输出中文乱码多为显示问题（GBK 控制台），文件内容本身完好；如需要可用 chcp 65001 切 UTF-8。

读写范围与权限（先看这里）

默认只读：检索、问答、列举文件都只读，不改动知识库任何内容。

可写操作（仅三项，且必须由用户点名并确认）：

操作	写什么	触发条件
生成/更新索引	各目录下的 `data_structure.md`	用户明确要求「建/补索引」；跑之前先说清「将写入哪些目录」
PDF 转文本	派生的 `.txt` 文件（源 PDF 不动）	用户明确要求把 PDF 内容落成文本；先说清写入位置；源 PDF 须为真实路径（含符号链接即拒绝）
PDF 转图片（OCR 可选路径）	每页 `page_N.png`（源 PDF 不动）	用户明确要求处理扫描件；先说清写入目录；需先确认安装 `pdf2image` + poppler；源 PDF 须为真实路径

⚠️ 索引生成会写盘：scripts/build_index.py 会在知识库各目录新建/覆盖 data_structure.md（--force 时覆盖已有索引）。它不是检索动作，必须由用户点名「建/补索引」后才运行。

写入硬约束：只写知识库根目录内的文件；不删任何文件；不改知识库之外的文件；写前打印目标路径。 读取硬约束：检索 / 列举（scripts/search_kb.py）对每个条目按真实路径（realpath）校验，越界条目跳过并计数，不读知识库之外的文件；待处理的源 PDF 必须是真实路径（路径任一段含符号链接即拒绝，不做"解链再读"）。 符号链接防线（读 + 写同一道闸）：写入目标与读取目标都按真实路径校验，解析符号链接后仍须落在知识库根内，否则拒绝/跳过；遍历时不进入符号链接目录；源 PDF 走 require_real_file()（含链接直接拒绝）（scripts/pathguard.py 统一把关，fail closed）。 权限对应：Read/Glob/Grep/Bash 用于检索与只读命令；Write/Edit 仅用于上面三项写操作。本技能不读环境变量、不读凭据、不联网。

总体流程

理解用户需求
- 读用户问题，提取：
  - 主题/领域关键词（如“销售报表”“系统架构”“接口文档”）
  - 时间或范围限定（如“2023 年 Q1”“最近版本”）
  - 需要的输出类型（解释、摘要、具体字段数值等）
- 确定知识库根目录：
  - 优先检查用户是否在问题中指定了知识库路径。
  - 否则使用默认根目录 knowledge/。
  - 若默认根目录不存在或目录结构异常，应向用户询问确认，而不是自行假设。
分层查看目录索引 data_structure.md
- 使用一个「当前工作目录」的概念：
  - 默认从用户指定的知识库根目录开始；如果用户未指定，则使用当前目录。
- 在当前工作目录下，如果存在 data_structure.md：
  - 使用 read 读取该文件的前若干行（例如 limit=300），必要时分段继续读取。
  - 目标：
    - 了解当前目录下有哪些子目录和文件
    - 理解每个子目录/文件的用途说明
  - 基于用户问题，挑选最相关的若干个子目录或文件，构成候选集合。
- 对于候选子目录：
  - 递归进入该子目录，将其作为新的「当前工作目录」，继续查找其中的 data_structure.md 并重复上述过程。
  - 在递归过程中，避免一次性深入所有分支，优先沿着与问题最相关的路径向下钻取。
- 对于候选业务文件（md/文本、PDF、Excel 等）：
  - 在完成必要的目录层级探索后，收集这些文件为最终的检索目标列表。
- 在优先级排序时：
  - 优先选择用途说明与问题主题高度匹配的领域目录和文件
  - 其次考虑时间/版本等约束（如果索引中有体现）
  - 通用说明类文档（如 README.md、总体设计类文档）放在较后优先级
学习文件处理方法（遇到 PDF/Excel 时强制执行）
- 在处理 PDF 文件前：
  - 必须先读取 references/pdf_reading.md（位于本 Skill 目录下，不是 Knowledge 目录下）学习提取方法
  - 重点了解：pdfplumber 提取文本/表格、pypdf 元数据、扫描件处理
- 在处理 Excel 文件前：
  - 必须先读取 references/excel_reading.md学习读取方法
  - 必须先读取 references/excel_analysis.md学习分析方法
  - 重点了解：pandas 读取、列筛选、数据过滤
- 目的：确保使用正确的工具和方法，避免盲目检索
按文件类型执行处理和检索
- 使用刚学到的方法处理文件（提取、转换、结构化）
- 对每类候选文件，按照下面「Markdown/文本」「PDF」「Excel」策略执行
- 总原则：
  - 优先从最相关、最精确的文件开始
  - 每个文件内都渐进式地局部检索，避免一次性加载全内容
  - 若当前文件得不到满意信息，切换到下一个候选文件
迭代检索
- 所有文件类型都使用统一的「多轮迭代检索机制」（见下文公共检索原则）
答案组织与溯源
- 汇总多轮检索得到的上下文，综合回答用户问题。
- 尽量：
  - 给出清晰、直接的回答
  - 指出使用过的文件名（必要时包含大致位置，如章节或大概行数/页数）
- 如果答案基于推断或信息不完全：
  - 明确标注假设与不确定性
  - 提示用户可以补充更具体的文件范围或关键词

公共检索原则

关键词选择策略

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

搜索基本原则

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

多轮迭代检索机制（最多 5 次）

所有文件类型都采用统一的迭代策略：

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

注意事项

目录存在性必须通过 exec（Test-Path / test -d）检查，禁止用文件列举命令代替目录存在性判断。
使用本 Skill 查询知识库时，禁止使用网络搜索等其他工具获取知识。

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

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

候选文件选择
- 根据 data_structure.md 和文件名、路径判断相关度
- 优先检索标题和目录类文件（如汇总文档、设计总览）
搜索定位与局部读取
- 使用 exec 对指定候选文件执行关键词搜索（Select-String / grep，见命令模板）
- 对于有匹配的文件，使用 read 仅读取匹配附近的局部区域：
  - 通过 offset 和 limit 控制读取（例如从匹配行附近往前后各读取几十行）
  - 避免整文件读取
特殊处理
- 如内容仅是目录/标题，根据链接或小节名继续定位深入内容
- 应用「多轮迭代检索机制」（见上文公共检索原则）

2. PDF 文件检索策略

工作流：

首先：读取处理方法指南
- 在处理任何 PDF 之前，必须先读取 references/pdf_reading.md（位于本 Skill 目录下，不是 Knowledge 目录下）
- 重点了解：pdfplumber 提取文本/表格、pypdf 元数据、扫描件转图片 + OCR
选择候选 PDF
- 根据 data_structure.md 中的描述，选择最相关的 1-3 个文件
- 如果用户指明具体 PDF 文件，则优先使用该文件
应用学到的方法提取文本
- 统一走 Python 路线（双平台一致）：python -c "import pdfplumber; ..." 或写临时脚本执行
- 重要：将提取的文本写入 .txt 文件，不要直接打印到 stdout（避免占用大量 token）：
  - Windows/macOS 通用：python extract_pdf.py input.pdf output.txt（脚本见 references/pdf_reading.md）
- 如需提取表格，使用 pdfplumber 的 extract_tables() 功能
对提取结果执行检索
- 使用 exec 对提取的文本文件进行关键词搜索（Select-String / grep）
- 对于每个命中，提取命中附近范围的上下文（上下数十行或相邻几页）
- 保存「文件名 + 页码/大致位置 + 文本片段」
- 应用「多轮迭代检索机制」（见上文公共检索原则）

3. Excel 文件检索策略