ast-outline

产品配图

关于

v0.4.0 自荐： 一句话： AI 编程助手的"代码骨架"工具包 —— 只需一个命令就能看清一个包的公共 API、两个文件间的依赖关系、整个仓库的循环引用、以及按语义找到相似代码段。12 个 MCP 工具，1 个二进制文件。现在支持 13 种语言。 🚀 从 0.4.0 到现在的变化 自上次自荐（v0.4.0，surface + 语义搜索）以来，ast-outline 从"代码阅读器"进化成了完整的代码分析工具链。 1. 依赖图子系统（v1.0.0）—— 重构前的"波及范围分析" 四个新命令，共享一个缓存依赖图： bash ast-outline deps src/auth.rs --depth 2 # auth.rs 引入了哪些文件（传递） ast-outline reverse-deps src/auth.rs # 谁引入了 auth.rs（重构波及范围） ast-outline cycles # 查找循环引用（CI 可配，存在循环则 exit 3） ast-outline graph . # 全量依赖图（文本 / JSON） ast-outline graph . --json # JSON 格式，schema: ast-outline.graph.v1 各语言导入解析策略 | 语言 | 解析能力 | |------|---------| | Rust | use crate:: / use super:: / mod foo;（含 #[path] 属性） | | Python | 相对导入 from .x import y、init.py 包解析、import a.b | | TypeScript | 扩展名探测链 .ts→.tsx→.d.ts→.js、index. 回退、tsconfig.json paths 别名 | | Java/Kotlin/Scala/C# | FQN 后缀索引（从 package/namespace 提取），内部类 strip-and-retry | | Go | go.mod module 前缀剥离，import "mymod/pkg/foo" 解析到 pkg/foo/.go | 2.0.1 新增： | 语言 | 导入指令 | 解析策略 | |------|---------|---------| | PHP | use Ns\Class、require/include | PSR-4 映射（composer.json 最长前缀优先）+ 相对路径回退 | | C++ | #include "local.h" / <system> | 相对路径解析，系统头标记 External | | Ruby | requirerelative | 本地文件解析，gem 标记 External | C++ AST 遍历器会递归进入 preprocifdef，所以 #ifndef HEADERGUARD 内部的 include 也能正确提取。PHP 遍历器处理嵌套导入（class → method → compoundstatement）。 2. 新语言适配器（v2.0.0）—— map / digest / show 覆盖 13 门语言 按语言分，每个适配器都能正确处理相应语言的语法细节： C++ — 类、结构体、枚举、构造函数/析构函数（tree-sitter-cpp 把构造/析构发射为 declaration 而非 functiondefinition，适配器已处理） PHP — 命名空间、接口、类、Trait；完整可见性及修饰符（public、static、abstract、readonly……） Ruby — 模块作为 Namespace、private/protected/public 逐方法作用域追踪、attrreader/writer/accessor 和 Rails 关联宏（hasmany、belongsto……）作为字段 SQL — 正则解析器处理 CREATE TABLE/VIEW/INDEX/FUNCTION/PROCEDURE/SEQUENCE；支持 Schema 限定名；PL/pgSQL 感知（处理 dollar-quoted 函数体和嵌套块注释） Markdown 也支持（.md/.markdown/.mdx/.mdown），按 heading 层级输出结构。 3. ast-outline install —— 一键接入所有主流 AI 编码工具（v0.5.0+） bash ast-outline install --all # 检测并安装到所有客户端 ast-outline install --target gemini --min-lines 150 # 只装 Gemini ast-outline install --target claude-code --local # 按项目安装（不写全局） ast-outline status # 查看已安装状态 ast-outline uninstall --all # 卸载 支持：claude-code、gemini、tabnine、cursor、aider、codex、copilot。 对 Claude Code、Gemini、Tabnine 还会注入 Read 拦截 Hook —— 当 LLM 尝试读取超过 --min-lines（默认 200）的源码文件时，自动替换为 map 输出（提取签名而非全文），Token 节省约 95%。 Claude Code Subagent 同步 Claude Code 的 Explore、Plan、general-purpose 等子智能体运行在隔离上下文中，看不到主 CLAUDE.md。ast-outline install 自动生成 .claude/agents/<Name>.md，内含完整的 ast-outline 提示词，让子智能体也能自动调用 ast-outline。 4. 命令重命名（v2.0.0 破坏性变更） | 旧名 | 新名 | 原因 | |------|------|------| | ast-outline outline | ast-outline map | "列出文件结构"而不是"再述一遍文件" | | graph --format text\|json\|dot\|dsm | graph（文本默认）+ graph --json | 与 deps / reverse-deps / cycles 保持一致 | 如果之前用 ast-outline install 安装过，重跑 ast-outline install --all 即可自动更新。 5. 增量重建 & 目录上溯（v1.1.0） Search 索引增量更新：首次构建后，后续只检查文件的 (mtime, size)，有变化才重新 hash。稳定状态下万文件仓库约 30ms 完成检查。 依赖图增量更新：同样基于 mtime 增量检测，--rebuild 强制重建。 目录上溯：在子目录执行 ast-outline search 或 deps 时，自动向上查找已存在的 .ast-outline/，实现在项目根目录的缓存上操作。 6. 其他改进 动态 digest 图例 — 只显示本次运行中出现过的符号标记 token（修复了一个图例总为空的潜在 bug） 批量解析错误警告 — 当 digest 中所有文件都解析失败时，红色横幅提示 安装器保护 — ast-outline install 不会覆盖手写的 ast-outline 内容，除非加 --force 更好的路径错误 — graph 告诉你传了文件而不是目录，deps/reverse-deps 告诉你传了目录而不是文件 stripquotes panic 修复 — 处理孤立的 " 或 ' token 不再崩溃 Subagent 前导修复（v1.0.1）— .claude/agents/Explore.md 的 frontmatter 现在正确，不会被 Claude 忽略 测试覆盖 11 个端到端测试覆盖 C++/PHP/Ruby 依赖图（PSR-4 解析、header-guard 传递、system-header 外部标记、reverse-deps 查询） 13 个 SQL 单元测试覆盖所有 DDL 类型、dollar-quoted 函数体、嵌套块注释 完整的跨语言集成测试套件：C++（类继承、构造/析构）、PHP（命名空间、trait、可见性）、Ruby（module 嵌套、attr/Rails 宏） 📦 安装 bash Homebrew (macOS) brew install aeroxy/tap/ast-outline Cargo cargo install ast-outline Nix nix run aeroxy/ast-outline 🧠 典型使用场景 bash 1. 看包的真正公共 API（解析所有重导出链） ast-outline surface . --tree 2. 重构前看波及范围 ast-outline reverse-deps src/auth.rs 3. 查找循环引用 ast-outline cycles 4. 语义搜索（BM25 + 密集向量） ast-outline search "how does login work" 5. 只看结构不看函数体 ast-outline map src/game.rs 6. 配合 AI 编码工具 ast-outline install --all 🙏 致谢 基于 ast-grep（@HerringtonDarkholme）和 tree-sitter 语义模型：minishlab/potion-code-16M MCP 协议标准：Anthropic Model Context Protocol 欢迎 Star、Issue、PR。让 LLM 理解代码时更聪明，而不是更暴力。

收录记录

1. 阮一峰周刊·用户投稿

   2026年4月26日 – 2026年5月10日 · 3 次收录