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