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-search | Claude Code 的 PreToolUse 钩子;从 stdin 读取钩子输入;在读取图谱之前刷新它 |
wingbox hook dirty | Claude 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 <file | id> [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 accept | reject [--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 [id | all]` | 检查每个部分风格的边界规则(或该部分声明的规则);每一行命名 :part、:style 和 :rule;类型导入和猜测的层分开报告;然后哪些文件做了其层可能不允许的事情(capability-violation:域外的 SQL,基础设施外的出向 HTTP,领域中的框架,带有 :line 和 :evidence)以及风格的模式检查(pattern-violation)。仅当每个部分都被检查时才返回 boundaries-ok;未读取声明规则的部分,或没有确定风格的部分,返回 boundaries-not-checked 和 boundaries-partial 而不是 ok。退出状态:2 未检查(声明规则未读取),1 违规,0 否则 - 永远不要在退出 2 时报告通过 |
| `invariants [id | all]` | 检查命名约定违规 |
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 REPL | repl |
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)。当语言未检测到时使用 ?。