1. 為什么設(shè)計(jì)稿與代碼之間總有一道人工翻譯的墻做前端或者全棧的朋友大概都有過(guò)這種體驗(yàn)產(chǎn)品經(jīng)理甩過(guò)來(lái)一個(gè)設(shè)計(jì)稿鏈接說(shuō)“就按這個(gè)做”然后你打開(kāi)一看圖層命名全是 Frame 427、Rectangle 18、Group 233光是理清哪個(gè)圖層對(duì)應(yīng)哪個(gè)組件就要花掉小半天。更別提改稿階段設(shè)計(jì)側(cè)微調(diào)了一個(gè)間距、換了一個(gè)圓角你這邊得手動(dòng)去代碼里翻對(duì)應(yīng)的樣式改完還要截圖比對(duì)來(lái)回確認(rèn)。這個(gè)過(guò)程中最耗時(shí)的不是寫代碼本身而是“人肉解析設(shè)計(jì)稿”這個(gè)環(huán)節(jié)。Figma 作為目前主流的界面設(shè)計(jì)工具本身提供了插件體系和 REST API理論上可以讓機(jī)器直接讀取設(shè)計(jì)稿的結(jié)構(gòu)化數(shù)據(jù)。但現(xiàn)實(shí)情況是很多團(tuán)隊(duì)用的免費(fèi)版賬號(hào)在 API 調(diào)用上有額度限制或者干脆沒(méi)有開(kāi)放某些接口權(quán)限。于是就有了一個(gè)很實(shí)際的需求能不能在不購(gòu)買付費(fèi)套餐的前提下讓本地的 AI Agent 直接讀懂 Figma 設(shè)計(jì)稿甚至反過(guò)來(lái)修改它Local Figma Agent MCP 就是沖著這個(gè)場(chǎng)景來(lái)的。它本質(zhì)上是一個(gè)運(yùn)行在本地的 MCP 服務(wù)通過(guò) Figma 桌面端提供的插件運(yùn)行環(huán)境把設(shè)計(jì)稿的節(jié)點(diǎn)樹(shù)、樣式屬性、組件信息暴露給本地的 Agent 進(jìn)程。Agent 拿到這些結(jié)構(gòu)化數(shù)據(jù)之后就可以做代碼生成、樣式比對(duì)、批量重命名、甚至反向修改設(shè)計(jì)稿的操作。整個(gè)過(guò)程不依賴 Figma 的云端付費(fèi) API走的是本地插件通道所以免費(fèi)賬號(hào)也能跑通。這篇文章適合三類人看一是前端開(kāi)發(fā)者想減少設(shè)計(jì)稿到代碼的手動(dòng)翻譯成本二是設(shè)計(jì)系統(tǒng)維護(hù)者需要批量處理圖層命名和組件規(guī)范三是對(duì) MCP 協(xié)議和 Agent 工具鏈感興趣的工程師想了解本地 Agent 如何與設(shè)計(jì)工具打通。我會(huì)從原理、環(huán)境搭建、核心操作、踩坑經(jīng)驗(yàn)幾個(gè)維度展開(kāi)盡量把每個(gè)環(huán)節(jié)的“為什么”講清楚讓你看完能直接上手復(fù)現(xiàn)。2. Local Figma Agent MCP 到底在做什么拆解本地插件通道的工作機(jī)制2.1 MCP 協(xié)議在這里扮演什么角色MCP 全稱 Model Context Protocol你可以把它理解成一套“Agent 和外部工具之間的通用插頭標(biāo)準(zhǔn)”。在沒(méi)有這套標(biāo)準(zhǔn)之前Agent 想調(diào)用一個(gè)外部能力得針對(duì)每個(gè)工具單獨(dú)寫適配代碼今天接 Figma 寫一套明天接數(shù)據(jù)庫(kù)又寫一套維護(hù)成本很高。MCP 的思路是定義統(tǒng)一的通信格式Agent 側(cè)作為客戶端工具側(cè)作為服務(wù)端雙方通過(guò)標(biāo)準(zhǔn)化的請(qǐng)求和響應(yīng)來(lái)交互。Local Figma Agent MCP 就是把這個(gè)服務(wù)端跑在本地。它啟動(dòng)之后會(huì)監(jiān)聽(tīng)一個(gè)本地端口Agent 通過(guò)這個(gè)端口發(fā)送指令比如“獲取當(dāng)前選中節(jié)點(diǎn)的屬性”“列出所有文本圖層的字體信息”“把某個(gè)節(jié)點(diǎn)的填充色改成指定值”。服務(wù)端收到指令后轉(zhuǎn)譯成 Figma 插件 API 能理解的調(diào)用執(zhí)行完再把結(jié)果回傳給 Agent。整個(gè)鏈路都在本機(jī)完成不經(jīng)過(guò)外部服務(wù)器所以響應(yīng)速度快也不受賬號(hào)套餐的 API 額度限制。這里有個(gè)關(guān)鍵點(diǎn)需要理解Figma 插件 API 和 Figma REST API 是兩套不同的東西。REST API 是走網(wǎng)絡(luò)的受套餐和權(quán)限約束插件 API 是運(yùn)行在 Figma 桌面端或?yàn)g覽器端插件沙箱里的只要插件被加載就能訪問(wèn)當(dāng)前文檔的節(jié)點(diǎn)樹(shù)。Local Figma Agent MCP 走的是后者所以才能繞開(kāi)付費(fèi)限制。當(dāng)然這也意味著它只能操作“當(dāng)前打開(kāi)的那個(gè)文檔”沒(méi)法在后臺(tái)批量處理一堆文件這是它的能力邊界。2.2 本地插件通道的數(shù)據(jù)流轉(zhuǎn)過(guò)程把整個(gè)數(shù)據(jù)流轉(zhuǎn)拆開(kāi)看大概是這么幾步。第一步你在 Figma 桌面端加載 Local Figma Agent MCP 對(duì)應(yīng)的插件插件啟動(dòng)后會(huì)建立一個(gè)本地通信通道通常是一個(gè) WebSocket 或者本地 HTTP 服務(wù)。第二步你在本地啟動(dòng) Agent 進(jìn)程它作為 MCP 客戶端去連接這個(gè)通道。第三步Agent 發(fā)送指令插件在 Figma 沙箱內(nèi)執(zhí)行對(duì)應(yīng)的 API 調(diào)用拿到節(jié)點(diǎn)數(shù)據(jù)。第四步數(shù)據(jù)經(jīng)過(guò)序列化后回傳給 AgentAgent 再?zèng)Q定下一步做什么。這個(gè)過(guò)程中最容易被忽略的是“節(jié)點(diǎn)樹(shù)的序列化”。Figma 的節(jié)點(diǎn)樹(shù)可能非常深一個(gè)頁(yè)面里嵌套幾十層 Group 是常事。如果一次性把整棵樹(shù)拉過(guò)來(lái)數(shù)據(jù)量會(huì)很大Agent 處理起來(lái)也慢。所以實(shí)際使用中通常的做法是先拉頂層節(jié)點(diǎn)按需展開(kāi)。比如先獲取當(dāng)前選中的節(jié)點(diǎn)或者按名稱過(guò)濾出特定類型的節(jié)點(diǎn)再逐層深入。這個(gè)策略和爬蟲(chóng)的“按需抓取”是一個(gè)道理避免一次性加載過(guò)多無(wú)用數(shù)據(jù)。另一個(gè)細(xì)節(jié)是樣式屬性的讀取。Figma 里一個(gè)矩形的填充可能來(lái)自樣式庫(kù)、可能來(lái)自本地樣式、也可能是直接設(shè)置的色值。插件 API 能區(qū)分這些來(lái)源但 Agent 拿到數(shù)據(jù)后需要自己判斷優(yōu)先級(jí)。比如做代碼生成時(shí)如果填充來(lái)自共享樣式那生成的代碼應(yīng)該引用對(duì)應(yīng)的設(shè)計(jì)令牌而不是硬編碼色值。這個(gè)判斷邏輯需要在 Agent 側(cè)實(shí)現(xiàn)MCP 服務(wù)本身只負(fù)責(zé)把原始數(shù)據(jù)吐出來(lái)。2.3 不買付費(fèi)套餐能用到什么程度免費(fèi)賬號(hào)在 Figma 里的限制主要是協(xié)作人數(shù)、版本歷史和部分云端 API 額度。Local Figma Agent MCP 走本地插件通道所以協(xié)作和版本歷史這些限制不影響它。它能做的事情包括讀取當(dāng)前文檔的完整節(jié)點(diǎn)樹(shù)、讀取和修改節(jié)點(diǎn)屬性、創(chuàng)建和刪除節(jié)點(diǎn)、批量重命名、導(dǎo)出節(jié)點(diǎn)為圖片或 SVG?；旧喜寮?API 能做的它都能通過(guò) Agent 來(lái)觸發(fā)。做不到的事情也要說(shuō)清楚它沒(méi)法訪問(wèn)你沒(méi)有打開(kāi)的文件沒(méi)法跨文件批量操作沒(méi)法讀取團(tuán)隊(duì)庫(kù)的完整元數(shù)據(jù)部分庫(kù)信息在插件 API 里是受限的。所以如果你的需求是“每天晚上自動(dòng)掃描團(tuán)隊(duì)所有設(shè)計(jì)稿并生成報(bào)告”那這個(gè)方案不合適還是得走云端 API。但如果你的需求是“在當(dāng)前打開(kāi)的設(shè)計(jì)稿里讓 Agent 幫我批量改圖層名、提取樣式、生成組件代碼”那它完全夠用。3. 從零搭起本地 Agent 與 Figma 的通信鏈路3.1 環(huán)境準(zhǔn)備別急著裝插件先把這幾樣確認(rèn)好動(dòng)手之前先把基礎(chǔ)環(huán)境理清楚。你需要的東西不多但每一樣都有坑。首先是 Figma 桌面端注意是桌面端不是瀏覽器端。雖然瀏覽器端也能跑插件但本地通信通道在桌面端更穩(wěn)定而且桌面端對(duì)本地文件系統(tǒng)的訪問(wèn)權(quán)限更寬松后續(xù)如果要導(dǎo)出文件會(huì)方便很多。版本方面建議保持最新老版本插件 API 可能有差異。然后是 Node.js 環(huán)境。Local Figma Agent MCP 的服務(wù)端和插件構(gòu)建腳本通常依賴 Node 工具鏈建議用 LTS 版本別用太新的實(shí)驗(yàn)版避免依賴包兼容問(wèn)題。裝完之后確認(rèn) npm 或 pnpm 能正常工作。如果你習(xí)慣用 yarn 也行但要注意鎖文件的一致性別混用。第三樣是 Agent 運(yùn)行環(huán)境。這個(gè)取決于你用哪個(gè) Agent 框架有的用 Python有的用 Node。關(guān)鍵是確認(rèn)你的 Agent 支持 MCP 客戶端功能。如果不支持就得自己寫一層適配把 MCP 的請(qǐng)求格式轉(zhuǎn)成 Agent 能理解的工具調(diào)用格式。這一步是很多人在搭建時(shí)卡住的地方因?yàn)槲臋n里往往默認(rèn)你已經(jīng)有一個(gè)支持 MCP 的 Agent 了。最后確認(rèn)一下端口占用情況。本地 MCP 服務(wù)通常會(huì)監(jiān)聽(tīng)一個(gè)固定端口比如 3000 或者 8080 附近的某個(gè)值。如果這個(gè)端口被其他服務(wù)占了啟動(dòng)時(shí)會(huì)報(bào)錯(cuò)。建議提前用命令行查一下端口占用或者直接在配置里改成一個(gè)不常用的端口省得后面排查。3.2 插件側(cè)的加載與調(diào)試為什么你的插件面板是空的插件加載這一步最常見(jiàn)的現(xiàn)象是“面板打開(kāi)了但一片空白”或者“提示連接失敗”。先說(shuō)空白的情況。這通常是因?yàn)椴寮?UI 線程和主線程通信出了問(wèn)題。Figma 插件分兩部分一部分是運(yùn)行在沙箱里的主邏輯能訪問(wèn) Figma API另一部分是 UI 面板運(yùn)行在 iframe 里負(fù)責(zé)展示界面。兩者通過(guò) postMessage 通信。如果 UI 面板加載了但沒(méi)收到主邏輯的數(shù)據(jù)就會(huì)空白。排查方法是打開(kāi) Figma 的插件開(kāi)發(fā)控制臺(tái)看有沒(méi)有報(bào)錯(cuò)。常見(jiàn)錯(cuò)誤包括UI 的 HTML 文件路徑寫錯(cuò)了、構(gòu)建產(chǎn)物沒(méi)有正確輸出、或者跨域限制導(dǎo)致 iframe 里的腳本加載失敗。如果是用構(gòu)建工具打包的確認(rèn)一下輸出目錄和插件 manifest 里配置的路徑是否一致。這個(gè)坑我踩過(guò)好幾次每次都是路徑問(wèn)題。連接失敗的情況多半是本地 MCP 服務(wù)沒(méi)啟動(dòng)或者端口對(duì)不上。插件側(cè)一般會(huì)有一個(gè)配置項(xiàng)讓你填本地服務(wù)的地址和端口確認(rèn)這個(gè)配置和服務(wù)端實(shí)際監(jiān)聽(tīng)的一致。另外注意有些系統(tǒng)對(duì)本地回環(huán)地址的訪問(wèn)有額外限制如果填的是 localhost 不通可以試試換成 127.0.0.1反過(guò)來(lái)也一樣。這個(gè)細(xì)節(jié)很小但確實(shí)會(huì)卡住人。3.3 Agent 側(cè)的配置把 MCP 服務(wù)注冊(cè)成可用工具Agent 側(cè)要做的核心事情是把 Local Figma Agent MCP 注冊(cè)成一個(gè)可調(diào)用的工具。不同 Agent 框架的注冊(cè)方式不一樣但思路是相通的你需要告訴 Agent“有一個(gè)叫 figma-local 的工具它的能力描述是什么怎么連接它”。能力描述很重要它決定了 Agent 在什么情況下會(huì)主動(dòng)調(diào)用這個(gè)工具。描述寫得太模糊Agent 可能該調(diào)用的時(shí)候不調(diào)用寫得太寬泛又可能在不相關(guān)的場(chǎng)景下亂調(diào)用。一個(gè)實(shí)用的做法是在工具描述里明確列出幾個(gè)典型操作比如“讀取當(dāng)前選中節(jié)點(diǎn)的屬性”“按名稱查找節(jié)點(diǎn)”“修改節(jié)點(diǎn)填充色”“批量重命名圖層”。這樣 Agent 在遇到類似需求時(shí)更容易匹配到這個(gè)工具。同時(shí)在 Agent 的系統(tǒng)提示里也可以加一句引導(dǎo)比如“當(dāng)用戶提到設(shè)計(jì)稿、Figma、圖層、組件時(shí)優(yōu)先考慮使用 figma-local 工具”。這種引導(dǎo)不是必須的但實(shí)測(cè)能明顯提升調(diào)用準(zhǔn)確率。配置完成后先做一個(gè)最簡(jiǎn)單的連通性測(cè)試讓 Agent 調(diào)用工具獲取當(dāng)前選中節(jié)點(diǎn)的名稱。如果返回了正確的名稱說(shuō)明鏈路通了。如果報(bào)錯(cuò)根據(jù)錯(cuò)誤信息逐段排查是 Agent 沒(méi)找到工具還是工具連不上服務(wù)還是服務(wù)連不上插件。分段定位比整體調(diào)試效率高得多。4. 讓 Agent 真正讀懂設(shè)計(jì)稿節(jié)點(diǎn)解析與語(yǔ)義提取的實(shí)操細(xì)節(jié)4.1 節(jié)點(diǎn)樹(shù)的讀取策略一次性拉取還是按需展開(kāi)前面提到過(guò)節(jié)點(diǎn)樹(shù)可能很深一次性拉取不現(xiàn)實(shí)。實(shí)際操作用的是“分層讀取”策略。第一步獲取當(dāng)前頁(yè)面的頂層節(jié)點(diǎn)列表通常數(shù)量不多幾十個(gè)以內(nèi)。第二步根據(jù) Agent 的任務(wù)目標(biāo)決定展開(kāi)哪些子樹(shù)。比如任務(wù)是“找出所有按鈕組件”那就按名稱或類型過(guò)濾只展開(kāi)可能是按鈕的節(jié)點(diǎn)。第三步對(duì)目標(biāo)節(jié)點(diǎn)讀取詳細(xì)屬性包括尺寸、位置、填充、描邊、圓角、字體等。這個(gè)策略的好處是數(shù)據(jù)量可控Agent 的處理速度快。壞處是需要多輪交互如果 Agent 的規(guī)劃能力不強(qiáng)可能會(huì)漏掉一些節(jié)點(diǎn)。為了減少遺漏可以在工具側(cè)提供一個(gè)“遞歸查找”的接口讓 Agent 指定一個(gè)過(guò)濾條件服務(wù)端在 Figma 沙箱內(nèi)遞歸遍歷只返回匹配的節(jié)點(diǎn)。這樣把遍歷邏輯放在服務(wù)端Agent 只需要發(fā)一次請(qǐng)求效率更高。過(guò)濾條件的寫法很關(guān)鍵。Figma 節(jié)點(diǎn)有 type 屬性比如 FRAME、TEXT、RECTANGLE、COMPONENT、INSTANCE 等。按 type 過(guò)濾是最常用的。另外還可以按 name 做模糊匹配按是否可見(jiàn)過(guò)濾按是否有特定插件數(shù)據(jù)過(guò)濾。組合使用這些條件能比較精準(zhǔn)地定位到目標(biāo)節(jié)點(diǎn)。我一般會(huì)建議在工具描述里把這些過(guò)濾能力寫清楚方便 Agent 自己組合。4.2 樣式信息的語(yǔ)義化從原始屬性到設(shè)計(jì)令牌拿到節(jié)點(diǎn)的原始屬性只是第一步真正有價(jià)值的是把這些屬性語(yǔ)義化。舉個(gè)例子一個(gè)矩形的填充色是 #1A73E8這是原始數(shù)據(jù)。但如果這個(gè)色值來(lái)自一個(gè)叫“Primary/Blue/500”的共享樣式那語(yǔ)義就是“主色藍(lán) 500”。Agent 在做代碼生成時(shí)應(yīng)該優(yōu)先使用語(yǔ)義化的設(shè)計(jì)令牌而不是硬編碼色值。這樣后續(xù)設(shè)計(jì)令牌變更時(shí)代碼只需要改一處。實(shí)現(xiàn)這個(gè)語(yǔ)義化需要在讀取節(jié)點(diǎn)屬性時(shí)同時(shí)讀取它引用的樣式 ID然后再去樣式表里查這個(gè) ID 對(duì)應(yīng)的名稱。Figma 插件 API 提供了獲取本地樣式和共享樣式的方法。需要注意的是共享樣式的讀取在某些權(quán)限下可能受限如果讀不到就退而求其次用本地樣式或者直接用原始值加一個(gè)標(biāo)記提示 Agent 這里可能需要人工確認(rèn)。字體信息也是類似的處理。一個(gè)文本節(jié)點(diǎn)的字體可能是“Inter Regular 14px”但設(shè)計(jì)系統(tǒng)里可能定義的是“Body/Regular”這樣的令牌。Agent 需要根據(jù)字體名稱、字重、字號(hào)去匹配設(shè)計(jì)令牌表。這個(gè)匹配邏輯可以放在 Agent 側(cè)也可以放在 MCP 服務(wù)側(cè)提供一個(gè)“解析樣式令牌”的工具。放在服務(wù)側(cè)的好處是復(fù)用性強(qiáng)多個(gè) Agent 都能用放在 Agent 側(cè)的好處是靈活可以根據(jù)不同項(xiàng)目的令牌規(guī)范調(diào)整。4.3 組件與實(shí)例的識(shí)別區(qū)分主組件和派生實(shí)例Figma 里組件和實(shí)例的關(guān)系類似于面向?qū)ο罄锏念惡蛯?duì)象。主組件定義結(jié)構(gòu)和默認(rèn)樣式實(shí)例繼承主組件但可以覆蓋部分屬性。Agent 在處理設(shè)計(jì)稿時(shí)必須能區(qū)分這兩者否則生成的代碼會(huì)出問(wèn)題。比如一個(gè)按鈕的主組件改了圓角所有實(shí)例都會(huì)跟著變但如果某個(gè)實(shí)例單獨(dú)覆蓋了圓角那它就不受主組件影響。讀取節(jié)點(diǎn)時(shí)INSTANCE 類型的節(jié)點(diǎn)會(huì)有一個(gè) componentId 指向主組件。Agent 可以通過(guò)這個(gè) ID 去獲取主組件的屬性然后對(duì)比實(shí)例的覆蓋屬性判斷哪些是繼承的、哪些是覆蓋的。這個(gè)信息對(duì)代碼生成很重要繼承的屬性可以抽成公共樣式覆蓋的屬性需要單獨(dú)處理。如果 Agent 不區(qū)分這些生成的代碼就會(huì)把所有屬性都寫死失去組件化的意義。另外組件的命名規(guī)范也影響 Agent 的理解。如果主組件叫“Button/Primary/Large”Agent 很容易推斷出這是一個(gè)大號(hào)主按鈕。如果叫“Frame 427”那就只能靠屬性推斷準(zhǔn)確率會(huì)下降。所以我在實(shí)際項(xiàng)目中會(huì)建議設(shè)計(jì)側(cè)盡量規(guī)范命名這不僅對(duì)人友好對(duì) Agent 也友好。如果命名已經(jīng)亂了可以先讓 Agent 做一輪批量重命名把命名規(guī)范起來(lái)再去做后續(xù)的代碼生成。5. 反向操作讓 Agent 修改設(shè)計(jì)稿的邊界與注意事項(xiàng)5.1 哪些修改是安全的哪些容易出問(wèn)題讓 Agent 修改設(shè)計(jì)稿聽(tīng)起來(lái)很美好但實(shí)際操作中要區(qū)分場(chǎng)景。安全的修改包括批量重命名圖層、統(tǒng)一修改填充色或描邊色、調(diào)整間距和圓角、替換文本內(nèi)容、顯示或隱藏特定圖層。這些操作的影響范圍明確出錯(cuò)了也容易回滾。不安全的修改包括刪除節(jié)點(diǎn)、改變節(jié)點(diǎn)層級(jí)結(jié)構(gòu)、替換主組件、修改自動(dòng)布局的關(guān)鍵參數(shù)。這些操作一旦出錯(cuò)可能破壞整個(gè)設(shè)計(jì)稿的結(jié)構(gòu)恢復(fù)起來(lái)很麻煩。我的建議是在讓 Agent 做任何修改之前先手動(dòng)保存一個(gè)版本或者復(fù)制一份文檔出來(lái)操作。Figma 的版本歷史在免費(fèi)版里有限制別指望靠它回滾。復(fù)制文檔是最穩(wěn)妥的改壞了直接刪掉副本就行。另外修改操作最好分批進(jìn)行改完一批檢查一批別一次性讓 Agent 跑完所有修改出了問(wèn)題都不知道是哪一步導(dǎo)致的。還有一個(gè)細(xì)節(jié)是自動(dòng)布局。Figma 的自動(dòng)布局Auto Layout有一套自己的約束邏輯Agent 修改子節(jié)點(diǎn)尺寸或間距時(shí)可能會(huì)觸發(fā)自動(dòng)布局的重新計(jì)算導(dǎo)致意料之外的位移。如果設(shè)計(jì)稿大量使用自動(dòng)布局建議 Agent 在修改前先讀取布局配置修改后驗(yàn)證布局是否還符合預(yù)期。這個(gè)驗(yàn)證步驟不能省否則改完一看全亂了。5.2 批量重命名的實(shí)戰(zhàn)策略批量重命名是 Agent 修改設(shè)計(jì)稿里最高頻、也最實(shí)用的操作。一個(gè)典型場(chǎng)景是設(shè)計(jì)稿從其他工具導(dǎo)入圖層名全是默認(rèn)的“Rectangle 1”“Group 2”需要按規(guī)范重命名。Agent 可以根據(jù)節(jié)點(diǎn)的類型、尺寸、位置、內(nèi)容來(lái)推斷合理的名稱。比如一個(gè) 375x812 的 Frame 可能是手機(jī)屏幕一個(gè)包含文本且寬度較小的節(jié)點(diǎn)可能是按鈕。具體策略可以分幾步。第一步按類型分組FRAME 歸 FRAMETEXT 歸 TEXTCOMPONENT 歸 COMPONENT。第二步對(duì)每組內(nèi)的節(jié)點(diǎn)根據(jù)尺寸和位置排序推斷層級(jí)關(guān)系。第三步結(jié)合文本內(nèi)容或已有命名生成候選名稱。第四步批量應(yīng)用重命名并輸出一份變更日志方便人工復(fù)核。這個(gè)流程里變更日志很重要因?yàn)?Agent 的推斷不可能百分之百準(zhǔn)確人工復(fù)核是必要的兜底。重命名時(shí)還要注意命名沖突。如果兩個(gè)節(jié)點(diǎn)被推斷成同一個(gè)名稱后續(xù)引用會(huì)出問(wèn)題。解決辦法是在名稱后加序號(hào)或者用更細(xì)粒度的特征來(lái)區(qū)分。比如兩個(gè)都是按鈕一個(gè)寬度 120一個(gè)寬度 200可以命名為“Button/Small”和“Button/Large”。這個(gè)邏輯可以在 Agent 側(cè)實(shí)現(xiàn)也可以做成 MCP 服務(wù)的一個(gè)工具讓 Agent 調(diào)用。5.3 修改后的驗(yàn)證怎么確認(rèn) Agent 沒(méi)把設(shè)計(jì)稿改壞修改完成后的驗(yàn)證環(huán)節(jié)很多人會(huì)忽略但它恰恰是最重要的。驗(yàn)證分兩個(gè)層面結(jié)構(gòu)驗(yàn)證和視覺(jué)驗(yàn)證。結(jié)構(gòu)驗(yàn)證是檢查節(jié)點(diǎn)樹(shù)是否完整有沒(méi)有節(jié)點(diǎn)丟失層級(jí)關(guān)系是否還正確。這個(gè)可以通過(guò)對(duì)比修改前后的節(jié)點(diǎn)數(shù)量和層級(jí)深度來(lái)快速判斷。如果修改前有 500 個(gè)節(jié)點(diǎn)修改后只剩 480 個(gè)那肯定有問(wèn)題得排查哪里丟了。視覺(jué)驗(yàn)證是導(dǎo)出修改后的關(guān)鍵頁(yè)面截圖和修改前的截圖做比對(duì)。如果只是重命名視覺(jué)上應(yīng)該完全一致如果有樣式修改視覺(jué)差異應(yīng)該符合預(yù)期。這個(gè)比對(duì)可以人工做也可以讓 Agent 做。Agent 做的話需要能讀取圖片并做像素級(jí)或結(jié)構(gòu)級(jí)比對(duì)。像素級(jí)比對(duì)對(duì)渲染差異很敏感結(jié)構(gòu)級(jí)比對(duì)更實(shí)用比如比對(duì)兩個(gè)截圖的布局網(wǎng)格是否一致。我自己的習(xí)慣是每次讓 Agent 做批量修改后都會(huì)讓它輸出一份“修改摘要”包括修改了哪些節(jié)點(diǎn)、改了什么、預(yù)期效果是什么。然后我拿著這份摘要去抽查幾個(gè)關(guān)鍵節(jié)點(diǎn)確認(rèn)無(wú)誤后再繼續(xù)下一步。這個(gè)習(xí)慣幫我避免了好幾次潛在的事故尤其是涉及組件和自動(dòng)布局的修改。6. 踩坑記錄那些文檔里不會(huì)寫的實(shí)際問(wèn)題6.1 插件沙箱的權(quán)限限制與繞行思路Figma 插件沙箱對(duì)某些 API 的調(diào)用是有限制的比如網(wǎng)絡(luò)請(qǐng)求、本地文件系統(tǒng)訪問(wèn)、部分跨文檔操作。Local Figma Agent MCP 走本地通信通道本身不涉及網(wǎng)絡(luò)請(qǐng)求所以網(wǎng)絡(luò)限制不影響它。但文件系統(tǒng)訪問(wèn)受限會(huì)影響導(dǎo)出功能。如果你想讓 Agent 把設(shè)計(jì)稿導(dǎo)出成圖片或 SVG 并保存到本地插件沙箱可能不允許直接寫文件。繞行思路是插件側(cè)把導(dǎo)出的數(shù)據(jù)通過(guò)本地通道傳給 MCP 服務(wù)由服務(wù)側(cè)負(fù)責(zé)寫文件。服務(wù)側(cè)運(yùn)行在 Node 環(huán)境里沒(méi)有沙箱限制可以自由讀寫本地文件。這個(gè)分工很關(guān)鍵插件負(fù)責(zé)和 Figma 交互服務(wù)負(fù)責(zé)和本地系統(tǒng)交互Agent 負(fù)責(zé)決策和調(diào)度。三層各司其職邊界清晰出問(wèn)題也容易定位是哪一層的毛病。另一個(gè)權(quán)限限制是跨文檔操作。插件只能訪問(wèn)當(dāng)前打開(kāi)的文檔沒(méi)法在后臺(tái)打開(kāi)另一個(gè)文檔并操作它。如果你的需求涉及多個(gè)文檔只能手動(dòng)切換或者用 Figma 的 REST API但那就回到付費(fèi)額度的問(wèn)題了。這個(gè)限制目前沒(méi)有太好的繞行方案只能接受。所以在規(guī)劃任務(wù)時(shí)盡量把同一文檔的操作集中在一起減少切換成本。6.2 大文檔下的性能瓶頸與優(yōu)化設(shè)計(jì)稿節(jié)點(diǎn)數(shù)量超過(guò)幾千個(gè)時(shí)性能問(wèn)題會(huì)很明顯。插件 API 的調(diào)用本身有開(kāi)銷每次讀取節(jié)點(diǎn)屬性都要跨沙箱邊界累積起來(lái)很慢。如果 Agent 還在一輪輪地發(fā)請(qǐng)求整體耗時(shí)可能從幾秒變成幾分鐘。優(yōu)化思路有幾個(gè)一是減少請(qǐng)求次數(shù)把多個(gè)讀取操作合并成一個(gè)批量請(qǐng)求二是緩存已讀取的節(jié)點(diǎn)數(shù)據(jù)避免重復(fù)讀取三是限制遍歷深度非必要不展開(kāi)深層子樹(shù)。批量請(qǐng)求的實(shí)現(xiàn)方式是在 MCP 服務(wù)側(cè)提供一個(gè)“批量讀取”接口接受一個(gè)節(jié)點(diǎn) ID 列表一次性返回所有節(jié)點(diǎn)的屬性。這樣 Agent 只需要發(fā)一次請(qǐng)求服務(wù)側(cè)在 Figma 沙箱內(nèi)循環(huán)讀取雖然總開(kāi)銷差不多但省去了多次通信的往返時(shí)間。實(shí)測(cè)下來(lái)批量讀取比逐個(gè)讀取能快三到五倍節(jié)點(diǎn)越多差距越明顯。緩存策略也要注意失效問(wèn)題。如果 Agent 讀取了節(jié)點(diǎn)數(shù)據(jù)然后修改了某個(gè)節(jié)點(diǎn)緩存里的數(shù)據(jù)就過(guò)期了。簡(jiǎn)單的做法是修改后清空相關(guān)節(jié)點(diǎn)的緩存或者干脆每次修改后重新讀取。復(fù)雜一點(diǎn)的做法是維護(hù)一個(gè)版本號(hào)每次修改遞增讀取時(shí)檢查版本號(hào)決定是否用緩存。這個(gè)看具體場(chǎng)景如果修改不頻繁簡(jiǎn)單清空就夠了。6.3 Agent 誤操作后的回滾方案Agent 誤操作是難免的關(guān)鍵是怎么快速回滾。前面說(shuō)過(guò)最穩(wěn)妥的方式是操作前復(fù)制文檔。但復(fù)制文檔有個(gè)問(wèn)題復(fù)制出來(lái)的文檔和原文檔是獨(dú)立的Agent 操作的是副本你確認(rèn)無(wú)誤后還得把改動(dòng)同步回原文檔。如果改動(dòng)很多同步本身也是工作量。所以這個(gè)方案適合改動(dòng)量大、風(fēng)險(xiǎn)高的場(chǎng)景日常小改動(dòng)沒(méi)必要這么重。輕量級(jí)的回滾方案是利用 Figma 的撤銷功能。插件 API 觸發(fā)的修改在 Figma 里是可以撤銷的只要在同一個(gè)會(huì)話里。所以如果 Agent 改錯(cuò)了立刻在 Figma 里按撤銷快捷鍵通常能恢復(fù)。但要注意撤銷棧有深度限制如果 Agent 連續(xù)做了很多步修改可能撤不回去。所以還是建議分批操作每批做完確認(rèn)一下確認(rèn)無(wú)誤再繼續(xù)。還有一個(gè)兜底方案是讓 Agent 在修改前先記錄原始值。比如要改一個(gè)節(jié)點(diǎn)的填充色先讀取當(dāng)前色值存下來(lái)修改后如果發(fā)現(xiàn)問(wèn)題可以用存下來(lái)的原始值改回去。這個(gè)方案需要 Agent 有“記錄-修改-回滾”的完整邏輯實(shí)現(xiàn)起來(lái)稍微復(fù)雜但對(duì)關(guān)鍵操作很值得。我一般會(huì)在涉及組件和布局的修改上用這個(gè)方案普通的重命名和樣式微調(diào)就不必了。7. 把 Agent 接入日常設(shè)計(jì)開(kāi)發(fā)流程的幾種玩法7.1 設(shè)計(jì)稿轉(zhuǎn)代碼從節(jié)點(diǎn)樹(shù)到組件代碼的映射這是最直接的玩法。Agent 讀取設(shè)計(jì)稿的節(jié)點(diǎn)樹(shù)識(shí)別出組件和布局生成對(duì)應(yīng)的前端代碼。映射規(guī)則可以自定義比如 FRAME 映射成 divTEXT 映射成 span 或 pINSTANCE 映射成組件引用。樣式方面填充色映射成 background-color描邊映射成 border圓角映射成 border-radius自動(dòng)布局映射成 flex 或 grid。這個(gè)過(guò)程中最麻煩的是布局推斷。Figma 的自動(dòng)布局和 CSS 的 flex 不是一一對(duì)應(yīng)的有些自動(dòng)布局的配置在 CSS 里需要額外的處理。比如 Figma 里的“間距自動(dòng)”在 CSS 里可能是 gap也可能是 margin取決于具體場(chǎng)景。Agent 需要根據(jù)節(jié)點(diǎn)的實(shí)際布局結(jié)果來(lái)反推最合適的 CSS 寫法而不是機(jī)械地翻譯屬性。這個(gè)推斷邏輯需要一些啟發(fā)式規(guī)則準(zhǔn)確率不可能百分之百但能省掉大部分手動(dòng)工作。生成的代碼質(zhì)量還取決于設(shè)計(jì)稿的規(guī)范程度。如果設(shè)計(jì)稿用了規(guī)范的組件和命名生成的代碼結(jié)構(gòu)會(huì)很清晰如果全是散亂的 Frame 和 Rectangle生成的代碼就是一堆嵌套 div可讀性很差。所以這個(gè)玩法的前提是設(shè)計(jì)稿本身有一定的規(guī)范性。如果設(shè)計(jì)稿不規(guī)范可以先做一輪規(guī)范化處理再生成代碼。7.2 設(shè)計(jì)規(guī)范檢查讓 Agent 當(dāng)你的設(shè)計(jì) lint 工具設(shè)計(jì)稿里經(jīng)常會(huì)出現(xiàn)不規(guī)范的地方用了不在設(shè)計(jì)系統(tǒng)里的色值、字體大小不在預(yù)設(shè)范圍內(nèi)、間距不是 4 的倍數(shù)、組件實(shí)例被解綁了等等。這些檢查人工做很費(fèi)時(shí)讓 Agent 做就很合適。Agent 遍歷節(jié)點(diǎn)樹(shù)對(duì)每個(gè)節(jié)點(diǎn)檢查預(yù)設(shè)的規(guī)則輸出違規(guī)列表。規(guī)則可以配置比如“所有填充色必須來(lái)自共享樣式”“所有字號(hào)必須是 12/14/16/20/24 之一”“所有間距必須是 4 的倍數(shù)”。這個(gè)玩法的價(jià)值在于它把設(shè)計(jì)規(guī)范的執(zhí)行從“事后人工檢查”變成了“隨時(shí)自動(dòng)檢查”。設(shè)計(jì)側(cè)改完稿跑一下 Agent立刻知道哪里不合規(guī)改完再跑直到通過(guò)。這比等到開(kāi)發(fā)階段才發(fā)現(xiàn)問(wèn)題要高效得多。而且規(guī)則可以隨設(shè)計(jì)系統(tǒng)演進(jìn)不斷更新Agent 的檢查邏輯也跟著更新保持一致性。實(shí)現(xiàn)上檢查規(guī)則可以寫成配置文件Agent 讀取配置后逐條執(zhí)行。每條規(guī)則對(duì)應(yīng)一個(gè)檢查函數(shù)輸入是節(jié)點(diǎn)屬性輸出是是否通過(guò)和違規(guī)詳情。這個(gè)架構(gòu)很靈活新增規(guī)則只需要加一個(gè)函數(shù)和一條配置。我見(jiàn)過(guò)一些團(tuán)隊(duì)把這種檢查集成到 CI 里設(shè)計(jì)稿更新后自動(dòng)跑結(jié)果發(fā)到群里效果不錯(cuò)。7.3 設(shè)計(jì)稿差異比對(duì)改版前后的自動(dòng)化 diff產(chǎn)品迭代時(shí)設(shè)計(jì)稿經(jīng)常改版。改版前后有哪些差異人工比對(duì)很費(fèi)眼。Agent 可以做自動(dòng)化 diff讀取兩個(gè)版本的節(jié)點(diǎn)樹(shù)按節(jié)點(diǎn) ID 或名稱匹配找出新增、刪除、修改的節(jié)點(diǎn)輸出差異報(bào)告。這個(gè)報(bào)告可以細(xì)化到屬性級(jí)別比如“按鈕的主色從 #1A73E8 改成了 #1B74E9”“卡片圓角從 8px 改成了 12px”。這個(gè)玩法的難點(diǎn)在于節(jié)點(diǎn)匹配。如果改版時(shí)節(jié)點(diǎn) ID 變了就得靠名稱和位置來(lái)匹配準(zhǔn)確率會(huì)下降。所以最好在設(shè)計(jì)側(cè)約定改版時(shí)盡量保留節(jié)點(diǎn) ID或者至少保留名稱。如果做不到Agent 的 diff 結(jié)果就需要人工復(fù)核但即便如此也比純?nèi)斯け葘?duì)快很多。差異報(bào)告的輸出格式可以很靈活簡(jiǎn)單的就是文本列表復(fù)雜點(diǎn)的可以生成 HTML 報(bào)告帶截圖對(duì)比。截圖對(duì)比需要導(dǎo)出節(jié)點(diǎn)圖片然后并排展示。這個(gè)在 MCP 服務(wù)側(cè)實(shí)現(xiàn)比較方便因?yàn)榉?wù)側(cè)可以寫文件生成 HTML 報(bào)告后直接在瀏覽器打開(kāi)看。我一般會(huì)生成一個(gè)簡(jiǎn)單的 HTML左邊是改前截圖右邊是改后截圖下面列出屬性差異一目了然。8. 關(guān)于這套方案的能力邊界與后續(xù)擴(kuò)展方向用了一段時(shí)間下來(lái)我的整體感受是Local Figma Agent MCP 這套方案在“單文檔、中等規(guī)模、規(guī)范化設(shè)計(jì)稿”的場(chǎng)景下表現(xiàn)很好能實(shí)實(shí)在在省掉大量重復(fù)勞動(dòng)。但它不是萬(wàn)能的跨文檔批量處理、超大文檔的性能、非規(guī)范設(shè)計(jì)稿的理解準(zhǔn)確率這些方面還有明顯的天花板。所以我的建議是先在小范圍試點(diǎn)跑通一個(gè)具體場(chǎng)景比如“批量重命名”或“設(shè)計(jì)規(guī)范檢查”確認(rèn)效果后再逐步擴(kuò)大使用范圍。擴(kuò)展方向上我覺(jué)得有幾個(gè)值得探索的點(diǎn)。一是把 MCP 服務(wù)和 CI 流程結(jié)合設(shè)計(jì)稿更新后自動(dòng)跑檢查和 diff結(jié)果推送到協(xié)作工具。二是把 Agent 的修改能力做成“建議模式”Agent 只輸出修改建議人工確認(rèn)后再執(zhí)行降低誤操作風(fēng)險(xiǎn)。三是積累一套針對(duì)自己團(tuán)隊(duì)設(shè)計(jì)系統(tǒng)的規(guī)則庫(kù)和提示詞模板讓 Agent 的理解準(zhǔn)確率隨著使用不斷優(yōu)化。這些方向都不需要額外的付費(fèi)成本靠本地工具鏈就能實(shí)現(xiàn)。最后說(shuō)一個(gè)實(shí)際體會(huì)這套方案的價(jià)值不在于“完全替代人工”而在于“把人工從重復(fù)勞動(dòng)里解放出來(lái)”。Agent 做批量處理人做關(guān)鍵決策和復(fù)核這個(gè)分工目前是最務(wù)實(shí)的。指望 Agent 全自動(dòng)搞定一切現(xiàn)階段還不現(xiàn)實(shí)但讓它承擔(dān)百分之七八十的機(jī)械工作完全可行。我在實(shí)際項(xiàng)目里就是這么用的效率提升很明顯而且隨著規(guī)則和提示詞的積累Agent 的表現(xiàn)會(huì)越來(lái)越好。