Klavis 仓库中的 FastAgent ripgrep 搜索 Agenttool-card 配置、规则体系与钩子源码解析【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis导读本文围绕 Klavis 仓库中 Hugging Face MCP Server 子项目mcp_servers/hugging_face内的 FastAgent 工具卡片 ripgrep-search.md 展开。该卡片将 ripgreprg封装为一个专用的搜索 Agent用于在代码仓库中快速完成多步、逐步收敛的代码/概念检索。读完本文你将掌握该 tool-card 的 frontmatter 配置含义、完整搜索规则、查询构造与输出控制技巧以及配套 Python 钩子在执行前后所做的自动修复与命令汇总并能在自己的 FastAgent 项目中直接复用这套配置。一、背景tool-card 是什么为什么需要 ripgrep 搜索 Agent在 FastAgent 的约定中.fast-agent目录下通常包含两类卡片agent-cards/定义具备特定职责的 Agent例如该仓库中的 dev.mdtool-cards/定义可被 Agent 调用的专用工具型 Agent例如ripgrep-search.md。ripgrep-search.md卡片头部注明tool_only: true表明它不会被当作普通会话 Agent 使用而是作为子 Agent 被dev等主 Agent 编排调用。dev.md中通过agents: [ripgrep_search]显式声明依赖并在代码导航部分说明分工LSP 工具负责结构化查询定义、引用、符号、悬停、诊断而 ripgrep_search Agent 负责广谱文本发现与文件操作见 dev.md。这一设计背景是在大规模仓库中让主模型直接猜测文件路径或逐目录人工浏览效率极低而一次性的宽泛正则搜索又容易产生海量噪音。将「规划 逐步收窄搜索」的过程封装成一个专门 Agent可以显著提升检索的确定性与可复现性。二、frontmatter 配置逐项解读卡片头部 YAML 是该工具的全部行为开关逐项说明如下name: ripgrep_search tool_only: true description: | Fast, multi-step code/concept search using ripgrep. ... shell: true model: gpt-oss use_history: false tool_hooks: before_tool_call: ../hooks/fix_ripgrep_tool_calls.py:fix_ripgrep_tool_calls after_turn_complete: ../hooks/report_ripgrep_commands.py:add_ripgrep_commands_to_output配置项值含义nameripgrep_searchAgent 标识符被dev卡片通过agents: [ripgrep_search]引用tool_onlytrue仅作为工具型子 Agent 存在不进入普通对话流程description长文本决定主 Agent 何时委派任务给该子 Agent 的语义描述定位文件、按语言/路径限制、先 count 再下钻、查找定义/实现/引用/文档shelltrue允许执行 shell 命令rg命令依赖此开关modelgpt-oss为该子 Agent 指定轻量快速的模型注释建议 gpt-oss 优先并提示参考 hf-toad-cards 快速上手获得进一步优化use_historyfalse关闭历史上下文每次调用独立执行避免跨任务状态污染tool_hooks.before_tool_call../hooks/fix_ripgrep_tool_calls.py:fix_ripgrep_tool_calls执行前钩子修复 LLM 常见的 rg 命令错误tool_hooks.after_turn_complete../hooks/report_ripgrep_commands.py:add_ripgrep_commands_to_output回合结束后钩子把实际执行的 rg 命令汇总追加到最终输出description中特别强调了一个高频事故点如果仓库根目录不是当前工作目录必须显式传入 repo root/path否则搜索会在错误的 workspace 中执行。这也是下面 Top Priority Rules 第一条的由来。三、顶层优先级规则Top Priority Rules卡片在正文开头用三条规则框定不可妥协的行为底线用户提供了 repo root 时每条rg命令都必须显式带上它——防止在错误的目录树上搜索每条rg命令必须携带标准排除 globs见第五节——防止把.git、node_modules、虚拟环境等噪音目录卷进结果禁止使用ls -R做递归发现一律用rg --files或rg -l——因为ls -R无法做内容过滤而rg的--files天然支持 glob 过滤与排除。四、核心规则Core Rules卡片给出七条核心执行规则是搜索 Agent 的行为准则始终实际执行rg命令而不是只做建议——子 Agent 的价值在于确定性执行ripgrep 默认递归绝不要使用-R/--recursive——-R是无效 flag会直接导致命令失败详见第六节钩子源码激进收窄结果用文件类型、路径、glob 排除快速缩小范围结果可能过宽时先 count若超过 50 个匹配转为摘要而非全量输出返回文件路径与行号——这是供主 Agent 继续下钻的最小完整信息单元退出码 1 无匹配不是错误——rg以退出码 1 表示无命中Agent 不应将其误判为命令失败最多 3 次发现尝试仍无结果则直接给出结论「workspace 中未找到not found in workspace」避免无限重试。规则 4 与 7 共同构成了「广度优先、逐步收敛」的策略骨架先粗查计数判断规模再按文件类型/路径下钻最多三轮即收束。五、标准排除项Standard Exclusions卡片要求每条命令都携带以下排除 globs这是防止输出爆炸的第一道防线-g !.git/* -g !node_modules/* -g !__pycache__/* -g !*.pyc -g !.venv/* -g !venv/*逐一说明!.git/*排除 Git 内部对象与历史避免命中.git下的打包内容!node_modules/*排除 npm/pnpm 依赖树本仓库为 pnpm workspacenode_modules规模通常远大于源码!__pycache__/*与!*.pyc排除 Python 字节码缓存!.venv/*与!venv/*排除两种常见命名的 Python 虚拟环境目录。这一组 globs 之所以被写进卡片正文而不是留给模型自由发挥是因为 LLM 在构造命令时经常遗漏排除项从而把构建产物、依赖源码和缓存文件混入搜索结果导致 token 浪费与结论污染。六、查询构造Query Forming与输出控制Output Control查询构造技巧参数用途典型场景-F--fixed-strings按字面字符串匹配禁用正则搜索含标点、特殊字符的标识符或字符串常量-S--smart-case智能大小写全小写模式时忽略大小写含大写时区分不确定目标的大小写风格时优先使用-w--word-regexp整词匹配避免init命中initialize、initialization-t或-g限制文件类型或路径 glob-t ts、-g *.py、-g packages/**rg --files -g pattern先按文件名/glob 定位文件再做内容搜索确认某文件是否存在、寻找某命名模式的文件卡片特别强调在内容搜索之前优先用rg --files -g pattern定位文件名。这符合「先缩文件集合、再查内容」的分层策略能显著减少内容匹配的噪音。输出控制发现阶段优先用rg -l只列文件而不是rg -c计数避免大仓库计数本身也昂贵用--max-count 1或head -n 50截断输出绝不倾倒大段输出只总结 top 文件 下一步建议把「继续下钻」的决定权交还给主 Agent。七、配套钩子源码解析执行前修复与执行后汇总卡片在 frontmatter 中引用了两个钩子其完整实现位于 fix_ripgrep_tool_calls.py 与 report_ripgrep_commands.py。这两个文件是理解这套搜索 Agent「可靠运行」的关键。7.1 before_tool_call修复 LLM 的两类常见错误fix_ripgrep_tool_calls钩子挂在before_tool_call阶段在execute工具真正运行前对模型生成的调用做校正源码注释明确点出它解决的两个问题问题一幻觉出的工具名变体。LLM 经常把execute写成各种变体。钩子内置了一张修正映射表TOOL_NAME_CORRECTIONS { exec: execute, executescript: execute, execscript: execute, executor: execute, exec_command: execute, }并在映射之外增加了兜底逻辑任何以exec开头且不等于execute的名字一律修正为execute同时记录 warning 日志源码 fix_ripgrep_tool_calls.py。问题二无效的-Rflag。ripgrep 默认递归-R不是合法参数。钩子对execute工具中所有包含rg的命令做字符串级清洗覆盖三种写法源码 fix_ripgrep_tool_calls.pyif -R in command: # 中间位置rg -R foo bar command command.replace( -R , ) if command.endswith( -R): # 结尾位置rg foo -R command command[:-3] if -R\n in command: # 换行前多行命令中的 -R command command.replace( -R\n, \n)修正后的命令写回args[command]并用logger.warning记录原始与修正后的命令便于事后审计模型行为。额外的副作用命令采集。同一钩子在清洗过程中会把所有包含rg的命令收集到 runner 上的_rg_commands集合set去重为第二个钩子提供数据源源码 fix_ripgrep_tool_calls.py。7.2 after_turn_complete把执行过的命令写入最终回复add_ripgrep_commands_to_output钩子挂在after_turn_complete阶段当本回合结束时若_rg_commands集合非空则按字典序排序生成一段 Markdown 摘要summary \n\nExecuted rg command(s):\n \n.join( f- {command} for command in commands )随后通过_append_summary_to_message尝试把摘要追加到当前消息最后一个文本块之后兼容 dict 与对象两种 message block 结构若当前消息无可追加位置则回退为追加一条新助手消息源码 report_ripgrep_commands.py。这一机制的价值在于可审计性主 Agent 与开发者都能在最终输出里看到「这个搜索 Agent 到底执行了哪些 rg 命令」便于复现、调试与信任建立。八、Agent 编排dev 卡片如何调用 ripgrep_search在 dev.md 中可以看到完整编排关系name: dev model: codex?reasoninghigh default: true shell: true agents: [ripgrep_search] function_tools: - multilspy_tools.py:lsp_hover - multilspy_tools.py:lsp_definition - multilspy_tools.py:lsp_references - multilspy_tools.py:lsp_document_symbols - multilspy_tools.py:lsp_workspace_symbols - multilspy_tools.py:lsp_diagnostics在提示词正文中dev对两套检索能力的定位做了明确分工见 dev.mdUse LSP tools for structural queries: definitions, references, symbols, hover info, diagnostics. Use the ripgrep_search agent for broad text discovery or file operations.即结构化、符号级的问题走 LSP 工具基于 typescript-language-server 的 MultiLSPy 封装见 multilspy_tools.py广谱文本发现、按名找文件、跨目录检索走 ripgrep_search。两者互补前者回答「这个符号是什么、被谁引用」后者回答「哪里的代码提到了某个字符串/模式」。九、实战示例从宽查到下钻的完整搜索链结合卡片规则一个典型的「搜索一个函数定义」的会话会这样推进第 1 步定位候选文件rg --files glob 收窄rg --files -g *.ts -g !node_modules/* -g !.git/* | head -n 50第 2 步宽查计数判断规模先 countrg -c -S mcp packages/mcp/src -g *.ts -g !node_modules/* -g !.git/*若命中文件数超过 50则只返回 top 文件摘要与下一步建议而不是倾倒全部行。第 3 步收窄下钻类型 路径 整词rg -n -w --max-count 1 ToolListChangedNotification packages/app packages/mcp -g *.ts -g !node_modules/* -g !.git/*返回文件路径 行号-n用-w避免ToolListChangedNotificationXXX之类的误命中。第 4 步无命中时的退出码语义rg -F some_never_exist_symbol . # 退出码 1输出为空按规则 6 与规则 7此时 Agent 应判断「无匹配 ≠ 错误」最多再换两轮查询角度仍无结果即输出结论「not found in workspace」。在 Klavis 仓库的 Hugging Face 子项目中这一套搜索 Agent 与仓库结构pnpm workspacepackages/app、packages/mcp、packages/e2e-python见 AGENTS.md配合默契搜索范围通常被-g packages/**这类路径 glob 快速限定再叠加标准排除项即可获得高质量命中。十、设计要点总结与复用建议从这份 tool-card 与其钩子实现中可以提炼出以下可复用的设计模式把「搜索策略」沉淀为提示词规则而不是依赖模型临场发挥多步收敛、先 count、最多 3 次尝试、返回路径行号这些确定性规则大幅提升了检索结果的可预测性用钩子兜底模型的已知弱点-R幻觉与工具名变体是 LLM 的高频错误与其反复提醒不如在before_tool_call阶段做字符串级修正执行透明化after_turn_complete钩子把实际执行过的命令写回回复让检索过程可审计、可复现显式声明标准排除项把.git、node_modules、虚拟环境等排除 globs 固化为模板常量避免每条命令重复生成时遗漏双轨检索分工LSP 管结构、ripgrep 管文本避免两类工具职责重叠导致的冗余调用。如果需要在本仓库中查看这套机制的完整落地可以依次阅读ripgrep-search.md规则定义、fix_ripgrep_tool_calls.py执行前修复、report_ripgrep_commands.py执行后汇总、dev.mdAgent 编排。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考