1. 为什么向量检索在知识库场景里越来越不够用如果你正在做企业知识库问答、代码助手或者文档检索系统大概率已经踩过这样的坑用户问“系统怎么防止恶意登录”向量检索返回了一堆讲“安全策略”的段落但真正包含“登录失败锁定”“验证码触发条件”的那几行代码或配置反而没被召回。问题不在 embedding 模型不够好而在于向量检索本质上是在做“语义相似度排序”它不保证精确命中也不理解文档的章节结构。传统 RAG 的流程大家都熟切块、嵌入、存向量库、查询时取 Top-K、拼进 Prompt。这套方案在文档量不大、问题比较泛的时候够用但一旦知识库变成几百份手册、上万行代码缺陷就暴露得很明显。切块会切断上下文一个完整的操作步骤可能被拆到三个 chunk 里向量匹配依赖嵌入质量调试时你很难说清到底是“没搜到”还是“搜到了但排序靠后”更麻烦的是索引维护文档一更新就得重新嵌入稍不注意就出现“索引陈旧”导致答非所问。我试过在一个 300 多篇技术文档的库里做对比纯向量方案在“精确查找某个配置项”这类问题上召回率经常掉到 60% 以下。而换一种思路——让大模型像人一样先看目录、再决定去哪个文件里 grep 关键词——同样的库准确率能拉到 90% 以上。这就是 Agent 式检索要解决的问题把“盲目语义匹配”换成“主动结构导航 精确文本搜索”。这篇文章会带你从零搭一套可运行的 Agent 检索骨架核心工具就是 grep 加一个大模型接口。你不需要向量数据库不需要 embedding 服务只需要一个能调工具函数的模型和一份结构化的文档目录。下面按“前置准备 → 配置骨架 → 验证请求 → 排错”的顺序走一遍。2. TaoToken 前置把模型接口和工具调用能力准备好Agent 检索的“大脑”是一个支持 function calling 的大模型。你可以用 GPT-5、Claude 或者 DeepSeek关键是要能通过 API 让模型输出结构化的工具调用请求。这里我用 TaoToken 作为统一接入层原因是它同时提供 OpenAI 兼容接口和 Claude 系列模型切换模型时不用改代码结构对做对比实验很方便。你需要先拿到一个 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新 Key复制保存。注意 Key 只在创建时显示一次丢了就得重新生成。如果你还没注册从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去注册即可。拿到 Key 之后记下两个地址对话补全的基础地址是https://taotoken.net/api模型列表可以在 https://taotoken.net/doc 查到。TaoToken 的接口格式和 OpenAI 官方一致所以你可以直接用 openai 的 SDK只需要把 base_url 改掉。这一点对后面写 Agent 循环很关键因为 function calling 的请求和响应结构完全兼容。注意不要把 API Key 硬编码在代码里提交到仓库。用环境变量或者本地 .env 文件管理后面配置骨架里我会给出具体写法。模型选择上做 Agent 检索建议用推理能力强的型号。GPT-5 在工具调用和多步推理上表现稳定Claude 系列对长文档结构的理解也不错。你可以在 https://taotoken.net/models 看到当前可用的模型列表选一个支持 function calling 的就行。如果只是做验证先用便宜的小模型跑通流程再换大模型提升效果。3. 可复制的 Agent 检索配置骨架这一节是核心我会给出一个完整的 Node.js 骨架包含三部分知识库目录生成、grep 工具函数、Agent 循环。你可以直接复制到本地跑。3.1 知识库预处理生成目录索引Agent 要先“知道有哪些文档”才能决定去哪个文件里搜。所以第一步是扫描你的文档目录生成一个结构化的清单。假设你的知识库放在./knowledge下全是.md和.txt文件用下面这段脚本生成目录 JSON// build-index.js const fs require(fs); const path require(path); const KB_ROOT ./knowledge; function walk(dir, prefix ) { const entries fs.readdirSync(dir, { withFileTypes: true }); let result []; for (const entry of entries) { const fullPath path.join(dir, entry.name); const relPath path.join(prefix, entry.name); if (entry.isDirectory()) { result result.concat(walk(fullPath, relPath)); } else if (entry.name.endsWith(.md) || entry.name.endsWith(.txt)) { const content fs.readFileSync(fullPath, utf-8); const firstLine content.split(\n).find(l l.trim().length 0) || ; result.push({ path: relPath, title: firstLine.replace(/^#\s*/, ).slice(0, 80), size: content.length }); } } return result; } const index walk(KB_ROOT); fs.writeFileSync(./kb-index.json, JSON.stringify(index, null, 2)); console.log(索引完成共 ${index.length} 个文档);跑完你会得到一个kb-index.json里面每个文档有路径、标题和大小。这个清单会在对话开始时作为系统消息的一部分发给模型让它对知识库结构有全局认识。如果文档很多可以只保留标题和路径不用把全文塞进去。3.2 grep 工具函数在指定文件里精确搜索Agent 需要调用一个搜索工具。我们用 Node.js 的child_process执行系统 grep支持正则和限定文件// tools.js const { execSync } require(child_process); const path require(path); const KB_ROOT ./knowledge; function searchDocuments({ query, file }) { // 安全校验禁止路径穿越 if (file (file.includes(..) || path.isAbsolute(file))) { return { error: 非法文件路径 }; } const target file ? path.join(KB_ROOT, file) : KB_ROOT; try { // -r 递归-n 显示行号-i 忽略大小写-E 扩展正则 const cmd grep -rniE ${JSON.stringify(query)} ${JSON.stringify(target)}; const output execSync(cmd, { encoding: utf-8, maxBuffer: 1024 * 1024 }); // 只返回前 50 行避免上下文过长 const lines output.split(\n).filter(Boolean).slice(0, 50); return { matches: lines, total: lines.length }; } catch (e) { // grep 没匹配到会返回非零退出码这里当作空结果处理 return { matches: [], total: 0 }; } } module.exports { searchDocuments };这个函数接收两个参数query是关键词或正则file是可选的文件路径。返回匹配到的行每行带文件名和行号。注意maxBuffer要设大一点否则大文件搜索会报错。3.3 Agent 循环让模型自主决定搜什么现在把模型接口和工具串起来。核心逻辑是发消息给模型 → 模型返回工具调用请求 → 执行 grep → 把结果塞回对话 → 模型继续推理或给出最终答案。循环直到模型不再请求工具。// agent.js require(dotenv).config(); const OpenAI require(openai); const { searchDocuments } require(./tools); const kbIndex require(./kb-index.json); const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: https://taotoken.net/api }); const tools [{ type: function, function: { name: search_documents, description: 在本地知识库中搜索关键词或正则表达式返回匹配的行, parameters: { type: object, properties: { query: { type: string, description: 搜索关键词或正则表达式 }, file: { type: string, description: 限定搜索的文件相对路径可选 } }, required: [query] } } }]; async function runAgent(userQuestion) { const messages [ { role: system, content: 你是一个知识库检索助手。以下是知识库的文档清单\n${JSON.stringify(kbIndex, null, 2)}\n\n你可以调用 search_documents 工具在文档中搜索。先根据问题判断可能相关的文件再构造精确的搜索词。如果第一次搜索结果不充分可以继续搜索。 }, { role: user, content: userQuestion } ]; for (let step 0; step 6; step) { const response await client.chat.completions.create({ model: gpt-5, messages, tools, temperature: 0.2 }); const msg response.choices[0].message; messages.push(msg); if (!msg.tool_calls || msg.tool_calls.length 0) { return msg.content; } for (const call of msg.tool_calls) { const args JSON.parse(call.function.arguments); console.log([工具调用] search_documents(${JSON.stringify(args)})); const result searchDocuments(args); messages.push({ role: tool, tool_call_id: call.id, content: JSON.stringify(result) }); } } return 检索步数超限请缩小问题范围。; } runAgent(系统如何防止恶意登录).then(console.log);把TAOTOKEN_API_KEY写进.env文件然后node agent.js就能跑。你会看到模型先输出工具调用日志比如搜索“登录失败”“锁定”“验证码”等关键词然后基于 grep 返回的行给出答案。4. 验证请求与成功结果跑通之后你需要确认三件事模型确实调用了工具、grep 返回了有效内容、最终答案引用了文档原文。先看工具调用日志。正常输出类似[工具调用] search_documents({query:登录失败|锁定|验证码,file:security.md}) [工具调用] search_documents({query:失败次数|阈值,file:config.md})这说明模型先定位到security.md用正则搜索多个相关词发现信息不够又去config.md查配置项。这就是 Agent 检索和向量检索的本质区别每一步搜索都是模型根据当前信息主动决策的而不是一次性 Top-K。再看最终答案。好的结果应该包含具体行号和原文片段比如“根据 security.md 第 42 行连续 5 次登录失败后触发账户锁定”。如果模型只给了泛泛的回答说明 grep 结果没被正确利用检查一下messages里 tool 角色的内容是不是完整的 JSON。你还可以用 TaoToken 的模型对话页面 https://taotoken.net/chat 快速验证模型是否支持 function calling。在页面上选 GPT-5发一条测试消息看它能不能正确理解工具定义。这个页面适合做接口连通性检查不用写代码。对于需要长期跑 Agent 任务的场景比如每天定时索引新文档并批量回答可以考虑用 Coding Plan https://taotoken.net/coding-plan 它在长会话和工具调用上有更好的配额支持。如果只是偶尔验证按量付费的 API Key 就够了。5. 本篇常见错排查grep 返回空但文档里明明有这个词。最常见的原因是大小写和编码。grep 默认区分大小写加-i忽略大小写。如果文档是 UTF-8 但系统 locale 不对中文搜索可能失败在命令前加LC_ALLC.UTF-8。另外检查KB_ROOT路径是不是相对路径Node 的工作目录和你想象的可能不一致用path.resolve转成绝对路径更稳。模型不调用工具直接编答案。两个原因一是系统提示里没强调“必须先用工具搜索”二是模型本身不支持 function calling。在 system message 里加一句“回答前必须先调用 search_documents 获取原文依据”并在请求里确认tools参数格式正确。如果换模型后仍然不调用去 https://taotoken.net/doc 确认该模型是否在支持列表里。工具调用参数解析报错。call.function.arguments是 JSON 字符串但模型偶尔会输出不合法 JSON比如多一个逗号。加一层 try-catch解析失败时把错误信息作为 tool 结果返回给模型让它重新生成。不要直接抛异常中断循环。搜索结果太长撑爆上下文。grep 匹配行数多的时候全部塞回去会占用大量 token。在searchDocuments里限制返回条数比如只取前 30 行并在结果里标注“已截断”。模型看到截断提示后会主动缩小搜索范围。路径穿越导致读到知识库外的文件。这是安全问题。在searchDocuments里校验file参数禁止..和绝对路径。生产环境还应该限制只能读特定后缀的文件避免模型构造出读取系统文件的命令。循环次数太多导致响应慢。默认设 6 步上限但有些问题模型会反复搜同一个文件。在系统提示里加“如果连续两次搜索结果相同请基于已有信息作答”能有效减少无效循环。实测下来大部分知识库问题 2 到 3 步就能收敛。6. 从检索到编码把 Agent 能力接到你的工作流这套骨架跑通之后你可以把它接到更多场景。比如做代码库问答把KB_ROOT指向你的项目目录grep 天然适合搜函数名、变量名和错误信息。模型先看目录结构再精确搜索比向量索引更可控。如果你用 Claude Code 做开发它的 agentic search 就是这个思路每次实时 grep 而不是预建索引。想了解这种模式在编码场景的完整用法可以看 https://taotoken.net/claude-code 。对于需要长期维护的知识库建议把索引生成脚本挂到 CI 里文档更新后自动重建kb-index.json。grep 搜索本身不需要索引所以不存在“索引陈旧”问题每次搜的都是最新文件内容。这是 Agent 方案相比向量 RAG 的一个实际优势维护成本低行为可预期。如果你想把模型对话能力直接嵌入内部工具TaoToken 的 API 兼容层可以让你在不改代码的情况下切换模型。先用小模型跑通流程再换大模型提升回答质量成本可控。接入文档在 https://taotoken.net/doc 里面有完整的请求示例和参数说明。最后留一个实用技巧在系统提示里给模型一个“搜索策略模板”比如“先搜文件名和标题再搜正文优先用文档中出现过的术语不要自己造词”。这能显著提升 grep 命中率。Agent 检索的效果一半靠模型推理一半靠你给的搜索约束。把这两件事做好知识库问答的准确率会有肉眼可见的提升。