别让 AI 背资料库，让它翻资料库

开场：一份查不动的资料库

假设你有一堆本地资料：产品文档、销售报表、会议纪要，整整齐齐放在 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 助手找东西快得多、准得多。

② 渐进式检索：翻书，不是背书

目录地图解决「去哪找」，渐进式检索解决「怎么读」。

这个技能有一条铁律：永远不全文件加载。它的检索是分步的：

1. 先用关键词在目录范围内定位（ Windows 上用 Select-String，macOS 上用 grep），找到包含关键内容的文件和行号；
2. 再用带行号范围的窗口读取（offset / limit），只读匹配位置附近的内容；
3. 信息不够，就再定位、再读，最多迭代 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 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 解决方案架构师 | 一人公司实践者

小遥项目：https://project.xiaoyaosai.com/

---

#OpenClaw #AI 助手 #开源项目 #知识库 #知识库检索 #本地优先 #RAG #效率工具 #一人公司 #人工智能