ast-grep-outline

使用 ast-grep outline

ast-grep outline 会打印源代码的精简结构图，并附带行号：顶层条目（导入、函数、类、结构体、接口、模块、枚举）及其直接成员（字段、方法、构造函数、枚举变体）。这是本地的纯语法视图，开销很低，可以在完整读取文件之前运行。

分阶段读取代码：通过搜索或文件名找到候选文件，查看其 outline，然后只打开 outline 指向的源代码范围。默认行为会根据输入调整：文件会显示其局部结构和成员摘要；目录则只会按组显示其导出接口。

适用场景

编辑前了解文件。 在阅读实现细节之前，先获取目录、依赖项和公共入口：

ast-grep outline <file>
ast-grep outline <file> --items imports
ast-grep outline <file> --items exports

梳理陌生目录。 扫描子树的公共接口，然后在确定要查找的内容后按符号类型缩小范围：

ast-grep outline <dir> --items exports
ast-grep outline <dir> --type struct,enum,function

深入查看已知符号。 搜索找到可能的名称后，列出其成员及行号，而不是读取整个函数体：

ast-grep outline <file> --match <symbol> --type class --view expanded

追踪依赖方向。 查找导入某个包或模块的文件，以确定更改应放在哪里：

ast-grep outline <dir> --items imports --view signatures

编辑后审查更改的文件。 Git 会告诉你哪些内容发生了变化；outline 会概述更改后的结构和公共接口：

ast-grep outline $(git diff --name-only HEAD) --items exports

参数指南

• --items <KIND> 选择顶层条目：structure 表示局部声明（文件的默认值），exports 表示公共 API（目录的默认值），imports 表示依赖项，all 表示同时关注导入和导出关系。
• --view <VIEW> 控制详细程度，由少到多依次为：names 用于扫描目录，signatures 为每个条目显示一行，digest 显示签名和成员名称，expanded 为每个成员显示一行及其行号。
• --match <REGEX> 按名称或签名筛选顶层条目。使用 Rust 正则表达式，区分大小写；不会匹配成员。
• --type <TYPE[,TYPE...]> 仅保留部分顶层符号类型，例如 --type class,function。method,field 之类的成员类型不会匹配顶层条目。
• --pub-members 在视图显示成员时隐藏私有成员。
• --json=stream 为每个文件输出一个带精确范围的 JSON 对象。仅在需要通过管道传输或后处理条目时使用；导航时优先使用文本格式。

限制

outline 显示的是局部语法结构。它不会解析引用、推断类型、追踪重新导出链，也不会构建调用图。如需回答这些问题，请使用 ast-grep run、rg 或基于编译器的工具，再对它们找到的候选文件使用 outline。