oh-my-pi 的 ast_grep 工具基于 ast-grep 的结构化源码搜索实战指南【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-piast_grep 是 oh-my-pi 编码代理coding agent内置的结构化代码搜索工具它不按文本匹配而是把模式编译成 AST 节点在语法树层面定位函数调用、声明、导入等语言结构。本文围绕 docs/tools/ast-grep.md 展开结合 TS 工具入口、Rust 原生引擎 与 语言定义层 的源码完整讲解该工具的参数契约、模式语法、执行流水线、多目标搜索、错误语义与各类上限帮助你理解并正确使用这条语义级 grep链路。一、工具定位什么时候该用 ast_grep普通grep文本正则擅长找字符串但遇到语法形状问题就很笨拙比如找出所有console.log(...)调用、所有const foo () ...形式的箭头函数、或者某个包里被命名的 import。这类需求用正则写起来既脆弱又难以覆盖语法变体换行、注释、嵌套括号。ast_grep的定位见模型侧提示词 packages/coding-agent/src/prompts/tools/ast-grep.md是当语法形状比文本更重要时使用——即调用、声明、语言结构这类场景。它的工具元信息也写得直白summary Search code with AST patterns (structural grep)label AST Grepapproval read只读操作无需写权限审批。它在 oh-my-pi 中的启用方式与大多数可发现工具一致默认关闭astGrep.enabled false在配置 packages/coding-agent/src/config/settings-schema.ts#L4348-L4357 中声明为布尔开关tab: tools分组Available Tools标签 AST Grep。开启后它是一个loadMode discoverable的按需加载工具工具注册与开关判定逻辑位于 packages/coding-agent/src/tools/index.ts其中if (name ast_grep) return session.settings.get(astGrep.enabled)一行即可确认开关与注册的直接绑定关系。作为对照astEdit.enabled默认值是true结构化改写工具默认开启说明搜索与改写两条链路被刻意分开管理。二、输入参数pat / path / skip / lang工具 Schema 定义在 packages/coding-agent/src/tools/ast-grep.ts#L41-L48共有四个字段字段类型必填说明patstring是单个 AST 模式。wrapper 会先trim()空串直接抛错pathstring否单个文件、目录、glob、带 backing file 的内部 URL 或可抓取的 web URL也支持用分号分隔的列表如src; tests。省略或为空时默认.工作区根。空条目会被拒绝内部 URL 的 glob 会被拒绝skipnumber否匹配偏移量。默认0实际取Math.floor(...)负数与非有限值会失败langstring否语言覆盖例如对含糊的.h文件指定cppSchema 注释中的典型用法参数校验逻辑在execute()中非常明确ast-grep.ts#L211-L219pat先trim()长度为 0 时抛ToolErrorpat must be a non-empty patternskip在未提供时为 0否则Math.floor(params.skip)Number.isFinite不成立或小于 0 时抛skip must be a non-negative numberpath通过toPathList(params.path)展开空列表时回退为[.]。2.1 模式语法模型可直接使用的元变量文档与提示词共同给出的模式语法是 ast-grep 的核心能力归纳如下语法含义约束$NAME捕获一个 AST 节点名称必须大写必须代表完整 AST 节点不能是部分 token 或字符串片段$_匹配一个 AST 节点但不绑定不产生元变量$$$NAME捕获零个或多个 AST 节点注意是三个$$$NAME是非法写法ast-grep 会惰性停在下一个可满足节点$$$匹配零个或多个 AST 节点且不绑定—关键规则提示词 ast-grep.md#L6-L13 中逐条列出代码侧同样有佐证同一元变量出现多次要求每处代码完全相同$A $A只匹配x x不会匹配x y模式必须能解析为单个合法 AST 节点非独立片段需要包裹如class $_ { … }提示词中 TypeScript 示例是async function $NAME($$$ARGS): $_ { $$$BODY }——用: $_容忍任意返回类型注解声明形式彼此不同function foo、方法foo()、const foo () {}是三种 AST 形状搜索没有找到之前先确认搜对了形式C 表达式语句调用需要末尾分号ns::doThing($ARG);、$CALLEE($ARG);最宽松的存在性检查直接用裸标识符作为模式如pat: processItems配合收窄的path。2.2 模式编译的自动降级MultipleNode 包装回退源码在 crates/pi-ast/src/ops.rs#L97-L160 给出了一个文档之外的实现细节当模式片段例如 JSON 的key: $V被 ast-grep 判定为多根节点PatternError::MultipleNode时compile_pattern()并不会直接失败而是尝试把片段包进一个最小合法上下文再编译。目前只有 JSON 有包装模板({, }, pair)并且会自动把裸元变量加上引号quote_bare_metavars见 ops.rs#L165-L200。对 Rust 还有额外的上下文模式编译把模式包进fn __rwp_wrapper() { … }见 ops.rs#L394-L400。这说明模式必须解析为单个节点是主规则但存在可自动修复的例外路径。三、支持的编程语言与扩展名推断文档给出的规范语言列表来自SupportLang::all_langs()crates/pi-ast/src/language/mod.rs#L337-L346共 55 种astro, bash, c, cmake, cpp, csharp, dart, clojure, css, diff, dockerfile, emacs-lisp, elixir, erlang, fortran, go, graphql, haskell, hcl, html, ini, java, javascript, json, just, julia, kotlin, lua, make, markdown, nix, objc, ocaml, odin, php, powershell, protobuf, python, r, regex, ruby, rust, scala, solidity, sql, starlark, svelte, swift, toml, tlaplus, tsx, typescript, verilog, vue, xml, yaml, zig3.1 扩展名推断不只是后缀表语言推断实现在 crates/pi-ast/src/language/mod.rs#L614-L668 的from_extension()除了后缀映射表还有几类无扩展名/特殊文件名规则Makefile/makefile/GNUmakefile→makeJustfile→justCMakeLists.txt→cmakeDockerfile、dockerfile、Dockerfile.*、Containerfile→dockerfile.emacs→emacs-lisp无扩展名的 shell rc/profile 文件zshrc、.bashrc、bash_profile、profile、kshrc等十余种→bash注释说明这样做的动机是否则它们解析不到语言会导致 block-aware 操作失效。别名系统LANG_ALIASESmod.rs#L670-L829非常宽松ts/cts/mts→ typescriptjs/jsx/mjs/cjs→ javascriptcu/cuh→ cppmm→ objctf/tfvars/terraform→ hclbzl同时映射 starlark 与 python 推断等。测试用例mod.rs#L831-L846明确验证了 CUDA 源码与头文件推断为 C。文档特别提示.h这类同时属于 C/C 的扩展名有歧义应当显式传lang。3.2 expando 字符各语言如何消化$一个容易忽略的底层事实mod.rs#L105-L169多数语言不接受$作为合法标识符字符因此pi-ast为这些语言实现了expando_charpre_process_pattern用µ、、_、z等替换元变量展开后的占位如 Go/Rust/Kotlin 用µC/C 用CSS/Nix 用_HTML 用z。而 JavaScript、TypeScript、Java、Bash、Python语法本身允许$或经过子集处理等则走 stub 实现。这是同一个模式写法跨语言行为一致得以成立的关键机制。四、输出契约一次调用的返回内容4.1 模型可见的contentast_grep是单次single-shot工具模型看到的content是一个文本块规则如下ast-grep.ts#L323-L412目录/多文件搜索时按文件分组输出匹配行以[PATH#HASH]分组头 *LINE:text呈现hashline 模式否则*LINE|text多行匹配的续行前导一个空格当 ast-grep 捕获了元变量时每个匹配追加一行可选meta: NAMEvalue, …按名称字典序排序输出无匹配时文本为No matches found若同时存在解析问题则变为No matches found. Parse issues mean the query may be mis-scoped; narrow \path before concluding absence. 并附上格式化后的解析问题结果被截断时文本以Result limit reached; narrow path or increase limit.结尾。值得注意的是无匹配的结果会被标记为useless()ast-grep.ts#L309注释解释零匹配即使带解析问题也无用因为后续调用在 compaction 时早已纠正了方向。4.2details元数据detailsAstGrepToolDetailsast-grep.ts#L137-L158包含计数与元信息不含完整匹配负载必有matchCount、fileCount、filesSearched、limitReached可选parseErrors上限去重后的解析错误、parseErrorsTotal去重后、封顶前的总数、scopePath、searchPath、cwd、files、fileMatches、displayContent、meta。文档特别强调原生返回的字节/行列范围byteStart、byteEnd、startLine、startColumn、endLine、endColumn只存在于原生结果中TS wrapper 不会直接把这些字段透传给模型模型看到的是渲染后的文本行。这些字段在排序键AstFindOrderKey中承担稳定排序职责ast.rs#L115-L146。五、执行流水线从 TS 校验到原生匹配文档给出了完整流程这里结合源码逐段展开校验AstGrepTool.execute()校验pat、规整skipast-grep.ts#L211-L219然后把pat包成单元素patterns数组——模型侧一次只能发一个模式见第 7 节 Notes。路径解析委托给resolveToolSearchScope()packages/coding-agent/src/tools/path-utils.ts规整条目、展开分号分隔列表并做条件性的逗号/空白切分、拒绝空path条目。内部 URL / 外部 URL内部 URL 走共享路由解析到 backing file 路径没有sourcePath的条目与内部 URL glob 会失败。可读的外部 URL 会被物化为不可变本地临时文件再搜索materializeReadUrlToFileast-grep.ts#L234-L243。多路径处理partitionExistingPaths()只在至少还有一个存活 base时才丢弃缺失 base全部缺失则调用失败。parseSearchPathPreferringLiteral()把单个路径拆成basePath 可选globresolveExplicitSearchPaths()把多个输入合并为公共 base 花括号联合 glob当公共祖先本身不在请求路径中时退化为多个独立targets多路径去重也在这里完成。目录判定wrapper 对解析后的 base 路径做stat决定输出是否按目录分组。分发单一 base 走一次原生astGrep(...)多目标走runMultiTargetAstGrep(...)ast-grep.ts#L77-L135——每个 target 各调一次原生绑定把路径 rebase 回公共根全局排序后应用skip与 wrapper 上限。原生执行crates/pi-natives/src/ast.rs#L638-L792规整并去重模式列表normalize_pattern_listtrim BTreeSet去重空列表报错解析MatchStrictness默认smart可选cst/ast/relaxed/signature/template见 ast.rs#L22-L60通过pi_walker做 gitignore 感知的目录扫描收集候选文件collect_candidatesast.rs#L425-L484hidden(true)、gitignore(true)、skip_git(true)、follow_links(Never)、按路径排序、走fs_cache缓存未显式传lang时按扩展名逐候选推断语言按语言集合分别编译模式compile_find_patternsast.rs#L601-L635同一模式在混合语言树中为每种语言各编译一次单语言编译失败只记录 parse error 并跳过该语言的文件不整体失败逐文件读取、ast.root().dfs().any(|node| node.is_error())检测语法错误节点并记录 parse issue、执行find_all(pattern)、按需捕获元变量includeMeta匹配保留使用容量化的BinaryHeapoffset limit 1避免为海量匹配物化全部负载。排序与分页原生结果按路径 源位置排序再按offset/limit分页page_retained_matchesast.rs#L200-L216limitReached在此判定。TS 收尾规整解析错误字符串正则归一化…: parse error (syntax tree contains error nodes)前缀、去重、按格式化路径分组、渲染锚点行、追加 limit/parse 提示返回toolResult(...).text(...).done()。六、多目标multi-target搜索跨目录联合是怎么做的当一次调用传入多个路径例如path: src; tests且它们只在根目录相遇时wrapper 走runMultiTargetAstGrepast-grep.ts#L77-L135。核心行为每个 target 单独调用原生astGrepoffset固定为 0limit取skip 50 1多取一个供全局排序后判断是否截断每次取回后用path.resolve(target.basePath, match.path)还原绝对路径再path.relative(commonBasePath, ...)rebase 回公共根路径分隔符统一为/用容量化 top-k 保留retainAstFindMatch与原生侧 BinaryHeap 同思路跨 target 全局保留最好的skip limit 1条随后全局排序、跳过skip、截取limit聚合totalMatches、filesWithMatches、filesSearched、parseErrors任一 target 触限即置limitReached。七、模式 / 变体与渲染细节场景行为单文件原生路径就是该文件输出为扁平匹配行列表目录 可选 glob原生扫描目录后按编译后的 glob 过滤多个显式路径/globwrapper 合成一个虚拟 scope或在路径仅在根相遇时逐 target 调用内部 URL路由解析到 backing 文件即可搜索外部可读 URL物化为不可变临时文件后搜索渲染模式resolveFileDisplayMode()决定 hashline 还是行号模式hashline 模式要求 edit 工具 hashline 编辑模式开启且每文件锚点还需要一次成功的整文件快照recordFileSnapshot()——超限或不可读文件回退为普通输出hashline 的关联机制值得展开在 hashline 模式下wrapper 对命中的文件调用getEditStore(this.session).recordSnapshotFile(absolutePath)生成整文件内容 tag匹配行渲染为[PATH#HASH]锚点并把命中的行体记录进recordSeenLinesFromBodyast-grep.ts#L314-L363。这样后续 edit 工具拿到锚点时只要文件未变tag 就能验证锚点有效性——这正是输出锚点供后续工具使用的落地机制。八、副作用与取消/超时语义文件系统TS wrapper 会stat输入路径原生代码通过fs_cache读取匹配文件并扫描目录crates/pi-natives/src/fs_cache 相关实现会话状态除常规工具转录/结果元数据外无额外副作用后台工作原生工作跑在阻塞 worker 上task::blocking(ast_grep, ct, ...)见 ast.rs#L659取消与可选原生超时通过CancelToken::heartbeat()协作完成——ast_grep的AstFindOptions支持signalAbortSignal与timeout_ms毫秒级墙钟超时ast.rs#L86-L89。九、上限与节流Limits Capswrapper 可见结果上限DEFAULT_AST_LIMIT 50ast-grep.ts#L247单 target 依赖原生默认 50DEFAULT_FIND_LIMITast.rs#L19多 target 每 target 拉skip 50 1条再重分页原生 limit 至少钳到 1offset缺省为 0ast.rs#L656-L657解析错误展示上限PARSE_ERRORS_LIMIT 20packages/coding-agent/src/tools/render-utils.tscapParseErrors()同时把details.parseErrors封顶到这 20 条去重项parseErrorsTotal保留去重后的真实总数目录扫描策略include_hidden: true、use_gitignore: true且默认跳过node_modules——除非 glob 文本里显式出现node_modulesast.rs#L450-L458node_modules_unless_mentioned过滤在 crates/pi-walker/src/lib.rs#L313 定义无硬性文件数上限候选数量就是解析后 path/glob 经 gitignore 过滤的展开结果多路径去重resolveExplicitSearchPaths()在解析前对相同 path 输入去重。十、错误语义什么会失败什么只是噪音硬错误wrapper 抛ToolError空pat、非法skip、空path条目、不支持的内部 URL glob、无sourcePath的内部 URL、路径缺失。可读的外部 URL 会先物化再搜索而不是被拒绝。硬错误原生侧返回错误不可读的搜索根、glob 编译失败取消Aborted: Signal或超时Aborted: Timeout。非致命问题积累在parseErrors单文件解析失败与单语言模式编译失败不致命被收集进parseErrors与成功匹配一同呈现某文件的语言没有可编译模式时该文件被跳过语法错误节点tree-sitter error node的文件仍会被搜索——语法警告是附加信息不是跳过条件no matches不是错误即使记录了解析问题。对模型使用者的实际含义解析问题parse issues通常意味着查询写歪了或范围定错了而不是代码里没有这个东西。提示词critical部分原话是Parse issues query failure, not absence: fix pattern or tightenpathbefore concluding no matches并要求避免根目录级全库扫描先收窄path。十一、进阶注意事项Notes一次一模式pat永远被 TS 工具包进单元素patterns数组即使原生绑定支持多模式patterns: OptionVecStringOR 语义见 ast.rs#L64-L66模型也无法通过ast_grep一次发多个模式。不相关模式应分开调用。混合语言树可行但建议单语言原生按候选集中实际出现的语言逐种编译因此ast_grep可以搜索混合语言树但提示词仍建议尽量单语言调用以减少解析噪音。一个模式可能对部分语言成功、对另一部分语言产生逐文件 parse error——测试 ast.rs#L1324-L1361 验证了混合树中($X) $X只改写 TypeScript 文件、Rust 文件原样保留的行为。glob 语义陷阱*.ts只匹配直接子文件**/*.ts才递归原生测试 ast.rs#L1283-L1309glob_star_matches_only_direct_children/glob_double_star_matches_recursively对此有直接断言。锚点格式依赖会话编辑模式输出锚点供后续工具使用但确切格式取决于当前会话的编辑模式hashline还是行号模式。十二、最小可运行示例结合工具自带示例ast-grep.ts#L177-L198以下调用形式在开启astGrep.enabled后可直接使用{ pat: console.log($$$), path: src/**/*.ts }{ pat: import { $$$IMPORTS } from \react\, path: src/**/*.ts }{ pat: const $NAME ($$$ARGS) $BODY, path: src/utils/**/*.ts }{ pat: logger.$_($$$ARGS), path: src/**/*.ts }{ pat: processItems, path: src/worker.ts }实践建议总结先收窄path再搜含糊扩展名显式给lang区分没匹配与模式歪了——出现 parse issues 时先修模式或收窄范围需要跨目录时用分号列表让 wrapper 做多目标联合排序。参考文件索引工具文档 docs/tools/ast-grep.mdTS 工具实现 packages/coding-agent/src/tools/ast-grep.ts模型侧提示词 packages/coding-agent/src/prompts/tools/ast-grep.md原生搜索/解析/匹配引擎 crates/pi-natives/src/ast.rs语言别名与扩展名推断 crates/pi-ast/src/language/mod.rs模式编译与编辑应用 crates/pi-ast/src/ops.rs路径/glob 解析 packages/coding-agent/src/tools/path-utils.ts解析错误去重与展示上限 packages/coding-agent/src/tools/render-utils.ts渲染模式hashline vs 行号 packages/coding-agent/src/utils/file-display-mode.ts开关配置项 packages/coding-agent/src/config/settings-schema.ts#L4348-L4357原生绑定契约 packages/natives/native/index.d.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 的 ast_grep 工具：基于 ast-grep 的结构化源码搜索实战指南
oh-my-pi 的 ast_grep 工具基于 ast-grep 的结构化源码搜索实战指南【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-piast_grep 是 oh-my-pi 编码代理coding agent内置的结构化代码搜索工具它不按文本匹配而是把模式编译成 AST 节点在语法树层面定位函数调用、声明、导入等语言结构。本文围绕 docs/tools/ast-grep.md 展开结合 TS 工具入口、Rust 原生引擎 与 语言定义层 的源码完整讲解该工具的参数契约、模式语法、执行流水线、多目标搜索、错误语义与各类上限帮助你理解并正确使用这条语义级 grep链路。一、工具定位什么时候该用 ast_grep普通grep文本正则擅长找字符串但遇到语法形状问题就很笨拙比如找出所有console.log(...)调用、所有const foo () ...形式的箭头函数、或者某个包里被命名的 import。这类需求用正则写起来既脆弱又难以覆盖语法变体换行、注释、嵌套括号。ast_grep的定位见模型侧提示词 packages/coding-agent/src/prompts/tools/ast-grep.md是当语法形状比文本更重要时使用——即调用、声明、语言结构这类场景。它的工具元信息也写得直白summary Search code with AST patterns (structural grep)label AST Grepapproval read只读操作无需写权限审批。它在 oh-my-pi 中的启用方式与大多数可发现工具一致默认关闭astGrep.enabled false在配置 packages/coding-agent/src/config/settings-schema.ts#L4348-L4357 中声明为布尔开关tab: tools分组Available Tools标签 AST Grep。开启后它是一个loadMode discoverable的按需加载工具工具注册与开关判定逻辑位于 packages/coding-agent/src/tools/index.ts其中if (name ast_grep) return session.settings.get(astGrep.enabled)一行即可确认开关与注册的直接绑定关系。作为对照astEdit.enabled默认值是true结构化改写工具默认开启说明搜索与改写两条链路被刻意分开管理。二、输入参数pat / path / skip / lang工具 Schema 定义在 packages/coding-agent/src/tools/ast-grep.ts#L41-L48共有四个字段字段类型必填说明patstring是单个 AST 模式。wrapper 会先trim()空串直接抛错pathstring否单个文件、目录、glob、带 backing file 的内部 URL 或可抓取的 web URL也支持用分号分隔的列表如src; tests。省略或为空时默认.工作区根。空条目会被拒绝内部 URL 的 glob 会被拒绝skipnumber否匹配偏移量。默认0实际取Math.floor(...)负数与非有限值会失败langstring否语言覆盖例如对含糊的.h文件指定cppSchema 注释中的典型用法参数校验逻辑在execute()中非常明确ast-grep.ts#L211-L219pat先trim()长度为 0 时抛ToolErrorpat must be a non-empty patternskip在未提供时为 0否则Math.floor(params.skip)Number.isFinite不成立或小于 0 时抛skip must be a non-negative numberpath通过toPathList(params.path)展开空列表时回退为[.]。2.1 模式语法模型可直接使用的元变量文档与提示词共同给出的模式语法是 ast-grep 的核心能力归纳如下语法含义约束$NAME捕获一个 AST 节点名称必须大写必须代表完整 AST 节点不能是部分 token 或字符串片段$_匹配一个 AST 节点但不绑定不产生元变量$$$NAME捕获零个或多个 AST 节点注意是三个$$$NAME是非法写法ast-grep 会惰性停在下一个可满足节点$$$匹配零个或多个 AST 节点且不绑定—关键规则提示词 ast-grep.md#L6-L13 中逐条列出代码侧同样有佐证同一元变量出现多次要求每处代码完全相同$A $A只匹配x x不会匹配x y模式必须能解析为单个合法 AST 节点非独立片段需要包裹如class $_ { … }提示词中 TypeScript 示例是async function $NAME($$$ARGS): $_ { $$$BODY }——用: $_容忍任意返回类型注解声明形式彼此不同function foo、方法foo()、const foo () {}是三种 AST 形状搜索没有找到之前先确认搜对了形式C 表达式语句调用需要末尾分号ns::doThing($ARG);、$CALLEE($ARG);最宽松的存在性检查直接用裸标识符作为模式如pat: processItems配合收窄的path。2.2 模式编译的自动降级MultipleNode 包装回退源码在 crates/pi-ast/src/ops.rs#L97-L160 给出了一个文档之外的实现细节当模式片段例如 JSON 的key: $V被 ast-grep 判定为多根节点PatternError::MultipleNode时compile_pattern()并不会直接失败而是尝试把片段包进一个最小合法上下文再编译。目前只有 JSON 有包装模板({, }, pair)并且会自动把裸元变量加上引号quote_bare_metavars见 ops.rs#L165-L200。对 Rust 还有额外的上下文模式编译把模式包进fn __rwp_wrapper() { … }见 ops.rs#L394-L400。这说明模式必须解析为单个节点是主规则但存在可自动修复的例外路径。三、支持的编程语言与扩展名推断文档给出的规范语言列表来自SupportLang::all_langs()crates/pi-ast/src/language/mod.rs#L337-L346共 55 种astro, bash, c, cmake, cpp, csharp, dart, clojure, css, diff, dockerfile, emacs-lisp, elixir, erlang, fortran, go, graphql, haskell, hcl, html, ini, java, javascript, json, just, julia, kotlin, lua, make, markdown, nix, objc, ocaml, odin, php, powershell, protobuf, python, r, regex, ruby, rust, scala, solidity, sql, starlark, svelte, swift, toml, tlaplus, tsx, typescript, verilog, vue, xml, yaml, zig3.1 扩展名推断不只是后缀表语言推断实现在 crates/pi-ast/src/language/mod.rs#L614-L668 的from_extension()除了后缀映射表还有几类无扩展名/特殊文件名规则Makefile/makefile/GNUmakefile→makeJustfile→justCMakeLists.txt→cmakeDockerfile、dockerfile、Dockerfile.*、Containerfile→dockerfile.emacs→emacs-lisp无扩展名的 shell rc/profile 文件zshrc、.bashrc、bash_profile、profile、kshrc等十余种→bash注释说明这样做的动机是否则它们解析不到语言会导致 block-aware 操作失效。别名系统LANG_ALIASESmod.rs#L670-L829非常宽松ts/cts/mts→ typescriptjs/jsx/mjs/cjs→ javascriptcu/cuh→ cppmm→ objctf/tfvars/terraform→ hclbzl同时映射 starlark 与 python 推断等。测试用例mod.rs#L831-L846明确验证了 CUDA 源码与头文件推断为 C。文档特别提示.h这类同时属于 C/C 的扩展名有歧义应当显式传lang。3.2 expando 字符各语言如何消化$一个容易忽略的底层事实mod.rs#L105-L169多数语言不接受$作为合法标识符字符因此pi-ast为这些语言实现了expando_charpre_process_pattern用µ、、_、z等替换元变量展开后的占位如 Go/Rust/Kotlin 用µC/C 用CSS/Nix 用_HTML 用z。而 JavaScript、TypeScript、Java、Bash、Python语法本身允许$或经过子集处理等则走 stub 实现。这是同一个模式写法跨语言行为一致得以成立的关键机制。四、输出契约一次调用的返回内容4.1 模型可见的contentast_grep是单次single-shot工具模型看到的content是一个文本块规则如下ast-grep.ts#L323-L412目录/多文件搜索时按文件分组输出匹配行以[PATH#HASH]分组头 *LINE:text呈现hashline 模式否则*LINE|text多行匹配的续行前导一个空格当 ast-grep 捕获了元变量时每个匹配追加一行可选meta: NAMEvalue, …按名称字典序排序输出无匹配时文本为No matches found若同时存在解析问题则变为No matches found. Parse issues mean the query may be mis-scoped; narrow \path before concluding absence. 并附上格式化后的解析问题结果被截断时文本以Result limit reached; narrow path or increase limit.结尾。值得注意的是无匹配的结果会被标记为useless()ast-grep.ts#L309注释解释零匹配即使带解析问题也无用因为后续调用在 compaction 时早已纠正了方向。4.2details元数据detailsAstGrepToolDetailsast-grep.ts#L137-L158包含计数与元信息不含完整匹配负载必有matchCount、fileCount、filesSearched、limitReached可选parseErrors上限去重后的解析错误、parseErrorsTotal去重后、封顶前的总数、scopePath、searchPath、cwd、files、fileMatches、displayContent、meta。文档特别强调原生返回的字节/行列范围byteStart、byteEnd、startLine、startColumn、endLine、endColumn只存在于原生结果中TS wrapper 不会直接把这些字段透传给模型模型看到的是渲染后的文本行。这些字段在排序键AstFindOrderKey中承担稳定排序职责ast.rs#L115-L146。五、执行流水线从 TS 校验到原生匹配文档给出了完整流程这里结合源码逐段展开校验AstGrepTool.execute()校验pat、规整skipast-grep.ts#L211-L219然后把pat包成单元素patterns数组——模型侧一次只能发一个模式见第 7 节 Notes。路径解析委托给resolveToolSearchScope()packages/coding-agent/src/tools/path-utils.ts规整条目、展开分号分隔列表并做条件性的逗号/空白切分、拒绝空path条目。内部 URL / 外部 URL内部 URL 走共享路由解析到 backing file 路径没有sourcePath的条目与内部 URL glob 会失败。可读的外部 URL 会被物化为不可变本地临时文件再搜索materializeReadUrlToFileast-grep.ts#L234-L243。多路径处理partitionExistingPaths()只在至少还有一个存活 base时才丢弃缺失 base全部缺失则调用失败。parseSearchPathPreferringLiteral()把单个路径拆成basePath 可选globresolveExplicitSearchPaths()把多个输入合并为公共 base 花括号联合 glob当公共祖先本身不在请求路径中时退化为多个独立targets多路径去重也在这里完成。目录判定wrapper 对解析后的 base 路径做stat决定输出是否按目录分组。分发单一 base 走一次原生astGrep(...)多目标走runMultiTargetAstGrep(...)ast-grep.ts#L77-L135——每个 target 各调一次原生绑定把路径 rebase 回公共根全局排序后应用skip与 wrapper 上限。原生执行crates/pi-natives/src/ast.rs#L638-L792规整并去重模式列表normalize_pattern_listtrim BTreeSet去重空列表报错解析MatchStrictness默认smart可选cst/ast/relaxed/signature/template见 ast.rs#L22-L60通过pi_walker做 gitignore 感知的目录扫描收集候选文件collect_candidatesast.rs#L425-L484hidden(true)、gitignore(true)、skip_git(true)、follow_links(Never)、按路径排序、走fs_cache缓存未显式传lang时按扩展名逐候选推断语言按语言集合分别编译模式compile_find_patternsast.rs#L601-L635同一模式在混合语言树中为每种语言各编译一次单语言编译失败只记录 parse error 并跳过该语言的文件不整体失败逐文件读取、ast.root().dfs().any(|node| node.is_error())检测语法错误节点并记录 parse issue、执行find_all(pattern)、按需捕获元变量includeMeta匹配保留使用容量化的BinaryHeapoffset limit 1避免为海量匹配物化全部负载。排序与分页原生结果按路径 源位置排序再按offset/limit分页page_retained_matchesast.rs#L200-L216limitReached在此判定。TS 收尾规整解析错误字符串正则归一化…: parse error (syntax tree contains error nodes)前缀、去重、按格式化路径分组、渲染锚点行、追加 limit/parse 提示返回toolResult(...).text(...).done()。六、多目标multi-target搜索跨目录联合是怎么做的当一次调用传入多个路径例如path: src; tests且它们只在根目录相遇时wrapper 走runMultiTargetAstGrepast-grep.ts#L77-L135。核心行为每个 target 单独调用原生astGrepoffset固定为 0limit取skip 50 1多取一个供全局排序后判断是否截断每次取回后用path.resolve(target.basePath, match.path)还原绝对路径再path.relative(commonBasePath, ...)rebase 回公共根路径分隔符统一为/用容量化 top-k 保留retainAstFindMatch与原生侧 BinaryHeap 同思路跨 target 全局保留最好的skip limit 1条随后全局排序、跳过skip、截取limit聚合totalMatches、filesWithMatches、filesSearched、parseErrors任一 target 触限即置limitReached。七、模式 / 变体与渲染细节场景行为单文件原生路径就是该文件输出为扁平匹配行列表目录 可选 glob原生扫描目录后按编译后的 glob 过滤多个显式路径/globwrapper 合成一个虚拟 scope或在路径仅在根相遇时逐 target 调用内部 URL路由解析到 backing 文件即可搜索外部可读 URL物化为不可变临时文件后搜索渲染模式resolveFileDisplayMode()决定 hashline 还是行号模式hashline 模式要求 edit 工具 hashline 编辑模式开启且每文件锚点还需要一次成功的整文件快照recordFileSnapshot()——超限或不可读文件回退为普通输出hashline 的关联机制值得展开在 hashline 模式下wrapper 对命中的文件调用getEditStore(this.session).recordSnapshotFile(absolutePath)生成整文件内容 tag匹配行渲染为[PATH#HASH]锚点并把命中的行体记录进recordSeenLinesFromBodyast-grep.ts#L314-L363。这样后续 edit 工具拿到锚点时只要文件未变tag 就能验证锚点有效性——这正是输出锚点供后续工具使用的落地机制。八、副作用与取消/超时语义文件系统TS wrapper 会stat输入路径原生代码通过fs_cache读取匹配文件并扫描目录crates/pi-natives/src/fs_cache 相关实现会话状态除常规工具转录/结果元数据外无额外副作用后台工作原生工作跑在阻塞 worker 上task::blocking(ast_grep, ct, ...)见 ast.rs#L659取消与可选原生超时通过CancelToken::heartbeat()协作完成——ast_grep的AstFindOptions支持signalAbortSignal与timeout_ms毫秒级墙钟超时ast.rs#L86-L89。九、上限与节流Limits Capswrapper 可见结果上限DEFAULT_AST_LIMIT 50ast-grep.ts#L247单 target 依赖原生默认 50DEFAULT_FIND_LIMITast.rs#L19多 target 每 target 拉skip 50 1条再重分页原生 limit 至少钳到 1offset缺省为 0ast.rs#L656-L657解析错误展示上限PARSE_ERRORS_LIMIT 20packages/coding-agent/src/tools/render-utils.tscapParseErrors()同时把details.parseErrors封顶到这 20 条去重项parseErrorsTotal保留去重后的真实总数目录扫描策略include_hidden: true、use_gitignore: true且默认跳过node_modules——除非 glob 文本里显式出现node_modulesast.rs#L450-L458node_modules_unless_mentioned过滤在 crates/pi-walker/src/lib.rs#L313 定义无硬性文件数上限候选数量就是解析后 path/glob 经 gitignore 过滤的展开结果多路径去重resolveExplicitSearchPaths()在解析前对相同 path 输入去重。十、错误语义什么会失败什么只是噪音硬错误wrapper 抛ToolError空pat、非法skip、空path条目、不支持的内部 URL glob、无sourcePath的内部 URL、路径缺失。可读的外部 URL 会先物化再搜索而不是被拒绝。硬错误原生侧返回错误不可读的搜索根、glob 编译失败取消Aborted: Signal或超时Aborted: Timeout。非致命问题积累在parseErrors单文件解析失败与单语言模式编译失败不致命被收集进parseErrors与成功匹配一同呈现某文件的语言没有可编译模式时该文件被跳过语法错误节点tree-sitter error node的文件仍会被搜索——语法警告是附加信息不是跳过条件no matches不是错误即使记录了解析问题。对模型使用者的实际含义解析问题parse issues通常意味着查询写歪了或范围定错了而不是代码里没有这个东西。提示词critical部分原话是Parse issues query failure, not absence: fix pattern or tightenpathbefore concluding no matches并要求避免根目录级全库扫描先收窄path。十一、进阶注意事项Notes一次一模式pat永远被 TS 工具包进单元素patterns数组即使原生绑定支持多模式patterns: OptionVecStringOR 语义见 ast.rs#L64-L66模型也无法通过ast_grep一次发多个模式。不相关模式应分开调用。混合语言树可行但建议单语言原生按候选集中实际出现的语言逐种编译因此ast_grep可以搜索混合语言树但提示词仍建议尽量单语言调用以减少解析噪音。一个模式可能对部分语言成功、对另一部分语言产生逐文件 parse error——测试 ast.rs#L1324-L1361 验证了混合树中($X) $X只改写 TypeScript 文件、Rust 文件原样保留的行为。glob 语义陷阱*.ts只匹配直接子文件**/*.ts才递归原生测试 ast.rs#L1283-L1309glob_star_matches_only_direct_children/glob_double_star_matches_recursively对此有直接断言。锚点格式依赖会话编辑模式输出锚点供后续工具使用但确切格式取决于当前会话的编辑模式hashline还是行号模式。十二、最小可运行示例结合工具自带示例ast-grep.ts#L177-L198以下调用形式在开启astGrep.enabled后可直接使用{ pat: console.log($$$), path: src/**/*.ts }{ pat: import { $$$IMPORTS } from \react\, path: src/**/*.ts }{ pat: const $NAME ($$$ARGS) $BODY, path: src/utils/**/*.ts }{ pat: logger.$_($$$ARGS), path: src/**/*.ts }{ pat: processItems, path: src/worker.ts }实践建议总结先收窄path再搜含糊扩展名显式给lang区分没匹配与模式歪了——出现 parse issues 时先修模式或收窄范围需要跨目录时用分号列表让 wrapper 做多目标联合排序。参考文件索引工具文档 docs/tools/ast-grep.mdTS 工具实现 packages/coding-agent/src/tools/ast-grep.ts模型侧提示词 packages/coding-agent/src/prompts/tools/ast-grep.md原生搜索/解析/匹配引擎 crates/pi-natives/src/ast.rs语言别名与扩展名推断 crates/pi-ast/src/language/mod.rs模式编译与编辑应用 crates/pi-ast/src/ops.rs路径/glob 解析 packages/coding-agent/src/tools/path-utils.ts解析错误去重与展示上限 packages/coding-agent/src/tools/render-utils.ts渲染模式hashline vs 行号 packages/coding-agent/src/utils/file-display-mode.ts开关配置项 packages/coding-agent/src/config/settings-schema.ts#L4348-L4357原生绑定契约 packages/natives/native/index.d.ts【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
