Community编程与开发github.com

Wingbox — 代码图谱与架构发现

为大型仓库和单体仓库提供代码图谱。在 grep 或读取文件之前使用它,适用于以下场景:变更会破坏什么(爆炸半径、影响分析)、谁在使用一个文件、函数、类型或包、功能在哪里实现、应该先读取哪些文件,以及模块和包之间如何相互依赖;在重构、跨包变更或任何非平凡编辑之前;以及探索不熟悉的代码库时。构建和查询架构感知的代码搜索、依赖图、调用流、模块边界和架构违规,支持 Python、TypeScript、TSX、Rust、C#、Java、Go、Ruby、Ruby on Rails、PHP、Laravel、Blade、Livewire、Eloquent、Dart 和 Flutter。

Wingbox — 代码图谱与架构发现 是什么?

Wingbox 是一个AI代理技能(例如与 Claude Code、Codex 或 Cursor 配合使用),它通过构建和查询架构感知的代码图谱,帮助开发者在大型或单体仓库中进行导航和重构。在读取任何源文件之前,它会提示开发者查询图,从而避免盲目地 grep 或阅读文件。它提供命令来构建代码图、分析模块的依赖关系、追溯 blast radius(影响分析)、查找调用链以及检测架构违规。该技能支持多种语言,包括 Python、TypeScript、Rust、C#、Java、Go、Ruby、PHP、Dart 等,并提供一个 /wingbox 命令,该命令会自动刷新图、进行分析,并在 markdown 报告和交互式 HTML 地图中显示结果。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/aileron-tech/wingbox/tree/HEAD

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Wingbox — 代码图谱与架构发现 是做什么的?

在读取源文件之前,查询 .wingbox/index.sexp 来发现模块、边界和依赖关系。永远不要盲目地阅读代码——先查询图谱。

/wingbox

当用户输入 /wingbox(在 Codex 中为 $wingbox)时,在执行任何其他操作之前执行以下操作:

  • /wingbox 无参数:查找图谱(项目根目录下的 .wingbox/index.sexp;每个 wingbox 命令也能从子文件夹中找到它)。如果图谱缺失或过时,则使用 wingbox build . 构建它。当项目的文件在图谱文件之后被修改时,图谱即为过时;以下检查可以找到这种情况:

    G=.wingbox/index.sexp
    [ ! -f "$G" ] || find . -type f -newer "$G" -not -path './.git/*' \
      -not -path './.wingbox/*' -not -path '*/node_modules/*' -print -quit
    

    重新构建只会重新解析内容已更改的文件。然后读取 .wingbox/REPORT.md,并向用户提供其“关键发现”、依赖最多的模块以及从哪里开始阅读,并说明映射文件是 .wingbox/map.html(wingbox open 会在离线浏览器中显示它)。

  • /wingbox <file>:运行 wingbox impact <file> 2 并总结依赖于该文件的内容以及应该首先读取哪些文件。

  • /wingbox <command> ...:运行 wingbox <command> ...(例如 /wingbox quick "file upload", /wingbox analyze src/billing/invoice)。

运行命令

当 wingbox 命令已安装(command -v wingbox)时,对于下面的每个查询都运行 wingbox <command> ...,并使用 wingbox build PATH 进行构建;它们接受与脚本相同的参数。通过 wingbox install 安装的技能没有 scripts/ 文件夹,并且始终使用该命令。

命令目的
`wingbox install [--global--project] [--assistant NAME ...] [--dry-run]`
`wingbox uninstall [--global--project] [--assistant NAME ...]`
wingbox open [PATH]在浏览器中打开项目的 .wingbox/map.html(如果没有浏览器则打印其路径)
wingbox update [--check] [--dry-run]使用 pipx、uv 或 pip 进行升级,然后刷新已安装的技能、代码块和钩子;警告早期版本遗留的文件(.code_graph*, wingbox-out/)
wingbox hook pre-searchClaude Code 的 PreToolUse 钩子;从 stdin 读取钩子输入;在读取图谱之前刷新它
wingbox hook dirtyClaude Code 在 Edit 和 Write 上的 PostToolUse 钩子:标记更改的文件,以便在下一次使用之前刷新图谱

每个命令都以文本形式输出事实;添加 --sexp 以获取 S 表达式。

脚本

此技能捆绑了 Python 脚本。在运行它们之前,先解析技能和目标根目录,以便扫描的项目始终是明确的:

  • scripts/code_graph_search.py — 查询代码图谱
  • scripts/build_code_graph.py — 从源代码生成代码图谱
  • scripts/build_infra_topology.py — 提取 Kustomize、Helm 和 Terraform 拓扑事实
  • scripts/git_descendants.py — 查找从 HEAD(或给定引用)开始的所有后代提交

切勿使用项目本地的这些脚本副本——它们可能已过时并输出 JSON 而不是 sexp。

前置条件

定位代码图谱。如果不存在,则构建它:

ls .wingbox/index.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /absolute/path/to/project && pwd -P)"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT" --full

Python 索引没有外部解析器依赖。对于其他检测到的语言,当解析器缺失或版本错误时,首次构建会在发布之前失败,并打印要运行的精确的每种语言命令,例如:

python3 -m pip install -r "$SKILL_ROOT/requirements/typescript.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/csharp.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/ruby.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/php.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/dart.txt"

只安装构建器命名的需求文件,然后重新运行它。requirements.txt 保留给基础设施拓扑依赖。

强制工作流程:先查询再读代码

对于非平凡的代码工作,在 rg、find、sed、cat、nl、打开目录或读取源文件之前,先运行代码图谱查询。该技能只有在作为第一个范围界定步骤使用,而不是在源文件已被检查后作为确认时,才有帮助。

当任务有明确的关键字时,快速首次通过:

python3 scripts/code_graph_search.py quick "keyword"

quick 搜索第一个匹配的模块,并立即运行 analyze。使用它来一步获取边界文件、依赖、反向依赖、层和违规。如果 quick 返回了错误的模块或没有匹配,则使用下面的显式 search -> analyze 流程。

步骤 1 — 查找模块 ID:

python3 scripts/code_graph_search.py search "keyword"
python3 scripts/code_graph_search.py entity EntityName

使用 search 或 entity 来定位模块 ID。模块 ID 是完整的相对路径,例如 billing-service/src/modules/invoice/invoice.service,而不是像 bs34 这样的短代码。代码图谱内部可能包含短的路径映射 ID,但它们会自动解析——始终传递人类可读的类似路径的字符串。不要猜测或发明模块 ID——始终先使用 search 确认。

步骤 2 — 分析模块(立即执行此操作,不是可选的):

python3 scripts/code_graph_search.py analyze <module-id>

analyze 是主要命令。它返回完整的上下文:边界文件、依赖、反向依赖、架构层和违规。在读取任何源代码之前始终运行它。

步骤 3 — 仅读取 analyze 输出中列出的边界文件。

步骤 4 — 不要读取整个目录。 如果边界显示 2-3 个相关文件,只读取这些文件。忽略目录中的所有其他内容。

命令参考

命令目的示例
search "<pattern>"在图谱上安全地执行文字/.* 搜索search "operative.*service"
analyze <id> [--all]完整模块分析(主要命令);除非使用 --all,否则最多命名 200 个依赖者;以与该模块相关的 (advice ...) 结束analyze drive/modules/drive/drive_schema
quick <keyword>搜索+分析第一个匹配(快捷方式)quick operatives
boundary <id>为变更读取哪些文件boundary operatives.service
boundary <id> --files-only仅文件路径(紧凑)boundary operatives.service --files-only
entity <Name> [--positions]查找定义 + 使用它们的模块;--positions:每个使用的位置(行和列)entity DrivePath --positions
usages <symbol> [--sexp] [--all]一个符号(Name、<file>::Name、<file>::Class.method)的所有使用,考虑到重新导出和别名,按文件、line:col 和类型(导入、重新导出、调用、类型、扩展、引用;对于接收者类型不在视野中的方法调用为 unresolved-call)显示;除非使用 --all,否则最多 200 个;在多个文件中定义的名字会列出候选者usages src/billing/invoice.ts::Invoice
deps <id> [depth]出向依赖树deps operatives.service 3
rdeps <id> [depth]爆炸半径(谁依赖于这个)rdeps drive_schema 2
`impact <fileid> [depth] --sexp [--all]`一个文件的爆炸半径:按最短深度的依赖者 + 要首先读取的文件;除非使用 --all,否则最多列出 200 个,计数始终完整;以关于该文件的建议结束
flow <id> <fn>追踪调用/数据流flow drive_api fetchFiles
module <id>单个模块及其边module operatives.controller
wingbox init [PATH] [--force] [--sexp] [--synonyms]将仓库拆分为部分,判断每个部分的架构风格(带有分数、证据和来源),并写入 .wingbox/config.yaml(除非使用 --force,否则保留);--synonyms 还通过内置词向量映射文件夹名称;在空文件夹中 --language L --style S --yes [--scaffold] 启动新项目(没有它们时会打印选项并退出 2)wingbox init --sexp
wingbox advice [--sexp] [--learned] / `wingbox advice acceptreject [--reason TEXT]`打开上次构建的建议(移动、修复违规、缺少文件夹),不包括已拒绝或长期忽略的建议;在 .wingbox/decisions.sexp 中记录决策
wingbox align [PART] [--to STYLE] [--learn] [--sexp]每个部分与其风格的差距(已放置的文件、遵循的规则、未放置的文件夹、违反的规则);--to 与另一种风格比较;--learn 写入学习到的文件夹和基线,以便仅报告新的违规wingbox align --sexp
wingbox place "<what>" [--part PART] [--sexp]根据部分风格的放置规则(当文件夹尚不存在时为 :new)以及它可以导入的内容,为新代码确定层和文件夹wingbox place "repository for invoices" --sexp
wingbox compare [--sexp]单体仓库的各个部分按语言:风格、层、差异(缺失的层、意味着另一层的文件夹名称、与大多数不同的风格)以及针对偏离部分的建议wingbox compare --sexp
wingbox learn --agent [PART] [--sexp] / wingbox learn --apply [FILE]/wingbox learn:运行 wingbox learn --agent,读取它命名的文件,仅以其格式回答((layer <part> <folder> <layer> :because "...")、(unknown ...)、最多一个 (style ...)),将答案传递给 wingbox learn --apply,显示结果;出错时修复命名的行并再次发送整个答案。当代码不确定一个文件夹时,在聊天中询问用户并以 :because "operator: <their words>" 回答;永远不要猜测。要更改 .wingbox/config.yaml,请遵循其顶部的说明wingbox learn --agent
`boundaries [idall]`检查每个部分风格的边界规则(或该部分声明的规则);每一行命名 :part、:style 和 :rule;类型导入和猜测的层分开报告;然后哪些文件做了其层可能不允许的事情(capability-violation:域外的 SQL,基础设施外的出向 HTTP,领域中的框架,带有 :line 和 :evidence)以及风格的模式检查(pattern-violation)。仅当每个部分都被检查时才返回 boundaries-ok;未读取声明规则的部分,或没有确定风格的部分,返回 boundaries-not-checked 和 boundaries-partial 而不是 ok。退出状态:2 未检查(声明规则未读取),1 违规,0 否则 - 永远不要在退出 2 时报告通过
`invariants [idall]`检查命名约定违规
layers按层显示所有模块,并显示设置每一层的部分、风格和规则layers
find_function <name>查找函数/方法定义find_function createOrder
find_type <name>查找类型/类/模块/接口/枚举定义find_type DriveDbCommitResponse
find_callchain <src> <tgt> [depth]追踪函数之间的调用路径find_callchain createOrder processPayment
find_callers <fn> [depth]谁调用了此函数find_callers handleRequest 3
find_calls <fn> [depth]此函数调用了什么find_calls createOrder 2
grep_functions <pattern>在源代码中搜索函数体grep_functions "validate.*input"
diff_functions [ref]git diff 中更改的函数diff_functions HEAD~3
query '<sexp>'可组合的 Scheme 查询query '(count (boundary "X"))'
repl交互式 Scheme REPLrepl
wingbox mcp [--root DIR]将这些命令作为 MCP 服务器上的工具运行(build、impact、usages、analyze、quick、boundary、deps、...),适用于 MCP 客户端claude mcp add wingbox -- wingbox mcp

impact 接受一个普通的文件路径。不带 --sexp 时,它会为人类打印可读的文本;代理传递 --sexp 以获取相同事实的紧凑 S 表达式形式,这是其他所有命令使用的格式。

快速参考:rg 查询

当你需要快速、有针对性的查找而无需调用 Python 脚本时,直接使用 rg 查询代码图谱。构建器将图写入 .wingbox/index.sexp:

# 关于模块的所有事实
rg 'drive/modules/drive_db/api ' .wingbox/index.sexp

# 谁导入了一个模块
rg 'imports .* drive/modules/commons/result' .wingbox/index.sexp

# 一个模块导入了什么
rg 'imports drive/modules/drive_db/api' .wingbox/index.sexp

# 对所有实体的所有引用
rg 'DriveDbCommitResponse' .wingbox/index.sexp

# 仓库中的所有类
rg '^\(cls drive/' .wingbox/index.sexp

# 数据流边
rg 'data-flow' .wingbox/index.sexp

# 通过从配置文件读取的名称加载的 Python 模块
rg 'registry-wires' .wingbox/index.sexp

这些单行命令对于快速检查很有用。对于结构化输出和完整分析,请使用 Python 脚本命令。

输出符号

所有输出都是 S 表达式事实,每行一个。请参阅 references/sexp-notation.md 了解完整格式。

关键模式:

(boundary <mod> :lang py :file <path> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <path> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <path> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Name> <line> :lang py :file <path>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<reason>")
(result <module-or-path>)
(result-count 42)

:lang 值:py = Python (snake_case), ts = TypeScript (camelCase), tsx = TSX (PascalCase,对于组件), rs = Rust (snake_case), cs = C# (PascalCase), java = Java, go = Go, rb = Ruby (snake_case), rbs = Ruby 签名 (snake_case), php = PHP (snake_case 或 PascalCase), dart = Dart (camelCase 或 snake_case), bf = Blade (snake_case 用于模板), proto = Protobuf (snake_case), tf = Terraform (snake_case), kustomize = Kustomize YAML, helm = Helm 图表 (snake_case)。当语言未检测到时使用 ?。

相关技能