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 鉤子;從標準輸入讀取鉤子輸入;在讀取圖形之前重新整理它 |
wingbox hook dirty | Claude Code 的 PostToolUse 鉤子,用於編輯和寫入:標記已變更的檔案,以便在下次使用前重新整理圖形 |
每個命令都以文字形式列印事實;加上 --sexp 可使用 S-expression。
腳本
此技能包含 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] | 完整的模組分析(主要命令);最多列出 200 個依賴項,除非加上 --all;以有關該模組的 (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 和種類(import、re-export、call、type、extends、reference;unresolved-call 用於接收者型別不在視野內的方法呼叫)列出;最多 200 個,除非加上 --all;在多個檔案中定義的名稱會列出候選項 | 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]` | 一個檔案的爆炸半徑:按最短深度排列的依賴項 + 首先讀取的檔案;最多列出 200 個,除非加上 --all,計數始終完整;以有關該檔案的建議結尾 |
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] | 按語言劃分的 monorepo 各部分:風格、層級、差異(缺少層級、表示另一層級的資料夾名稱、與大多數不同的風格)以及對偏差部分的建議 | 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-expression 形式的事實,這也是所有其他命令使用的格式。
快速參考: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-expression 事實,每行一個。有關完整格式,請參閱 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),rb = Ruby(snake_case),cs = C#(PascalCase),java = Java(camelCase),go = Go(camelCase),rs = Rust(snake_case),php = PHP(camelCase),dart = Dart(camelCase)。