圖：原理、接入與實踐)
平時畫架構(gòu)圖最煩什么不是不知道怎么寫代碼而是畫圖這件事本身就是個“高成本低產(chǎn)出”的活兒。需求一變服務(wù)一拆圖就廢了圖一廢后面接手的人又得重新讀代碼猜結(jié)構(gòu)。GitHub 上最近被開發(fā)者反復(fù)轉(zhuǎn)發(fā)的一個項目archify走的就是另一個路子它不讓你動手畫而是直接把“生成可交互架構(gòu)圖”做成一個 AI 代理能夠調(diào)用的技能模塊——你只需要告訴你的 AI 助手“幫我看一下這個項目的架構(gòu)”剩下的掃描代碼、識別依賴、渲染交互式圖譜全自動完成。我第一時間拉下來試了試前后折騰了兩天期間踩了不少文檔里沒寫的坑。這篇就把它的工作原理、接入方式、實操過程和問題排查從頭到尾捋清楚如果你也在搞 AI 代理、代碼分析或者架構(gòu)可視化這篇應(yīng)該能讓你少走很多彎路。1. 項目概述archify 到底解決了一個什么問題1.1 傳統(tǒng)架構(gòu)圖維護的痛點先說一個所有維護過老項目的人都經(jīng)歷過的場景你接手一套代碼幾百個文件幾十個微服務(wù)注釋約等于沒有。領(lǐng)導(dǎo)說“你出個架構(gòu)圖”你打開 Visio 或者 Draw.io對著代碼文件一個一個找依賴關(guān)系。畫完了交付兩周后服務(wù)拆分圖又過期了。這種文檔漂移問題在軟件工程里一直是老大難——圖一旦跟代碼脫節(jié)就徹底失去參考價值。archify 的想法很簡單架構(gòu)圖不該由人手動去維護因為代碼本身就是最權(quán)威的架構(gòu)事實來源。與其人去讀代碼然后畫圖不如讓程序去掃描代碼、解析依賴、聚類模塊邊界然后自動生成一張圖。而且它還不止生成靜態(tài)圖而是輸出一張可交互的網(wǎng)頁版架構(gòu)圖——你可以點開某個服務(wù)節(jié)點看它依賴了誰折疊不想看的分支甚至直接定位到對應(yīng)的源碼文件。1.2 為什么做成“AI 代理的技能模塊”這是 archify 和普通的代碼可視化工具最不一樣的地方。它不是給你一個按鈕讓你上傳代碼而是暴露了一個可以被大語言模型直接調(diào)用的工具接口。所謂技能模塊就是給 AI 代理增加一種“能做特定動作”的能力——agent 在對話過程中如果發(fā)現(xiàn)需要理解代碼結(jié)構(gòu)它可以自動調(diào)用 archify把掃描請求發(fā)出去然后拿結(jié)果繼續(xù)推理。這個設(shè)計思路非常務(wù)實?，F(xiàn)階段的 AI 助手雖然能讀懂代碼片段但面對整個倉庫時受限于上下文窗口它對全局依賴關(guān)系的感知是零散的。如果給代理配一個專門的架構(gòu)掃描工具它就能在分析大型項目時先獲取一張全局結(jié)構(gòu)圖再帶著這張圖去做代碼解釋、重構(gòu)建議、影響面分析。等于給了大模型一副“全景眼鏡”不再局限于看哪算哪。1.3 archify 的定位與適用人群如果你正在做下面這幾類事情archify 大概率對你有用給老項目補架構(gòu)文檔需要快速生成一張可以交付的架構(gòu)圖搭建個人 AI 編程助手希望它能理解你本地項目的結(jié)構(gòu)做微服務(wù)治理或者系統(tǒng)設(shè)計評審需要一張能交互、能下鉆的依賴關(guān)系圖或者單純就是覺得手動畫圖太浪費時間。項目本身以 Python 為主依賴管理用的是標準 pyproject 方式本地環(huán)境下通過 pip 就能安裝。生成的交互式 HTML 頁面完全離線運行不依賴任何第三方 CDN 或在線服務(wù)這一點對很多公司內(nèi)網(wǎng)環(huán)境來說非常友好。2. 核心設(shè)計思路AI 代理如何完成自動掃描與圖譜生成2.1 從代碼目錄到架構(gòu)節(jié)點的解析流程我把 archify 的執(zhí)行鏈路拆成四步來看代碼掃描、依賴分析、模塊聚類、渲染輸出。代碼掃描層負責遍歷目標倉庫的文件識別支持的語言類型目前對 Python、TypeScript/JavaScript、Java 的支持最完整同時跳過構(gòu)建產(chǎn)物、虛擬環(huán)境、node_modules 這類無關(guān)目錄。這個階段的關(guān)鍵是速度——archify 使用了多進程并行遍歷實測一個兩萬文件的中型倉庫全量掃描大概在十秒級別。依賴分析層讀取不同語言的模塊引用關(guān)系Python 包里的 import 語句、TypeScript 項目里的 import/export、Java 里的包引用等。archify 沒有走運行時字節(jié)碼分析的老路而是做靜態(tài)引用采集好處是快且不依賴項目能編譯通過代價是動態(tài)導(dǎo)入、反射調(diào)用這類場景會漏掉一部分隱性依賴遇到這種情況人工補一下關(guān)系即可。模塊聚類層做的事情非常像一次簡化版的逆向外推根據(jù)代碼目錄結(jié)構(gòu)和包名把解析出來的模塊關(guān)系聚合成服務(wù)或組件級別的節(jié)點。比如services/order目錄下的所有模塊會被歸到 “訂單服務(wù)” 這個節(jié)點再把這個節(jié)點跟它實際調(diào)用的數(shù)據(jù)庫、消息隊列、下游服務(wù)建立邊關(guān)系。渲染輸出層的產(chǎn)物有兩種一種是標準 Mermaid 格式方便直接在 Markdown 文檔里預(yù)覽另一種就是核心賣點的交互式 HTML——節(jié)點可以拖拽、點擊聚焦、按層級折疊展開還支持搜索定位。2.2 為什么大模型直接生成 Mermaid 不可行有人可能會問現(xiàn)在大模型本身就會寫 Mermaid讓 GPT 直接畫一套微服務(wù)架構(gòu)圖不就行了這事兒我試過效果真的不穩(wěn)定。大模型對代碼庫的全局結(jié)構(gòu)沒有真實感知它只能根據(jù)你提供的片段和它的先驗知識去“猜”架構(gòu)一旦項目里存在非典型目錄結(jié)構(gòu)、自定義框架封裝、或者復(fù)雜的跨服務(wù)調(diào)用它畫出來的圖往往跟真實代碼對不上。而 archify 走的是“先掃描事實再讓模型參與組織與表達”的路線。它提供的圖數(shù)據(jù)是真實依賴關(guān)系的采樣結(jié)果AI 代理拿到這些結(jié)構(gòu)化數(shù)據(jù)后可以沿著真實的結(jié)果去做解讀、提煉、繪圖參數(shù)調(diào)整。比起讓模型自己編這相當于先給了它一份“標準答案”錯誤率天然低了很多。2.3 技能模塊與大模型工具調(diào)用的關(guān)系從 AI 代理的角度看archify 就是一個標準的工具注冊單元。現(xiàn)在主流代理框架都支持工具注冊像 Claude 的 tool use、OpenClaw 的 action 模塊、以及各類支持 MCPModel Context Protocol的客戶端。archify 提供了兩種接入方式一種是作為命令行工具被代理通過 shell 方式調(diào)用另一種是通過 MCP 接口注冊為標準工具。MCP 方式我個人比較推薦。它把工具描述、輸入?yún)?shù) Schema 和調(diào)用執(zhí)行封裝成統(tǒng)一協(xié)議代理在需要獲取項目結(jié)構(gòu)信息時自行決定是否調(diào)用不需要你在 prompt 里寫一堆調(diào)用規(guī)則。接入后你可以在對話里直接說“分析一下當前倉庫的模塊依賴畫一張交互架構(gòu)圖”代理會自己完成從目錄定位、掃描調(diào)用、結(jié)果接收、再到把 HTML 文件路徑返回到對話里的完整閉環(huán)。2.4 生成的數(shù)據(jù)結(jié)構(gòu)與圖譜表達archify 內(nèi)部用的是節(jié)點-邊node-edge數(shù)據(jù)結(jié)構(gòu)來組織架構(gòu)關(guān)系節(jié)點記錄了名稱、類型service/database/mq/module、描述、源碼路徑邊上記錄了關(guān)系類型depends_on/calls/contains和描述。這個結(jié)構(gòu)和 Neo4j 這類圖數(shù)據(jù)庫的模型很像所以如果后續(xù)要做更復(fù)雜的架構(gòu)分析直接把導(dǎo)出的 JSON 灌進圖數(shù)據(jù)庫做查詢也是可行的。交互式 HTML 側(cè)用的是類似力導(dǎo)向圖的渲染方案重依賴但不是 D3.js整體包體做了精簡單個頁面在 400KB 左右。每個節(jié)點都綁定了源碼跳轉(zhuǎn)鏈接點擊后會在新標簽頁打開對應(yīng)文件這一點對代碼走讀寫報告特別順手。3. 實操篇把 archify 接入到本地 AI 代理工作流3.1 環(huán)境準備與安裝先說環(huán)境要求。archify 基于 Python 3.11 開發(fā)建議在干凈的虛擬環(huán)境里安裝避免污染全局 Python 環(huán)境python3.11 -m venv .venv source .venv/bin/activate pip install archify如果是 macOS 用戶建議用 Homebrew 里的 Python 3.12 版本系統(tǒng)自帶 Python 比較容易踩權(quán)限坑。安裝完之后跑一下版本驗證archify --version看到版本號輸出就算成功。如果你打算走 MCP 方式接入還需要確保你用的代理客戶端支持 MCP 協(xié)議我用的是 OpenClaw配置文件里聲明一下即可。3.2 快速掃描生成第一張交互圖進入一個你想分析的項目目錄直接執(zhí)行archify scan --input /path/to/your/project --format html --output ./arch.html第一次跑的時候它會全量掃描過程中終端會打印已識別的模塊數(shù)量和依賴關(guān)系條數(shù)。跑完之后打開arch.html你會看到一張帶力導(dǎo)向效果的交互圖節(jié)點顏色區(qū)分了服務(wù)、數(shù)據(jù)庫、外部 API 等類型圖上方有一個搜索框用來定位節(jié)點。如果只想生成 Markdown 友好的 Mermaid 格式archify scan --input /path/to/your/project --format mermaid --output ./arch.md生成的 Mermaid 代碼可以直接粘貼到支持 Mermaid 的文檔平臺展示。我的習慣是先跑 HTML 格式用于交互分析確認整體結(jié)構(gòu)沒問題后再補一份 Mermaid 放進設(shè)計文檔。3.3 通過 MCP 將 archify 注冊為代理技能MCP 方式接入的配置非常簡單以 OpenClaw 示例在其配置文件中添加{ mcpServers: { archify: { command: archify, args: [mcp] } } }重啟代理后用類似“請生成當前項目的交互式架構(gòu)圖”的指令測試。代理會自動感知到已注冊的工具并在對話中調(diào)用。實測下來從發(fā)出指令到收到 HTML 文件路徑整個過程通常在 20 秒內(nèi)取決于倉庫規(guī)模與磁盤讀寫速度。3.4 面向大型倉庫的配置建議大型倉庫直接全量掃描生成的圖會變成一團亂麻沒法看。archify 提供了裁剪參數(shù)來處理這種情況在實際項目里我用了這樣的配置archify scan --input ./ --format html --output ./arch.html \ --ignore build,dist,.git,.venv,tests \ --focus services,api,core \ --depth 2--ignore指定跳過目錄--focus指定重點分析目錄--depth控制解析遞歸深度。它解決了一個畫圖經(jīng)典問題只展示你關(guān)心層級的架構(gòu)而不是把每個函數(shù)都鋪在圖上。配合模塊聚類參數(shù)還能進一步合并同類節(jié)點讓架構(gòu)圖的抽象層級更合理。比例控制上我拿一個電商后端項目測過完整掃描有 800 多個節(jié)點加上--depth 2和--focus之后壓縮到 40 個核心節(jié)點這已經(jīng)非常接近一張人工繪制的架構(gòu)概要圖了。4. 案例實操從零生成微服務(wù)架構(gòu)交互圖4.1 目標項目結(jié)構(gòu)介紹我用一個模擬的電商后端項目做完整演示項目目錄是這樣布局的ecommerce/ ├── api-gateway/ # 網(wǎng)關(guān)服務(wù) ├── services/ │ ├── user/ # 用戶服務(wù) │ ├── order/ # 訂單服務(wù) │ ├── payment/ # 支付服務(wù) │ └── inventory/ # 庫存服務(wù) ├── shared/ │ ├── mq/ # 消息隊列客戶端封裝 │ └── db/ # 數(shù)據(jù)庫訪問層 ├── docs/ └── scripts/這個結(jié)構(gòu)比較典型有網(wǎng)關(guān)層、業(yè)務(wù)服務(wù)層、基礎(chǔ)設(shè)施層正好能展示 archify 在分層聚類上的表現(xiàn)。4.2 掃描過程的完整記錄執(zhí)行archify scan --input ./ecommerce --format html --output ./ecommerce-arch.html掃描期間終端輸出的信息反映了它的解析進度[archify] scanning 186 source files... [archify] detected git repo, using ref HEAD [archify] module clusters found: gateway(1), service(4), db(2), mq(2) [archify] edges resolved: 23 [archify] rendering interactive canvas...注意第二行detected git repo——archify 會讀取 Git 歷史來輔助判斷模塊歸屬如果不在 Git 倉庫里運行有的高級聚類功能會降級。邊緣關(guān)系只解析出了 23 條主要因為模擬項目服務(wù)間調(diào)用本來就不算密集真實的微服務(wù)系統(tǒng)會多得多。4.3 生成的交互架構(gòu)圖解讀打開輸出的 HTML 后默認視圖按模塊邊界展開。畫面上五個主要節(jié)點——網(wǎng)關(guān)、用戶服務(wù)、訂單服務(wù)、支付服務(wù)、庫存服務(wù)是最大的一級節(jié)點分布在畫布中央連線表示它們之間的調(diào)用關(guān)系。操作細節(jié)做得很到位。鼠標懸停一條邊會顯示這條依賴對應(yīng)的實際代碼位置點擊后跳轉(zhuǎn)到源碼。雙擊某個服務(wù)節(jié)點整個畫布會以它為焦點展開剩下的節(jié)點全部收縮成側(cè)邊欄列表。這種交互邏輯對排查“這個服務(wù)到底被誰調(diào)用了”這類問題特別有效比傳統(tǒng)靜態(tài)架構(gòu)圖效率高太多了。訂單服務(wù)的下鉆視圖值得單獨說一下。它能看到內(nèi)部的控制器層、領(lǐng)域服務(wù)層、倉儲層各自依賴的組件以及它對消息隊列和生產(chǎn)者的引用情況。這就是交互式架構(gòu)圖對比靜態(tài)圖的優(yōu)勢——宏觀和微觀切換變得完全無感。4.4 增量更新與 CI 流程結(jié)合的思路架構(gòu)圖要長期保鮮就必須在每次代碼變更后更新。archify 提供了--ref參數(shù)支持基于 Git 引用的增量分析可以結(jié)合 CI 流水線實現(xiàn)自動更新archify scan --input ./ecommerce --format html \ --output ./docs/architecture/index.html \ --ref origin/main每次主分支有合并流水線跑一次任務(wù)自動刷新架構(gòu)圖產(chǎn)物。然后通過團隊的文檔平臺把更新后的 HTML 發(fā)布出去。這樣做到“有代碼變更有圖變更”架構(gòu)文檔跟著代碼走的體驗比強調(diào)“我們定期維護文檔”靠譜多了。5. 踩坑記錄實測中的問題與排查思路5.1 掃描速度過慢我第一次在真實項目里跑 archify直接對倉庫根目錄全量掃描結(jié)果卡了近三分鐘才出結(jié)果。排查發(fā)現(xiàn)虛擬環(huán)境.venv、前端依賴目錄node_modules、打包產(chǎn)物目錄都被當成了源碼內(nèi)容解析了。后來添加了全局忽略配置# ~/.config/archify/ignore.toml [ignore] dirs [.venv, node_modules, build, dist, target, __pycache__]再跑速度從三分鐘降到十幾秒。如果你的倉庫里混入了大體積的 SQL 腳本或者數(shù)據(jù)文件也建議在忽略列表里加一下避免無意義的磁盤讀取。5.2 交互式 HTML 在瀏覽器里白屏白屏問題多數(shù)不是 archify 生成的 HTML 有 bug而是瀏覽器版本過舊不支持 ES6 語法和 Canvas 相關(guān) API。公司內(nèi)網(wǎng)環(huán)境里員工用的瀏覽器版本往往滯后得厲害遇到白屏先別懷疑項目切換一個 Chrome 內(nèi)核瀏覽器試試。另外有些電腦配置了嚴格的 Content-Security-Policy 或防火墻策略攔截了頁面內(nèi)嵌腳本執(zhí)行。建議直接檢查瀏覽器 Console 的報錯信息是腳本執(zhí)行被攔截還是資源加載被攔截對癥處理。5.3 MCP 注冊后代理無法發(fā)現(xiàn)工具如果你通過 MCP 注冊了 archify但代理始終不調(diào)用它大概率是兩個原因。一個是 MCP 服務(wù)啟動失敗命令行方式能跑但 MCP 模式下起不來另一個是工具描述信息太模糊代理不知道這個工具在什么場景下該用。排查第一項直接在終端跑archify mcp看是否正常監(jiān)聽。排查第二項我建議把工具描述寫得足夠明確例如{ name: generate_project_architecture, description: 掃描代碼倉庫并生成可交互架構(gòu)圖。當用戶詢問項目架構(gòu)、模塊依賴、服務(wù)關(guān)系時調(diào)用此工具。, parameters: {} }工具描述越明確代理的調(diào)用觸發(fā)越可靠。5.4 大型項目生成的 HTML 文件過大在小微服務(wù)上 archify 表現(xiàn)很好但一旦掃描整個中大型單體倉庫生成的 HTML 可能達到 2-3MB打開顯慢。解決方案是在生成時增加裁剪參數(shù)控制參與渲染的節(jié)點數(shù)量。我在實際使用中形成的規(guī)則是單次渲染超過 150 個節(jié)點就開始影響瀏覽體驗。配置--max-nodes 120并調(diào)整--depth 1到合適的層級可以讓 HTML 文件體積控制在 500KB 以下交互流暢度也會明顯改善。5.5 與 AI 代理組合時的隱性成本archify 作為技能模塊接入 AI 代理后還需要留意上下文開銷。代理調(diào)用工具之后拿到的是一份包含節(jié)點、邊、描述的 JSON這個數(shù)據(jù)對象本身不大但如果在一次對話里反復(fù)讓代理生成多張不同項目的架構(gòu)圖上下文里疊加的 JSON 會越來越多導(dǎo)致后續(xù)對話變慢。解決辦法是每次分析完只保留關(guān)鍵結(jié)論把完整的 JSON 數(shù)據(jù)寫入本地緩存文件而不是留在對話里。我通常讓代理只回傳“發(fā)現(xiàn) 4 個服務(wù)節(jié)點和 23 條依賴關(guān)系”這類摘要需要細節(jié)時再讀文件整體效率高出很多。6. 我對 archify 的看法與后續(xù)擴展方向6.1 項目現(xiàn)狀的客觀評估從我這兩天的實際體驗來看archify 目前的成熟度介于“能用的工具”和“好用的產(chǎn)品”之間。它最核心的掃描-聚類-渲染鏈路已經(jīng)跑通了交互式 HTML 的體驗在同類開源工具里算得上第一梯隊。但分支支持、異常處理、新語言適配這些環(huán)節(jié)還有不少缺口代碼里能看到一些實驗性質(zhì)的模塊劃分項目的日常維護活躍度也在變化中。對于一個面向 AI 代理的工具來說當前階段最大的價值在于把“理解架構(gòu)”這個能力從人轉(zhuǎn)移到了機器。即使你只把它當 CLI 工具用不接任何代理它也能大幅壓縮畫圖的時間。6.2 延展方向可交互架構(gòu)圖之上的更多可能性交互式架構(gòu)圖只是第一步基于圖數(shù)據(jù)的擴展玩法其實很多。比如結(jié)合代碼指標在節(jié)點上展示復(fù)雜度、提交頻率、缺陷率就變成了一張“架構(gòu)體檢圖”把架構(gòu)數(shù)據(jù)與運行時指標關(guān)聯(lián)起來就能做依賴健康度透視分析哪些節(jié)點是故障擴散的源頭。跟 AI 代理結(jié)合最值得期待的方向是“架構(gòu)評審助手”。讓代理定期調(diào)用 archify 生成基線與本次變更兩張架構(gòu)圖自動對比新舊結(jié)構(gòu)差異然后從依賴增加、循環(huán)引用、模塊膨脹等維度輸出評審意見。這一步如果能走通就等于把代碼架構(gòu)守護變成了自動化流水線的一部分而 archify 正好補上了“讓代理獲得真實結(jié)構(gòu)感知”的關(guān)鍵環(huán)節(jié)。我在實際操作中體會最深的一點是工具本身能不能自動化畫圖其實不是最關(guān)鍵的關(guān)鍵是它讓 AI 代理與真實代碼庫之間建立了一條可靠的、結(jié)構(gòu)化的信息通道。以后凡是需要“理解項目全貌”的 AI 任務(wù)都可以在這條通道上做文章。先掃描再推理后輸出這套工作流用在文檔生成、代碼走查、運維排障上價值都會比單獨畫一張架構(gòu)圖大得多。 AI 代理自動生成交互式架構(gòu)圖：原理、接入與實踐
平時畫架構(gòu)圖最煩什么不是不知道怎么寫代碼而是畫圖這件事本身就是個“高成本低產(chǎn)出”的活兒。需求一變服務(wù)一拆圖就廢了圖一廢后面接手的人又得重新讀代碼猜結(jié)構(gòu)。GitHub 上最近被開發(fā)者反復(fù)轉(zhuǎn)發(fā)的一個項目archify走的就是另一個路子它不讓你動手畫而是直接把“生成可交互架構(gòu)圖”做成一個 AI 代理能夠調(diào)用的技能模塊——你只需要告訴你的 AI 助手“幫我看一下這個項目的架構(gòu)”剩下的掃描代碼、識別依賴、渲染交互式圖譜全自動完成。我第一時間拉下來試了試前后折騰了兩天期間踩了不少文檔里沒寫的坑。這篇就把它的工作原理、接入方式、實操過程和問題排查從頭到尾捋清楚如果你也在搞 AI 代理、代碼分析或者架構(gòu)可視化這篇應(yīng)該能讓你少走很多彎路。1. 項目概述archify 到底解決了一個什么問題1.1 傳統(tǒng)架構(gòu)圖維護的痛點先說一個所有維護過老項目的人都經(jīng)歷過的場景你接手一套代碼幾百個文件幾十個微服務(wù)注釋約等于沒有。領(lǐng)導(dǎo)說“你出個架構(gòu)圖”你打開 Visio 或者 Draw.io對著代碼文件一個一個找依賴關(guān)系。畫完了交付兩周后服務(wù)拆分圖又過期了。這種文檔漂移問題在軟件工程里一直是老大難——圖一旦跟代碼脫節(jié)就徹底失去參考價值。archify 的想法很簡單架構(gòu)圖不該由人手動去維護因為代碼本身就是最權(quán)威的架構(gòu)事實來源。與其人去讀代碼然后畫圖不如讓程序去掃描代碼、解析依賴、聚類模塊邊界然后自動生成一張圖。而且它還不止生成靜態(tài)圖而是輸出一張可交互的網(wǎng)頁版架構(gòu)圖——你可以點開某個服務(wù)節(jié)點看它依賴了誰折疊不想看的分支甚至直接定位到對應(yīng)的源碼文件。1.2 為什么做成“AI 代理的技能模塊”這是 archify 和普通的代碼可視化工具最不一樣的地方。它不是給你一個按鈕讓你上傳代碼而是暴露了一個可以被大語言模型直接調(diào)用的工具接口。所謂技能模塊就是給 AI 代理增加一種“能做特定動作”的能力——agent 在對話過程中如果發(fā)現(xiàn)需要理解代碼結(jié)構(gòu)它可以自動調(diào)用 archify把掃描請求發(fā)出去然后拿結(jié)果繼續(xù)推理。這個設(shè)計思路非常務(wù)實?，F(xiàn)階段的 AI 助手雖然能讀懂代碼片段但面對整個倉庫時受限于上下文窗口它對全局依賴關(guān)系的感知是零散的。如果給代理配一個專門的架構(gòu)掃描工具它就能在分析大型項目時先獲取一張全局結(jié)構(gòu)圖再帶著這張圖去做代碼解釋、重構(gòu)建議、影響面分析。等于給了大模型一副“全景眼鏡”不再局限于看哪算哪。1.3 archify 的定位與適用人群如果你正在做下面這幾類事情archify 大概率對你有用給老項目補架構(gòu)文檔需要快速生成一張可以交付的架構(gòu)圖搭建個人 AI 編程助手希望它能理解你本地項目的結(jié)構(gòu)做微服務(wù)治理或者系統(tǒng)設(shè)計評審需要一張能交互、能下鉆的依賴關(guān)系圖或者單純就是覺得手動畫圖太浪費時間。項目本身以 Python 為主依賴管理用的是標準 pyproject 方式本地環(huán)境下通過 pip 就能安裝。生成的交互式 HTML 頁面完全離線運行不依賴任何第三方 CDN 或在線服務(wù)這一點對很多公司內(nèi)網(wǎng)環(huán)境來說非常友好。2. 核心設(shè)計思路AI 代理如何完成自動掃描與圖譜生成2.1 從代碼目錄到架構(gòu)節(jié)點的解析流程我把 archify 的執(zhí)行鏈路拆成四步來看代碼掃描、依賴分析、模塊聚類、渲染輸出。代碼掃描層負責遍歷目標倉庫的文件識別支持的語言類型目前對 Python、TypeScript/JavaScript、Java 的支持最完整同時跳過構(gòu)建產(chǎn)物、虛擬環(huán)境、node_modules 這類無關(guān)目錄。這個階段的關(guān)鍵是速度——archify 使用了多進程并行遍歷實測一個兩萬文件的中型倉庫全量掃描大概在十秒級別。依賴分析層讀取不同語言的模塊引用關(guān)系Python 包里的 import 語句、TypeScript 項目里的 import/export、Java 里的包引用等。archify 沒有走運行時字節(jié)碼分析的老路而是做靜態(tài)引用采集好處是快且不依賴項目能編譯通過代價是動態(tài)導(dǎo)入、反射調(diào)用這類場景會漏掉一部分隱性依賴遇到這種情況人工補一下關(guān)系即可。模塊聚類層做的事情非常像一次簡化版的逆向外推根據(jù)代碼目錄結(jié)構(gòu)和包名把解析出來的模塊關(guān)系聚合成服務(wù)或組件級別的節(jié)點。比如services/order目錄下的所有模塊會被歸到 “訂單服務(wù)” 這個節(jié)點再把這個節(jié)點跟它實際調(diào)用的數(shù)據(jù)庫、消息隊列、下游服務(wù)建立邊關(guān)系。渲染輸出層的產(chǎn)物有兩種一種是標準 Mermaid 格式方便直接在 Markdown 文檔里預(yù)覽另一種就是核心賣點的交互式 HTML——節(jié)點可以拖拽、點擊聚焦、按層級折疊展開還支持搜索定位。2.2 為什么大模型直接生成 Mermaid 不可行有人可能會問現(xiàn)在大模型本身就會寫 Mermaid讓 GPT 直接畫一套微服務(wù)架構(gòu)圖不就行了這事兒我試過效果真的不穩(wěn)定。大模型對代碼庫的全局結(jié)構(gòu)沒有真實感知它只能根據(jù)你提供的片段和它的先驗知識去“猜”架構(gòu)一旦項目里存在非典型目錄結(jié)構(gòu)、自定義框架封裝、或者復(fù)雜的跨服務(wù)調(diào)用它畫出來的圖往往跟真實代碼對不上。而 archify 走的是“先掃描事實再讓模型參與組織與表達”的路線。它提供的圖數(shù)據(jù)是真實依賴關(guān)系的采樣結(jié)果AI 代理拿到這些結(jié)構(gòu)化數(shù)據(jù)后可以沿著真實的結(jié)果去做解讀、提煉、繪圖參數(shù)調(diào)整。比起讓模型自己編這相當于先給了它一份“標準答案”錯誤率天然低了很多。2.3 技能模塊與大模型工具調(diào)用的關(guān)系從 AI 代理的角度看archify 就是一個標準的工具注冊單元。現(xiàn)在主流代理框架都支持工具注冊像 Claude 的 tool use、OpenClaw 的 action 模塊、以及各類支持 MCPModel Context Protocol的客戶端。archify 提供了兩種接入方式一種是作為命令行工具被代理通過 shell 方式調(diào)用另一種是通過 MCP 接口注冊為標準工具。MCP 方式我個人比較推薦。它把工具描述、輸入?yún)?shù) Schema 和調(diào)用執(zhí)行封裝成統(tǒng)一協(xié)議代理在需要獲取項目結(jié)構(gòu)信息時自行決定是否調(diào)用不需要你在 prompt 里寫一堆調(diào)用規(guī)則。接入后你可以在對話里直接說“分析一下當前倉庫的模塊依賴畫一張交互架構(gòu)圖”代理會自己完成從目錄定位、掃描調(diào)用、結(jié)果接收、再到把 HTML 文件路徑返回到對話里的完整閉環(huán)。2.4 生成的數(shù)據(jù)結(jié)構(gòu)與圖譜表達archify 內(nèi)部用的是節(jié)點-邊node-edge數(shù)據(jù)結(jié)構(gòu)來組織架構(gòu)關(guān)系節(jié)點記錄了名稱、類型service/database/mq/module、描述、源碼路徑邊上記錄了關(guān)系類型depends_on/calls/contains和描述。這個結(jié)構(gòu)和 Neo4j 這類圖數(shù)據(jù)庫的模型很像所以如果后續(xù)要做更復(fù)雜的架構(gòu)分析直接把導(dǎo)出的 JSON 灌進圖數(shù)據(jù)庫做查詢也是可行的。交互式 HTML 側(cè)用的是類似力導(dǎo)向圖的渲染方案重依賴但不是 D3.js整體包體做了精簡單個頁面在 400KB 左右。每個節(jié)點都綁定了源碼跳轉(zhuǎn)鏈接點擊后會在新標簽頁打開對應(yīng)文件這一點對代碼走讀寫報告特別順手。3. 實操篇把 archify 接入到本地 AI 代理工作流3.1 環(huán)境準備與安裝先說環(huán)境要求。archify 基于 Python 3.11 開發(fā)建議在干凈的虛擬環(huán)境里安裝避免污染全局 Python 環(huán)境python3.11 -m venv .venv source .venv/bin/activate pip install archify如果是 macOS 用戶建議用 Homebrew 里的 Python 3.12 版本系統(tǒng)自帶 Python 比較容易踩權(quán)限坑。安裝完之后跑一下版本驗證archify --version看到版本號輸出就算成功。如果你打算走 MCP 方式接入還需要確保你用的代理客戶端支持 MCP 協(xié)議我用的是 OpenClaw配置文件里聲明一下即可。3.2 快速掃描生成第一張交互圖進入一個你想分析的項目目錄直接執(zhí)行archify scan --input /path/to/your/project --format html --output ./arch.html第一次跑的時候它會全量掃描過程中終端會打印已識別的模塊數(shù)量和依賴關(guān)系條數(shù)。跑完之后打開arch.html你會看到一張帶力導(dǎo)向效果的交互圖節(jié)點顏色區(qū)分了服務(wù)、數(shù)據(jù)庫、外部 API 等類型圖上方有一個搜索框用來定位節(jié)點。如果只想生成 Markdown 友好的 Mermaid 格式archify scan --input /path/to/your/project --format mermaid --output ./arch.md生成的 Mermaid 代碼可以直接粘貼到支持 Mermaid 的文檔平臺展示。我的習慣是先跑 HTML 格式用于交互分析確認整體結(jié)構(gòu)沒問題后再補一份 Mermaid 放進設(shè)計文檔。3.3 通過 MCP 將 archify 注冊為代理技能MCP 方式接入的配置非常簡單以 OpenClaw 示例在其配置文件中添加{ mcpServers: { archify: { command: archify, args: [mcp] } } }重啟代理后用類似“請生成當前項目的交互式架構(gòu)圖”的指令測試。代理會自動感知到已注冊的工具并在對話中調(diào)用。實測下來從發(fā)出指令到收到 HTML 文件路徑整個過程通常在 20 秒內(nèi)取決于倉庫規(guī)模與磁盤讀寫速度。3.4 面向大型倉庫的配置建議大型倉庫直接全量掃描生成的圖會變成一團亂麻沒法看。archify 提供了裁剪參數(shù)來處理這種情況在實際項目里我用了這樣的配置archify scan --input ./ --format html --output ./arch.html \ --ignore build,dist,.git,.venv,tests \ --focus services,api,core \ --depth 2--ignore指定跳過目錄--focus指定重點分析目錄--depth控制解析遞歸深度。它解決了一個畫圖經(jīng)典問題只展示你關(guān)心層級的架構(gòu)而不是把每個函數(shù)都鋪在圖上。配合模塊聚類參數(shù)還能進一步合并同類節(jié)點讓架構(gòu)圖的抽象層級更合理。比例控制上我拿一個電商后端項目測過完整掃描有 800 多個節(jié)點加上--depth 2和--focus之后壓縮到 40 個核心節(jié)點這已經(jīng)非常接近一張人工繪制的架構(gòu)概要圖了。4. 案例實操從零生成微服務(wù)架構(gòu)交互圖4.1 目標項目結(jié)構(gòu)介紹我用一個模擬的電商后端項目做完整演示項目目錄是這樣布局的ecommerce/ ├── api-gateway/ # 網(wǎng)關(guān)服務(wù) ├── services/ │ ├── user/ # 用戶服務(wù) │ ├── order/ # 訂單服務(wù) │ ├── payment/ # 支付服務(wù) │ └── inventory/ # 庫存服務(wù) ├── shared/ │ ├── mq/ # 消息隊列客戶端封裝 │ └── db/ # 數(shù)據(jù)庫訪問層 ├── docs/ └── scripts/這個結(jié)構(gòu)比較典型有網(wǎng)關(guān)層、業(yè)務(wù)服務(wù)層、基礎(chǔ)設(shè)施層正好能展示 archify 在分層聚類上的表現(xiàn)。4.2 掃描過程的完整記錄執(zhí)行archify scan --input ./ecommerce --format html --output ./ecommerce-arch.html掃描期間終端輸出的信息反映了它的解析進度[archify] scanning 186 source files... [archify] detected git repo, using ref HEAD [archify] module clusters found: gateway(1), service(4), db(2), mq(2) [archify] edges resolved: 23 [archify] rendering interactive canvas...注意第二行detected git repo——archify 會讀取 Git 歷史來輔助判斷模塊歸屬如果不在 Git 倉庫里運行有的高級聚類功能會降級。邊緣關(guān)系只解析出了 23 條主要因為模擬項目服務(wù)間調(diào)用本來就不算密集真實的微服務(wù)系統(tǒng)會多得多。4.3 生成的交互架構(gòu)圖解讀打開輸出的 HTML 后默認視圖按模塊邊界展開。畫面上五個主要節(jié)點——網(wǎng)關(guān)、用戶服務(wù)、訂單服務(wù)、支付服務(wù)、庫存服務(wù)是最大的一級節(jié)點分布在畫布中央連線表示它們之間的調(diào)用關(guān)系。操作細節(jié)做得很到位。鼠標懸停一條邊會顯示這條依賴對應(yīng)的實際代碼位置點擊后跳轉(zhuǎn)到源碼。雙擊某個服務(wù)節(jié)點整個畫布會以它為焦點展開剩下的節(jié)點全部收縮成側(cè)邊欄列表。這種交互邏輯對排查“這個服務(wù)到底被誰調(diào)用了”這類問題特別有效比傳統(tǒng)靜態(tài)架構(gòu)圖效率高太多了。訂單服務(wù)的下鉆視圖值得單獨說一下。它能看到內(nèi)部的控制器層、領(lǐng)域服務(wù)層、倉儲層各自依賴的組件以及它對消息隊列和生產(chǎn)者的引用情況。這就是交互式架構(gòu)圖對比靜態(tài)圖的優(yōu)勢——宏觀和微觀切換變得完全無感。4.4 增量更新與 CI 流程結(jié)合的思路架構(gòu)圖要長期保鮮就必須在每次代碼變更后更新。archify 提供了--ref參數(shù)支持基于 Git 引用的增量分析可以結(jié)合 CI 流水線實現(xiàn)自動更新archify scan --input ./ecommerce --format html \ --output ./docs/architecture/index.html \ --ref origin/main每次主分支有合并流水線跑一次任務(wù)自動刷新架構(gòu)圖產(chǎn)物。然后通過團隊的文檔平臺把更新后的 HTML 發(fā)布出去。這樣做到“有代碼變更有圖變更”架構(gòu)文檔跟著代碼走的體驗比強調(diào)“我們定期維護文檔”靠譜多了。5. 踩坑記錄實測中的問題與排查思路5.1 掃描速度過慢我第一次在真實項目里跑 archify直接對倉庫根目錄全量掃描結(jié)果卡了近三分鐘才出結(jié)果。排查發(fā)現(xiàn)虛擬環(huán)境.venv、前端依賴目錄node_modules、打包產(chǎn)物目錄都被當成了源碼內(nèi)容解析了。后來添加了全局忽略配置# ~/.config/archify/ignore.toml [ignore] dirs [.venv, node_modules, build, dist, target, __pycache__]再跑速度從三分鐘降到十幾秒。如果你的倉庫里混入了大體積的 SQL 腳本或者數(shù)據(jù)文件也建議在忽略列表里加一下避免無意義的磁盤讀取。5.2 交互式 HTML 在瀏覽器里白屏白屏問題多數(shù)不是 archify 生成的 HTML 有 bug而是瀏覽器版本過舊不支持 ES6 語法和 Canvas 相關(guān) API。公司內(nèi)網(wǎng)環(huán)境里員工用的瀏覽器版本往往滯后得厲害遇到白屏先別懷疑項目切換一個 Chrome 內(nèi)核瀏覽器試試。另外有些電腦配置了嚴格的 Content-Security-Policy 或防火墻策略攔截了頁面內(nèi)嵌腳本執(zhí)行。建議直接檢查瀏覽器 Console 的報錯信息是腳本執(zhí)行被攔截還是資源加載被攔截對癥處理。5.3 MCP 注冊后代理無法發(fā)現(xiàn)工具如果你通過 MCP 注冊了 archify但代理始終不調(diào)用它大概率是兩個原因。一個是 MCP 服務(wù)啟動失敗命令行方式能跑但 MCP 模式下起不來另一個是工具描述信息太模糊代理不知道這個工具在什么場景下該用。排查第一項直接在終端跑archify mcp看是否正常監(jiān)聽。排查第二項我建議把工具描述寫得足夠明確例如{ name: generate_project_architecture, description: 掃描代碼倉庫并生成可交互架構(gòu)圖。當用戶詢問項目架構(gòu)、模塊依賴、服務(wù)關(guān)系時調(diào)用此工具。, parameters: {} }工具描述越明確代理的調(diào)用觸發(fā)越可靠。5.4 大型項目生成的 HTML 文件過大在小微服務(wù)上 archify 表現(xiàn)很好但一旦掃描整個中大型單體倉庫生成的 HTML 可能達到 2-3MB打開顯慢。解決方案是在生成時增加裁剪參數(shù)控制參與渲染的節(jié)點數(shù)量。我在實際使用中形成的規(guī)則是單次渲染超過 150 個節(jié)點就開始影響瀏覽體驗。配置--max-nodes 120并調(diào)整--depth 1到合適的層級可以讓 HTML 文件體積控制在 500KB 以下交互流暢度也會明顯改善。5.5 與 AI 代理組合時的隱性成本archify 作為技能模塊接入 AI 代理后還需要留意上下文開銷。代理調(diào)用工具之后拿到的是一份包含節(jié)點、邊、描述的 JSON這個數(shù)據(jù)對象本身不大但如果在一次對話里反復(fù)讓代理生成多張不同項目的架構(gòu)圖上下文里疊加的 JSON 會越來越多導(dǎo)致后續(xù)對話變慢。解決辦法是每次分析完只保留關(guān)鍵結(jié)論把完整的 JSON 數(shù)據(jù)寫入本地緩存文件而不是留在對話里。我通常讓代理只回傳“發(fā)現(xiàn) 4 個服務(wù)節(jié)點和 23 條依賴關(guān)系”這類摘要需要細節(jié)時再讀文件整體效率高出很多。6. 我對 archify 的看法與后續(xù)擴展方向6.1 項目現(xiàn)狀的客觀評估從我這兩天的實際體驗來看archify 目前的成熟度介于“能用的工具”和“好用的產(chǎn)品”之間。它最核心的掃描-聚類-渲染鏈路已經(jīng)跑通了交互式 HTML 的體驗在同類開源工具里算得上第一梯隊。但分支支持、異常處理、新語言適配這些環(huán)節(jié)還有不少缺口代碼里能看到一些實驗性質(zhì)的模塊劃分項目的日常維護活躍度也在變化中。對于一個面向 AI 代理的工具來說當前階段最大的價值在于把“理解架構(gòu)”這個能力從人轉(zhuǎn)移到了機器。即使你只把它當 CLI 工具用不接任何代理它也能大幅壓縮畫圖的時間。6.2 延展方向可交互架構(gòu)圖之上的更多可能性交互式架構(gòu)圖只是第一步基于圖數(shù)據(jù)的擴展玩法其實很多。比如結(jié)合代碼指標在節(jié)點上展示復(fù)雜度、提交頻率、缺陷率就變成了一張“架構(gòu)體檢圖”把架構(gòu)數(shù)據(jù)與運行時指標關(guān)聯(lián)起來就能做依賴健康度透視分析哪些節(jié)點是故障擴散的源頭。跟 AI 代理結(jié)合最值得期待的方向是“架構(gòu)評審助手”。讓代理定期調(diào)用 archify 生成基線與本次變更兩張架構(gòu)圖自動對比新舊結(jié)構(gòu)差異然后從依賴增加、循環(huán)引用、模塊膨脹等維度輸出評審意見。這一步如果能走通就等于把代碼架構(gòu)守護變成了自動化流水線的一部分而 archify 正好補上了“讓代理獲得真實結(jié)構(gòu)感知”的關(guān)鍵環(huán)節(jié)。我在實際操作中體會最深的一點是工具本身能不能自動化畫圖其實不是最關(guān)鍵的關(guān)鍵是它讓 AI 代理與真實代碼庫之間建立了一條可靠的、結(jié)構(gòu)化的信息通道。以后凡是需要“理解項目全貌”的 AI 任務(wù)都可以在這條通道上做文章。先掃描再推理后輸出這套工作流用在文檔生成、代碼走查、運維排障上價值都會比單獨畫一張架構(gòu)圖大得多。