oh-my-pi 编码 Agent 的 grep 工具实战：双引擎正则搜索、路径选择器与跨行匹配的完整指南-北京尧图网络

oh-my-pi 编码 Agent 的 grep 工具实战双引擎正则搜索、路径选择器与跨行匹配的完整指南【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读oh-my-pi⌥ Coding agent with the IDE wired in为编码 Agent 内置了一个模型直接调用的grep工具其使用规则与强制约束记录在模型提示词 packages/coding-agent/src/prompts/tools/grep.md 中。本文以这份提示词为骨架结合工具实现 packages/coding-agent/src/tools/grep.ts、原生搜索引擎 crates/pi-natives/src/grep.rs 以及完整的行为规格 docs/tools/grep.md系统讲解 path 参数语法、行选择器、跨行模式、超时与分页策略以及 Rust regex 与 PCRE2 双引擎的匹配原理。读完本文你将理解 Agent 在 oh-my-pi 中应如何高效、安全地使用grep检索代码并能够据此设计自己的编码 Agent 提示词与搜索策略。一、工具定位为什么强制使用内置 grep 而非 shell grep/rggrep.md的第一行就点明了工具的本质Searches files/internal URLs: Rust regex, PCRE2 fallback——它同时覆盖普通文件与内部 URL底层采用 Rust regex 引擎并在必要时回退到 PCRE2。提示词中的critical区块给出了两条不可违反的约束MUST use instead of shellgrep/rg.Agent 必须使用内置grep工具而不能退回到 bash 工具里执行grep/rg。原因在于实现层的设计内置工具返回结构化结果GrepMatch列表、filesWithMatches、limitReached等元数据模型可以直接消费结果按文件分组并以可点击路径呈现支持后续read/edit的 hashline 锚点回跳见 docs/tools/grep.md 的 Outputs 一节原生调用受SEARCH_GREP_TIMEOUT_MS 30_00030 秒墙钟预算约束并由 AbortSignal 驱动取消避免失控搜索烧 CPU工具自动处理.gitignore、隐藏文件、超大文件截断、归档成员、内部 URL 等边界这些是裸rg命令不具备的。二、path 参数全解文件、目录、glob、内部 URL 与分号分隔列表instruction区块第一条给出了 path 的完整语义path: known files, directories, globs, internal URLs; roots;-separated.即 path 可以同时接受已知文件、目录、glob 模式、内部 URL且多个搜索根用分号;分隔。2.1 参数 schema 与默认值从实现 packages/coding-agent/src/tools/grep.ts 的searchSchema可以看到完整参数参数类型必填说明patternstring是正则模式空白模式会被拒绝Pattern must not be empty但模式本身会原样保留首尾空格是正则的合法语义如缩进锚点pathstring否文件、目录、glob、内部 URL、归档成员或行选择器可传分号分隔列表如src; tests省略或为空时默认搜索工作区根.caseboolean否是否大小写敏感默认truegitignoreboolean否目录扫描时是否尊重.gitignore默认trueskipnumber否多文件结果的分页偏移按文件页为单位默认0负数或非有限值会被拒绝2.2 分隔符展开规则packages/coding-agent/test/tools/grep-path-lists.test.ts 用一组测试固化了分隔符的展开行为分号无条件拆分apps/; packages/; phases/会被无条件拆成三个独立目录逗号有条件拆分仅当拆分后至少一个部分能解析为存在的路径时才拆分空格有条件拆分仅当拆分后每一部分都能解析时才拆分避免误拆含空格的真实路径已存在且本身含分隔符的路径保持原样如folder with spaces/这类含空格的目录不会被拆开测试search keeps a single path that contains spaces验证了含空格目录folder with spaces/能被正确整体搜索测试search resolves bracketed literal paths (Next.js routes)验证了apps/[id]/page.tsx这种含[id]的 Next.js 路由目录当字面路径真实存在时字面路径优先于 glob 字符类解释。2.3 glob 与内部 URL 的交互限制内部 URL如artifact://、skill://、omp://不支持 glob 元字符*、?、[、{。实现中resolveInternalSearchInputs()会在解析前用hasGlobPathChars()检查并抛出Glob patterns are not supported for internal URLs: ...。一个例外是omp://根它通过内部 URL 补全展开为所有内嵌文档文件从而可以作为文档搜索根使用OMP_ROOT_URL_RE见 grep.ts。此外ssh://远程路径会提前失败没有本地文件可供搜索工具会提示改用read读取远程文件或定位到具体远程文件再 grep。三、宽泛搜索会超时先 glob 缩小范围instruction第二条是一个重要的实践约束Broad searches may time out → narrow scope or useglobfirst.宽泛搜索例如对整个仓库根.搜索一个高频词容易触发超时。实现层面的证据每次原生 grep 调用有SEARCH_GREP_TIMEOUT_MS 30_00030 秒预算超时抛错Grep timed out after 30s; narrow paths or pattern, or scope with \glob first见 grep.ts原生目录扫描在 crates/pi-natives/src/grep.rs 中执行且刻意关闭了目录扫描缓存build_grep_walk_request硬编码.cache(false)超大文件有MAX_FILE_BYTES 4 * 1024 * 10244 MiB上限原生 grep 只扫描文件前 4 MiB 的 mmap 窗口超出部分不返回匹配JS 侧镜像为NATIVE_GREP_MAX_FILE_BYTES。因此推荐的搜索策略是先用glob文件查找工具定位候选文件集合再对精确目录或文件执行grep或者将 path 限定到具体子目录、用更精确的模式。四、单文件行选择器src/foo.ts:50-100instruction第三条定义了行选择器语法One-file line selector:src/foo.ts:50-100; never selects search root.path 可以携带:N-M形式的行区间选择器把搜索限定在指定行范围内单行区间src/foo.ts:50-100第 50100 行起始行行数src/foo.ts:5010从第 50 行起 10 行多段区间src/foo.ts:50-100,200-300关键限制是行选择器只适用于单个文件。实现中有三处强制校验Line-range selector requires a single file, not a glob: ...——glob 不能带行选择器Line-range selector requires a single file: ... is a directory——目录不能带行选择器Path not found for line-range selector: ...——选择器指向的文件必须真实存在。“never selects search root”意味着src/foo.ts:50-100中:50-100永远不会被解释成搜索根的一部分——它只会被剥离为行过滤条件。JS 侧在原生 grep 返回后用isLineInRanges()按绝对行号过滤并且会裁剪掉落在区间之外的上下文行避免泄漏被调用方明确排除的内容见 grep.ts。值得注意的是行选择器语法与read工具的 selector 语法保持一致parseSel的镜像实现isReadSelectorGrammar因此grep接受的内部 URL selector 与read完全兼容但read独有的:-N尾部语法在grep中被拒绝——因为匹配的行号过滤只需要绝对行号尾部语义无意义。五、跨行匹配字面\n与\\ninstruction第四条Literal\nor\\nenables cross-line patterns.多行模式不是靠参数开关打开的而是由模式本身驱动当 pattern 中包含真实的换行符或字面\n两个字符序列时effectiveMultiline才为 true见 grep.ts。这使 Agent 可以匹配跨多行的代码片段例如查找function foo(\n arg这样的函数定义与参数块在虚拟资源内部 URL 内容上多行模式使用 JSRegExp的gm标志但要注意超大虚拟资源4 MiB的多行搜索会回退到 JS 正则方言而行模式的超大资源则按行边界分块交给原生 RE2 以保持方言一致nativeChunkedLineIndexes()。六、底层匹配原理Rust regex → PCRE2 → 字面量三级回退grep.md第一行的 “Rust regex, PCRE2 fallback” 对应 crates/pi-natives/src/grep.rs 的build_matcher()四级决策清洗花括号sanitize_braces()先把非量词语义的{/}如模板字符串里的${platform}、a{b}自动转义为\{/\}而合法量词如a{2,4}保持正则语义优先 Rust regex使用grep_regex::RegexMatcher默认按行匹配line_terminator \n线性时间、无灾难性回溯PCRE2 回退当模式需要 Rust regex 刻意省略的 lookaround环视与 backreference反向引用等特性时build_pcre_matcher()用grep_pcre2::PcreMatcher重试PCRE2 JIT 默认开启macOS 上除外可用环境变量OMP_PCRE2_JIT1/0强制开关见 grep.rs括号修复与字面量兜底若报错信息包含unclosed group/unopened group典型的“模式中混入一个游离(”如fetchProvider(会先转义未配对的括号再重试两个引擎都拒绝时最终把原模式整体按字面量转义后搜索而不是让整个搜索失败。对应的测试固化了这些行为grep.rs 中的grep_supports_pcre2_lookaround_and_backreferences、grep_supports_multiline_pcre2_backreferences_and_lookahead、stray_parenthesis_preserves_surrounding_regex、valid_regex_is_not_escaped等。这意味着 Agent 在 oh-my-pi 中写正则时可以放心使用(?...)前瞻、\1反向引用等 PCRE2 特性而无需先判断引擎支持度。七、输出形态、上限与分页7.1 结果格式匹配行由formatMatchLine()格式化为*LINE:content匹配行与LINE:content上下文行文件头在 hashline 模式下形如[src/login.ts#1F2A]#1F2A是会话快照存储派生的四字符十六进制 tag供后续read/edit校验文件是否变化。目录/多文件结果通过formatGroupedFiles()渲染成多级前缀折叠的目录树每层嵌套一个#目录头以/结尾。7.2 各类上限速查来自 docs/tools/grep.md 的 Limits Caps 一节上限值说明DEFAULT_FILE_LIMIT20单页最多展示的文件数超出时提示Use skipN for the next pageMULTI_FILE_PER_FILE_MATCHES20多文件搜索时单文件匹配数上限防止单个热点文件挤占多样性SINGLE_FILE_MATCHES200单文件搜索的匹配数上限无多样性顾虑INTERNAL_TOTAL_CAP2000JS 分组前从原生 grep 获取的匹配总数硬上限DEFAULT_MAX_COLUMN512每行最多 512 字符超出截断并标记linesTruncatedtruncateHead字节上限50 KiB最终文本输出按字节截断grep.ts把行数上限设为MAX_SAFE_INTEGER因此实际是字节封顶而非行数封顶grep.contextBefore/grep.contextAfter1 / 3上下文行数默认值可在设置中修改见 settings-schema.ts 附近SEARCH_GREP_TIMEOUT_MS30_000单次原生调用墙钟预算MAX_FILE_BYTES4 MiB单文件扫描窗口上限注意上下文默认值与直觉不同前文 1 行、后文 3 行。grep.enabled true默认开启工具是可发现discoverable而非必需essential等级。7.3 无匹配与警告无匹配时返回No matches found当skip越过最后一页时返回No more results (N files total; skip... is past the end)。这两类结果都会被标记为useless促使 Agent 立即修正搜索方向。目录扫描跳过超大文件、归档存在不可读成员、多路径存在缺失项时均会在结果尾部附加非致命警告说明。八、多轮开放搜索与 eager delegationcritical区块第二句在 eager delegation 启用时要求Open-ended multi-round search MUST use Task scout, not chained calls.当会话设置启用 eager delegation 且 scout侦察子 Agent可用时开放式的多轮搜索必须交给Taskscout组合而不是链式调用多次grep。这背后的工程动机是grep单次调用有 30 秒超时与 20 文件/页的分页机制链式多次 grep 既浪费 token又容易因上下文累积偏离目标而 scout 子 Agent 可以在独立会话中并行、分轮地做开放式探查主 Agent 只消费汇总结果。这条规则是可配置的GrepTool.description渲染时根据sessionDelegationBias(session) eager和isScoutSpawnable(...)动态决定是否注入该句见 grep.ts也就是说提示词会随会话策略自适应变化。九、虚拟资源与归档成员grep 的搜索边界除了文件系统grep还能搜索两类特殊目标内部 URL虚拟资源没有sourcePath的资源如某些artifact://、skill://、virtual://内容会在内存中通过 JSRegExp搜索有sourcePath的资源则走其底层文件omp://根可展开为全部内嵌文档。不可变与虚拟源不会铸造可编辑的 hashline 锚点。packages/coding-agent/test/tools/grep-internal-urls.test.ts 验证了这些解析路径。归档成员bundle.zip:src/foo.ts这样的归档成员路径会被提取为临时 UTF-8 文件后交给原生 grep 搜索结果显示为原始archive.ext:member选择器可直接回传给read。二进制或非 UTF-8 成员会被跳过并报告为不可读Cannot search archive member(s): ...。十、实操要点速记不要用 shell grep/rg内置grep结构化、可分页、可回跳、受超时保护是 Agent 的唯一正确入口。先缩小再搜宽泛搜索先glob再对精确路径 grep必要时缩小 pattern。path 用分号分隔多根src; tests逗号/空格也能展开但仅当所有片段都存在。单文件限定行区间src/foo.ts:50-100、src/foo.ts:5010、src/foo.ts:50-100,200-300注意不能用于 glob 或目录。跨行匹配靠模式驱动pattern 含\n或真实换行即启用多行模式无需额外开关。正则放心用 PCRE2 特性lookaround、backreference 等会自动回退到 PCRE2且 JIT 默认开启。关注分页与截断信号skip翻页、fileLimitReached/perFileLimitReached表明结果被截断Agent 应继续翻页或收敛范围。开放式多轮搜索交给 Task scout避免链式 grep 造成超时与上下文膨胀。以上规则即 packages/coding-agent/src/prompts/tools/grep.md 这份提示词的完整展开读者若需进一步深入可对照阅读工具实现 packages/coding-agent/src/tools/grep.ts、原生引擎 crates/pi-natives/src/grep.rs、行为规格 docs/tools/grep.md 以及两组测试 grep-path-lists.test.ts 与 grep-internal-urls.test.ts。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

oh-my-pi 编码 Agent 的 grep 工具实战：双引擎正则搜索、路径选择器与跨行匹配的完整指南

相关推荐

IMM-UKF三维目标跟踪：解决机动突变下的状态坍塌

openai-agents-python REPL 实用工具：用 run_demo_loop 在终端快速调试智能体

2026年学术写作AI工具全解析：降重、润色与格式优化

更多资讯

Vue3自定义Tabs组件实现与翻页交互优化

10 分钟实战 OpenMetadata：把散落各处的表变成可搜索的数据目录

Vue3+Three.js轻量级VR博物馆前端架构

Cherry Studio 代码规范精讲：函数早退（Early Return）与无效计算消除

PHP成绩管理系统源码实战：从表设计到统计部署

LlamaIndex QueryEngineTool 深度指南：将查询引擎封装为 Agent 工具的完整实战

今日更新

Linux 内核 ARM 虚拟内存布局全解析：从 4GB 地址空间划分到源码级验证

AIGC降重工具测评与教育应用指南

数据容灾核心指标与实战方案解析

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？