Claude Code
源码解析

Claude Code 是 Anthropic 开源的顶级 Agent Runtime。它将 LLM、工具调用、多 Agent 协作、权限安全、Terminal UI 有机融合，构建出工业级的 AI 编程助手。本指南带你逐模块深入学习。

40+
内置工具
12
核心模块
100+
Hooks
7
Task 类型
ARCHITECTURE OVERVIEW
Terminal UI (Ink/React)
SDK / API
↓   ↓
QueryEngine · main loop (query.ts)
↓
Tool System
Agent System
Permission
↓    ↓    ↓
Task Runtime
MCP Layer
↓
AppState (Immutable Store)
Services

MODULE MAP 12个核心模块一览

Claude Code 的代码库按职责被清晰地分为12个学习单元，从底层类型定义到顶层 UI，每层都有精心设计的接口边界。

🔧
② Tool 系统
src/Tool.ts · src/tools/

所有工具的抽象基础。定义了 Tool 接口和 buildTool() 工厂函数。40+ 内置工具都实现这个接口。

TypeScript Interface Zod Schema
🔄
③ Query 引擎
src/query.ts · QueryEngine.ts

Agent 的核心循环。负责发送消息到 Claude API、处理流式响应、调度工具调用，是整个 Agent 的"心脏"。

Main Loop Streaming
🤖
④ Agent 系统
src/tools/AgentTool/

多 Agent 协作核心。支持 fork subagent、remote agent、in-process teammate，实现真正的并行 Agent 协作。

Subagent Coordinator
⚙️
⑤ Task 系统
src/Task.ts · src/tasks/

异步任务管理。7 种 TaskType（local_bash、local_agent、remote_agent 等），统一的状态机管理生命周期。

Async Runtime State Machine
📦
⑥ 状态管理
src/state/AppStateStore.ts

基于 DeepImmutable 的全局状态树。AppState 包含 settings、tasks、permissions、messages 等所有运行时状态。

Immutable React Context
🔐
⑦ 权限系统
src/utils/permissions/

多层权限守卫。从 PermissionMode（default/bypassPermissions）到工具级 checkPermissions，构建安全边界。

Security Access Control
🔌
⑧ MCP 集成
src/services/mcp/

Model Context Protocol 完整实现。动态连接 MCP 服务器、加载外部工具、管理资源，实现无限扩展能力。

MCP Protocol Dynamic Tools
🧩
⑨ 服务层
src/services/

API 调用、会话压缩、Analytics、Memory、SessionMemory 等核心服务。支持自动 compact 防止 context 溢出。

API Compact Analytics
🖥️
⑩ UI 层
src/ink/ · src/components/ · src/screens/

基于 Ink (React for Terminal) 的 TUI 框架。每个工具都有独立的 UI 组件，支持流式渲染和实时更新。

Ink React Terminal
🚀
⑪ CLI 入口
src/entrypoints/ · src/commands/

60+ CLI 命令的注册和路由。从 REPL 交互式模式到 SDK 模式，统一的命令调度层。

CLI Commands

MODULE 02 Tool 系统 — 一切工具的基石

Tool 系统是 Claude Code 最核心的设计。所有工具（Bash、FileEdit、Agent 等）都通过统一的 Tool<Input, Output, Progress> 泛型接口定义，并用 buildTool() 工厂函数构建，实现了"默认安全"的可扩展架构。

Tool 接口核心方法调用链

validateInput()
→
checkPermissions()
→
canUseTool()
→
call()
→
ToolResult<Output>
renderToolUseMessage()
+
renderToolUseProgressMessage()
+
renderToolResultMessage()
📐
Tool<Input, Output, Progress> 接口
src/Tool.ts — 核心类型定义

Tool 接口是整个系统的契约。关键设计决策：

export type Tool<
Input extends AnyObject = AnyObject,
Output = unknown,
P extends ToolProgressData = ToolProgressData,
> = {
// 身份
readonly name: string
aliases?: string[]
readonly maxResultSizeChars: number // 超限写磁盘

// 核心行为
call(args, context, canUseTool, parentMsg, onProgress?): Promise<ToolResult<Output>>
validateInput?(input, context): Promise<ValidationResult>
checkPermissions(input, context): Promise<PermissionResult>

// 特性标志
isConcurrencySafe(input): boolean // 可并发执行？
isReadOnly(input): boolean
isDestructive?(input): boolean // 不可撤销？
interruptBehavior?(): 'cancel' | 'block'

// UI 渲染（React/Ink）
renderToolUseMessage(input, options): React.ReactNode
renderToolResultMessage?(content, progress, options): React.ReactNode
renderToolUseProgressMessage?(progress, options): React.ReactNode
}
设计亮点

maxResultSizeChars：超大工具输出自动写磁盘，Claude 收到文件路径引用而非原始内容，避免 context 爆炸。
isConcurrencySafe：明确标记哪些工具可以并行运行，系统自动调度并发执行。
interruptBehavior：用户发新消息时，运行中工具是取消还是等待，工具自主声明。

🏭
buildTool() 工厂函数
Tool.ts — 默认安全原则
const TOOL_DEFAULTS = {
isEnabled: () => true,
isConcurrencySafe: () => false, // 默认不并发
isReadOnly: () => false, // 默认可写
isDestructive: () => false,
checkPermissions: () =>
Promise.resolve({ behavior: 'allow' }),
toAutoClassifierInput: () => '',
userFacingName: () => '',
}

export function buildTool<D>(def: D): BuiltTool<D> {
return { ...TOOL_DEFAULTS, ...def }
}

fail-closed 设计：默认不安全的选项（如并发）全部关闭，工具必须主动声明自己是安全的。

📋
ToolUseContext — 工具的运行环境
Tool.ts — 上下文传递

每次工具调用都携带完整的运行上下文，包含：

  • options：tools列表、model、mcpClients、thinkingConfig
  • abortController：中断控制，用户 Ctrl+C 即传播
  • getAppState/setAppState：读写全局状态
  • messages：完整对话历史
  • setToolJSX：工具可以推送自定义 UI
  • agentId：子 agent 上下文标识
  • contentReplacementState：工具结果预算控制
🗂️
40+ 内置工具清单
src/tools/ 目录
BashTool
FileReadTool
FileEditTool
FileWriteTool
GlobTool
GrepTool
AgentTool
TaskCreateTool
MCPTool
WebSearchTool
WebFetchTool
TodoWriteTool
NotebookEditTool
REPLTool
LSPTool
SkillTool

MODULE 03 Query 引擎 — Agent 的心脏

query.ts 是整个 Agent 的核心循环。它负责：构建 system prompt → 调用 Claude API（流式）→ 解析 tool_use 块 → 并发执行工具 → 收集结果 → 再次调用 API，循环直到 stop_reason = "end_turn"。

Main Loop 完整流程

用户消息进入
→
processUserInput()
→
fetchSystemPromptParts()
→
normalizeMessagesForAPI()
API call (streaming)
→
accumulate stream events
→
stop_reason?
= tool_use
→
并发执行工具
→
tool_results 追加
→
回到 API call
= end_turn
→
返回最终响应
🌊
流式处理架构
query.ts — streaming events

Claude API 以 SSE 流方式返回，query.ts 处理多种事件类型：

// StreamEvent 类型
'content_block_start' // 文本/工具块开始
'content_block_delta' // 增量内容（流式文字）
'content_block_stop' // 工具参数收集完毕
'message_delta' // stop_reason 到达
'message_stop' // 请求完成

工具调用参数通过 delta 逐字节积累，完整接收后才执行工具——这意味着 UI 可以实时展示"正在生成参数"。

⚡
并发工具执行
query.ts — concurrency control

当 Claude 一次性输出多个 tool_use 块，系统根据 isConcurrencySafe() 决定执行策略：

  • 所有工具都是 concurrencySafe → 全部并发执行
  • 存在非并发安全工具 → 串行执行
  • 混合情况 → 按依赖关系调度
例子

FileReadTool 是并发安全的（只读），BashTool 默认不是（可能修改文件系统状态）。

🗜️
Auto Compact
services/compact/ — context 管理

当 context window 接近上限时，系统自动压缩历史：

  • calculateTokenWarningState() 监控 token 用量
  • 触发 compact → 调用专用 LLM 总结历史消息
  • 保留关键 tool_use 边界，插入 CompactBoundaryMessage
  • 支持 reactive（实时）和 post-turn 两种模式
📝
QueryEngine — SDK 模式入口
src/QueryEngine.ts

QueryEngine 是在 SDK 模式（非交互式）下使用的高层封装，额外处理：

  • Session 持久化和恢复
  • 结构化输出（SDKMessage 流）
  • 重试逻辑（categorizeRetryableAPIError）
  • Cost tracking 和 usage 统计
  • Transcript 记录（sessionStorage）

MODULE 04 Agent 系统 — 多 Agent 协作

Claude Code 支持递归的多 Agent 架构。主 Agent 可以通过 AgentTool 启动子 Agent，子 Agent 可以继续启动孙 Agent，形成任意深度的 Agent 树。同时支持 Coordinator Mode（蜂群模式）实现真正的并行协作。

Agent 层级关系

Main Agent (REPL / QueryEngine)
↓ AgentTool.call()
Local Subagent (runAgent)
|
Remote Agent (API)
|
In-Process Teammate
|
Fork Subagent (worktree)
🚀
runAgent() — 子 Agent 核心
tools/AgentTool/runAgent.ts

每个子 Agent 都有完整隔离的上下文：

// createSubagentContext() 关键设计
{
agentId: AgentId, // 唯一 ID
setAppState: /* no-op */, // 隔离状态
setAppStateForTasks: /* root */, // 共享任务
messages: [], // 独立历史
readFileState: clone(), // 克隆缓存
}

子 agent 的 setAppState 是 no-op，防止状态污染主线程，但 setAppStateForTasks 打通到根 store，实现 Task 共享。

🌿
Fork Subagent — Git Worktree
tools/AgentTool/forkSubagent.ts

Fork Agent 在独立的 git worktree 中运行，实现真正的文件系统隔离：

  • 创建临时 git worktree（独立分支）
  • 子 Agent 在 worktree 中自由修改文件
  • 完成后 hasWorktreeChanges() 检测差异
  • 主 Agent 决定是否合并变更
🐝
Coordinator Mode (蜂群)
src/coordinator/coordinatorMode.ts

Coordinator Mode 是 Claude Code 的并行协作模式：

  • 一个 Coordinator Agent 负责分解任务
  • 多个 Worker Agent 并行执行子任务
  • Worker 完成后 Coordinator 汇总结果
  • 通过 useSwarmInitialization hook 初始化
👥
In-Process Teammate
tasks/InProcessTeammateTask/

Teammate 是 UI 可见的长期 Agent 协作者：

  • 在主进程内运行（同一 Node.js 线程）
  • 用户可以在 UI 切换查看 Teammate 的对话
  • 通过 Mailbox（消息队列）与主 Agent 通信
  • 使用 getParentSessionId() 关联父会话
🤖
内置 Agent 类型
tools/AgentTool/built-in/ · loadAgentsDir.ts

Claude Code 预置了多种专用 Agent，同时支持从 .claude/agents/ 目录加载用户自定义 Agent：

generalPurpose
explore
shell
browser-use
docs-researcher
best-of-n-runner
关键设计

filterAgentsByMcpRequirements()：只列出满足 MCP 服务器前置条件的 Agent。ONE_SHOT_BUILTIN_AGENT_TYPES：标记只能运行一次的内置 Agent 类型。

MODULE 05 Task 系统 — 异步任务管理

Task 系统管理所有长期运行的异步操作。每个 Task 都有独立 ID、输出文件、状态机，支持后台运行、进度推送、优雅终止。

📊
7 种 TaskType
Task.ts — 类型系统
type TaskType =
| 'local_bash' // b前缀 Shell命令
| 'local_agent' // a前缀 本地子Agent
| 'remote_agent' // r前缀 远程Agent
| 'in_process_teammate' // t前缀
| 'local_workflow' // w前缀
| 'monitor_mcp' // m前缀 MCP监控
| 'dream' // d前缀 自主任务

Task ID 格式：前缀字母 + 8位随机字符，如 b3f7a2k1（bash task），确保类型可从 ID 识别。

⚡
状态机
Task.ts — lifecycle
pending
→
running
→
completed
↘
failed
↘
killed

isTerminalTaskStatus() 判断终态（completed/failed/killed），防止向死亡 Task 注入消息。

💾
磁盘输出流
utils/task/diskOutput.ts

每个 Task 都有专属输出文件（outputFile），关键设计：

  • outputOffset：记录已读取位置，支持增量读取
  • TaskOutput 类管理文件读写
  • UI 轮询 outputOffset 展示实时输出
  • 磁盘文件确保进程崩溃后可恢复
🐚
LocalShellTask
tasks/LocalShellTask/

管理后台运行的 Shell 命令。BashTool 超时后自动转为后台 Task：

  • spawnShellTask()：启动后台命令
  • registerForeground()：主动转前台
  • backgroundExistingForegroundTask()：转后台
  • ASSISTANT_BLOCKING_BUDGET_MS = 15000ms 超限自动后台化

MODULE 06 状态管理 — 不可变全局状态树

AppState 是整个应用的唯一真相来源。基于 DeepImmutable 类型包装，通过 store.setState() 的函数式更新模式，配合 React Context 分发到所有组件。

🗃️
AppState 完整结构
state/AppStateStore.ts
type AppState = DeepImmutable<{
// 核心配置
settings: SettingsJson
mainLoopModel: ModelSetting
toolPermissionContext: ToolPermissionContext

// 运行时状态
messages: Message[]
tasks: Map<string, TaskState>
mcpClients: MCPServerConnection[]
loadedPlugins: LoadedPlugin[]
agentDefinitions: AgentDefinitionsResult

// UI 状态
expandedView: 'none' | 'tasks' | 'teammates'
verbose: boolean
speculationState: SpeculationState // 预测执行

// 高级特性
fileHistoryState: FileHistoryState
attributionState: AttributionState
todoList?: TodoList
}>
⚡
SpeculationState — 预测执行
高级特性

Speculation 是 Claude Code 独特的性能优化：在用户还在思考时，系统预测下一步操作并提前执行：

  • status: 'active' 时记录预测消息和写入路径
  • writtenPathsRef 追踪覆盖写的文件（Overlay）
  • 用户确认后直接应用，无需等待 LLM 重跑
  • timeSavedMs 记录节省的时间
🔄
Store 模式
state/store.ts

类 Zustand 的自定义 Store 实现：

// 函数式更新（不可变）
store.setState(prev => ({
...prev,
verbose: true
}))

// React 订阅
useSyncExternalStore(
store.subscribe,
store.getState
)

所有状态更新通过纯函数 (prev) => next 进行，配合 DeepImmutable 彻底杜绝意外突变。

MODULE 07 权限系统 — 多层安全防护

Claude Code 的权限系统是业界最复杂的 Agent 权限架构之一。从全局 PermissionMode 到单次工具调用，经历多层检查，确保用户始终掌控 AI 的行为边界。

权限检查链路

PermissionMode 全局模式
→
alwaysAllowRules / alwaysDenyRules
→
validateInput()
checkPermissions()
→
PreToolUse Hook
→
Auto Classifier
→
用户确认 UI
🔑
PermissionMode 三种模式
utils/permissions/PermissionMode.ts
type PermissionMode =
| 'default' // 正常询问
| 'bypassPermissions' // 完全信任
| 'plan' // 只规划不执行

Plan Mode：EnterPlanModeTool 激活，模型只能规划，所有写操作被阻止。ExitPlanModeTool 允许模型主动退出。

bypassPermissions：需要 isBypassPermissionsModeAvailable 开关，且有环境变量守卫。

📏
规则引擎
ToolPermissionContext

三张规则表按优先级生效：

  • alwaysDenyRules（最高优先）：永远拒绝
  • alwaysAllowRules：永远允许，跳过确认
  • alwaysAskRules：强制每次询问

规则按 source 分组（user、project、enterprise），企业规则不可被用户覆盖。

🔒
DenialTracking
utils/permissions/denialTracking.ts

拒绝次数跟踪，防止 Agent 无限重试被拒绝的操作：

  • 累计拒绝次数超过阈值 → 回退到提示模式
  • 异步子 Agent 有独立的 localDenialTracking
  • 防止主线程状态无法更新的情况下计数丢失
🤖
Auto Classifier
Auto Mode 安全分类

Auto Mode 下，每个工具调用由 LLM 分类器评估安全性：

  • toAutoClassifierInput()：工具生成分类器输入
  • 分类器返回 allow/deny/ask
  • 安全相关工具必须实现此方法（否则 skip）
  • awaitAutomatedChecksBeforeDialog：先等分类器再弹窗

MODULE 08 MCP 集成 — 无限扩展能力

Model Context Protocol (MCP) 是 Claude Code 的扩展机制。通过动态连接 MCP 服务器，Claude Code 可以获得任意新工具、资源和能力，实现真正的"插件化 Agent"。

🔌
MCPServerConnection
services/mcp/types.ts

每个 MCP 服务器连接包含：

  • 连接状态（connecting/connected/failed）
  • 工具列表（动态加载到 Tools）
  • 资源列表（ServerResource[]）
  • 权限作用域（ScopedMcpServerConfig）
// connectToServer() 流程
getMcpConfigByName() → 读取配置
connectToServer() → 建立连接
fetchToolsForClient() → 加载工具
→ 工具注入 ToolUseContext.options.tools
📦
MCPTool — 动态工具包装
tools/MCPTool/

每个 MCP 外部工具被包装为 Claude Code 内部 Tool：

  • 工具名格式：mcp__服务名__工具名
  • inputJSONSchema 直接使用 MCP 服务器提供的 schema
  • shouldDefer：大量 MCP 工具通过 ToolSearch 延迟加载
  • alwaysLoad：标记为始终加载（不延迟）
📚
MCP Resources
tools/ListMcpResourcesTool · ReadMcpResourceTool

MCP 资源是只读的数据源，Claude 可以读取：

  • ListMcpResourcesTool：列出所有可用资源
  • ReadMcpResourceTool：按 URI 读取资源内容
  • 资源通过 mcpResources Map 缓存在 ToolUseContext
🔍
ToolSearchTool — 延迟加载
tools/ToolSearchTool/

当 MCP 工具太多时，ToolSearch 实现按需加载：

  • shouldDefer = true 的工具不出现在初始 prompt
  • Claude 通过 ToolSearch 搜索找到工具
  • searchHint：工具提供关键词供搜索匹配
  • 避免 context 被大量工具 schema 占满
🔐
MCP Auth & Elicitation
tools/McpAuthTool · elicitationHandler.ts

MCP 服务器的认证和交互协议：

  • ElicitRequestURLParams：服务器请求用户输入 URL
  • handleElicitation：SDK 模式直接处理，REPL 模式走 UI 队列
  • McpAuthTool：触发 OAuth 等认证流程
  • 错误码 -32042：触发 elicitation 流程

MODULE 09 服务层 — 核心基础设施

services/ 目录包含支撑整个系统运行的基础服务：API 调用、会话压缩、Analytics、内存管理、插件系统等。这些服务通过 ToolUseContext 注入，对工具和 Agent 透明可用。

🌐
API 层
services/api/claude.ts

Claude API 调用的完整封装：

  • accumulateUsage()：token 用量累计
  • withRetry()：指数退避重试
  • categorizeRetryableAPIError()：错误分类
  • dumpPrompts：调试模式保存完整请求
  • Upstream Proxy 支持（企业部署）
🗜️
Compact 服务
services/compact/

会话历史压缩，防止 context 溢出：

  • autoCompact：监控 token 用量自动触发
  • reactiveCompact：实时压缩（feature flag）
  • contextCollapse：上下文折叠（feature flag）
  • buildPostCompactMessages()：生成压缩后消息序列
📊
Analytics
services/analytics/

基于 GrowthBook 的特性开关和事件追踪：

  • logEvent()：带类型安全的埋点（路径/代码不得入参）
  • getFeatureValue_CACHED_MAY_BE_STALE()：Feature Flags
  • 所有 analytics 参数类型：AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS — 强制命名约定防止敏感信息泄露
🧠
SessionMemory & Memory
services/SessionMemory/ · memdir/

多层记忆系统：

  • CLAUDE.md：项目级记忆文件（memdir）
  • SessionMemory：会话内动态记忆提取
  • nestedMemoryAttachments：子目录 CLAUDE.md 自动注入
  • extractMemories：AI 自动提取重要信息存档
🧩
Plugin 系统
services/plugins/ · src/plugins/

可扩展的插件架构：

  • builtinPlugins.ts：内置插件列表
  • pluginLoader.ts：动态加载外部插件
  • 插件可注册新工具、新命令、新 Hooks
  • isRestrictedToPluginOnly：企业插件安全策略
📡
AgentSummary & PromptSuggestion
services/AgentSummary/ · PromptSuggestion/

增强用户体验的辅助 AI 服务：

  • AgentSummary：子 Agent 完成后自动生成摘要
  • PromptSuggestion：实时建议下一步操作
  • awaySummary：后台任务完成通知摘要
  • 均为独立的 LLM 调用（轻量模型）

MODULE 10 UI 层 — Terminal UI 框架

Claude Code 使用 Ink（React for Terminal）构建 TUI。每个工具都有独立的 React 组件负责渲染，支持流式渲染、实时进度、虚拟滚动等高级特性。

🖥️
Ink 架构
src/ink/ · src/main.tsx

Ink 将 React 组件渲染到 Terminal：

  • ink.ts：Ink 实例管理（render/unmount）
  • main.tsx（803KB!）：REPL 主组件，汇聚所有 hooks
  • 支持完整的 React 生命周期和 hooks
  • useVirtualScroll：大消息列表虚拟滚动
🎭
Tool UI 模式
每个 Tool 目录的 UI.tsx

每个工具实现完整的渲染生命周期：

// 工具执行前
renderToolUseMessage() // 展示调用意图
// 工具执行中
renderToolUseProgressMessage() // 实时进度
renderToolUseQueuedMessage() // 排队等待
// 工具执行后
renderToolResultMessage() // 结果展示
renderToolUseRejectedMessage() // 被拒绝
renderToolUseErrorMessage() // 错误信息
🎯
Screens
src/screens/

多个全屏视图，通过键盘切换：

  • REPL 主界面（对话流）
  • Tasks Panel（后台任务列表）
  • Teammates Panel（Agent 协作视图）
  • Message Selector（历史消息跳转）
🔤
输入系统
src/hooks/useTextInput.ts

功能丰富的终端输入处理：

  • useVimInput：完整的 vim 模式支持
  • useArrowKeyHistory：命令历史（上下箭头）
  • useHistorySearch：Ctrl+R 历史搜索
  • usePasteHandler：图片粘贴支持
  • useTypeahead：实时补全建议

MODULE 11 CLI 入口 — 命令系统

Claude Code 提供 60+ 个 CLI 命令，覆盖从日常开发到高级 Agent 功能的一切场景。命令通过统一的注册机制接入 REPL，斜杠命令在对话中直接可用。

📂
命令分类
src/commands/ — 60+ 命令
/init
/config
/memory
/commit
/pr
/review
/agent
/resume
/tasks
/mcp
/login
/compact
/export
/voice
/share
/model
/plan
/permissions
🚪
Entrypoints
src/entrypoints/

多种运行模式的入口：

  • REPL 模式：交互式对话（默认）
  • Print 模式：单次查询 + 输出
  • SDK 模式：程序化调用 QueryEngine
  • agentSdkTypes：SDKMessage / SDKStatus 类型
🏗️
Bootstrap
src/bootstrap/

启动初始化流程：

  • getSessionId()：会话 UUID 管理
  • getProjectRoot()：项目根目录检测
  • isSessionPersistenceDisabled()：持久化开关
  • 状态恢复（teleport/resume 功能）

MODULE 12 设计精髓 — 顶级 Agent 的工程智慧

总结 Claude Code 源码中最值得学习的工程设计模式和架构决策。这些是把一个"会用 LLM"的玩具变成"工业级 Agent Runtime"的关键。

🎯
1. Fail-Closed 默认原则
TOOL_DEFAULTS 设计

所有工具默认：不并发、不只读、不可绕过权限。工具必须主动声明安全特性。这确保新工具在默认情况下是安全的，必须显式"解锁"能力。

学习要点

安全系统的最佳实践：白名单优于黑名单，显式优于隐式。

📐
2. 类型安全的 API 边界
DeepImmutable + Zod + TypeScript

三层类型保护：Zod 验证输入 schema → DeepImmutable 防止状态突变 → TypeScript 编译期检查。Analytics 参数类型名 AnalyticsMetadata_I_VERIFIED... 把审查要求编码进类型系统。

🗂️
3. Context 传递模式
ToolUseContext 设计

ToolUseContext 是一个"运行时宇宙"，包含所有工具需要的一切。通过显式传递而非全局变量，使每次工具调用都是可测试、可追踪的。子 Agent 通过 createSubagentContext() 克隆并覆盖关键字段。

💾
4. 大输出磁盘化
maxResultSizeChars 机制

当工具输出超过 maxResultSizeChars 时，自动写入磁盘并返回文件路径引用。Claude 按需读取，永不因大输出撑爆 context window。这是 Agent 在实际工程中必须解决的问题。

⚡
5. Speculation 预测执行
SpeculationState 设计

在用户输入时预测 Claude 的下一步工具调用，提前执行，用户确认后立即应用。通过 Overlay 文件系统避免预测错误污染真实状态。将感知延迟降低数秒。

🔀
6. 分层 Agent 隔离
createSubagentContext 模式

子 Agent 的 setAppState 是 no-op（防止状态污染），但 setAppStateForTasks 打通到根 Store（任务共享）。这种"选择性穿透"是多层 Agent 系统状态管理的精妙解法。

🔒
7. 中断传播机制
AbortController 链式传播

每个工具调用都携带 AbortController。用户 Ctrl+C 触发根 controller 中止，信号通过 context 链式传播到所有正在运行的工具和子 Agent，实现优雅取消。

🎨
8. UI 与逻辑解耦
Tool 接口的 render 分离

工具的执行逻辑（call()）和 UI 渲染（renderToolResultMessage()）完全分离。SDK 模式跳过所有渲染方法，REPL 模式使用完整 UI。同一份工具逻辑，两种消费方式。

LEARNING PATH 推荐学习顺序

  • 第1步：读 Tool.ts — 理解工具接口契约，这是理解一切的基础
  • 第2步：读 query.ts 前200行 — 理解 Agent 主循环如何运转
  • 第3步：读 tools/BashTool/BashTool.tsx — 看最核心工具的完整实现
  • 第4步：读 state/AppStateStore.ts — 理解全局状态的结构
  • 第5步：读 tools/AgentTool/runAgent.ts — 理解子 Agent 如何创建和运行
  • 第6步：读 utils/permissions/ — 理解权限系统的完整链路
  • 第7步：读 services/mcp/client.ts — 理解 MCP 动态工具加载
  • 第8步：读 services/compact/autoCompact.ts — 理解 context 管理
  • 第9步：尝试自己写一个工具，用 buildTool() 实现完整接口
  • 第10步：用 Claude Code SDK 模式调用 QueryEngine，跟踪完整调用链
模块 1 / 12
← 上一节
下一节 →