Claude Code Agent系統完整指南
整理版優先睇
完整介紹Claude Code Agent系統嘅架構同設計原則，從ReAct循環到團隊協作，提供漸進式構建方法。
呢篇文章係笨小葱學習Learn Claude Code之後嘅總結，主要分享Agent智能體嘅完整功能同構建步驟。作者從開發者角度，整理咗Agent系統嘅七層能力棧，由用戶交互層到團隊協作層，強調唔係單一程序，而係一個技術棧。整體結論係：Agent系統嘅核心唔係令模型更聰明，而係令系統可以可靠咁組織、調度、執行同恢復。
文章詳細剖析咗ReAct循環機制（思考-行動-觀察-循環），解釋點解呢個循環係Agent由聊天機械人躍遷為任務執行者嘅關鍵。之後介紹工具系統（本地工具管道同MCP外部插件）、規劃與任務系統（子智能體同持久化任務圖）、知識管理系統（Skill按需加載、Memory、上下文壓縮、系統提示詞組裝）、擴展與控制系統（權限、Hook、錯誤恢復）、執行與調度系統（後台任務、定時調度）同團隊協作系統（Agent團隊、團隊協議、自主代理、Worktree隔離）。
最後總結咗核心設計原則：主循環保持純粹、上下文管理分層、權限先行、錯誤可恢復、任務驅動、隔離並行、漸進複雜。強調先守住最小正確模型，再逐步擴展能力。
- Agent核心係ReAct循環（思考-行動-觀察-循環），唔係模型更聰明，而係可靠嘅循環機制，先係任務執行者嘅關鍵。
- 工具系統分本地工具管道（Dispatch Map）同外部MCP插件，所有工具調用必須經過權限閘門，安全係底線。
- 規劃系統引入子智能體（上下文隔離）同持久化任務圖（依賴關係），支援跨會話工作流，複雜任務有得拆。
- 知識管理系統用Skill按需加載、Memory跨會話記憶、上下文壓縮三層防禦，系統提示詞六段式組裝，避免token浪費。
- 團隊協作用長期駐留Agent、結構化協議、自主認領同Worktree隔離，實現並行開發，隔離係並行嘅前提。
內容片段
內部表示 (靈活、可擴展) API 協議格式 (嚴格、標準化)├─ 附加調試信息 ───► ├─ 只保留標準字段├─ 工具超時標記 ├─ tool 結果必填├─ 壓縮標記 └─ 角色嚴格交替└─ 用戶取消狀態Agent核心架構：ReAct循環係心臟
好多人第一次接觸Agent，會以為佢嘅核心競爭力係「模型更聰明」。其實唔係。真正令Agent由聊天機械人躍遷為任務執行者嘅，係一套可靠嘅循環機制。呢個機制就係ReAct模式——思考、行動、觀察、循環，逐步推進，唔係一次過完成曬。
- 1 Think（思考）：LLM基於當前上下文推理，決定下一步做咩。
- 2 Act（行動）：選擇並調用外部工具，例如讀檔案、執行命令。
- 3 Observe（觀察）：獲取工具執行結果，更新上下文。
- 4 Loop（循環）：基於觀察重新思考，重複直到任務完成。
工具系統同規劃：由「動口」到「動手」
一個只能「動口」嘅Agent好快就會見到天花板。真正嘅生產力來自於「動手」——讀檔案、執行命令、寫程式、查數據庫。工具系統就係Agent同外部世界交互嘅橋樑。喺本地，透過Dispatch Map靈活擴展工具，零侵入核心代碼；喺外部，透過MCP協議接入第三方服務，好似裝咗USB接口咁方便。但無論工具來自邊度，都必須經過同一道權限閘門，否則便利性會變成安全後門。
當任務變複雜，Agent需要規劃同分解能力。子智能體（Sub-Agent）提供上下文隔離，將子任務放喺乾淨環境執行，最後只帶結論返嚟。持久化任務系統將「會話裏嘅todo」升級為任務圖（Task Graph），引入依賴關係，系統可以主動判斷邊啲任務就緒。
知識管理系統：按需加載，避免token浪費
Agent需要管理唔同類型嘅知識。Skill係可複用嘅領域能力，按需加載——平時只畀Agent一個輕量目錄，需要嗰陣先注入完整內容。噉樣可以避免system prompt太臃腫，大部分token都用喺當前有用嘅知識上。Memory</highlight>系統解決跨會話連續性，只保存跨會話仍然成立且無法從代碼重新推導嘅知識，好似用戶偏好、設計決策背景等。
上下文壓縮係另一層防禦。再聰明嘅模型都逃唔過上下文窗口限制，所以系統有三層壓縮策略：將大輸出存磁盤、替換太耐遠嘅消息、生成連續性摘要。壓縮後必須保住五樣嘢：當前任務目標、已完成關鍵動作、已修改檔案、關鍵決定、下一步要做咩。
- 兩層心智模型：第1層輕量目錄（技能名+描述），第2層按需正文。
- Memory四類值得保存：用戶偏好、用戶糾正、項目背景、外部資源指針。
- 系統提示詞六段式組裝：core + tools + skills + memory + claude_md + dynamic_context。
擴展控制同執行調度：可靠嘅執行引擎
一個健壯嘅Agent系統需要完善嘅控制同擴展機制。權限系統係安全基礎，採用四層過濾：黑名單→模式檢查（plan模式只讀唔寫）→白名單→灰區問用戶。噉樣既保證流暢度，又守住安全底線。Hook系統提供靈活擴展點，主循環唔使因為每個小需求而改動，只需要喺固定生命週期節點觸發Hook就得。
錯誤恢復係面向恢復嘅系統設計。API調用唔係100%可靠，網絡抖動、token耗盡、上下文超限——系統必須具備自愈能力：先分類錯誤（輸出截斷、上下文太長、臨時連接失敗），再選擇對應恢復路徑（續寫提示、壓縮舊上下文、指數退避），最後先宣告失敗。執行同調度方面，後台任務將長執行同主循環解耦，定時調度令Agent擁有時間記憶，兩者最終都送回主循環統一處理。
團隊協作系統：多Agent並行工作
當單Agent能力邊界出現，可以組建Agent團隊。同子智能體「用完即走」唔同，團隊成員係長期駐留嘅，有名、有專長定義、有私有記憶。團隊協作需要結構化協議，每條消息帶類型、唯一編號同載荷，同時有請求追蹤表記錄協作流程。
為咗避免每件事都要人手分配，引入自主代理（Autonomous Agent）：Agent完成工作後進入idle狀態，自動檢查郵箱同任務板，如果有適合自己嘅ready任務就原子認領。而Worktree隔離借鑑Git worktree機制，每個任務有獨立目錄同分支，避免並行工作互相干擾。任務記錄回答「做咩、邊個做、狀態」，Worktree記錄回答「喺邊做、目錄喺邊」，兩者透過task_id關聯。
呢篇文章係笨小葱學完Learn Claude Code之後嘅一啲總結，主要係分享一個完整嘅agent智能體有啲咩功能，同埋點樣一步一步構建一個agent。
Agent 系統整體架構
成個 Agent 系統，佢唔係一個單體程序，而係一個由多層能力逐步疊加而成嘅技術棧。
用戶交互層，負責將人類嘅自然語言意圖翻譯成系統可以執行嘅任務；
核心循環層（ReAct）係系統嘅"心臟"，驅動住思考、行動、觀察同迭代嘅永動機；
工具與擴展層，等 Agent 可以讀寫文件、調用外部服務，而且安全可控；
任務與協作層，支撐住由單任務到多 Agent 協作嘅複雜度躍遷；
知識管理層，負責喺有限嘅上下文窗口入面，巧妙咁組織 Skill、Memory 同系統提示詞。
一、Agent 核心架構
四個核心步驟：
Think (思考)：LLM 根據當前上下文進行推理，決定下一步
Act (行動)：揀選並調用外部工具
Observe (觀察)：獲取工具執行結果，更新上下文
Loop (循環)：根據觀察重新思考，循環直至任務完成
二、工具系統
2.1 本地工具管道
Dispatch Map 機制：加入新工具只需註冊到調度表，零侵入核心代碼
消息規範化：Agent 內部消息格式靈活，但發送畀 API 之前必須通過規範化層清洗
內部表示 (靈活、可擴展) API 協議格式 (嚴格、標準化)
├─ 附加調試信息 ───► ├─ 只保留標準字段
├─ 工具超時標記 ├─ tool 結果必填
├─ 壓縮標記 └─ 角色嚴格交替
└─ 用戶取消狀態
一個淨係識得"把口"嘅 Agent 好快就會遇到瓶頸。真正嘅生產力來自於"動手"——讀文件、行命令、寫代碼、查數據庫。
2.2 外部插件與 MCP
當 Agent 開始喺你嘅工作流程站穩陣腳，本地硬編碼嘅工具往往就唔夠用。你可能需要連接公司嘅內部 API、第三方嘅 SaaS 服務、甚至同事嘅微服務。
MCP (Model Context Protocol) 將工具來源由"本地硬編碼"升級成"外部可插拔"
三層架構：
plugin manifest：聲明發現同啟動邊啲 server
MCP server：外部進程/連接對象，暴露一組能力
MCP tool：server 暴露嘅具體調用能力
MCP嘅出現，就好似畀 Agent 裝咗個"USB 接口"：外部服務只要實現 MCP 協議，Agent 就可以自動識別佢提供咗啲咩工具、參數格式係咩、點樣調用。
呢個意味住，你嘅 Agent 由"封閉花園"變咗做"開放平台"。
但呢度有一個絕對唔可以妥協嘅原則：無論工具係本地定係外部 MCP，都必須經過同一道權限閘門。
如果唔係，MCP 帶嚟嘅便利性就會瞬間變成安全後門。
三、規劃與任務系統
當任務變得複雜嗰陣，Agent 需要具備規劃同分解能力。介紹兩種任務處理機制：子智能體適合一次性局部任務嘅上下文隔離，持久化任務系統就支持跨會話嘅複雜工作流管理，包括依賴追蹤同狀態持久化。
3.1 子智能體
當你同 Agent 進行一場長達 20 輪嘅深度對話之後，上下文會堆積大量嘅中間結果、試錯記錄同臨時推理。
呢啲"歷史包袱"對當前任務或者仲有價值，但如果接下來你想叫佢處理一個完全獨立嘅子任務（例如"幫我查嚇呢個函數嘅文檔"），冗長嘅上下文反而會變成噪音。
子智能體（Sub-Agent）就係為咗解決呢個矛盾而產生嘅。佢唔係就咁"再開一個 LLM 窗口"咁粗暴，而係通過上下文隔離，將子任務放喺一個乾淨嘅環境執行，最後淨係將"結論摘要"帶返去主對話。就好似：你叫一個專家去調研一個子課題，你唔關心佢睇咗幾多篇論文、推翻咗幾多假設，你只需要佢最後畀出嗰份 Executive Summary。
核心價值：唔係"多一個模型實例"，而係"多一個乾淨上下文"
3.2 持久化任務系統
將"會話入面嘅 todo"升級成"可以持久化嘅任務圖"
關鍵數據結構 - TaskRecord：
┌─────────────────────────────────────────────────────────┐
│ TaskRecord
├─────────────────────────────────────────────────────────┤
│ id - 唯一標識
│ subject - 一句話描述做什麼
│ description - 補充說明
│ status - pending / in_progress / completed
│ blockedBy - 還在等誰
│ blocks - 它完成後會解鎖誰
│ owner - 現在由誰來做
└─────────────────────────────────────────────────────────┘
就緒判斷（核心能力）：判斷任務可唔可以開始執行
會話入面嘅 todo 清單適合"一次性任務"，但現實中嘅項目通常係跨日、跨星期甚至跨月。今日做到一半嘅代碼重構，聽日轉個會話繼續；用戶上星期提嘅需求，呢個星期先排到期開發日程。
如果冇持久化任務系統，Agent 每次開場都要重新理解"我哋喺邊、下一步做咩"。
將 todo 升級為任務圖（Task Graph），核心改進在於引入咗"依賴關係"。任務 A 完成之後自動解鎖任務 B，任務 C 被任務 D 阻塞嘅時候一目瞭然。
呢個唔單止係一個"待辦清單"，更加係一個"就緒判斷引擎"——系統可以主動話畀 Agent 知："而家呢啲嘢可以開始做喇。"
四、知識管理系統
Agent 需要管理唔同類型嘅知識：Skill 係可重用嘅領域能力，Memory 係跨會話嘅用戶認知，上下文壓縮保證長對話嘅連續性。呢度介紹點樣有效組織同利用呢啲知識，避免上下文膨脹同時保持工作連貫性。
4.1 Skill 按需加載
當 agent 具備咗調工具、規劃、分配子任務嘅能力之後，面對新問題：唔同任務需要唔同嘅領域知識，如果全部塞入 system prompt，會導致：
大部分 token 浪費喺當前用唔到嘅知識上
prompt 越來越臃腫，主線規則變到唔清晰
兩層心智模型：
┌─────────────────────────────────────┐
│ 第 1 層：輕量目錄
│ - skill 名稱
│ - skill 描述
│ - 讓模型知道"有哪些可用"
├─────────────────────────────────────┤
│ 第 2 層：按需正文
│ - 只有真正需要時才加載
│ - 通過 tool_result 注入上下文
└─────────────────────────────────────┘
Skill vs Memory vs CLAUDE.md 邊界：
| 概念 | 定位 | 判斷法 |
|---|---|---|
| Skill | 可選知識包，某類任務先需要 | "呢啲係某類任務先需要嘅做法或知識" |
| Memory | 跨會話有價值嘅信息 | "呢啲係需要長期記住嘅事實或偏好" |
| CLAUDE.md | 穩定嘅全局規則 | "呢啲係更加穩定嘅全局規則" |
System prompt 就好似 Agent 嘅"入職培訓手冊"。如果將呢本手冊寫到包羅萬有——前端規範、後端規範、運維腳本、數據分析技巧——Agent 處理任何任務嗰陣都要先讀完呢本"百科全書"，大部分 token 都浪費咗喺當下無關嘅知識上。
Skill 系統嘅精髓係"按需加載"。平時淨係話畀 Agent 一個輕量目錄："我哋有前端技能包、SQL 技能包、安全審計技能包。" 只有當 Agent 決定要處理數據庫相關任務嘅時候，先將 SQL 技能包嘅完整內容注入上下文。就好似外科醫生入手術室之前，唔會帶齊成本醫學教科書，而係淨係拎同當前手術相關嘅器械同流程單。
4.2 上下文壓縮
再聰明嘅模型，都逃唔過上下文窗口嘅物理限制。
當 Agent 連續讀取咗幾個大文件、執行咗幾輪長命令輸出之後，歷史記錄就會好似雪球咁越滾越大。如果唔加幹預，遲早會撞上 token 上限，或者令模型淹沒喺噪音之中。
上下文壓縮唔係"刪歷史"，而係"換個方式記歷史"。
它分為三層防禦：
第一層，將超大嘅工具輸出存到磁盤，上下文淨係保留路徑同預覽；
第二層，將太耐之前嘅消息替換成佔位提示；
第三層，如果整體都係太長，就生成一份"連續性摘要"，將幾十輪對話嘅核心信息濃縮成幾段話。
壓縮之後一定要保住嘅 5 樣嘢：
當前任務目標
已完成嘅關鍵動作
已修改/睇過嘅文件
關鍵決定同約束
下一步應該做咩
4.3 記憶系統
一個冇記憶嘅 Agent，就好似一個每日朝早都會失憶嘅同事。
你尋日先話畀佢知"我哋團隊用 tab 縮進"，今日佢寫代碼又變返做空格；你上星期糾正過佢"匯報嗰陣要先畀結論再畀細節"，呢個星期佢又開始長篇大論。
Memory 系統解決嘅就係呢種"跨會話連續性"。但唔係所有信息都值得永久記住。好嘅記憶管理遵循一個簡單原則：淨係保存啲跨會話仍然成立、而且冇辦法從當前代碼/文檔重新推導出嚟嘅知識。
用戶嘅代碼風格偏好、項目嘅設計決策背景、外部系統嘅連結地址——呢啲值得記；
而某個函數嘅參數列表、當前分支嘅名、臨時嘅調試日誌——呢啲唔值得記，因為佢哋一係會變，一係隨時可以重新獲取。
四類值得保存嘅 Memory：
| 類型 | 保存內容 | 示例 |
|---|---|---|
| user | 用戶偏好 | 鍾意咩代碼風格、回答要簡潔定係詳細 |
| feedback | 用戶明確糾正/確認過嘅位 | "唔好咁改"、"以後先做呢個" |
| project | 代碼睇唔出嘅項目背景 | 某設計決定係因為合規而唔係技術 |
| reference | 外部資源指針 | 問題單喺邊個睇板 |
4.4 系統提示詞組裝
好多開發者喺構建 Agent 嗰陣，最大嘅技術債往往產生於 system prompt。一開始佢只係一段簡單嘅字符串，但隨住功能迭代，prompt 入面開始混雜工具列表、動態日期、用戶偏好、本輪臨時提醒……最終變成一團好難調試嘅"意大利麵"。
解決之道係將 prompt 組裝當成一條流水線，而唔係一堆靜態文本。由核心身份說明、到工具列表、到 skills 目錄、到 memory 內容、再到 CLAUDE.md 規則鏈，每一段都有清晰嘅邊界同職責。
穩定嘅信息放喺固定嘅模塊入面，臨時嘅提醒就單獨注入。咁樣當某個模塊需要更新嗰陣，你唔需要喺一大段文字入面小心翼翼咁做"外科手術"。
六段式組裝：
core # 核心身份和行為說明
+ tools # 工具列表
+ skills # skills 元信息
+ memory # memory 內容
+ claude_md # CLAUDE.md 指令鏈
+ dynamic_context # 動態環境信息
= final system prompt
關鍵邊界：穩定說明 vs 動態提醒
穩定說明：身份、規則、工具、長期約束
動態提醒：本輪臨時需要嘅補充上下文
五、擴展與控制系統
一個健壯嘅 Agent 系統需要完善嘅控制同擴展機制。權限系統係安全嘅基礎，Hook 系統提供靈活嘅擴展點，錯誤恢復保證系統遇到問題嗰陣可以自癒而唔係崩潰。呢三者共同構建咗 Agent 嘅可控性同可靠性。
5.1 權限系統
"意圖"唔可以直接變成"執行"，中間一定要經過權限檢查。
一個好嘅權限管道應該係分層遞進嘅：
先檢查"黑名單"（明顯危險嘅命令直接拒絕），
再檢查"當前模式"（plan 模式下淨係允許讀唔允許寫），
然後檢查"白名單"（安全嘅日常操作自動放行），
最後剩低嘅灰區先交畀用戶確認。呢個四層過濾機制，既保證咗流暢度，又守住了安全底線。
權限管道（四步模型）：
三種核心權限模式：
| 模式 | 含義 | 場景 |
|---|---|---|
| default | 未命中規則時問用戶 | 日常交互 |
| plan | 淨係允許讀，唔允許寫 | 計劃、審查、分析 |
| auto | 簡單安全操作自動過，危險再問 | 高流暢度探索 |
5.2 Hook 系統
主循環嘅代碼應該好似憲法咁穩定，唔應該因為每個小需求就去改佢。Hook 系統就係為咗呢種"擴展但唔侵入"嘅需求而產生嘅。
無論係會話開始嗰陣打印歡迎語、工具執行前做一次額外校驗、定係執行後寫一條審計日誌，都可以通過 Hook 掛接到固定嘅生命週期節點上。
主循環只需要關心"喺咩時機觸發 Hook"同"Hook 嘅返回值代表咩"，至於 Hook 內部做咗啲咩，佢唔需要知道。呢種解耦，係保持系統長期可維護嘅關鍵。
三個核心事件：
| 事件 | 觸發時機 |
|---|---|
| SessionStart | 會話開始嗰陣 |
| PreToolUse | 工具執行前 |
| PostToolUse | 工具執行後 |
統一返回約定：
| 退出碼 | 含義 | 作用 |
|---|---|---|
| 0 | 正常繼續 | 觀察 |
| 1 | 阻止當前動作 | 攔截 |
| 2 | 注入補充消息，再繼續 | 補充 |
5.3 錯誤恢復
現實世界入面嘅 API 調用從來都唔係 100% 可靠。網絡抖動、token 耗盡、上下文超限——呢啲問題如果處理得唔好，Agent 就會好似個玻璃公仔咁一碰就碎。
健壯嘅 Agent 系統一定要有"自癒"能力。輸出被截斷咗？注入續寫提示再試一次。上下文太長喇？觸發壓縮策略之後再試一次。網絡超時喇？按指數退避等一陣再試一次。
關鍵係：先分類錯誤，再揀恢復路徑，最後先宣告失敗。 呢個唔係 try-catch 嘅堆砌，而係一種"面向恢復"嘅系統設計思維。
三類問題 + 三條恢復路徑：
| 問題類型 | 觸發原因 | 恢復路徑 |
|---|---|---|
| 輸出被截斷 | token 用完 | 注入續寫提示，再試一次 |
| 上下文太長 | prompt 裝唔入窗口 | 壓縮舊上下文，再試一次 |
| 臨時連接失敗 | 網絡、超時、限流 | 退避等待，再試一次 |
六、執行與調度系統
實際業務入面好多操作係好花時間嘅（例如編譯、測試、數據拉取），唔可以畀主循環一直等。呢章介紹後台任務機制解決異步執行問題，以及定時調度機制支持週期性任務，兩者結合實現完整嘅任務執行能力。
6.1 後台任務
假設你叫 Agent 行一套完整嘅測試套件，或者編譯一個大型項目。如果呢啲操作都阻塞喺主循環入面，Agent 就只能乾等，用戶亦只能望住屏幕發呆。
後台任務機制將"長執行"同"主循環"解耦咗。
Agent 發起一個後台任務之後，即刻拎到一個 task_id 繼續處理其他嘢；後台執行線自己行命令，完成之後將摘要推到通知隊列。
下一輪主循環由隊列度"Drain"出結果，繼續推進。
呢度最重要嘅一個認知糾偏：主循環仍然只有一條，並行嘅係等待，唔係主循環本身。 你唔會因為咁而引入複雜嘅多線程鎖問題。
6.2 定時調度
有啲意圖唔係"而家就要做"，而係"聽日朝早 9 點做"或者"每星期一晚行一次"。定時調度就係畀 Agent 擁有"時間記憶"嘅能力。
佢嘅實現唔複雜：核心就三個部件——調度記錄（記住幾時做咩）、定時檢查器（每分鐘睇一次有冇匹配）、通知隊列（將到期嘅調度事件送回主循環）。
當時間到咗，調度器唔會自己偷偷執行，而係將 prompt 好似一條新消息咁注入主循環，由主循環統一決策。
咁樣，定時任務同用戶嘅即時請求，最終都走到咗同一條處理路徑上。
三個部分：
| 部分 | 職責 |
|---|---|
| 調度記錄 | 記住"幾時做咩" |
| 定時檢查器 | 每分鐘睇"而家係咪匹配" |
| 通知隊列 | 將觸發嘅事件送回主循環 |
與後台任務嘅區別：
後台任務："已經啟動嘅慢操作，結果幾時返嚟？"
定時調度："一件事應該喺未來幾時開始？"
七、團隊協作系統
複雜項目往往需要多個 Agent 協同工作。呢章由單個長駐 Agent 嘅定義開始，逐步構建團隊協作能力：團隊協議規範協作流程，自主代理等 Agent 可以主動認領任務，Worktree 隔離保證並行工作互不幹擾。
7.1 Agent 團隊
當單 Agent 嘅能力邊界開始顯現嗰陣，一個好自然嘅想法係：可唔可以好似組建開發團隊咁，組建一個 Agent 團隊？
同子智能體"用完即走"唔同，團隊成員係長期駐留的。
佢哋有名、有專長定義、有私有記憶。一個專門負責代碼審查嘅 Agent、一個專門負責文檔寫作嘅 Agent、一個專門負責測試嘅 Agent，佢哋可以喺同一個任務板上協作。
關鍵係，呢種協作唔係"一個超級 LLM 分飾多角"，而係等唔同角色喺各自擅長嘅領域深度鑽研。
子 agent vs 團隊成員：
| 維度 | 子 agent | 團隊成員 |
|---|---|---|
| 生命週期 | 用完即走 | 長期駐留 |
| 身份 | 臨時創建 | 有名、有專長定義 |
| 狀態 | 無記憶 | 持久化狀態 |
| 協作 | 單向委派 | 多向溝通、互相調用 |
7.2 團隊協議
多 Agent 協作如果只係"拉個group自由聊天"，好快就會陷入混亂：A 向 B 提出一個請求，B 回覆咗，但 A 唔知道呢條回覆對應邊個請求；C 同時 send 咗三個任務畀 D，D 分唔清優先級。
團隊協議嘅作用，就係為呢種多向溝通加上結構化約束。
每條協議消息都帶有類型（type）、唯一編號（request_id）同載荷（payload）。
同時，系統維護一張請求追蹤表，記錄每個協作請求目前係 pending、approved 定係 rejected。協議唔負責實際工作嘅推進，佢只負責"等協作流程有據可查"。
兩層結構：
| 層級 | 作用 | 示例 |
|---|---|---|
| 協議消息 | 定義消息係點樣 | type / request_id / payload |
| 請求追蹤表 | 記錄事情去到邊一步 | pending / approved / rejected |
四類關鍵對象邊界：
| 對象 | 回答咩問題 |
|---|---|
| MessageEnvelope | 邊個同邊個講咗咩 |
| ProtocolEnvelope | 呢個係咪結構化請求或響應 |
| RequestRecord | 協作流程走到邊一步 |
| TaskRecord | 真正嘅工作項目係咩 |
7.3 自主代理
團隊入面如果每件事都要靠一個"隊長"手動分配，效率好快就會變成瓶頸。自主代理（Autonomous Agent）解決嘅就係"邊個做"嘅自動化問題。
當一個 Agent 完成手頭工作之後，佢會進入 idle 狀態。喺呢個狀態下，佢會先檢查郵箱（有冇明確 send 畀我嘅消息），再掃描任務板（有冇符合我角色嘅 ready 任務），如果有，就自動認領並切換返 work 狀態。
為咗避免兩個 Agent 同時認領同一個任務，認領操作一定要係原子的——就好似搶飛時嘅鎖機制一樣。
兩個階段切換：
7.4 Worktree 隔離
多個 Agent 並行工作，如果大家都喺同一個代碼目錄入面改文件，衝突同污染幾乎係無可避免。
Worktree 隔離借用咗 Git 嘅 worktree 機制，畀每個任務分配一條獨立嘅"車道"（獨立嘅目錄同分支）。
任務記錄負責回答"做咩、邊個做、狀態點樣"，Worktree 記錄負責回答"喺邊做、目錄喺邊、對應邊個分支"。兩者通過 task_id 關聯。一個任務完成之後，佢嘅 worktree 可以選擇保留（畀 review 用）或者刪除（清理空間）。呢個係"隔離並行"設計原則喺工程層面嘅直接落地。
兩張表：
| 表 | 負責回答 |
|---|---|
| 任務板 | 做咩、邊個做、狀態點樣 |
| worktree 註冊表 | 喺邊做、目錄喺邊、對應邊個任務 |
關鍵認知：任務記錄工作目標，worktree 記錄執行車道。
睇到呢度，你可能會問：呢啲模塊聽落都好抽象，放喺真實業務入面應該點組合？答案係：按需裁剪，漸進疊加。
軟件開發 Agent 可能需要完整嘅七層能力（由代碼審查到 Worktree 隔離）；
而一個簡單嘅客服助手，可能只需要基礎 ReAct Loop + 知識庫 + Memory 就夠。
最核心嘅建議係：先守住最小正確模型，再逐步擴展能力。 唔好為咗一個"未來可能會用到嘅團隊協議"，就將第一版嘅單 Agent 系統搞到過度工程。
八、核心設計原則總結
以下原則貫穿成個 Agent 系統嘅設計，係構建可靠、可維護系統嘅指導思想。喺實際開發入面應該成日對照呢啲原則做決策。
主循環保持純粹：工具擴展通過 Dispatch Map，行為擴展通過 Hook
上下文管理分層：活躍上下文 vs 持久記憶 vs 外部知識源
權限先行：任何執行都必須經過權限檢查
錯誤可恢復：區分錯誤類型，揀恢復路徑，唔輕易失敗
任務驅動：由子任務委派到持久化任務圖，再到自治認領
隔離並行：Worktree 提供執行隔離，後台任務提供執行並行
漸進複雜：先守住最小正確模型，再逐步擴展能力
最後一句話總結：
Agent 系統嘅核心唔係令模型更聰明，而係令系統可以可靠咁組織、調度、執行同恢復。模型係引擎，系統係車架——只有車架夠堅固，引擎嘅馬力先真正轉化為速度。
本文是笨小葱在學習了Learn Claude Code之後的一些總結，主要是分享一下完整的agent智能體包含哪些功能，以及如何一步步構建一個agent。
Agent 系統整體架構
整個 Agent 系統，它不是一個單體程序，而是一個由多層能力漸進疊加而成的技術棧。
用戶交互層，負責把人類的自然語言意圖翻譯成系統可執行的任務；
核心循環層（ReAct）是系統的"心臟"，驅動着思考、行動、觀察和迭代的永動機；
工具與擴展層，讓 Agent 能夠讀寫文件、調用外部服務、並且安全可控；
任務與協作層，支撐着從單任務到多 Agent 協作的複雜度躍遷；
知識管理層，負責在有限的上下文窗口內，巧妙地組織 Skill、Memory 和系統提示詞。
一、Agent 核心架構
四個核心步驟：
Think (思考)：LLM 基於當前上下文進行推理，決定下一步
Act (行動)：選擇並調用外部工具
Observe (觀察)：獲取工具執行結果，更新上下文
Loop (循環)：基於觀察重新思考，循環直到任務完成
二、工具系統
2.1 本地工具管道
Dispatch Map 機制：添加新工具只需註冊到調度表，零侵入核心代碼
消息規範化：Agent 內部消息格式靈活，但發送給 API 前必須通過規範化層清洗
內部表示 (靈活、可擴展) API 協議格式 (嚴格、標準化)
├─ 附加調試信息 ───► ├─ 只保留標準字段
├─ 工具超時標記 ├─ tool 結果必填
├─ 壓縮標記 └─ 角色嚴格交替
└─ 用戶取消狀態
一個只能"動嘴"的 Agent 很快就會觸及天花板。真正的生產力來自於"動手"——讀文件、跑命令、寫代碼、查數據庫。
2.2 外部插件與 MCP
當 Agent 開始在你的工作流中站穩腳跟，本地硬編碼的工具往往就不夠用了。你可能需要連接公司的內部 API、第三方的 SaaS 服務、甚至同事的微服務。
MCP (Model Context Protocol) 把工具來源從"本地硬編碼"升級成"外部可插拔"
三層架構：
plugin manifest：聲明發現和啓動哪些 server
MCP server：外部進程/連接對象，暴露一組能力
MCP tool：server 暴露的具體調用能力
MCP的出現，就像給 Agent 裝上了"USB 接口"：外部服務只要實現 MCP 協議，Agent 就能自動識別它提供了哪些工具、參數格式是什麼、如何調用。
這意味着，你的 Agent 從"封閉花園"變成了"開放平台”。
但這裏有一個絕不能妥協的原則：無論工具來自本地還是外部 MCP，都必須經過同一道權限閘門。
否則，MCP 帶來的便利性就會瞬間變成安全後門。
三、規劃與任務系統
當任務變得複雜時，Agent 需要具備規劃和分解能力。介紹兩種任務處理機制：子智能體適合一次性局部任務的上下文隔離，持久化任務系統則支持跨會話的複雜工作流管理，包括依賴追蹤和狀態持久化。
3.1 子智能體
當你和 Agent 進行一場長達 20 輪的深度對話後，上下文中會堆積大量的中間結果、試錯記錄和臨時推理。
這些"歷史包袱"對當前任務或許還有價值，但如果接下來你想讓它處理一個完全獨立的子任務（比如"幫我查一下這個函數的文檔"），冗長的上下文反而會成為噪音。
子智能體（Sub-Agent）就是為解決這個矛盾而生的。它不是簡單地"再開一個 LLM 窗口"這麼粗暴，而是通過上下文隔離，把子任務放到一個乾淨的環境中執行，最後只把"結論摘要"帶回到主對話。這就像是：你讓一位專家去調研一個子課題，你不關心他翻了多少篇論文、推翻了多少假設，你只需要他最後給出的那份 Executive Summary。
核心價值：不是"多一個模型實例"，而是"多一個乾淨上下文"
3.2 持久化任務系統
把"會話裏的 todo"升級成"可持久化的任務圖"
關鍵數據結構 - TaskRecord：
┌─────────────────────────────────────────────────────────┐
│ TaskRecord
├─────────────────────────────────────────────────────────┤
│ id - 唯一標識
│ subject - 一句話描述做什麼
│ description - 補充說明
│ status - pending / in_progress / completed
│ blockedBy - 還在等誰
│ blocks - 它完成後會解鎖誰
│ owner - 現在由誰來做
└─────────────────────────────────────────────────────────┘
就緒判斷（核心能力）：判斷任務是否可以開始執行
會話裏的 todo 清單適合"一次性任務"，但現實中的項目往往是跨天、跨周甚至跨月的。今天做到一半的代碼重構，明天換個會話繼續；用戶上週提的需求，這周才排到開發日程。
如果沒有持久化任務系統，Agent 每次開場都要重新理解"我們在哪、接下來做什麼"。
把 todo 升級為任務圖（Task Graph），核心改進在於引入了"依賴關係"。任務 A 完成後自動解鎖任務 B，任務 C 被任務 D 阻塞時一目瞭然。
這不僅僅是一個"待辦清單"，更是一個"就緒判斷引擎"——系統能主動告訴 Agent："現在這些事情可以開始做了。"
四、知識管理系統
Agent 需要管理不同類型的知識：Skill 是可複用的領域能力，Memory 是跨會話的用戶認知，上下文壓縮保證長對話的連續性。這裏介紹如何有效組織和利用這些知識，避免上下文膨脹同時保持工作連貫性。
4.1 Skill 按需加載
當 agent 具備調工具、規劃、分配子任務的能力後，面臨新問題：不同任務需要不同的領域知識，如果全部塞進 system prompt，會導致：
大部分 token 浪費在當前用不到的知識上
prompt 越來越臃腫，主線規則變得不清晰
兩層心智模型：
┌─────────────────────────────────────┐
│ 第 1 層：輕量目錄
│ - skill 名稱
│ - skill 描述
│ - 讓模型知道"有哪些可用"
├─────────────────────────────────────┤
│ 第 2 層：按需正文
│ - 只有真正需要時才加載
│ - 通過 tool_result 注入上下文
└─────────────────────────────────────┘
Skill vs Memory vs CLAUDE.md 邊界：
| 概念 | 定位 | 判斷法 |
|---|---|---|
| Skill | 可選知識包，某類任務才需要 | "這是某類任務才需要的做法或知識" |
| Memory | 跨會話有價值的信息 | "這是需要長期記住的事實或偏好" |
| CLAUDE.md | 穩定的全局規則 | "這是更穩定的全局規則" |
System prompt 就像是 Agent 的"入職培訓手冊"。如果把這個手冊寫得包羅萬象——前端規範、後端規範、運維腳本、數據分析技巧——Agent 處理任何任務時都要先讀完這本"百科全書"，大部分 token 都浪費在了當下無關的知識上。
Skill 系統的精髓是"按需加載"。平時只告訴 Agent 一個輕量目錄："我們有前端技能包、SQL 技能包、安全審計技能包。" 只有當 Agent 決定要處理數據庫相關任務時，才把 SQL 技能包的完整內容注入上下文。這就像是外科醫生進手術室前，不會把整本醫學教材都帶上，而是隻拿與當前手術相關的器械和流程單。
4.2 上下文壓縮
再聰明的模型，也逃不過上下文窗口的物理限制。
當 Agent 連續讀取了幾個大文件、執行了幾輪長命令輸出後，歷史記錄就會像雪球一樣越滾越大。如果不加干預，遲早會撞上 token 上限，或者讓模型淹沒在噪聲中。
上下文壓縮不是"刪歷史"，而是"換種方式記歷史"。
它分為三層防禦：
第一層，把超大的工具輸出存到磁盤，上下文中只保留路徑和預覽；
第二層，把太久遠的消息替換成佔位提示；
第三層，如果整體還是太長，就生成一份"連續性摘要"，把幾十輪對話的核心信息濃縮成幾段話。
壓縮後必須保住的 5 樣東西：
當前任務目標
已完成的關鍵動作
已修改/查看的文件
關鍵決定與約束
下一步應該做什麼
4.3 記憶系統
一個沒有記憶的 Agent，就像是一個每天早上都會失憶的同事。
你昨天才告訴他"我們團隊用 tab 縮進"，今天他寫代碼時又變回了空格；你上週糾正過他"彙報時要先給結論再給細節"，這周他又開始長篇大論。
Memory 系統解決的就是這種"跨會話連續性"。但並不是所有信息都值得永久記住。好的記憶管理遵循一個簡單原則：只保存那些跨會話仍然成立、且無法從當前代碼/文檔中重新推導出來的知識。
用戶的代碼風格偏好、項目的設計決策背景、外部系統的連結地址——這些值得記；
而某個函數的參數列表、當前分支的名字、臨時的調試日誌——這些不值得記，因為它們要麼會變，要麼隨時可以重新獲取。
四類值得保存的 Memory：
| 類型 | 保存內容 | 示例 |
|---|---|---|
| user | 用戶偏好 | 喜歡什麼代碼風格、回答要簡潔還是詳細 |
| feedback | 用戶明確糾正/確認過的地方 | "不要這樣改"、"以後先做這個" |
| project | 代碼看不出來的項目背景 | 某設計決定因合規而非技術 |
| reference | 外部資源指針 | 問題單在哪個看板 |
4.4 系統提示詞組裝
很多開發者在構建 Agent 時，最大的技術債往往產生於 system prompt。一開始它只是一段簡單的字符串，但隨着功能迭代，prompt 裏開始混雜工具列表、動態日期、用戶偏好、本輪臨時提醒……最終變成一團難以調試的"意大利麪條"。
解決之道是把 prompt 組裝當成一條流水線，而不是一堆靜態文本。從核心身份說明、到工具列表、到 skills 目錄、到 memory 內容、再到 CLAUDE.md 規則鏈，每一段都有清晰的邊界和職責。
穩定的信息放在固定的模塊裏，臨時的提醒單獨注入。這樣當某個模塊需要更新時，你不需要在一大段文字裏小心翼翼地做"外科手術"。
六段式組裝：
core # 核心身份和行為說明
+ tools # 工具列表
+ skills # skills 元信息
+ memory # memory 內容
+ claude_md # CLAUDE.md 指令鏈
+ dynamic_context # 動態環境信息
= final system prompt
關鍵邊界：穩定說明 vs 動態提醒
穩定說明：身份、規則、工具、長期約束
動態提醒：本輪臨時需要的補充上下文
五、擴展與控制系統
一個健壯的 Agent 系統需要完善的控制和擴展機制。權限系統是安全的基礎，Hook 系統提供靈活的擴展點，錯誤恢復保證系統遇到問題時能夠自愈而非崩潰。這三者共同構建了 Agent 的可控性和可靠性。
5.1 權限系統
"意圖"不能直接變成"執行"，中間必須經過權限檢查。
一個好的權限管道應該是分層遞進的：
先檢查"黑名單"（明顯危險的命令直接拒絕），
再檢查"當前模式"（plan 模式下只允許讀不允許寫），
然後檢查"白名單"（安全的日常操作自動放行），
最後剩下的灰區才交給用戶確認。這個四層過濾機制，既保證了流暢度，又守住了安全底線。
權限管道（四步模型）：
三種核心權限模式：
| 模式 | 含義 | 場景 |
|---|---|---|
| default | 未命中規則時問用戶 | 日常交互 |
| plan | 只允許讀，不允許寫 | 計劃、審查、分析 |
| auto | 簡單安全操作自動過，危險再問 | 高流暢度探索 |
5.2 Hook 系統
主循環的代碼應該像憲法一樣穩定，不應該因為每個小需求都去修改它。Hook 系統就是為這種"擴展但不侵入"的需求而生的。
無論是會話開始時打印歡迎語、工具執行前做一次額外校驗、還是執行後寫一條審計日誌，都可以通過 Hook 掛接到固定的生命週期節點上。
主循環只需要關心"在什麼時機觸發 Hook"和"Hook 的返回值代表什麼"，至於 Hook 內部做了什麼，它無需知曉。這種解耦，是保持系統長期可維護的關鍵。
三個核心事件：
| 事件 | 觸發時機 |
|---|---|
| SessionStart | 會話開始時 |
| PreToolUse | 工具執行前 |
| PostToolUse | 工具執行後 |
統一返回約定：
| 退出碼 | 含義 | 作用 |
|---|---|---|
| 0 | 正常繼續 | 觀察 |
| 1 | 阻止當前動作 | 攔截 |
| 2 | 注入補充消息，再繼續 | 補充 |
5.3 錯誤恢復
現實世界中的 API 調用從來不是 100% 可靠的。網絡抖動、token 耗盡、上下文超限——這些問題如果處理不好，Agent 就會像個玻璃娃娃一樣一碰就碎。
健壯的 Agent 系統必須具備"自愈"能力。輸出被截斷了？注入續寫提示再試一次。上下文太長了？觸發壓縮策略後再試一次。網絡超時了？按指數退避等待後再試一次。
關鍵是：先分類錯誤，再選擇恢復路徑，最後才宣告失敗。 這不是 try-catch 的堆砌，而是一種"面向恢復"的系統設計思維。
三類問題 + 三條恢復路徑：
| 問題類型 | 觸發原因 | 恢復路徑 |
|---|---|---|
| 輸出被截斷 | token 用完 | 注入續寫提示，再試一次 |
| 上下文太長 | prompt 裝不進窗口 | 壓縮舊上下文，再試一次 |
| 臨時連接失敗 | 網絡、超時、限流 | 退避等待，再試一次 |
六、執行與調度系統
實際業務中很多操作是耗時的（如編譯、測試、數據拉取），不能讓主循環一直等待。本章介紹後台任務機制解決異步執行問題，以及定時調度機制支持週期性任務，兩者結合實現完整的任務執行能力。
6.1 後台任務
假設你讓 Agent 運行一套完整的測試套件，或者編譯一個大型項目。如果這些操作都阻塞在主循環裏，Agent 就只能乾等着，用戶也只能盯着屏幕發呆。
後台任務機制把"長執行"和"主循環"解耦了。
Agent 發起一個後台任務後，立刻拿到一個 task_id 繼續處理其他事情；後台執行線獨自跑命令，完成後把摘要推到通知隊列。
下一輪主循環從隊列裏"Drain"出結果，繼續推進。
這裏最重要的是一個認知糾偏：主循環仍然只有一條，並行的是等待，不是主循環本身。 你不會因此引入複雜的多線程鎖問題。
6.2 定時調度
有些意圖不是"現在就要做"，而是"明天早上 9 點做"或者"每週一晚上跑一次"。定時調度就是讓 Agent 擁有"時間記憶"的能力。
它的實現並不複雜：核心就三個部件——調度記錄（記住何時做什麼）、定時檢查器（每分鐘看一次有沒有匹配）、通知隊列（把到期的調度事件送回主循環）。
當時間到了，調度器不會自己偷偷執行，而是把 prompt 像一條新消息一樣注入主循環，由主循環統一決策。
這樣，定時任務和用戶的即時請求，最終都走到了同一條處理路徑上。
三個部分：
| 部分 | 職責 |
|---|---|
| 調度記錄 | 記住"何時做什麼" |
| 定時檢查器 | 每分鐘看"現在是否匹配" |
| 通知隊列 | 把觸發的事件送回主循環 |
與後台任務的區別：
後台任務："已經啓動的慢操作，結果什麼時候回來？"
定時調度："一件事應該在未來什麼時候開始？"
七、團隊協作系統
複雜項目往往需要多個 Agent 協同工作。本章從單個長駐 Agent 的定義開始，逐步構建團隊協作能力：團隊協議規範協作流程，自主代理讓 Agent 能夠主動認領任務，Worktree 隔離保證並行工作互不干擾。
7.1 Agent 團隊
當單 Agent 的能力邊界開始顯現時，一個很自然的想法是：能不能像組建開發團隊一樣，組建一個 Agent 團隊？
與子智能體"用完即走"不同，團隊成員是長期駐留的。
它們有名字、有專長定義、有私有記憶。一位專門負責代碼審查的 Agent、一位專門負責文檔寫作的 Agent、一位專門負責測試的 Agent，它們可以在同一個任務板上協作。
關鍵是，這種協作不是"一個超級 LLM 分飾多角"，而是讓不同角色在各自擅長的領域裏深耕。
子 agent vs 團隊成員：
| 維度 | 子 agent | 團隊成員 |
|---|---|---|
| 生命週期 | 用完即走 | 長期駐留 |
| 身份 | 臨時創建 | 有名字、有專長定義 |
| 狀態 | 無記憶 | 持久化狀態 |
| 協作 | 單向委派 | 多向溝通、互相調用 |
7.2 團隊協議
多 Agent 協作如果只是"拉個羣自由聊天"，很快就會陷入混亂：A 向 B 提了一個請求，B 回覆了，但 A 不知道這條回覆對應的是哪個請求；C 同時給 D 發了三個任務，D 分不清優先級。
團隊協議的作用，就是給這種多向溝通加上結構化約束。
每條協議消息都帶有類型（type）、唯一編號（request_id）和載荷（payload）。
同時，系統維護一張請求追蹤表，記錄每個協作請求當前是 pending、approved 還是 rejected。協議不負責實際工作的推進，它只負責"讓協作流程有據可查"。
兩層結構：
| 層級 | 作用 | 示例 |
|---|---|---|
| 協議消息 | 定義消息長什麼樣 | type / request_id / payload |
| 請求追蹤表 | 記錄事情走到哪一步 | pending / approved / rejected |
四類關鍵對象邊界：
| 對象 | 回答什麼問題 |
|---|---|
| MessageEnvelope | 誰跟誰說了什麼 |
| ProtocolEnvelope | 這是不是結構化請求或響應 |
| RequestRecord | 協作流程走到哪一步 |
| TaskRecord | 真正的工作項是什麼 |
7.3 自主代理
團隊裏如果每件事都要靠一個"隊長"手動分配，效率很快就會成為瓶頸。自主代理（Autonomous Agent）解決的就是"誰來做"的自動化問題。
當一位 Agent 完成手頭工作後，它會進入 idle 狀態。在這個狀態下，它會先檢查郵箱（有沒有明確發給我的消息），再掃描任務板（有沒有符合我角色的 ready 任務），如果有，就自動認領並切換回 work 狀態。
為了避免兩個 Agent 同時認領同一個任務，認領操作必須是原子的——就像搶火車票時的鎖機制一樣。
兩個階段切換：
7.4 Worktree 隔離
多個 Agent 並行工作，如果大家都在同一個代碼目錄裏改文件，衝突和污染幾乎是不可避免的。
Worktree 隔離借鑑了 Git 的 worktree 機制，給每個任務分配一條獨立的"車道"（獨立的目錄和分支）。
任務記錄負責回答"做什麼、誰在做、狀態如何"，Worktree 記錄負責回答"在哪做、目錄在哪、對應哪個分支"。兩者通過 task_id 關聯。一個任務完成後，它的 worktree 可以選擇保留（供 review 用）或刪除（清理空間）。這是"隔離並行"設計原則在工程層面的直接落地。
兩張表：
| 表 | 負責回答 |
|---|---|
| 任務板 | 做什麼、誰在做、狀態如何 |
| worktree 註冊表 | 在哪做、目錄在哪、對應哪個任務 |
關鍵認知：任務記錄工作目標，worktree 記錄執行車道。
看到這裏，你可能會問：這些模塊聽起來都很抽象，放到真實業務裏該怎麼組合？答案是：按需裁剪，漸進疊加。
軟件開發 Agent 可能需要完整的七層能力（從代碼審查到 Worktree 隔離）；
而一個簡單的客服助手，可能只需要基礎 ReAct Loop + 知識庫 + Memory 就夠了。
最核心的建議是：先守住最小正確模型，再逐步擴展能力。 不要為了一個"未來可能用到的團隊協議"，就把第一版的單 Agent 系統搞成過度工程。
八、核心設計原則總結
以下原則貫穿整個 Agent 系統的設計，是構建可靠、可維護系統的指導思想。在實際開發中應時刻對照這些原則進行決策。
主循環保持純粹：工具擴展通過 Dispatch Map，行為擴展通過 Hook
上下文管理分層：活躍上下文 vs 持久記憶 vs 外部知識源
權限先行：任何執行都必須經過權限檢查
錯誤可恢復：區分錯誤類型，選擇恢復路徑，不輕易失敗
任務驅動：從子任務委派到持久化任務圖，再到自治認領
隔離並行：Worktree 提供執行隔離，後台任務提供執行並行
漸進複雜：先守住最小正確模型，再逐步擴展能力
最後一句話總結：
Agent 系統的核心不是讓模型更聰明，而是讓系統能夠可靠地組織、調度、執行和恢復。模型是引擎，系統是車架——只有車架足夠堅固，引擎的馬力才能真正轉化為速度。