前一陣我把一個(gè)開(kāi)源大模型團(tuán)隊(duì)放出的 Agent 框架源碼從前到后拆了一遍。拆之前我的預(yù)期挺簡(jiǎn)單一個(gè) Agent 框架核心就是“模型調(diào)用工具執(zhí)行”插件化無(wú)非是把工具注冊(cè)表做成可擴(kuò)展的而已。拆完之后這個(gè)預(yù)期被徹底推翻了——在這套設(shè)計(jì)里插件化不是掛在骨架上的裝飾而是骨架本身。這篇文章不打算給你復(fù)述文檔。我想講的是從源碼層面看到的“插件化”是怎么一步步變厚的啟動(dòng)階段做了哪些事、內(nèi)置插件走的是哪些插槽、你寫(xiě)自定義插件的時(shí)候會(huì)遇到哪些隱藏約定還有我實(shí)際排查過(guò)的三個(gè)坑。如果你正在自研智能體應(yīng)用或者想把一個(gè)別人的 Agent 框架集成進(jìn)業(yè)務(wù)系統(tǒng)這篇應(yīng)該能幫你在動(dòng)手之前先建立一張地圖。1. 為什么插件化會(huì)決定 Agent 框架的上限1.1 “工具函數(shù)列表”和“插件體系”是兩碼事很多 Agent 工程起步時(shí)都會(huì)定義一個(gè)工具列表把搜索、計(jì)算器、查數(shù)據(jù)庫(kù)之類(lèi)的函數(shù)掛上去模型需要時(shí)按名稱調(diào)用。這種實(shí)現(xiàn)跑 Demo 沒(méi)問(wèn)題但把工具函數(shù)塞進(jìn)一個(gè)大數(shù)組只算“擴(kuò)展能力”不算“插件化”。插件化意味著整個(gè)運(yùn)行過(guò)程可以被插拔。我把這套框架拆完之后印象最深的一件事是它的內(nèi)核幾乎沒(méi)有業(yè)務(wù)邏輯所有外部能力都是通過(guò)接口進(jìn)來(lái)的。模型供應(yīng)商是一個(gè)插件記憶存儲(chǔ)是一個(gè)插件工具注冊(cè)是一個(gè)插件統(tǒng)計(jì)觀測(cè)也是一個(gè)插件。內(nèi)核只做一件事把對(duì)話循環(huán)跑起來(lái)然后在每個(gè)關(guān)鍵節(jié)點(diǎn)把控制權(quán)交給注冊(cè)好的插件。這個(gè)差別不是實(shí)現(xiàn)細(xì)節(jié)上的差別而是架構(gòu)思路上的差別。前者把擴(kuò)展點(diǎn)寫(xiě)死在代碼里后者把擴(kuò)展點(diǎn)定義成一種“協(xié)議”。1.2 Agent 框架比普通后端框架更需要插件化為什么偏偏 Agent 框架要把插件化做得這么重我拆的時(shí)候一直在想這個(gè)問(wèn)題。后來(lái)想明白了一個(gè)很現(xiàn)實(shí)的點(diǎn)Agent 系統(tǒng)的運(yùn)行循環(huán)是反復(fù)迭代的——模型發(fā)一個(gè)請(qǐng)求工具返回一個(gè)結(jié)果再傳給模型再調(diào)用下一個(gè)工具。如果你把“模型調(diào)用方式”“記憶讀取策略”“工具沖突處理”全部硬編碼進(jìn)主循環(huán)任何業(yè)務(wù)上的新需求都會(huì)變成對(duì)主循環(huán)的修改。比如今天要用流式輸出明天要切換一個(gè)向量數(shù)據(jù)庫(kù)后天要接入多個(gè)模型的自動(dòng)路由。在主循環(huán)里堆 if else 是最快的翻車(chē)方式。插件化把變化點(diǎn)抽成一個(gè)接一個(gè)的插槽業(yè)務(wù)方只需要關(guān)心自己負(fù)責(zé)的那個(gè)插槽不需要理解整個(gè)循環(huán)。而且 Agent 場(chǎng)景天然多模型、多工具、多記憶策略這些東西的組合是乘法級(jí)別的。硬編碼只能支持線性增長(zhǎng)插件化才能支撐組合式增長(zhǎng)。1.3 既然插件化這么好為什么多數(shù)框架不做透拆這套框架的過(guò)程中我也順手翻過(guò)其他幾個(gè)開(kāi)源 Agent 項(xiàng)目。很多項(xiàng)目的問(wèn)題不是沒(méi)有插件概念而是插件化只做了一層皮有 Plugin 類(lèi)、有 register 方法但插件之間無(wú)法互相調(diào)用插件生命周期沒(méi)人管理插件配置要靠全局變量傳遞。真正做透插件化的成本很高。第一你要定義一套足夠穩(wěn)定的生命周期第二你要處理插件之間的依賴關(guān)系第三你要給插件提供上下文對(duì)象而不是讓它們各自取全局狀態(tài)第四你還要處理加載順序和配置合并這些邊緣問(wèn)題。這些設(shè)計(jì)每一條都燒時(shí)間而且短期內(nèi)看不出收益。所以當(dāng)我在源碼里看到一整套“配置合并 → 模塊掃描 → 生命周期管理 → 上下文注入”的鏈路時(shí)我意識(shí)到這不是順手寫(xiě)的而是認(rèn)真設(shè)計(jì)過(guò)的。2. 啟動(dòng)階段的三條暗線配置合并、模塊掃描、生命周期管理拆解啟動(dòng)過(guò)程是我覺(jué)得收獲最大的部分。一個(gè) Agent 服務(wù)啟動(dòng)看起來(lái)只是“讀配置文件拉起服務(wù)”但插件化的地基全部埋在這里。2.1 第一條暗線配置合并的順序框架啟動(dòng)時(shí)配置來(lái)源不是單一的一個(gè)文件而是有多層默認(rèn)配置、本地配置文件、環(huán)境變量、命令行參數(shù)。這四層配置需要按優(yōu)先級(jí)合并。我在源碼里看到的合并邏輯是分層 Merge先加載默認(rèn)配置再用配置文件覆蓋默認(rèn)值接著用環(huán)境變量覆蓋配置文件最后命令行參數(shù)優(yōu)先級(jí)最高。每一層都是深合并不是整塊替換。這個(gè)順序直接決定了插件能不能拿到正確的配置。如果你自己實(shí)現(xiàn)插件化我建議把“配置合并”放進(jìn)啟動(dòng)器的前置階段并且給每個(gè)插件發(fā)一個(gè)只讀的配置快照而不是讓插件直接去讀全局配置。一旦插件散落在各處讀環(huán)境變量你就再也無(wú)法控制它們的可測(cè)試性了。2.2 第二條暗線模塊掃描啟動(dòng)階段的第二件事是找到所有插件。這里沒(méi)有用一長(zhǎng)串 import 硬編碼而是走了一套“聲明式掃描”。核心邏輯大概是先讀配置里聲明啟用了哪些插件再按照插件路徑去逐一導(dǎo)入模塊導(dǎo)入之后調(diào)用模塊暴露的注冊(cè)入口。# 示意代碼插件掃描與注冊(cè) import importlib import logging logger logging.getLogger(__name__) def load_plugins(registry, config): plugin_paths config.get(plugins, []) if not plugin_paths: return [] for plugin_path in plugin_paths: try: module importlib.import_module(plugin_path) except ImportError: logger.warning(plugin %s not found, skip, plugin_path) continue if hasattr(module, register): # 注冊(cè)階段只聲明能力不做初始化 module.register(registry) else: logger.warning(plugin %s has no register function, plugin_path)這段看起來(lái)簡(jiǎn)單但有兩個(gè)關(guān)鍵點(diǎn)。一是“注冊(cè)階段不初始化”這意味著 register 只負(fù)責(zé)把插件的能力聲明填到注冊(cè)表里不連接數(shù)據(jù)庫(kù)、不創(chuàng)建線程池。真正做重活的是后續(xù)的 setup 階段。二是“按配置聲明加載”而不是自動(dòng)掃描所有包這樣既能控制加載范圍也能避免無(wú)意間把測(cè)試插件帶進(jìn)生產(chǎn)環(huán)境。2.3 第三條暗線生命周期管理注冊(cè)只是第一步插件要從“已注冊(cè)”變成“可運(yùn)行”中間還有一整套生命周期鉤子。我拆下來(lái)看到的鉤子主要有下面這幾個(gè)每個(gè)鉤子的觸發(fā)時(shí)機(jī)和作用完全不同鉤子名稱觸發(fā)時(shí)機(jī)典型用途validate插件注冊(cè)完成后校驗(yàn)依賴是否齊全、配置是否合法setup框架啟動(dòng)過(guò)程中建立外部連接、初始化客戶端start第一個(gè)對(duì)話開(kāi)始前預(yù)熱緩存、加載預(yù)訓(xùn)練向量stop服務(wù)關(guān)閉前保存檢查點(diǎn)、落盤(pán)狀態(tài)teardown資源回收階段關(guān)閉連接、清理線程池這套生命周期最大的價(jià)值是把“插件的代碼”和“框架的運(yùn)行狀態(tài)”解耦了。插件作者不需要猜測(cè)自己應(yīng)該在哪一步連接數(shù)據(jù)庫(kù)直接按鉤子語(yǔ)義來(lái)實(shí)現(xiàn)就行。比如你做一個(gè)記憶插件在 setup 里建立向量庫(kù)連接在 stop 里把內(nèi)存索引寫(xiě)盤(pán)在 teardown 里釋放連接整個(gè)生命周期就能被框架穩(wěn)定地控制住。我在自己的工程里后來(lái)也復(fù)刻了這套生命周期哪怕只是極簡(jiǎn)版也幫我避免了很多“插件對(duì)象被創(chuàng)建但還沒(méi)初始化”的尷尬問(wèn)題。3. 內(nèi)置插件拆出來(lái)的四種“難做但值得做”的插槽框架內(nèi)置插件并不多但每個(gè)插槽的選擇都很有代表性。我挑四個(gè)印象最深的插槽展開(kāi)說(shuō)它們分別處理的是模型接入、工具注冊(cè)、記憶存儲(chǔ)、可觀測(cè)性。3.1 模型適配器把“換模型”變成換插件模型適配器是外部模型和內(nèi)部循環(huán)之間的接口。整套框架的對(duì)話循環(huán)不直接關(guān)心你用的是哪家模型、什么格式、什么參數(shù)體系。它只認(rèn)一個(gè)統(tǒng)一的聊天完成接口包括普通生成和流式生成兩個(gè)變體。我拆下來(lái)看到的接口設(shè)計(jì)大概是這樣的思路定義一個(gè) ChatModel 抽象里面有一個(gè) chat 方法和一個(gè) stream 方法不同模型各自實(shí)現(xiàn)這兩個(gè)方法。業(yè)務(wù)層要切換模型時(shí)只需要在配置里換掉當(dāng)前激活的模型適配器。這個(gè)插槽的價(jià)值在只接一種模型的時(shí)候體現(xiàn)不出來(lái)。一旦你需要在不同供應(yīng)商之間做自動(dòng)路由、需要根據(jù)任務(wù)難度選擇不同模型、需要灰度切換模型版本模型適配器就是唯一的改動(dòng)入口。沒(méi)有這個(gè)插槽換模型意味著把主循環(huán)里的調(diào)用全部改一遍。3.2 工具注冊(cè)器把“工具聲明”和“工具執(zhí)行”拆開(kāi)第二個(gè)讓我眼前一亮的內(nèi)置插槽是工具注冊(cè)器。很多實(shí)現(xiàn)里工具就是一個(gè)可調(diào)用函數(shù)最多帶上一個(gè) JSON Schema 描述。但在這套框架里工具被拆成了兩個(gè)階段聲明和執(zhí)行。聲明階段提供工具的元信息包括名稱、描述、參數(shù) Schema、權(quán)限要求執(zhí)行階段才是真正跑業(yè)務(wù)邏輯。框架在每次調(diào)用工具前會(huì)先校驗(yàn)參數(shù)再執(zhí)行映射執(zhí)行完畢還會(huì)把結(jié)果經(jīng)過(guò)統(tǒng)一的后續(xù)處理鉤子送回對(duì)話循環(huán)。這個(gè)設(shè)計(jì)說(shuō)直白點(diǎn)就是把“工具調(diào)用”從一個(gè)函數(shù)調(diào)用變成了一條有攔截點(diǎn)的鏈路。審計(jì)日志可以在執(zhí)行前攔截權(quán)限校驗(yàn)可以在執(zhí)行前攔截參數(shù)糾錯(cuò)也可以在 Schema 校驗(yàn)階段完成。如果只是把函數(shù)直接塞給模型這些能力強(qiáng)加不進(jìn)去。3.3 記憶存儲(chǔ)記憶變成可替換的存儲(chǔ)后端記憶存儲(chǔ)是很多 Agent 項(xiàng)目最后才會(huì)考慮的事。前期對(duì)話短直接在上下文里塞就好等到對(duì)話歷史超過(guò)模型上下文窗口才不得不做壓縮和檢索。這套框架把記憶抽象成了幾個(gè)操作保存、讀取、列出、刪除。默認(rèn)實(shí)現(xiàn)是內(nèi)存存儲(chǔ)但接口不變的情況下你可以換成向量庫(kù)、關(guān)系庫(kù)、文件存儲(chǔ)甚至接一層混合存儲(chǔ)熱數(shù)據(jù)放內(nèi)存冷數(shù)據(jù)放向量庫(kù)。這個(gè)插槽對(duì)我的啟發(fā)是記憶不應(yīng)該被硬編碼成“歷史消息數(shù)組”而應(yīng)該是一種可檢索的存儲(chǔ)接口。接口定得好后續(xù)加檢索器、加壓縮策略都很順手。接口定得差比如直接暴露一個(gè)列表讓你往里面 append那后面做任何優(yōu)化都要改業(yè)務(wù)代碼。3.4 觀測(cè)與評(píng)測(cè)讓數(shù)據(jù)收集也走插件通道這個(gè)插槽是我原本沒(méi)想到的?？蚣馨讶罩?、指標(biāo)、調(diào)用鏈追蹤、評(píng)測(cè)回調(diào)全都做成了插件。每完成一次模型調(diào)用框架會(huì)觸發(fā)一個(gè)“調(diào)用完成”鉤子每次工具執(zhí)行結(jié)束也會(huì)觸發(fā)對(duì)應(yīng)的鉤子。觀測(cè)插件只需要訂閱這些鉤子就能匯總 token 用量、耗時(shí)、調(diào)用次數(shù)、成功率。這比在業(yè)務(wù)代碼里到處埋點(diǎn)要干凈得多。業(yè)務(wù)方不需要關(guān)心數(shù)據(jù)怎么上報(bào)框架也不需要在主循環(huán)里寫(xiě)死一個(gè) metrics 系統(tǒng)。兩邊通過(guò)鉤子協(xié)議交互想接 Prometheus 就接 Prometheus想接日志平臺(tái)就接日志平臺(tái)。表格總結(jié)一下這四個(gè)插槽方便對(duì)照插槽類(lèi)型核心接口思想默認(rèn)實(shí)現(xiàn)常見(jiàn)擴(kuò)展場(chǎng)景模型適配器統(tǒng)一 chat/stream 接口單一模型直連多模型路由、灰度切換工具注冊(cè)器聲明與執(zhí)行分離本地函數(shù)注冊(cè)權(quán)限校驗(yàn)、審計(jì)、動(dòng)態(tài)工具記憶存儲(chǔ)save/recall/list/delete內(nèi)存存儲(chǔ)向量庫(kù)、數(shù)據(jù)庫(kù)、多層存儲(chǔ)觀測(cè)與評(píng)測(cè)鉤子訂閱本地日志指標(biāo)上報(bào)、調(diào)用鏈追蹤值得注意的是這四個(gè)插槽不是四個(gè)各自獨(dú)立的系統(tǒng)。它們?nèi)抗灿猛惶咨芷?、同一個(gè)配置注入機(jī)制、同一個(gè)上下文對(duì)象。這就是把插件化做透的意義當(dāng)你學(xué)會(huì)寫(xiě)其中一個(gè)插件其他插件的寫(xiě)法也就都會(huì)了。4. 隱藏的約定注冊(cè)入口、配置注入與加載優(yōu)先級(jí)這部分內(nèi)容文檔里基本不會(huì)寫(xiě)全我是靠翻源碼和跑調(diào)試才摸清楚的。我把它們稱為“隱藏的約定”因?yàn)椴蛔袷剡@些約定插件代碼也能運(yùn)行但會(huì)在一兩周后突然出問(wèn)題而且問(wèn)題非常難查。4.1 一個(gè)模塊必須暴露統(tǒng)一的注冊(cè)入口每個(gè)插件模塊都要暴露一個(gè) register 函數(shù)框架加載時(shí)統(tǒng)一調(diào)用。這個(gè)約定的好處是可以做靜態(tài)檢查框架在啟動(dòng)階段就能發(fā)現(xiàn)插件模塊缺少注冊(cè)入口從而快速失敗而不是等到運(yùn)行中途才發(fā)現(xiàn)某個(gè)能力缺失。這和我們寫(xiě)單元測(cè)試很像。你寫(xiě)測(cè)試用例時(shí)不希望靠魔法自動(dòng)發(fā)現(xiàn)測(cè)試函數(shù)你會(huì)約定測(cè)試類(lèi)必須繼承某個(gè)基類(lèi)或方法名必須以 test 開(kāi)頭。插件系統(tǒng)也是同理統(tǒng)一入口比反射魔法更可控。4.2 插件聲明元數(shù)據(jù)而不是靠猜每個(gè)插件模塊還要聲明自己的名稱、版本號(hào)和依賴關(guān)系。依賴聲明在這個(gè)框架里特別重要因?yàn)椴寮g可以互相調(diào)用。比如你的業(yè)務(wù)插件要用內(nèi)置記憶插件就必須在元數(shù)據(jù)里聲明這個(gè)依賴加載器會(huì)做依賴檢查依賴缺失時(shí)它會(huì)明確報(bào)錯(cuò)而不是讓你的插件運(yùn)行到一半再去訪問(wèn)空實(shí)例。4.3 配置注入是“帶命名空間”的不是全局裸露的插件讀取配置時(shí)拿到的不是整個(gè)全局配置對(duì)象而是一個(gè)被隔離的配置片段?？蚣軙?huì)給每個(gè)插件分配一個(gè)獨(dú)立的配置命名空間。插件只能感知自己命名空間下的配置不能隨隨便便讀到其他插件的內(nèi)部配置。這樣做的好處是隔離性。多個(gè)插件都由同一個(gè)團(tuán)隊(duì)開(kāi)發(fā)時(shí)全局配置隨手可讀一旦插件數(shù)量變多、甚至由不同團(tuán)隊(duì)開(kāi)發(fā)命名空間隔離能避免配置名互相覆蓋。我見(jiàn)過(guò)太多因?yàn)槿峙渲面I沖突導(dǎo)致的線上事故所以這一點(diǎn)我極其贊同。4.4 加載優(yōu)先級(jí)內(nèi)置先于外部聲明順序決定覆蓋關(guān)系框架加載插件時(shí)默認(rèn)先加載內(nèi)置插件再按用戶聲明順序加載外部插件。這個(gè)順序意味著外部插件可以覆蓋內(nèi)置插件的某些行為但內(nèi)置插件始終先注冊(cè)保證基礎(chǔ)能力可用。加載順序還影響同名鉤子的執(zhí)行順序。如果你寫(xiě)了多個(gè)插件都訂閱了同一個(gè)“工具調(diào)用前”的鉤子那么先加載的插件會(huì)先執(zhí)行。這一點(diǎn)不搞清楚排查鉤子執(zhí)行順序的時(shí)候會(huì)非常困惑。4.5 約定太多也會(huì)變成負(fù)擔(dān)我必須說(shuō)句公道話這套框架的約定足夠多多到新手剛開(kāi)始一定會(huì)懵。約定帶來(lái)了規(guī)則的一致性也讓“框架感”更強(qiáng)。在實(shí)際落地時(shí)我給團(tuán)隊(duì)的內(nèi)部規(guī)范是約定要選最有價(jià)值的寫(xiě)進(jìn)文檔其他用代碼示例引導(dǎo)。千萬(wàn)別指望所有人自覺(jué)看源碼。5. 排查插件鏈路時(shí)踩過(guò)的三個(gè)關(guān)鍵坑拆這套框架期間我自己寫(xiě)了好幾個(gè)自定義插件也順手修改過(guò)內(nèi)置插件。這個(gè)過(guò)程中踩了三個(gè)坑每個(gè)都花了不少時(shí)間排查。現(xiàn)在回頭看它們恰恰能說(shuō)明插件化設(shè)計(jì)里的幾個(gè)隱藏取舍。5.1 插件 B 調(diào)用插件 A拿到的是空實(shí)例第一個(gè)坑出現(xiàn)在插件互相調(diào)用時(shí)。我在自定義插件里要讀取內(nèi)置記憶插件的內(nèi)容直接在 setup 階段訪問(wèn)結(jié)果拿到的是 None。我一開(kāi)始以為是注冊(cè)失敗加了一堆日志才發(fā)現(xiàn)是加載順序問(wèn)題我的插件先于內(nèi)置記憶插件完成 setup所以訪問(wèn)時(shí)記憶插件的實(shí)例還沒(méi)有被初始化。排查鏈路是這樣走的第一步確認(rèn)插件是否出現(xiàn)在注冊(cè)表里第二步加日志打印每個(gè)插件的 setup 時(shí)間和順序第三步發(fā)現(xiàn)同名插件的 setup 順序完全取決于加載順序第四步翻到一個(gè)依賴檢查機(jī)制需要在插件元數(shù)據(jù)里顯式聲明依賴。根因找到了框架沒(méi)有做自動(dòng)依賴拓?fù)渑判蚨且箝_(kāi)發(fā)者顯式聲明依賴。表面上看這不夠“智能”但設(shè)計(jì)意圖是避免隱式依賴帶來(lái)的循環(huán)引用和無(wú)限遞歸。修復(fù)方式就是在元數(shù)據(jù)里補(bǔ)上依賴聲明并且在訪問(wèn)別的插件時(shí)加一個(gè)空值守衛(wèi)。5.2 配置文件里寫(xiě)了參數(shù)加載后還是默認(rèn)值第二個(gè)坑更隱蔽。我在配置文件里寫(xiě)了一個(gè)記憶插件的參數(shù)結(jié)果運(yùn)行起來(lái)發(fā)現(xiàn)參數(shù)沒(méi)生效還是代碼里的默認(rèn)值。第一反應(yīng)是框架沒(méi)讀我的配置文件后來(lái)打印了實(shí)際配置才發(fā)現(xiàn)配置文件被加載了但合并邏輯是淺合并導(dǎo)致我的自定義參數(shù)被默認(rèn)配置整體覆蓋了。排查過(guò)程讓我理解了框架的選擇。它默認(rèn)實(shí)現(xiàn)的是“按頂層鍵覆蓋”而不是“全路徑深合并”。這種策略的好處是避免嵌套結(jié)構(gòu)被意外合并出預(yù)期之外的組合壞處是如果你只改了子字段父級(jí)整塊可能被覆蓋。解決辦法是自定義插件要提供結(jié)構(gòu)清晰的默認(rèn)配置塊并且在合并時(shí)采用逐字段深合并。這也提醒我在業(yè)務(wù)代碼里處理多層配置時(shí)明確合并策略比約定優(yōu)先級(jí)更重要。5.3 熱加載之后上下文不同步第三個(gè)坑是熱加載導(dǎo)致的。開(kāi)發(fā)調(diào)試時(shí)我啟用了插件的熱加載能力修改插件代碼后不需要重啟服務(wù)。但運(yùn)行中的 Agent 主循環(huán)還是拿著舊的對(duì)象引用導(dǎo)致改了代碼不生效。排查后發(fā)現(xiàn)熱加載只替了注冊(cè)表里的插件對(duì)象但已經(jīng)在運(yùn)行中的上下問(wèn)里持有的實(shí)例不會(huì)自動(dòng)更新?？蚣苓x擇的是“會(huì)話級(jí)上下文快照”每個(gè)對(duì)話持有自己的插件引用新的對(duì)話才會(huì)拿到新版本插件。這個(gè)設(shè)計(jì)取舍我可以理解如果強(qiáng)行更新運(yùn)行中的上下文很可能會(huì)導(dǎo)致正在執(zhí)行的調(diào)用鏈引用到不兼容的對(duì)象崩潰更頻繁。排查完之后我給自己定了個(gè)規(guī)矩插件熱加載只用于開(kāi)發(fā)調(diào)試絕不在生產(chǎn)環(huán)境開(kāi)著。6. 落地到自己的項(xiàng)目最小可用的 Agent 插件骨架拆完別人的框架真正有用的收獲是能提煉出一套可以落到自己項(xiàng)目里的最小骨架。這里我把它寫(xiě)出來(lái)你可以直接參考。6.1 核心結(jié)構(gòu)Registry Context Lifecycle最小骨架只需要三個(gè)核心組件。Registry 負(fù)責(zé)注冊(cè)和查詢插件Context 負(fù)責(zé)在插件之間傳遞狀態(tài)Lifecycle 負(fù)責(zé)在正確時(shí)間調(diào)用插件的初始化與清理方法。6.2 極簡(jiǎn)實(shí)現(xiàn)示例下面這段 Python 代碼展示的就是這套最小骨架的核心接口。它不追求完整但保留了最重要的生命周期和鉤子機(jī)制。from typing import Any, Callable, Dict, List class PluginContext: 插件上下文所有插件共享的狀態(tài)容器 def __init__(self, global_config: Dict[str, Any]): self.config global_config self.store: Dict[str, Any] {} class AgentPlugin: 插件基類(lèi)子類(lèi)只需要按需重寫(xiě)鉤子方法 name: str base_plugin version: str 0.0.1 dependencies: List[str] [] def setup(self, ctx: PluginContext): pass def before_tool_call(self, ctx: PluginContext, tool_name: str, args: dict): pass def after_tool_call(self, ctx: PluginContext, tool_name: str, result: Any): pass def teardown(self): pass class Registry: 插件注冊(cè)表管理插件的注冊(cè)、查詢和鉤子分發(fā) def __init__(self): self.plugins: Dict[str, AgentPlugin] {} self.hooks: Dict[str, List[Callable]] {} def register(self, plugin: AgentPlugin): self.plugins[plugin.name] plugin for hook_name in [before_tool_call, after_tool_call]: fn getattr(plugin, hook_name, None) if fn is None: continue self.hooks.setdefault(hook_name, []).append(fn) def get(self, name: str): return self.plugins.get(name) def run_hook(self, hook_name: str, *args, **kwargs): fns self.hooks.get(hook_name, []) for fn in fns: fn(*args, **kwargs) def startup(self, ctx: PluginContext): for plugin in self.plugins.values(): plugin.setup(ctx) def shutdown(self): for plugin in reversed(list(self.plugins.values())): plugin.teardown()如果你之前沒(méi)接觸過(guò)這類(lèi)設(shè)計(jì)可以把它想象成一個(gè)“有登記、有回調(diào)、有啟動(dòng)順序”的插件總線。主循環(huán)只需要在對(duì)應(yīng)位置調(diào)用run_hook插件注冊(cè)時(shí)自動(dòng)訂閱這些鉤子。6.3 為什么我堅(jiān)持用 Context 而不是全局變量這個(gè)骨架里特別強(qiáng)調(diào)了 Context是因?yàn)?Agent 對(duì)話天然是并發(fā)場(chǎng)景。如果你用模塊級(jí)全局變量來(lái)傳遞狀態(tài)兩個(gè)并發(fā)對(duì)話會(huì)在同一份狀態(tài)上互相覆蓋這會(huì)引發(fā)非常難查的問(wèn)題。Context 對(duì)象每一個(gè)對(duì)話循環(huán)創(chuàng)建一份插件在回調(diào)時(shí)拿到的永遠(yuǎn)是當(dāng)前對(duì)話的狀態(tài)。這樣做雖然多了一點(diǎn)傳參成本但換來(lái)的是并發(fā)安全。6.4 不需要照搬的部分不是所有細(xì)節(jié)都需要復(fù)制。比如我不建議一上來(lái)就做完整的依賴拓?fù)渑判?、?fù)雜的熱加載、多層配置合并。先把“注冊(cè)入口、生命周期、Context 傳遞”這三件事做好插件系統(tǒng)已經(jīng)能支撐大部分業(yè)務(wù)需求。后續(xù)再慢慢補(bǔ)強(qiáng)遠(yuǎn)比一開(kāi)始就造一個(gè)重型框架更穩(wěn)妥。7. 拆完源碼后我的插件設(shè)計(jì)原則變了說(shuō)實(shí)話拆之前我對(duì)插件化的理解還停留在“接口加注冊(cè)表”拆完之后沉淀下來(lái)的是幾條更細(xì)的設(shè)計(jì)原則。寫(xiě)在這里也算給自己提個(gè)醒。第一注冊(cè)階段必須是純聲明不能做任何初始化動(dòng)作。凡是 register 里連接數(shù)據(jù)庫(kù)、創(chuàng)建線程池的插件代碼都是定時(shí)炸彈。注冊(cè)只做能力登記啟動(dòng)階段再做實(shí)際初始化。第二插件之間的依賴必須顯式聲明。哪怕你的插件現(xiàn)在只有一個(gè)也要把 dependency 字段留著。部署插件不是寫(xiě)單機(jī)腳本你會(huì)很難記住誰(shuí)依賴誰(shuí)讓框架在啟動(dòng)時(shí)幫你檢查依賴比運(yùn)行時(shí)崩潰再查要高效得多。第三鉤子的粒度要圍繞 Agent 主循環(huán)來(lái)定。不要憑空定義很多看似漂亮的鉤子要對(duì)著真實(shí)的主循環(huán)找出變化點(diǎn)工具調(diào)用前、工具調(diào)用后、模型響應(yīng)后、會(huì)話結(jié)束。定義滿覆蓋率高插件作者才有地方插。第四上下文對(duì)象要小而明確。Context 里塞太多全局?jǐn)?shù)據(jù)最后會(huì)變成一個(gè)沒(méi)有文檔的萬(wàn)能包。寧可讓插件自己去注冊(cè)表取數(shù)據(jù)也別在 Context 里堆所有中間結(jié)果。第五插件出錯(cuò)要能局部隔離?？蚣茉谶@種場(chǎng)景下最害怕的就是一個(gè)插件的異常拖垮整個(gè)對(duì)話。我在最小骨架里特意沒(méi)有處理這個(gè)問(wèn)題但實(shí)際落地時(shí)我會(huì)在 run_hook 外層包一層 try/except把插件異常轉(zhuǎn)成可觀測(cè)的日志項(xiàng)而不是直接拋出整個(gè)調(diào)用鏈。這套源碼拆完之后我自己最大的變化是不再把插件化當(dāng)成一個(gè)“錦上添花”的功能而是開(kāi)始把它當(dāng)作 Agent 框架的基礎(chǔ)設(shè)施。工具會(huì)越來(lái)越多模型會(huì)越來(lái)越雜記憶和評(píng)測(cè)會(huì)越來(lái)越重沒(méi)有一套清晰的插件骨架這些東西遲早會(huì)把主循環(huán)變成一座搬不動(dòng)的泥山。如果你也在做類(lèi)似的項(xiàng)目我建議你先別急著追求復(fù)雜框架找個(gè)周末把自己項(xiàng)目里“未來(lái)一定會(huì)變”的那幾個(gè)點(diǎn)列出來(lái)然后照著注冊(cè)表、生命周期、上下文這三件套畫(huà)一版極簡(jiǎn)骨架。跑一個(gè)老朋友對(duì)話的 Demo再回頭決定要不要把某個(gè)能力收編成插件。你會(huì)發(fā)現(xiàn)先搭骨架再填肉比直接在肉上打補(bǔ)丁要省心得多。