Article
如何開發好維護的 AI Agent？一人開發者必學的外掛模組化設計實戰
AI Agent 模組化架構實測結論：避免自製 AI Agent 越做越混亂的核心在於「徹底落實最小主幹與外掛分離」。主幹系統僅負責輸入接收、對話狀態維持與工具調度分派，嚴禁塞入具體業務邏輯；所有專門能力（如記憶庫、排程、外部 API）一律封裝為獨立外掛。當新功能出錯或需要迭代時，只需單獨拔除或啟停該外掛即可無痛退版，能大幅提升系統穩定度並降低 80% 以上的維護成本。
很多熱衷於自製 AI Agent 的朋友，常常在社群上跟我分享同一個痛苦經歷：「剛開始做一個能幫忙查資料的小助理覺得超神，但隨著功能越加越多，系統開始越來越笨、動不動就報錯。想修一個小 bug，卻連帶壞了其他三個功能，最後整份專案變成一坨誰也看不懂的廢鐵。」
這種痛苦我完全能體會。
在早期開發時，我曾嘗試屈就現成的第三方系統，試圖用落落長的提示詞（Skill）和自訂記憶強行去校正 AI 的行為。但實測下來成功率非常不穩定，尤其是在本地端運行開源模型時，稍微複雜一點的指令就會引發連鎖錯誤。更崩潰的是，每當第三方軟體更新一次，我辛苦調校好的工作流程就被破壞殆盡。
後來我花了一整週把整個系統全部推倒重構，徹底改成了 「最小主幹＋外掛注入」 的架構。從那之後，我的 Agent 系統再也沒有發生過代碼失控的情況。
這篇文章我想跟你分享這個經過實戰驗證的架構設計思維。
為什麼萬能型單體架構注定失敗？
在軟體工程中，過度耦合永遠是系統崩潰的元兇。在 AI Agent 開發中，這個問題會被進一步放大：
- Prompt 污染與上下文爆炸：當你把所有規則都寫在主程式的 System Prompt 裡，AI 在每次推理時都必須讀取大量無關資訊，不僅浪費 Token，更會大幅提高模型遺忘關鍵指令的機率。
- 單點故障導致全盤癱瘓：如果你的發文模組和主調度邏輯寫在同一個檔案裡，一旦社群 API 改版拋出錯誤，整個 Agent 就會直接罷工，連最基礎的對話功能都無法執行。
- 退版成本極高：有了一個新靈感，興沖沖寫了 300 行代碼進去。兩天後發現不好用想拿掉，卻發現這段代碼已經跟其他函式深度糾纏在一起，拆都拆不掉。
你可以參考我之前寫的 地端大模型 Agent Harness 架構實戰，了解底層狀態機與排程器的設計細節。
最小主幹＋外掛注入架構的設計原則
要徹底解決上述問題，核心在於建立嚴格的 「系統邊界」，把整個 Agent 拆解為乾淨的兩層架構：
- 第一層：最小可運作主幹（Core Harness）
- 就像手機的作業系統，只負責聽取輸入、維持對話狀態，並將任務分派給對應的模組。
- 第二層：獨立功能外掛（Plugins）
- 就像手機上的各個 App，每項能力獨立存在、隨時可插拔：
- 外掛 A（知識庫檢索）：專門負責查閱你的私有筆記與文件。
- 外掛 B（自動化任務）：專門負責社群發文、通訊軟體排程通知。
- 外掛 C（本機工具箱）：專門負責執行本機腳本或代碼測試。
- 就像手機上的各個 App，每項能力獨立存在、隨時可插拔：
1. 最小可運作主幹（Core Harness）：極度克制
主幹系統是 Agent 的骨架，它的職責必須極度單純：
- 只負責三件事：接收輸入、維護會話狀態、調度外掛。
- 嚴格控制檔案行數：任何單一核心代碼檔案只要超過一定行數，就必須依功能進一步拆分子模組，盡量避免出現幾千行的巨型檔案。
- 不寫具體業務邏輯：主幹裡面不應出現「去抓某個網頁」、「去發某個 API」等具體行為。
2. 功能一律外掛化（Plugin-First）：獨立可啟停
所有具備特定目的的能力，通通做成獨立外掛：
- 獨立配置與沙盒：每個外掛擁有自己獨立的目錄、依賴與 Prompt 規範。
- 熱插拔機制：主程式透過清單或設定檔動態載入外掛。不需要的功能隨時設為關閉，完全不佔用執行緒與 Token 資源。
3. 做錯就砍，秒級無痛退版
這個架構帶來的最大好處就是 「實驗零負擔」。
當你今天看到一個新的開源工具或想到一個新功能，直接開一個新的外掛資料夾進行測試。跑通了就留著；測試後發現不如預期，直接把整個外掛資料夾刪除就好。主幹系統毫髮無傷，代碼庫永遠維持乾淨清爽。
落地實戰：如何結合 MCP 標準化工具鏈？
在具體實作外掛時，強烈建議採用 MCP (Model Context Protocol) 作為統一介面：
- 資料庫外掛：將你的本地筆記、歷史紀錄包裝成 MCP 服務。你可以參考我整理的 12 款開源 AI Agent 工具與框架全覽 了解不同工具的整合方式。
- 通訊外掛：透過 Telegram Bot 或 Discord Webhook，將 Agent 的主動通知能力獨立封裝。
- 任務驗收外掛：設計專門的代碼審查與檢查清單外掛，讓 AI 自主完成品質把關。
配合 自製專屬 AI Agent 的 700 小時經驗，你會發現自己不再是整天在修復 bug 的救火隊員，而是能從容指揮 AI 團隊的系統架構師。
把時間花在打磨系統，而不是屈就工具
與其花時間去迎合別人做好的黑盒子系統，每天提心吊膽擔心官方更新會不會破壞工作流，不如把時間花在理解底層邏輯與系統設計上。
一個好的架構，能讓你的自製 AI Agent 隨著時間推移不斷吸收新外掛、變得越來越強大，同時永遠保持穩定與可控。
這是我在多輪重構中得到的最寶貴經驗。希望這個「主幹＋外掛」的設計思維，能幫助你在自製專屬 AI Agent 的路上走得更穩、更遠！
常見問題 FAQ
為什麼自製 AI Agent 很容易越改越爛、最後變成難以維護的混亂系統？
最主要的原因是缺乏主幹與功能的邊界劃分。很多人一有新想法，就把爬蟲、記憶庫、特定業務邏輯直接寫進主程式中。隨著代碼膨脹，各模組高度耦合，一旦某個小功能出錯或需要退版，就會牽一髮而動全身，導致整個 Agent 崩潰。
什麼是「最小可運作主幹（Harness）」？它應該包含哪些職責？
最小主幹只負責三項核心職責：接收與解析使用者輸入、維護基本的對話與執行狀態、以及根據意圖調度分派工具。主幹必須極度純粹，不包含任何具體業務邏輯，並對每個檔案的行數進行嚴格約束。
外掛注入（Plugin Injection）架構在日常維護時有什麼具體好處？
所有擴展功能（如行事曆管理、發文工具、私有資料庫）都以獨立外掛形式存在。當你想測試新想法時，只需掛上新外掛；若實測後悔或發現有 bug，直接拔除該外掛即可秒級退版，完全不會影響主幹系統的正常運作。