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