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 代理技能,透過建構程式碼庫的架構感知圖形(包括模組邊界、依賴關係和呼叫流程),協助開發者在大型儲存庫和 monorepo 中進行導航。它的主要用途是在執行檔案操作(如 'grep'、'cat' 或 'find')之前查詢此圖形,以了解變更的影響、找出功能的實作位置,並發現架構違規。Wingbox 支援廣泛的語言,包括 Python、TypeScript、Rust、C#、Java、Go、Ruby、PHP 和 Dart,並可與 Claude Code、Codex 和其他 AI 編碼代理整合。其工作流程圍繞著兩個核心步驟:首先,使用 'search' 或 'quick' 等命令透過關鍵字定位模組,然後立即執行 'analyze' 命令以擷取該模組的完整上下文,包括邊界檔案、依賴關係和反向依賴關係。這種「先查詢後讀取」的方法能大幅減少需要手動檢查的檔案數量,使開發者能專注於相關程式碼,並降低意外副作用或中斷的風險。

相容平台✓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 鉤子;從標準輸入讀取鉤子輸入;在讀取圖形之前重新整理它
wingbox hook dirtyClaude 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 <fileid> [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 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]按語言劃分的 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 [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-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)。

相關技能