Claude Code 源碼揭秘：6 個默認agent幹活 + 3 個組件管事，多 Agent 協作的工業級實現，不污染上下文

💡 閲讀前記得關注+星標，及時收到更新推送

「Claude Code 源碼揭秘」系列嘅第八篇，上一篇《Claude Code 源碼揭秘：70% 觸發壓縮、LCS 差分快照、全局/項目雙記憶 — 三層架構榨乾 200K 窗口》，講嘅係點樣喺有限嘅上下文窗口入面塞更多資訊。但仲有另一個諗法：將任務分出去，等子代理用獨立嘅上下文做嘢。

用 Claude Code 做複雜任務嘅時候，你可能會留意到一個現象：佢會「派出」一啲子任務去執行，執行完再整合結果。

例如你叫佢「分析整個代碼庫嘅架構」，佢唔會傻下傻下咁將所有文件都讀入上下文，而係派一個 Explore 代理去搜索關鍵文件，搜完之後將結果帶返嚟。

呢個就係子代理系統。

翻 src/agents/ 和 src/tools/agent.ts，實現咗兩類嘢：6 種可以調用嘅子代理（通過 Task 工具派出去做嘢）同 3 種基礎設施組件（內部自動運行）。呢套設計嘅核心思想係：主代理做包工頭，子代理做嘢，做完將結果帶返嚟，唔污染主上下文。

我之前做分佈式系統嘅時候，都用過類似嘅「任務分發」模式。主節點負責調度，工作節點負責執行，結果整合返主節點。Claude Code 嘅子代理系統，本質上係同一個套路，只不過「節點」換成咗「代理」，「任務」換成咗「prompt」。

先睇嚇呢 6 種子代理各自做啲乜。呢啲子代理都係通過 Task 工具調用嘅，Claude 會根據任務性質自動判斷派邊個。

general-purpose 代理 —— 通用任務專家

複雜嘅多步驟研究任務派俾佢。需要綜合使用多種工具、探索多個文件嘅場景。

{
  subagent_type: 'general-purpose',
  prompt: 'Research how authentication is implemented across the codebase'
}

擁有所有工具嘅訪問權限（tools: ['*']），係最「全能」嘅代理。

Explore 代理 —— 代碼庫探索專家

你叫 Claude Code「揾嚇項目入面邊度處理咗用戶認證」，佢唔會自己一個一個文件咁翻，而係派 Explore 代理去搜。

const explorer = new ExploreAgent({
  thoroughness: 'medium',  // quick / medium / very thorough
  query: 'find authentication logic',
  targetPath: './src',
  maxResults: 50
});

三個徹底程度：quick 返回 20 個結果，medium 返回 50 個，very thorough 返回 200 個。搜完之後將文件列表、代碼片段、總結都帶返嚟。

Plan 代理 —— 軟件架構師

你叫 Claude Code「幫我設計一個用戶系統」，佢會派 Plan 代理去規劃。Plan 代理係唯讀嘅，唔可以改文件，只能分析同設計：

// Plan 代理禁用的工具
disabledTools: ['Write', 'Edit', 'MultiEdit', 'NotebookEdit']

返回嘅嘢好齊全：需求分析、架構決策、實現步驟、關鍵文件、風險評估、替代方案。

claude-code-guide 代理 —— 文檔查詢助手

回答關於 Claude Code 本身嘅問題，例如「點樣配置 MCP」、「hooks 點樣用」。

{
  subagent_type: 'claude-code-guide',
  prompt: 'How do I configure MCP servers?'
}

工具權限：['Glob', 'Grep', 'Read', 'WebFetch', 'WebSearch']，可以搜索文檔同網絡。

claude-md-guardian 代理 —— CLAUDE.md 維護者

呢個係一個特殊嘅後台代理，喺會話開始時同重大變更後自動運行，負責維護同更新 CLAUDE.md 文件。

// 自動觸發時機
- 會話開始時
- 功能完成後
- 重構後
- 新增依賴後
- 架構變更後

工具權限：['Bash', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'Skill']。

statusline-setup 代理 —— 狀態欄配置助手

配置 Claude Code 嘅狀態欄顯示設置，比較輕量。

{
  subagent_type: 'statusline-setup',
  prompt: 'Configure the status line to show token count'
}

工具權限：['Read', 'Edit']，只需要讀寫配置文件。

除咗呢 6 種可以調用嘅子代理，仲有 3 種基礎設施組件。佢哋唔係通過 Task 工具調用嘅，而係系統內部自動運行，用戶無感知。

Parallel 組件 —— 並發執行管理器

當 Claude 同時派出多個子代理時，Parallel 組件自動接管並發控制：

const pool = new AgentPool(5);  // 最多 5 個併發

// 任務有依賴關係時，自動拓撲排序
const graph = createDependencyGraph(tasks);
// 同一層並行，下一層等上一層完成

仲有重試機制、超時控制、優先級排序。呢塊設計得好似線程池。

Monitor 組件 —— 執行監控

自動追蹤所有代理嘅執行情況，收集性能指標：Token 使用、API 調用、工具延遲、成本、錯誤率。超過閾值會警報。

Resume 組件 —— 狀態恢復

自動保存代理嘅執行狀態。每個重要步驟都會儲存檢查點，出錯咗可以從檢查點恢復，唔使從頭嚟過。用戶可以通過 Task { resume: "agent-id" } 手動恢復暫停咗嘅代理。

呢啲子代理同基礎設施組件各司其職，但有個關鍵問題：佢哋點樣唔污染主上下文？

呢個係整個子代理系統最精妙嘅設計——四層上下文隔離。

第一層係繼承類型。子代理創建時，可以選擇從父代理繼承幾多上下文：

type ContextInheritanceType = 'full' | 'summary' | 'minimal' | 'isolated';

• • full：全部繼承，唔壓縮
• • summary：繼承歷史前 20 條、文件前 10 個、工具結果前 15 個，壓縮到 30000 tokens
• • minimal：只繼承最近 5 條歷史，唔繼承文件同工具結果
• • isolated：完全隔離，從零開始

大部分情況用 summary 或 minimal。子代理只需要知道「大概做緊乜」，唔需要知道所有細節。

第二層係敏感數據過濾。子代理創建時，自動過濾敏感資訊：

// 自動檢測的敏感模式
const sensitivePatterns = [
  'api_key', 'password', 'secret', 'token',
  'credentials', 'auth', 'bearer', 'private_key'
];

// 敏感文件
const sensitiveFiles = [
  '.env*', 'credentials.json', 'secrets.yaml', 'id_rsa'
];

匹配到嘅內容會被替換成 [Sensitive content filtered]。噉樣就算子代理「叛變」咗，都攞唔到敏感資訊。

我之前做多租户系統嘅時候，都用過類似嘅數據隔離策略。唔同租户嘅數據要嚴格隔離，就算代碼有 bug 都唔可以泄露。Claude Code 呢度嘅思路係一樣嘅——子代理之間默認唔信任。

第三層係Token 壓縮。子代理嘅上下文有大細限制：

// 壓縮策略
1. 對話歷史：保留最近 10 條，舊消息摘要化
2. 文件上下文：只保留最近修改的文件，超出的只保留元數據
3. 工具結果：保留最近的，超長輸出截斷（>500 字符）

第四層係沙箱隔離。每個子代理運行喺獨立嘅沙箱入面：

const sandbox = contextIsolation.createSandbox(context, agentId, {
  maxTokens: 100000,           // Token 限制
  maxFiles: 50,                // 文件數限制
  maxToolResults: 100,         // 工具結果數限制
  allowedTools: ['Glob', 'Grep', 'Read'],  // 工具白名單
});

超過限制，沙箱自動掛起。Explore 代理只能用搜索類工具，Plan 代理唔可以用寫入類工具——各自只有完成任務所需嘅最小權限。

呢四層隔離疊加起嚟，形成咗一道嚴密嘅防線。子代理做嘢嘅時候，唔會將無關資訊帶返主上下文，亦唔會越權操作。

主代理同子代理之間點樣協作？呢度有三個核心機制。

消息總線 —— 異步通信

// 點對點消息
await messageBus.send({
  from: 'explore-agent-1',
  to: 'main-agent',  // 結果返回主代理
  type: 'task:completed',
  payload: exploreResult,
  priority: 7
});

// 廣播消息
await messageBus.broadcast('agent:idle', { agentId: 'plan-1' });

// 請求-響應（帶超時）
const response = await messageBus.request(
  'plan-agent', 'plan:request', { task: '...' },
  'explore-agent', 5000  // 5 秒超時
);

消息隊列有大細限制（100 條），滿咗會刪除優先級最低嘅。呢個係防止消息堆積嘅經典做法。

共享狀態管理器 —— 同步協調

// 原子操作
const updated = sharedState.compareAndSwap('result', oldValue, newValue);

// 監聽變化
sharedState.watch('progress', (value) => {
  console.log(`Progress: ${value.percentage}%`);
});

// 分佈式鎖
const lock = await sharedState.lock('critical_section', agentId, 5000);
// ... 臨界區
sharedState.unlock(lock);

呢塊設計得好似 Redis 嘅原子操作。CAS（Compare-And-Swap）、分佈式鎖、發佈訂閲... 都係分佈式系統入面嘅經典模式。

我之前做分佈式任務調度嘅時候，都用過類似嘅設計。多個 worker 同時搶任務，用 CAS 保證只有一個可以搶到。Claude Code 呢度嘅共享狀態管理器，思路係一樣嘅。

代理協調器 —— 任務分配

// 註冊代理能力
coordinator.registerAgent({
  agentId: 'explore-1',
  type: 'explore',
  capabilities: ['search', 'analyze'],
  currentLoad: 0.3,
  status: 'idle'
});

// 分配任務（支持多種負載均衡策略）
const assignedAgent = await coordinator.assignTask(task, {
  requiredAgentType: 'explore',
  loadBalanceStrategy: 'least-busy',  // 或 round-robin / random
});

// 死鎖檢測
const deadlock = coordinator.detectDeadlock();
if (deadlock) {
  console.log('Circular dependency:', deadlock.dependencyChain);
}

協調器負責「邊個嚟做呢個嘢」。優先揀負載低嘅代理，避免某個代理被累死。仲有死鎖檢測，防止 A 等 B、B 等 A 嘅情況。

將整個子代理系統串起嚟睇：

子代理做嘢嘅時候，主代理嘅上下文唔會膨脹。子代理做完咗，佢嘅上下文就會被丟棄，只有結果被帶返嚟。

呢個就係「唔污染主上下文」嘅核心——子代理係一次性嘅，用完就掉。

仲有個細節值得一提：檢查點系統。

// 每個檢查點記錄
checkpoint: {
  step: 3,
  messages: [...],      // 該步之前的所有消息
  toolCalls: [...],     // 已執行的工具調用
  results: {...}        // 中間結果
}

// 從檢查點恢復
await stateManager.resumeFrom(checkpointId);

子代理執行嘅每個重要步驟都會儲存檢查點。如果中途死咗，可以從最近嘅檢查點恢復，唔使從頭嚟過。

我之前做長時間運行嘅批處理任務時，都用過類似嘅檢查點機制。任務可能跑幾個鐘，中途機器重啟咗唔可以全部重新嚟過，要從上次停嘅地方繼續。Claude Code 呢度嘅 Resume 組件，就係做呢樣嘢嘅。

睇完呢部分代碼，我總結一下呢套設計嘅精髓：

分層隔離 —— 四層上下文隔離，子代理只攞到需要嘅資訊
消息驅動 —— 異步通信，鬆耦合，易擴展
池化複用 —— Worker 池，避免頻繁創建銷毀嘅開銷
檢查點恢復 —— 容錯機制，死咗可以繼續嚟

呢套架構最大嘅好處係可擴展。想加一種新嘅子代理？實現接口，註冊到協調器，就搞掂咗。主代理唔需要知道子代理嘅實現細節，只需要知道「呢個類型嘅代理可以做啲乜」。

如果呢篇文章對你有幫助，歡迎點讚轉發，關注唔迷路⭐️

下一篇講擴展性系統。Commands、Plugins、Skills 呢三個模塊係點樣令 Claude Code「生出」新能力嘅？

本文基於 Claude Code 2.0.76 版本源碼分析，主要文件：src/agents/、src/tools/agent.ts 目錄。

💡 閲讀前記得關注+星標，及時獲取更新推送

「Claude Code 源碼揭秘」系列的第八篇，上一篇《Claude Code 源碼揭秘：70% 觸發壓縮、LCS 差分快照、全局/項目雙記憶 — 三層架構榨乾 200K 窗口》，說的是怎麼在有限的上下文窗口裏塞下更多信息。但還有另一個思路：把任務分出去，讓子代理用獨立的上下文幹活。

用 Claude Code 幹複雜任務的時候，你可能注意到一個現象：它會"派出"一些子任務去執行，執行完再彙總結果。

比如你讓它"分析整個代碼庫的架構"，它不會傻乎乎地把所有文件都讀進上下文，而是派一個 Explore 代理去搜索關鍵文件，搜完了把結果帶回來。

這就是子代理系統。

翻 src/agents/ 和 src/tools/agent.ts，實現了兩類東西：6 種可調用的子代理（通過 Task 工具派出去幹活）和 3 種基礎設施組件（內部自動運行）。這套設計的核心思想是：主代理當包工頭，子代理幹活，幹完把結果帶回來，不污染主上下文。

我之前做分佈式系統的時候，也用過類似的"任務分發"模式。主節點負責調度，工作節點負責執行，結果彙總回主節點。Claude Code 的子代理系統，本質上是同一個套路，只不過"節點"換成了"代理"，"任務"換成了"prompt"。

先看看這 6 種子代理各自幹什麼。這些子代理都是通過 Task 工具調用的，Claude 會根據任務性質自動判斷派哪個。

general-purpose 代理 —— 通用任務專家

複雜的多步驟研究任務派它。需要綜合使用多種工具、探索多個文件的場景。

{
  subagent_type: 'general-purpose',
  prompt: 'Research how authentication is implemented across the codebase'
}

擁有所有工具的訪問權限（tools: ['*']），是最"全能"的代理。

Explore 代理 —— 代碼庫探索專家

你讓 Claude Code "找找項目裏哪裏處理了用戶認證"，它不會自己一個個文件翻，而是派 Explore 代理去搜。

const explorer = new ExploreAgent({
  thoroughness: 'medium',  // quick / medium / very thorough
  query: 'find authentication logic',
  targetPath: './src',
  maxResults: 50
});

三個徹底程度：quick 返回 20 個結果，medium 返回 50 個，very thorough 返回 200 個。搜完了把文件列表、代碼片段、總結都帶回來。

Plan 代理 —— 軟件架構師

你讓 Claude Code "幫我設計一個用戶系統"，它會派 Plan 代理去規劃。Plan 代理是隻讀的，不能改文件，只能分析和設計：

// Plan 代理禁用的工具
disabledTools: ['Write', 'Edit', 'MultiEdit', 'NotebookEdit']

返回的東西很全：需求分析、架構決策、實現步驟、關鍵文件、風險評估、替代方案。

claude-code-guide 代理 —— 文檔查詢助手

回答關於 Claude Code 本身的問題，比如"怎麼配置 MCP"、"hooks 怎麼用"。

{
  subagent_type: 'claude-code-guide',
  prompt: 'How do I configure MCP servers?'
}

工具權限：['Glob', 'Grep', 'Read', 'WebFetch', 'WebSearch']，可以搜索文檔和網絡。

claude-md-guardian 代理 —— CLAUDE.md 維護者

這是個特殊的後台代理，在會話開始時和重大變更後自動運行，負責維護和更新 CLAUDE.md 文件。

// 自動觸發時機
- 會話開始時
- 功能完成後
- 重構後
- 新增依賴後
- 架構變更後

工具權限：['Bash', 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'Skill']。

statusline-setup 代理 —— 狀態欄配置助手

配置 Claude Code 的狀態欄顯示設置，比較輕量。

{
  subagent_type: 'statusline-setup',
  prompt: 'Configure the status line to show token count'
}

工具權限：['Read', 'Edit']，只需要讀寫配置文件。

除了這 6 種可調用的子代理，還有 3 種基礎設施組件。它們不是通過 Task 工具調用的，而是系統內部自動運行，用戶無感知。

Parallel 組件 —— 併發執行管理器

當 Claude 同時派出多個子代理時，Parallel 組件自動接管併發控制：

const pool = new AgentPool(5);  // 最多 5 個併發

// 任務有依賴關係時，自動拓撲排序
const graph = createDependencyGraph(tasks);
// 同一層並行，下一層等上一層完成

還有重試機制、超時控制、優先級排序。這塊設計得很像線程池。

Monitor 組件 —— 執行監控

自動跟蹤所有代理的執行情況，收集性能指標：Token 使用、API 調用、工具延遲、成本、錯誤率。超過閾值會告警。

Resume 組件 —— 狀態恢復

自動保存代理的執行狀態。每個重要步驟都會存檢查點，出錯了可以從檢查點恢復，不用從頭來。用戶可以通過 Task { resume: "agent-id" } 手動恢復暫停的代理。

這些子代理和基礎設施組件各司其職，但有個關鍵問題：它們怎麼不污染主上下文？

這是整個子代理系統最精妙的設計——四層上下文隔離。

第一層是繼承類型。子代理創建時，可以選擇從父代理繼承多少上下文：

type ContextInheritanceType = 'full' | 'summary' | 'minimal' | 'isolated';

• • full：全部繼承，不壓縮
• • summary：繼承歷史前 20 條、文件前 10 個、工具結果前 15 個，壓縮到 30000 tokens
• • minimal：只繼承最近 5 條歷史，不繼承文件和工具結果
• • isolated：完全隔離，從零開始

大部分情況用 summary 或 minimal。子代理只需要知道"大概在幹什麼"，不需要知道所有細節。

第二層是敏感數據過濾。子代理創建時，自動過濾敏感信息：

// 自動檢測的敏感模式
const sensitivePatterns = [
  'api_key', 'password', 'secret', 'token',
  'credentials', 'auth', 'bearer', 'private_key'
];

// 敏感文件
const sensitiveFiles = [
  '.env*', 'credentials.json', 'secrets.yaml', 'id_rsa'
];

匹配到的內容會被替換成 [Sensitive content filtered]。這樣即使子代理"叛變"了，也拿不到敏感信息。

我之前做多租户系統的時候，也用過類似的數據隔離策略。不同租户的數據要嚴格隔離，即使代碼有 bug 也不能泄露。Claude Code 這裏的思路是一樣的——子代理之間默認不信任。

第三層是Token 壓縮。子代理的上下文有大小限制：

// 壓縮策略
1. 對話歷史：保留最近 10 條，舊消息摘要化
2. 文件上下文：只保留最近修改的文件，超出的只保留元數據
3. 工具結果：保留最近的，超長輸出截斷（>500 字符）

第四層是沙箱隔離。每個子代理運行在獨立的沙箱裏：

const sandbox = contextIsolation.createSandbox(context, agentId, {
  maxTokens: 100000,           // Token 限制
  maxFiles: 50,                // 文件數限制
  maxToolResults: 100,         // 工具結果數限制
  allowedTools: ['Glob', 'Grep', 'Read'],  // 工具白名單
});

超過限制，沙箱自動掛起。Explore 代理只能用搜索類工具，Plan 代理不能用寫入類工具——各自只有完成任務所需的最小權限。

這四層隔離疊加起來，形成了一道嚴密的防線。子代理幹活的時候，不會把無關信息帶回主上下文，也不會越權操作。

主代理和子代理之間怎麼協作？這裏有三個核心機制。

消息總線 —— 異步通信

// 點對點消息
await messageBus.send({
  from: 'explore-agent-1',
  to: 'main-agent',  // 結果返回主代理
  type: 'task:completed',
  payload: exploreResult,
  priority: 7
});

// 廣播消息
await messageBus.broadcast('agent:idle', { agentId: 'plan-1' });

// 請求-響應（帶超時）
const response = await messageBus.request(
  'plan-agent', 'plan:request', { task: '...' },
  'explore-agent', 5000  // 5 秒超時
);

消息隊列有大小限制（100 條），滿了會刪除優先級最低的。這是防止消息堆積的經典做法。

共享狀態管理器 —— 同步協調

// 原子操作
const updated = sharedState.compareAndSwap('result', oldValue, newValue);

// 監聽變化
sharedState.watch('progress', (value) => {
  console.log(`Progress: ${value.percentage}%`);
});

// 分佈式鎖
const lock = await sharedState.lock('critical_section', agentId, 5000);
// ... 臨界區
sharedState.unlock(lock);

這塊設計得很像 Redis 的原子操作。CAS（Compare-And-Swap）、分佈式鎖、發佈訂閲... 都是分佈式系統裏的經典模式。

我之前做分佈式任務調度的時候，也用過類似的設計。多個 worker 同時搶任務，用 CAS 保證只有一個能搶到。Claude Code 這裏的共享狀態管理器，思路是一樣的。

代理協調器 —— 任務分配

// 註冊代理能力
coordinator.registerAgent({
  agentId: 'explore-1',
  type: 'explore',
  capabilities: ['search', 'analyze'],
  currentLoad: 0.3,
  status: 'idle'
});

// 分配任務（支持多種負載均衡策略）
const assignedAgent = await coordinator.assignTask(task, {
  requiredAgentType: 'explore',
  loadBalanceStrategy: 'least-busy',  // 或 round-robin / random
});

// 死鎖檢測
const deadlock = coordinator.detectDeadlock();
if (deadlock) {
  console.log('Circular dependency:', deadlock.dependencyChain);
}

協調器負責"誰來幹這個活"。優先選負載低的代理，避免某個代理被累死。還有死鎖檢測，防止 A 等 B、B 等 A 的情況。

把整個子代理系統串起來看：

子代理幹活的時候，主代理的上下文不會膨脹。子代理幹完了，它的上下文就被丟棄，只有結果被帶回來。

這就是"不污染主上下文"的核心——子代理是一次性的，用完就扔。

還有個細節值得一提：檢查點系統。

// 每個檢查點記錄
checkpoint: {
  step: 3,
  messages: [...],      // 該步之前的所有消息
  toolCalls: [...],     // 已執行的工具調用
  results: {...}        // 中間結果
}

// 從檢查點恢復
await stateManager.resumeFrom(checkpointId);

子代理執行的每個重要步驟都會存檢查點。如果中途掛了，可以從最近的檢查點恢復，不用從頭來。

我之前做長時間運行的批處理任務時，也用過類似的檢查點機制。任務可能跑幾個小時，中途機器重啓了不能全部重來，得從上次停的地方繼續。Claude Code 這裏的 Resume 組件，就是幹這個的。

翻完這部分代碼，我總結一下這套設計的精髓：

分層隔離 —— 四層上下文隔離，子代理只拿到需要的信息
消息驅動 —— 異步通信，松耦合，易擴展
池化複用 —— Worker 池，避免頻繁創建銷燬的開銷
檢查點恢復 —— 容錯機制，掛了能接着來

這套架構最大的好處是可擴展。想加一種新的子代理？實現接口，註冊到協調器，就完事了。主代理不需要知道子代理的實現細節，只需要知道"這個類型的代理能幹什麼"。

如果這篇文章對你有幫助，歡迎點贊轉發，關注不迷路⭐️

下一篇聊擴展性系統。Commands、Plugins、Skills 這三個模塊是怎麼讓 Claude Code "長出"新能力的？

本文基於 Claude Code 2.0.76 版本源碼分析，主要文件：src/agents/、src/tools/agent.ts 目錄。