开场：一份查不动的资料库 假设你有一堆本地资料：产品文档、销售报表、会议纪要，整整齐齐放在 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 /ai-market-guide/ ，把 SKILL.md 、 references/ 、 scripts/ 放进你的 skills 目录。
Step 2：放资料 + 生成索引 把文档放进工作区的 knowledge/ 目录（ md / pdf / xlsx 都行），然后运行一条命令生成目录地图： python scripts/build_index.py knowledge Step 3：用大白话问 不用记任何命令，像聊天一样问： 从知识库查一下 2024 年销售报表的关键数字 知识库里产品定价策略是怎么写的？ AI 助手会自动完成：看目录地图 → 定位相关文件 → 只读需要的部分 → 带来源回答。
和其他方案的区别 有人会问：为什么不直接上向量 RAG ？做个对比就清楚了： 向量 RAG 方案 xiaoyaoclaw-kb-retriever 依赖 embedding 模型 / 云端 API key / 本地 ML 运行时 grep + read + 按需装 Python 包，无云服务 索引 需要构建向量索引 轻量 data_structure.md 文本索引，一条命令生成 隐私 部分方案要上传云端 全本地，资料不出本机 平台 多为 Unix 向 Windows / macOS 双平台一等公民 语言 英文为主 中英双语 上下文开销 需加载索引 / 向量 渐进式检索，只读匹配窗口 两种方案不是替代关系，是适用场景不同。
向量 RAG 擅长模糊语义匹配，适合资料海量、问题开放的场景，代价是要建索引、要跑模型、可能要上云。而个人和中小团队的本地资料库——几十个文档、几百个文件——绝大多数问题都是「哪个文件里有这个数字」「这份报告结论是什么」，用目录定位加关键词检索，又快又准又省，多数情况下根本用不上向量索引。
写在最后 AI 助手搜索本地资料翻车，本质是搜索方式的问题：把整座资料库往上下文里塞，再大的上下文窗口也会被塞满。正确的做法，是让它学会像人一样查资料——先看目录，翻到相关页，只读需要的段落，最后告诉你出处。
这也是 kb-retriever 这个项目想做的事：给本地资料库一张地图，给 AI 助手一套省着读的方法。它是我们开源的「十件套」里的第四件。
这套体系覆盖了 AI 助手工作流的各个环节： 件 项目 定位 🏠 第一件 xiaoyaoclaw-workspace-initializer 给 agent 一个「家」：标准目录 + WORKSPACE.md 规范 + 配置安全 🧠 第二件 xiaoyaoclaw-memory-distill 记忆蒸馏：把会话蒸馏成永久记忆 🗂️ 第三件 xiaoyaoclaw-task-progress-tracker 任务进度：目录即容器， PROGRESS.md 即进度 📚 第四件 xiaoyaoclaw-kb-retriever 知识库检索：本地资料，问啥答啥（就是今天的主角） 🩺 第五件 xiaoyaoclaw-workspace-auditor 工作区体检：只读扫描，分级报告 📎 第六件 xiaoyaoclaw-web-clipper 网页剪藏：好内容一键存进知识库 🤝 第七件 xiaoyaoclaw-agent-orchestrator 多 Agent 协作：拆任务、分活、汇总、重试 📊 第八件 xiaoyaoclaw-usage-report 用量报告：任务耗时、token 消耗一目了然 🎛️ 第九件 xiaoyaoclaw-commander 跨工具指挥：让 Claude Code 等外部工具指挥 OpenClaw 🔍 第十件 xiaoyaoclaw-seo-skill 网站 SEO：审计 + AI 搜索优化（ AEO/GEO ） 它和十件套里其他项目的配合是直接的：initializer 定好的标准目录里就包含 knowledge/ ，正好是 kb-retriever 的默认检索根目录； web-clipper 把网页文章剪藏成 Markdown ，落进 knowledge/clippings/ 后，再运行一次 build_index.py ，新内容就能被检索到。
项目是 MIT 协议，开源免费，代码在 GitHub ，也可以直接从 ClawHub 安装。如果你也在给 AI 助手搭本地资料库，不妨试试让它学会「像人一样查资料」。
dtsola — IT 解决方案架构师 | 一人公司实践者 小遥项目： /ai-market-guide/ #OpenClaw #AI 助手 #开源项目 #知识库 #知识库检索 #本地优先 #RAG #效率工具 #一人公司 #人工智能