ccusage 仓库中使用 ast-grep 进行结构化代码检索：从 `run --pattern` 到关系规则与 `--debug-query`

ccusage 仓库中使用 ast-grep 进行结构化代码检索从run --pattern到关系规则与--debug-query【免费下载链接】ccusagenpx ccusage项目地址: https://gitcode.com/gh_mirrors/cc/ccusage本篇指南以 ccusage 仓库内的.agents/skills/ast-grep/SKILL.md技能文档为主体讲解在 Rust 与 TypeScript 混合的大型代码库中如何用 ast-grep 做语法结构层面的代码搜索——例如查找带特定参数的宏调用、匹配某个 match 分支的形态、或定位挂在某个 item 上的属性。读完本文你将掌握 ast-grep 的完整工作流如何从run --pattern起步、何时改用内联关系规则、stopBy: end的陷阱以及用--debug-query排查解析失败的技巧。何时该用 ast-grep结构化搜索与rg的分工ccusage 仓库的根文档 AGENTS.md 对工具定位有一句话概括ast-grep负责 structural searches in Rust or TypeScriptRust 或 TypeScript 的结构化搜索。这正是 SKILL.md 给出的选择判据当一次搜索依赖语法结构时就该拿起 ast-grep——典型场景包括查找带特定参数的宏调用例如某个println!、format!或自定义宏的调用形态匹配某种 match 分支的形状比如「只有单一表达式、没有 guard 的分支」定位挂在某个 item 上的属性attribute如#[derive(...)]、#[cfg(...)]。反过来如果只是找一段普通文本ripgreprg更快也更合适而重复代码的检测不属于 ast-grep 的职责由similarity-rs负责——这一点在 reduce-similarities 技能文档 中明确写明TypeScript 侧的重复代码检测归属typescript与ast-grep两个技能Rust 侧的重复函数、impl 方法、并行 struct/enum 定义则走similarity-rs。三者的边界可以总结为场景首选工具纯文本、无语法依赖的搜索rg依赖语法结构宏参数、match 分支形态、属性ast-grep重复代码检测similarity-rsRust/typescriptast-grepTS环境准备从 Nix dev shell 获得 ast-grepccusage 的开发环境统一由 Nix dev shell 提供。打开 nix/dev-shell.nix 的buildInputs约第 27–69 行可以看到工具链中同时并列着similarity、ast-grep、ripgrep、fd、fzf、delta、just等开发工具——ast-grep就来自这里。因此按 SKILL.md 的说明使用时有两条路径如果 shell 已经通过direnv激活直接调用ast-grep或sg即可如果当前 shell 尚未激活 dev shell需要给一次性命令加前缀direnv exec . ast-grep --help仓库内没有sgconfig.yml关系规则走--inline-rulesast-grep通常支持通过项目级配置文件sgconfig.yml声明规则集rule set但 ccusage 仓库刻意不放置这份文件。按照 SKILL.md 的约定所有关系型relational规则一律通过以下两种方式之一传递scan --inline-rules——把规则以 YAML/JSON 形式内联写在命令行中一个用完即弃的临时--rule文件——适合规则较长、内联不便时用完即删不进入仓库。这样做的好处是仓库根目录保持干净规则的生命周期与一次检索任务绑定不会出现「项目规则集」与临时需求互相污染的情况。限定搜索范围rust、apps、docs、nixccusage 是一个多语言 monorepo生产 CLI 以 Rust 为主见 AGENTS.md 的 Repository Shape 一节apps/ccusage是 npm 发布面bin 启动器、schema 产物、打包与基准脚本另有docs文档站和nix构建配置。因此 SKILL.md 给出的经验是把搜索范围限定到rust、apps、docs或nix之一可以让大规模搜索保持快速# 只搜 Rust 侧 direnv exec . ast-grep run --pattern match $X { ... } rust # 只搜 TypeScript/npm 侧 direnv exec . ast-grep run --pattern console.$METHOD($ARGS) apps即使不做范围限定、直接在整个仓库根目录搜索ast-grep 也会自动跳过被 gitignore 忽略的目录树所以裸根搜索不会把node_modules、构建产物等卷进来。核心工作流先run --pattern不足再放宽SKILL.md 给出的起点非常明确先用run --pattern起步只有在匹配不足under-matches时才逐步放宽。这是与「一上来就写复杂关系规则」相反的做法——先用最直接的语法模式确认 AST 形态再决定是否需要关系约束。例如在 ccusage 的 rust/crates/ccusage-core/src/agent_report.rs 中就有大量按kind分支的match语句约第 51、69 行cost.rs 中也有按mode分支的 match约第 39 行。如果想找出「所有对kind变量做 match 的位置」可以先从最宽松的形态开始ast-grep run --pattern match $X { ... } rust/crates/ccusage-core/src确认能命中后再决定是否收紧为具体的变量名、分支数量或 guard 条件。如果宽松模式命中过多、精确模式又完全命中不了问题往往出在预期形态与实际 AST 不一致——这时就该进入调试环节。关系规则的陷阱务必给stopBy: end当单个 pattern 不足以表达查询时需要用关系规则relational rule描述「某个子节点相对于父节点/兄弟节点的位置关系」。这里有一个必须记住的坑SKILL.md 专门强调关系规则要给定stopBy: end否则它们会在该方向上的第一个节点处停下。也就是说如果你用follows、precedes、inside、has等关系字段时忘记指定stopBy匹配会在遇到沿途第一个节点时就终止导致结果集偏离预期。正确写法示例# scan --inline-rules 或 --rule 文件中的关系规则片段 rule: pattern: $BODY inside: kind: match_arm stopBy: endstopBy: end表示一直走到该方向的尽头才停止而不是停在第一个节点上。模式不匹配预期形态用--debug-query导出解析结果结构化搜索最常见的挫败感是pattern 看起来没问题但就是匹配不到。此时不要靠猜SKILL.md 给出的手段是用--debug-query把解析结果 dump 出来直接查看你的 pattern 被解析成了什么 AST 形态ast-grep run --pattern match $X { ... } --debug-query对照 dump 出的节点树就能定位到是 meta 变量$X的绑定范围不对、省略号...的位置不对还是对某个语法结构的形态理解有误。--debug-query本质上是「以解析器视角看问题」比反复肉眼对比源码更高效。在 ccusage 中的典型实战场景结合技能文档 frontmatter 的说明与仓库现状ast-grep 在 ccusage 中的典型任务包括查找 Rust 语法模式在rust/crates核心 crate与rust/adapters各 Agent 适配器中检索特定宏调用、match 分支形态或属性例如定位所有对kind/mode/status做 match 的分发逻辑可参考 agent_report.rs、cost.rs。查找 TypeScript 语法模式在apps/ccusage的src/cli.js及各类脚本中做结构化检索。验证迁移validating migrations在批量重构如 match 结构改造、宏替换、属性增删之后用 AST 级搜索确认「不存在遗漏的旧形态」比文本级rg更可靠。编写 AST 级搜索命令把可复用的检索命令沉淀进技能或文档供后续任务直接调用。无论哪种场景都遵循同一套纪律限定范围rust/apps/docs/nix、从run --pattern起步、关系规则带stopBy: end、不匹配就--debug-query。这套方法论来自 SKILL.md是仓库内 Agent 协作时的事实标准。【免费下载链接】ccusagenpx ccusage项目地址: https://gitcode.com/gh_mirrors/cc/ccusage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考