开场：一份查不动的资料库
假设你有一堆本地资料：产品文档、销售报表、会议纪要，整整齐齐放在 knowledge/ 目录里。你想让 AI 助手从中找一个数字，比如「2024 年华东区 Q3 的销售额」。
常见的结果有三种。
第一种，它把整个 Excel 文件一次性读进上下文。几 MB 的表格、几万行数据，直接把会话的上下文窗口塞满。轻则回答超时，重则读到一半就断，你得到的是一句「内容太多，我处理不了」。
第二种，它在目录里瞎翻。不知道资料库里有什么，就只能一层一层找，翻到哪算哪。文件少还好，文件一多，找东西全靠运气。
第三种最隐蔽：它找不到答案，又不肯承认，于是给你编一个看起来合理的数字。数字格式正确、单位正确，唯独不是真的——因为检索太贵，它选择了「猜」。
这三种结果，对应着三个典型的检索误区。AI 助手不是不会查资料，问题是它不会「省着」检索：一上来就想把整座图书馆搬进脑子里，而不是像人一样，先看目录，再翻到相关那一页。
为什么 AI 助手搜索本地资料容易翻车
问题出在四个地方。
上下文是稀缺资源。 AI 助手一次会话能处理的信息量是有限的，专业说法叫上下文窗口。整文件硬读等于把大半容量赌在一份文件上：资料稍微大一点，要么溢出，要么挤掉其他重要内容。用整文件硬读来检索，是一种成本极高的搜索方式。
没有目录意识。 AI 助手知道「怎么找」，但不知道「有什么」。没有索引导航，它就只能全目录扫描。扫描本身又慢又乱，还容易漏。人查资料不会从第一页翻起，因为人有目录；AI 助手没有目录，就只能蛮力。
格式处理没有章法。 PDF 有文字版和扫描版之分，Excel 常有多个 sheet。工具用错了，提取出来的就是一堆乱码和空行——垃圾进，垃圾出。很多搜索失败，不是没找到文件，是第一步就没读对。
动不动就上重武器。 一提到「知识库问答」，很多人第一反应是向量 RAG：embedding 模型、向量索引、云端 API key。为了找一个数字，要把整份资料库预处理、建索引，甚至上传到云端。成本高，配置重，隐私还悬着。
这四个问题叠加，结果就是：资料越重要、越庞大，AI 助手反而越不敢碰。
解法：像人查资料一样检索
我们做这个项目之前，先做了一次生态调研，结论很明确：本地知识库检索是整个 AI 技能生态里的空白带。搜索类技能很多，但绝大多数是网络搜索、论文检索、API 封装；真正定位「本地知识库检索问答」的，全生态只有个位数。而这几个里，要么要装运行时，要么要调云端 embedding，没有一个满足「轻量 + 本地 + 中文」三个条件。
唯一底子合格的是一个开源技能：ConardLi 的 kb-retriever（MIT 协议，GitHub 1.1 万 star）。它的机制是纯文本检索——分层索引 + 关键词定位 + 窗口读取，零外部依赖、不建向量索引、不调任何 API。设计思路就是「像人查资料」：先看目录地图，再翻到相关章节，只读需要的段落，最后标注出处。
但它有个问题：它是为 Claude Code、Cursor 这类工具写的，里面的工具名（Read、Grep、Glob）在 OpenClaw 生态里直接用不了，中文触发也弱，还没有发布到技能市场。
于是我们把它 fork 下来，做了一轮适配改造，发布了这个项目：xiaoyaoclaw-kb-retriever（OpenClaw Knowledge Base Retriever，知识库检索器）。它是我们开源「十件套」里的第四件。
改造保留了上游的精华机制，补上了五块短板：工具名适配 OpenClaw、中英双语触发、Windows/macOS 双平台命令、新增一键建索引脚本、发布到 ClawHub。下面说三个关键设计。
三个关键设计
① 目录地图：每层目录一份索引，顺着钻不整树扫
这个技能的核心，是给资料库画一张「目录地图」。
它在每一层目录里维护一份 data_structure.md 索引文件，记录这一层有什么子目录、每个目录装了什么、大致内容是什么。AI 助手收到提问后，不是一头扎进文件堆，而是先看根目录的索引，判断资料可能在哪个分支，再顺着索引树往下钻一层、看一层，直到定位到具体文件。
knowledge/
├── data_structure.md ← 总索引：这一层有什么
├── 产品文档/
│ ├── data_structure.md ← 子索引
│ └── 产品白皮书.pdf
├── 销售报表/
│ ├── data_structure.md
│ └── 2024-销售数据.xlsx
└── 会议纪要/索引越清晰，检索越快。但问题来了：索引谁来写？原版靠 AI 助手现场发挥，行为约束弱，建出来的索引质量不稳定。这是我们在改造里新增 build_index.py 脚本的原因——一条命令自动扫描目录树，生成索引骨架：
python scripts/build_index.py knowledge有新的资料进来，重跑一次即可；已有的索引会自动跳过，不会重复生成。不跑也能用，但跑了之后，AI 助手找东西快得多、准得多。
② 渐进式检索：翻书，不是背书
目录地图解决「去哪找」，渐进式检索解决「怎么读」。
这个技能有一条铁律：永远不全文件加载。它的检索是分步的：
先用关键词在目录范围内定位（Windows 上用
Select-String，macOS 上用grep），找到包含关键内容的文件和行号；
再用带行号范围的窗口读取（
offset/limit），只读匹配位置附近的内容；
信息不够，就再定位、再读，最多迭代 5 轮，直到凑齐答案。
整个过程像人翻书：先靠目录找到第 180 页，只读那一页，而不是把整本书背下来。遇到大 PDF，还有专门的按页范围提取脚本（extract_pdf_text.py），同样不整文件读入。
上下文开销被压到最低：检索一次资料，可能只消耗几千 token，而不是几十万。省下来的上下文，AI 助手才能同时处理多份资料、做对比、组织回答。
③ 先学后处理，来源可溯
检索之外，还有两道保险。
第一道叫「先学后处理」。PDF 和 Excel 各有各的读法：PDF 要区分文字版和扫描版，Excel 要注意多 sheet 和合并单元格。这个技能规定：遇到 PDF/Excel，AI 助手必须先读技能自带的处理教程（references），再动手提取。用对工具再干活，避免第一步就提取出一堆垃圾。
第二道叫「来源可溯」。AI 助手的回答必须带引用——文件路径加位置。每个数字、每句结论都能回溯到原始资料。这从根本上防住了「编一个看起来合理的数字」：想编可以，但出处对不上，一眼就能看穿。
另外补充一点：整个检索过程全在本地。不建向量索引、不调云端 API、不上传任何文件，PDF/Excel 处理需要时按需安装白名单 Python 包（pdfplumber、pandas），缺什么装什么。敏感资料不出本机，这对一人公司和中小企业尤其重要。
三步上手
整个安装到使用，大约 5 分钟。
Step 1：安装技能
clawhub install xiaoyaoclaw-kb-retriever或者从 GitHub 手动安装：git clone https://github.com/dtsola/xiaoyaoclaw-kb-retriever，把 SKILL.md、references/、scripts/ 放进你的 skills 目录。
Step 2：放资料 + 生成索引
把文档放进工作区的 knowledge/ 目录（md / pdf / xlsx 都行），然后运行一条命令生成目录地图：
python scripts/build_index.py knowledgeStep 3：用大白话问
不用记任何命令，像聊天一样问：
从知识库查一下 2024 年销售报表的关键数字
知识库里产品定价策略是怎么写的？
AI 助手会自动完成：看目录地图 → 定位相关文件 → 只读需要的部分 → 带来源回答。
和其他方案的区别
有人会问：为什么不直接上向量 RAG？做个对比就清楚了：
两种方案不是替代关系，是适用场景不同。向量 RAG 擅长模糊语义匹配，适合资料海量、问题开放的场景，代价是要建索引、要跑模型、可能要上云。而个人和中小团队的本地资料库——几十个文档、几百个文件——绝大多数问题都是「哪个文件里有这个数字」「这份报告结论是什么」，用目录定位加关键词检索，又快又准又省，多数情况下根本用不上向量索引。
写在最后
AI 助手搜索本地资料翻车，本质是搜索方式的问题：把整座资料库往上下文里塞，再大的上下文窗口也会被塞满。
正确的做法，是让它学会像人一样查资料——先看目录，翻到相关页，只读需要的段落，最后告诉你出处。这也是 kb-retriever 这个项目想做的事：给本地资料库一张地图，给 AI 助手一套省着读的方法。
它是我们开源的「十件套」里的第四件。这套体系覆盖了 AI 助手工作流的各个环节：
它和十件套里其他项目的配合是直接的：initializer 定好的标准目录里就包含 knowledge/，正好是 kb-retriever 的默认检索根目录；web-clipper 把网页文章剪藏成 Markdown，落进 knowledge/clippings/ 后，再运行一次 build_index.py，新内容就能被检索到。
项目是 MIT 协议，开源免费，代码在 GitHub，也可以直接从 ClawHub 安装。如果你也在给 AI 助手搭本地资料库，不妨试试让它学会「像人一样查资料」。
dtsola — IT解决方案架构师 | 一人公司实践者
用户交流和反馈群
扫码加入【小遥 AI · 用户交流群】——产品反馈、使用交流、功能建议（用户专属）。
#OpenClaw #AI助手 #开源项目 #知识库 #知识库检索 #本地优先 #RAG #效率工具 #一人公司 #人工智能
