从 Claude Code 源码出发,拆解生产级 AI Agent 的核心架构设计
Claude Code 是 Anthropic 推出的终端原生 AI Agent。它不是简单的"对话封装",而是一个完整的终端 Agent 框架——核心是思考→行动→观察的循环(Reasoning → Acting → Observing),围绕这个循环构建了工具系统、权限模型、上下文管理、多 Agent 协调等完整基础设施。
本文档将逐一拆解每个核心子系统,说明它们存在的理由、内部设计、以及你如何在自己的 Agent 中复现这些模式。
搭建 Agent 第一步不是写 UI,不是设计工具,而是确定循环。它是 Agent 的"操作系统",其他所有系统都挂在这个循环上。
Agent Loop 是一个思考→行动→观察的迭代过程:
Claude Code 的实现分为两个层次:
你的最小实现应该包含以下核心结构:
// 最小 Agent Loop 骨架
class AgentLoop {
// 单次查询:构建上下文 → 调用 LLM → 处理工具 → 返回结果
async query(context: ToolUseContext): Promise<AgentResult> {
// 1. 构建系统提示
const systemPrompt = await this.buildSystemPrompt(context)
// 2. 调用 LLM(流式)
const response = await this.callLLM(systemPrompt, context.messages)
// 3. 处理流式事件
for await (const event of response) {
if (event.type === 'text') this.handleText(event)
if (event.type === 'tool_use') {
// 4. 执行工具
const result = await this.executeTool(event, context)
context.messages.push(result)
// 5. 循环 — 把结果送回 LLM
return this.query(context) // 递归继续
}
if (event.type === 'end_turn') break
}
return { messages: context.messages }
}
// 工具执行
async executeTool(toolUse, context) {
// 权限检查 → 执行 → 返回结果
const tool = this.toolRegistry.get(toolUse.name)
await this.permissionCheck(tool, toolUse.input)
return await tool.execute(toolUse.input)
}
}
Claude Code 有一个精巧的 token 预算系统:
// query/tokenBudget.ts
class TokenBudgetTracker {
continuationCount: number // 当前轮的恢复次数
lastDeltaTokens: number // 最后一块的 token 数
lastGlobalTurnTokens: number // 全局累计
startedAt: number // 开始时间
// 检查是否需要继续
checkTokenBudget(
agentId: string | undefined,
budget: number | null, // --max-turn-budget
globalTurnTokens: number // 当前已消耗的 token 数
): 'continue' | 'stop' {
// 1. 收益递减检测:最后一块少于 500 tokens 时停止
// 2. 预算检查:超过 max-turn-budget 时停止
// 3. 完成度检查:达到 COMPLETION_THRESHOLD (90%) 时停止
}
}
Claude Code 返回的响应中可能包含多个 tool_use 块。如何高效执行这些工具是一个关键的性能优化点。
Claude Code 的 StreamingToolExecutor 将工具分为两类:
// 1. 并发安全工具 — 可同时执行
// Glob、Grep、FileRead、WebFetch、WebSearch 等只读操作
// 这些工具互不干扰,可以并行运行
// 2. 独占工具 — 一次只能执行一个
// Bash、FileEdit、FileWrite 等写操作
// 同时执行可能产生竞态
// 执行策略:
// ┌─────────┐ ┌─────────┐ ┌─────────┐
// │ Glob │ │ Grep │ │ Read │ ← 并发安全,同时运行
// └─────────┘ └─────────┘ └─────────┘
// ┌──────────┐
// │ Bash │ ← 独占,等前面的并发工具完成后再执行
// └──────────┘
// ┌──────────┐
// │ Edit │ ← 独占,串行执行
// └──────────┘
// StreamingToolExecutor
class StreamingToolExecutor {
private tools: TrackedTool[] = []
// 子 abortController — 当兄弟工具失败时杀死它
private siblingAbortController: AbortController
// 添加工具到队列
addTool(block: ToolUseBlock, assistantMessage: AssistantMessage): void {
// 判断是否并发安全
const isConcurrencySafe = toolHasTag(toolDefinition, 'concurrency-safe')
// 如果可以立即执行,直接启动
if (this.canStartExecution(tool)) {
this.executeTool(tool)
}
}
// 是否可以开始执行
private canStartExecution(tool: TrackedTool): boolean {
if (tool.isConcurrencySafe) {
// 并发安全工具:只要没有正在执行的独占工具
return !this.hasRunningExclusiveTool()
} else {
// 独占工具:没有正在执行的任何工具
return this.tools.every(t => t.status !== 'executing')
}
}
// 获取剩余结果(阻塞等待所有工具完成)
async getRemainingResults(): Promise<MessageUpdate> {
// 按工具原始顺序返回结果
// 并发安全工具的结果可能乱序完成,但返回时保证顺序
}
// 放弃所有待处理和正在执行的工具(fallback 时调用)
discard(): void {
// 待启动的不会启动,正在执行的收到 synthetic error
}
}
// 工具执行的每个阶段都发出进度事件
// 用户可以在终端看到实时状态
事件流:
queued → 工具加入队列等待执行
executing → 开始执行(显示 spinner)
progress → 执行中的增量输出(Bash 的 stdout)
completed → 执行完成
yielded → 被放弃(discard)
// 长时间运行的工具(Bash)
// 每行输出都作为 ProgressMessage 流式显示
// 用户可以实时看到命令的输出
工具是 Agent 与外部世界交互的接口。Claude Code 的工具系统设计非常精巧,值得深入学习。
Claude Code 中每个工具是独立目录,包含 4 个标准文件:
tools/BashTool/ ← 实际有 18 个文件
├── BashTool.tsx ← 工具定义 (Schema, isEnabled, 权限)
├── prompt.ts ← 系统提示词片段(告诉 LLM 怎么用)
├── UI.tsx ← Ink 终端渲染组件
├── bashSecurity.ts ← 安全校验逻辑(tree-sitter 解析)
├── bashPermissions.ts ← 权限规则匹配(通配符、前缀)
├── commandSemantics.ts ← 命令语义分析(只读 vs 写入)
├── readOnlyValidation.ts ← 只读模式验证
├── sedEditParser.ts ← sed 命令解析(检测文件修改)
├── sedValidation.ts ← sed 命令安全验证
├── shouldUseSandbox.ts ← 是否启用沙箱执行
├── destructiveCommandWarning.ts ← 危险命令警告
├── pathValidation.ts ← 路径穿越防护
├── modeValidation.ts ← 权限模式验证
├── toolName.ts ← 工具名常量
├── utils.ts ← 工具函数
├── bashCommandHelpers.ts ← 命令辅助
├── commentLabel.ts ← 注释标签
└── BashToolResultMessage.tsx ← 结果消息渲染
每个工具需要定义以下核心接口:
// Tool.ts — 工具完整类型定义(源码中有 30+ 个方法/属性)
interface Tool<TInput extends AnyObject, TOutput, TProgress extends ToolProgressData> {
// ═══ 元数据 ═══
name: string // 工具名(LLM 调用的 key)
aliases?: string[] // 别名(重命名兼容,如 'KillShell' → 'TaskStop')
searchHint?: string // ToolSearch 关键词(3-10 词)
readonly inputSchema: TInput // Zod Schema
inputJSONSchema?: ToolInputJSONSchema // MCP 工具直接用 JSON Schema
outputSchema?: z.ZodType // 输出 Schema(可选)
maxResultSizeChars: number // 结果大小上限(超过则持久化到磁盘)
readonly strict?: boolean // 严格模式(API 更严格遵循 Schema)
readonly shouldDefer?: boolean // 延迟加载(ToolSearch 模式)
readonly alwaysLoad?: boolean // 始终加载(不被 defer)
isMcp?: boolean // 是否 MCP 工具
isLsp?: boolean // 是否 LSP 工具
mcpInfo?: { serverName: string; toolName: string } // MCP 服务端信息
// ═══ 生命周期 ═══
isEnabled(): boolean // 当前环境是否可用
isConcurrencySafe(input): boolean // 是否并发安全(只读=true)
isReadOnly(input): boolean // 是否只读操作
isDestructive?(input): boolean // 是否破坏性操作(删除、覆盖)
// ═══ 权限 ═══
checkPermissions(input, context): Promise<PermissionResult>
preparePermissionMatcher?(input): Promise<(pattern: string) => boolean>
// ═══ 输入处理 ═══
validateInput?(input, context): Promise<ValidationResult>
backfillObservableInput?(input: Record<string, unknown>): void // 给 hooks 回填字段
inputsEquivalent?(a, b): boolean // 输入等价判断
// ═══ 执行 ═══
call(input, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<TOutput>>
interruptBehavior?(): 'cancel' | 'block' // 用户中断时的行为
// ═══ 提示词 ═══
description(input, options): Promise<string> // 动态描述
prompt(options): Promise<string> // 系统提示词片段
// ═══ UI 渲染 ═══
renderToolUseMessage(input, options): React.ReactNode
renderToolResultMessage?(content, progress, options): React.ReactNode
renderToolUseProgressMessage?(progress, options): React.ReactNode
renderToolUseRejectedMessage?(input, options): React.ReactNode
renderToolUseErrorMessage?(result, options): React.ReactNode
renderGroupedToolUse?(toolUses, options): React.ReactNode | null
userFacingName(input): string
userFacingNameBackgroundColor?(input): keyof Theme | undefined
getToolUseSummary?(input): string | null
getActivityDescription?(input): string | null
renderToolUseTag?(input): React.ReactNode
// ═══ 搜索与分类 ═══
isSearchOrReadCommand?(input): { isSearch: boolean; isRead: boolean; isList?: boolean }
isOpenWorld?(input): boolean
isTransparentWrapper?(): boolean
isResultTruncated?(output): boolean
extractSearchText?(out): string
toAutoClassifierInput(input): unknown // Auto 模式分类器输入
mapToolResultToToolResultBlockParam(content, toolUseID): ToolResultBlockParam
}
Claude Code 使用动态工具组装,不是硬编码列表:
// tools.ts — 工具注册表
// 1. 所有基础工具(构建时的完整列表)
function getAllBaseTools(): Tools {
return [
AgentTool,
BashTool,
FileEditTool,
FileReadTool,
FileWriteTool,
GlobTool,
GrepTool,
WebFetchTool,
WebSearchTool,
// ... ~40 个工具
// 条件性加入(Feature Flag 在构建时消除)
...(feature('PROACTIVE') ? [SleepTool] : []),
...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ExitWorktreeTool] : []),
]
}
// 2. 按权限过滤
function getTools(permissionContext): Tools {
const tools = getAllBaseTools()
return filterToolsByDenyRules(tools, permissionContext)
}
// 3. 合并 MCP 外部工具
function assembleToolPool(permissionContext, mcpTools): Tools {
const builtIn = getTools(permissionContext)
const allowedMcp = filterToolsByDenyRules(mcpTools, permissionContext)
// 内置工具优先,MCP 工具排序在后(prompt cache 稳定性)
return uniqBy(
[...builtIn].sort(byName).concat(allowedMcp.sort(byName)),
'name'
)
}
Claude Code 使用 Zod v4 定义工具输入 Schema,自动生成 JSON Schema 供 LLM 调用:
// 工具 Schema 示例 — BashTool
const BashInputSchema = z.object({
command: z.string().describe('The command to execute'),
description: z.string().optional()
.describe('Brief description of what this command does'),
is_background: z.boolean().optional()
.default(false)
.describe('Run in background'),
wait: z.string().optional()
.describe('Wait for a specific string in output'),
})
// 在工具定义中使用
class BashTool implements Tool<typeof BashInputSchema> {
parameters = zodToJsonSchema(BashInputSchema)
}
LLM 返回 tool_use 块
│
├─ 1. 查找工具定义
│ └─ toolRegistry.get(toolName)
│
├─ 2. Schema 验证
│ └─ Zod 校验输入参数
│
├─ 3. 权限检查(见下一节)
│
├─ 4. 执行
│ └─ tool.execute(input) → 输出流式事件
│
├─ 5. 结果显示
│ └─ tool.renderToolResultUseMessage(input) → React Node
│
└─ 6. 结果裁剪(大结果时)
└─ applyToolResultBudget() → 截断/压缩
当工具结果太大时,Claude Code 不会直接丢弃,而是按工具类型分策略处理:
这是 MicroCompact(微压缩)策略的一部分——在每次工具调用后检查。
系统提示词是 Agent 行为的"基因"——它决定了 Agent 的性格、能力边界和判断标准。Claude Code 的系统提示词非常复杂,由 10+ 个独立模块组装而成,每个模块负责不同的职责。
// Claude Code 的系统提示词组装流程
// 总共 ~15,000+ tokens,分为以下模块:
┌─────────────────────────────────────────────────────┐
│ 系统提示词 │
│ │
│ 1. 角色定义 (Intro) │
│ "You are an interactive agent that helps │
│ users with software engineering tasks."
│ │
│ 2. 网络安全指令 (Cyber Risk) │
│ "Do not generate malicious code..."
│ │
│ 3. 系统行为说明 (System) │
│ "All text you output is displayed to the user..."
│ "Tools are executed in a user-selected │
│ permission mode..."
│ │
│ 4. 执行行为指南 (Doing Tasks) │
│ "Don\'t add features beyond what was asked..."
│ "Be careful not to introduce security │
│ vulnerabilities..."
│ │
│ 5. 行动谨慎指南 (Actions) │
│ "Carefully consider the reversibility..."
│ "Only take risky actions carefully..."
│ │
│ 6. 工具使用指南 (Tools) │
│ "Prefer dedicated tools over Bash..."
│ "If you need to edit a file..."
│ │
│ 7. 子 Agent 指南 (Agent) │
│ "Sub-agents inherit the same tools..."
│ │
│ 8. 记忆系统 (Memory) │
│ "Use CLAUDE.md for persistent state..."
│ "Autosave user preferences..."
│ │
│ 9. 动态上下文 (Dynamic) │
│ "Working directory: /home/user/project"
│ "Git status: 2 files modified"
│ "MCP servers: 3 connected"
│ │
│ 10. 工具 Schema (Tool Definitions) │
│ 每个工具的 JSON Schema 描述 │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ ⚡ 缓存分界线 (Cache Boundary) │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ 11. 用户上下文 (User Context) │
│ "Preferred language: Chinese"
│ │
│ 12. 系统上下文 (System Context) │
│ "MCP server instructions..."
│ │
│ 13. 输出风格 (Output Style) │
│ "Respond in a concise style..."
│ │
└─────────────────────────────────────────────────────┘
Claude Code 在提示词中间插入了一个 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记:
// 缓存分界线的作用:
__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__
// 分界线之前的内容:
// → 跨组织缓存(scope: global)
// → 角色定义、系统说明、工具指南
// → 这些内容对所有用户都一样,可以复用缓存
// 分界线之后的内容:
// → 用户/会话级缓存(scope: session)
// → 用户上下文、MCP 指令、输出风格
// → 这些内容因用户而异,不能跨用户缓存
// 提示词组装的代码结构
async function getSystemPrompt(
tools: Tools,
mainLoopModel: string,
additionalWorkingDirectories: string[],
mcpClients: MCPServerConnection[],
): Promise<string[]> {
// 1. 获取静态部分(角色 + 行为指南)
const intro = getSimpleIntroSection()
const cyberRisk = getSimpleCyberRiskSection()
const system = getSimpleSystemSection()
const tasks = getSimpleDoingTasksSection()
const actions = getActionsSection()
const tools = getUsingYourToolsSection(enabledTools)
// 2. 注入缓存分界线
const boundary = SYSTEM_PROMPT_DYNAMIC_BOUNDARY
// 3. 获取动态部分
const memory = await loadMemoryPrompt()
const gitStatus = await getGitStatus()
const mcpInstructions = getMcpInstructions(mcpClients)
// 4. 返回数组(系统消息 = 数组拼接)
return [
intro, cyberRisk, system, tasks, actions, tools,
boundary,
memory, gitStatus, mcpInstructions,
]
}
权限系统是 Agent 安全性的基石。Claude Code 的权限设计是多层纵深防御的典范。
// 用户可设置的模式
type PermissionMode =
| 'default' // 默认:每次工具调用都询问用户
| 'plan' // 计划模式:只允许读操作(文件读取、搜索)
| 'acceptEdits' // 接受编辑:文件修改自动批准
| 'bypassPermissions' // 绕过全部:信任 Agent(危险!)
| 'dontAsk' // 不问:类似 bypass
| 'auto' // 自动审批:基于分类器判断
规则可以来自多个层级,优先级从高到低:
// 权限规则来源(按优先级排序)
type PermissionRuleSource =
| 'policySettings' // 组织策略(最高优先级)
| 'cliArg' // CLI 命令行参数
| 'userSettings' // 用户设置
| 'projectSettings' // 项目设置 (.claude/settings.json)
| 'localSettings' // 本地设置
| 'flagSettings' // 功能开关
// 每条规则决定行为
type PermissionBehavior = 'allow' | 'deny' | 'ask'
// 权限上下文 — 快照化以防止竞态
type ToolPermissionContext = {
mode: PermissionMode
alwaysAllowRules: ToolPermissionRules // 按工具名 → 参数模式映射
alwaysDenyRules: ToolPermissionRules
alwaysAskRules: ToolPermissionRules
isBypassPermissionsModeAvailable: boolean
isAutoModeAvailable?: boolean
// 后台 Agent 标记 — 无 UI 时自动拒绝
shouldAvoidPermissionPrompts?: boolean
}
// 权限检查函数
async function canUseTool(
tool: Tool,
input: unknown,
context: ToolPermissionContext
): Promise<PermissionResult> {
// 1. 检查 deny rules
const denyRule = findMatchingRule(tool.name, input, context.alwaysDenyRules)
if (denyRule) return { result: false, reason: denyRule.message }
// 2. 检查 allow rules
if (isAlwaysAllowed(tool.name, input, context)) {
return { result: true }
}
// 3. 根据 mode 处理
switch (context.mode) {
case 'plan':
return handlePlanMode(tool, input)
case 'auto':
return handleAutoMode(tool, input) // 调用分类器
case 'default':
return handleInteractivePrompt(tool, input) // 显示对话框
case 'bypassPermissions':
return { result: true }
}
}
// 拒绝追踪 — 连续拒绝时可自动拒绝同类操作
type DenialTrackingState = {
// 按工具名追踪最近 N 次拒绝
recentDenials: Map<string, Timestamp[]>
}
Plan 模式是 Claude Code 最精巧的 UX 设计之一——它让 Agent 先以只读方式探索代码库,理解上下文后,再切换到修改模式。
// 没有 Plan 模式的问题:
用户: "重构这个模块的错误处理"
Agent (直接修改):
1. 读第一个文件... 还没理解全貌
2. 就开始改了!
3. 改到一半发现架构不兼容
4. 改坏了,回滚...
// 结果:浪费时间,可能引入 bug
// 有了 Plan 模式:
用户: "重构这个模块的错误处理" (Plan 模式)
Agent (只读探索):
1. 读所有相关文件
2. grep 错误处理模式
3. 理解依赖关系
4. 输出一个详细计划
5. 用户确认后,切换到修改模式
6. 按计划精确执行
// 结果:更准确、更安全、更高效
// Plan 模式的核心:通过权限模型实现
// 1. 注册 Plan 模式的权限配置
const planPermissionMode: PermissionMode = {
name: 'plan',
// 允许的操作(只读)
autoAllow: [
'FileReadTool', // 读文件
'GlobTool', // 查找文件
'GrepTool', // 搜索内容
'BashTool[git:*]', // 只读 git 命令
'WebSearchTool', // 搜索
],
// 禁止的操作(写入)
autoDeny: [
'FileEditTool', // 编辑
'FileWriteTool', // 写入
'BashTool[rm:*]', // 删除
'BashTool[mv:*]', // 移动
],
}
// 2. 切换到 Plan 模式
// 用户可以通过 /plan 命令或 UI 按钮切换
// 切换后,Agent 的所有写入操作都会被拦截
// 3. Agent 自己也能切换
// 系统提示词告诉 Agent:
// "You are in plan mode. Read files, explore the codebase,
// but DO NOT make any changes until the user approves."
// 4. 用户确认后,退出 Plan 模式
// /plan off 或点击按钮
// Agent 按计划执行修改
Hooks 是 Claude Code 的可扩展性设计——允许用户在工具执行的各个生命周期节点注入自定义逻辑。
// Claude Code 的 Hook 系统有 4 个生命周期节点
┌─────────────────────────────────────────────────────┐
│ Hook 生命周期 │
│ │
│ 用户输入 ──→ PreToolUse ──→ 工具执行 ──→ PostToolUse │
│ │ │
│ ↓ ↓
│ PostSampling Notification
│ │
│ SessionStart ──→ 会话初始化(加载记忆、检查环境) │
└─────────────────────────────────────────────────────┘
// PreToolUse Hook
// - 工具执行前触发
// - 可以修改输入参数、阻止执行、或添加额外检查
// - 例如:检查 Bash 命令是否包含危险操作
// PostToolUse Hook
// - 工具执行后触发
// - 可以处理结果、触发后续操作、记录日志
// - 例如:Bash 执行完后,自动检查输出是否包含敏感信息
// PostSampling Hook
// - LLM 返回响应后触发(在工具执行之前)
// - 可以修改 LLM 响应、记录推理过程
// - 例如:记录 LLM 的 token 使用情况
// SessionStart Hook
// - 会话开始时触发
// - 可以初始化环境、加载配置、检查依赖
// - 例如:检查 git 状态、加载 CLAUDE.md
// Hook 注册
type HookContext = {
toolName: string
input: Record<string, unknown>
result?: unknown
messages: Message[]
systemPrompt: SystemPrompt
}
type Hook = (ctx: HookContext) => Promise<void> | void
// 注册表
const hooks = {
preToolUse: new Map<string, Hook[]>(),
postToolUse: new Map<string, Hook[]>(),
postSampling: new Map<string, Hook[]>(),
sessionStart: new Map<string, Hook[]>(),
}
// 注册 hook
hooks.preToolUse.set('BashTool', [
async (ctx) => {
if (ctx.input.command.includes('rm -rf')) {
throw new Error('危险命令被阻止')
}
}
])
// 执行 hook
async function executeHooks(phase: string, toolName: string, ctx) {
const phaseHooks = hooks[phase].get(toolName) || []
for (const hook of phaseHooks) {
await hook(ctx)
}
}
Agent 的状态管理比前端应用复杂——不仅管理 UI 状态,还要管理消息流、工具执行、MCP 连接等并发状态。
// AppStateStore.ts — 全局不可变状态
type AppState = DeepImmutable<{
// 消息系统
messages: Message[] // 对话消息(用户 + 助手 + 工具)
// 工具系统
tools: Tool[] // 可用内置工具
mcpClients: MCPServerConnection[] // MCP 连接
mcpTools: Tool[] // MCP 提供的工具
mcpResources: Record<string, Resource[]> // MCP 资源
// 权限系统
permissionContext: ToolPermissionContext // 权限上下文(快照)
// 会话
conversationId: UUID // 会话 ID
agentDefinitions: AgentDefinitionsResult // Agent 定义
agentType?: string // 当前 Agent 类型
// 生命周期
settings: SettingsJson // 用户设置
plugins: LoadedPlugin[] // 已加载插件
taskStates: Map<string, TaskState> // 后台任务
// ... 更多 ~100+ 字段
}>
// store.ts — 自定义响应式 Store
type Store<T> = {
getState: () => T // 读取快照
setState: (f: (prev: T) => T) => void // 不可变更新
subscribe: (f: () => void) => () => void // 订阅变更
}
Claude Code 的消息类型不仅仅是"用户"和"助手"——它有精细的分类:
// types/message.ts — 消息类型体系
type Message =
| UserMessage // 用户输入
| AssistantMessage // 助手回复(含 tool_use 块)
| AssistantRedactedThinkingMessage // 被隐藏的思考过程
| AssistantThinkingMessage // Extended Thinking 内容
| ToolResultMessage // 工具执行结果
| ProgressMessage // 进度更新(如 Bash 正在执行)
| SystemMessage // 系统级消息(压缩边界等)
| TombstoneMessage // 被压缩或删除的旧消息
| ToolUseSummaryMessage // 工具调用汇总
| AttachmentMessage // 附件(文件、图片)
( ˘ ³˘)♥ 好的消息类型设计让调试变简单
根据项目复杂度选择:
| 方案 | 适合场景 | 参考 |
|---|---|---|
Zustand |
中小型 Agent,快速启动 | 轻量、TypeScript 友好 |
自定义 Store + DeepImmutable |
大型 Agent,需要精细控制 | Claude Code 的方式 |
Redux Toolkit |
团队项目,需要 DevTools | 生态成熟,学习曲线高 |
Signal (Preact/Solid) |
性能敏感的 UI | 细粒度响应式更新 |
Agent 每次会话都是一段连续对话。会话结束后如何保存状态、如何恢复上下文、如何处理崩溃恢复,是生产级 Agent 必须解决的问题。
// Claude Code 使用 LRU 缓存来跟踪文件状态
// 避免重复读取同一文件,也用于检测文件是否被修改
class FileStateCache {
private cache = new Map<string, CachedFile>()
private maxSize = 1000 // 最多缓存 1000 个文件
async getFileState(path: string): Promise<FileState> {
const cached = this.cache.get(path)
if (cached) {
const stat = await fs.stat(path)
if (stat.mtimeMs === cached.mtime) {
return cached.state // 缓存有效
}
this.cache.delete(path) // 文件被修改,清除缓存
}
const content = await fs.readFile(path, 'utf-8')
const state = { content, lines: content.split('\n') }
this.cache.set(path, { mtime: stat.mtimeMs, state })
// LRU 淘汰
if (this.cache.size > this.maxSize) {
const oldest = this.cache.keys().next().value
this.cache.delete(oldest)
}
return state
}
// 工具修改文件后主动更新缓存
updateFileState(path: string, content: string): void {
this.cache.set(path, {
mtime: Date.now(),
state: { content, lines: content.split('\n') },
})
}
}
// 会话生命周期
Session {
id: string // 唯一标识
messages: Message[] // 完整对话历史
toolResults: Map<string, ToolResult> // 工具结果(可能很大)
createdAt: number
lastActiveAt: number
metadata: {
totalTokens: number // 累计 token 使用
model: string // 使用的模型
}
}
// 存储策略
// 1. 内存存储(热会话)→ 当前活跃会话,快速访问
// 2. 磁盘存储(冷会话)→ 历史会话持久化到 ~/.claude/sessions/
// 3. 崩溃恢复→ 每次 LLM 调用前保存 checkpoint,崩溃后从最近的 checkpoint 恢复
// 记忆系统:不是数据库,而是项目根目录下的 markdown 文件
// ~/.claude/CLAUDE.md → 用户级记忆(全局)
// .claude/CLAUDE.md → 项目级记忆(仅当前项目)
// .claude/CLAUDE.local.md → 本地记忆(不提交到 git)
// 记忆格式是 markdown,用户可以直接编辑
// 也可以让 Agent 自动写入
// Agent 读取时机:会话开始时自动加载,注入系统提示词
// Agent 写入时机:用户说 "remember this" 或 /memory 命令触发
LLM 上下文窗口有限(通常 200K tokens),会话一长就会溢出。上下文管理是生产级 Agent 必须解决的难题。
Claude Code 使用三级压缩,每层解决不同粒度的问题:
// context.ts — 系统提示构建
async function getSystemContext(): Promise<string> {
// 并行收集各类上下文
const [gitStatus, osInfo, claudeMds] = await Promise.all([
getGitStatus(), // Git 状态
getPlatformInfo(), // OS 信息、Shell 类型
getClaudeMds(), // CLAUDE.md 文件
])
return [
`<SystemInfo>${osInfo}</SystemInfo>`,
gitStatus ? `<GitStatus>${gitStatus}</GitStatus>` : '',
// 工具定义由 QueryEngine 自动注入
].filter(Boolean).join('\n')
}
// 工具定义的 XML 化
// 每个工具的定义被转换成 LLM 可读的 XML 格式
//
// <tool_description>
// <tool_name>Bash</tool_name>
// <description>Execute shell commands</description>
// <parameter>
// <name>command</name>
// <type>string</type>
// <required>true</required>
// <description>The command to execute</description>
// </parameter>
// ...
// 全局缓存断裂点 — 工具定义在系统提示中的位置
// claude_code_system_cache_policy 确保改动后不产生大范围缓存失效
Claude Code 使用目录化记忆:
// memdir/ — 持久化记忆目录
memdir/
├── paths.ts ← 记忆文件路径管理
├── memdir.ts ← 加载 / 存储记忆
├── item.ts ← 记忆项类型
└── ...
// 记忆自动提取
services/
└── extractMemories/
└── ... ← 在会话结束后自动提取关键信息并写入记忆
// 记忆加载
async function loadMemoryPrompt(): Promise<string> {
// 读取 memdir/ 下的所有记忆文件
// 去重 + 排序
// 拼接到系统提示中
}
// CLAUDE.md 文件
// 项目级别的记忆,位于项目根目录
// 用户手动维护或 Agent 自动更新
终端 UI 不等于简陋。Claude Code 证明了 React + Ink 可以在终端中构建复杂的交互式界面。
React 组件树 (Virtual DOM)
│
├─ Ink Reconciler (自定义)
│ └─ 将 React Fiber 映射到终端节点
│
├─ Yoga 布局引擎
│ └─ Flexbox 在终端中的布局计算
│
└─ Ink Renderer
└─ 输出 ANSI 转义序列到终端
层级:
App.tsx (根)
└─ REPL.tsx (交互主屏)
├─ VirtualMessageList.tsx (虚拟滚动)
├─ TextInput.tsx (输入框)
├─ VimTextInput.tsx (Vim 模式)
├─ PermissionDialog
├─ HelpV2.tsx (帮助面板)
└─ ... 140+ 组件
你的 Agent 至少需要这些 UI 能力:
// 1. 消息列表 — 支持虚拟滚动
// 架构: 只渲染可见区域的消息,其他只保留占位符
// 参考: VirtualMessageList.tsx
// 2. 消息渲染 — 按类型分组件
type MessageRenderer =
| AssistantTextMessage ← 纯文本回复
| AssistantThinking ← LLM 思考过程(可折叠)
| ToolUseMessage ← 工具调用(显示工具名 + 参数)
| ToolResultMessage ← 工具结果(截断显示)
| ProgressMessage ← 进度(Bash 执行中、文件上传中)
// 3. 权限对话框
// 显示工具名、参数预览、允许/拒绝按钮
// 超时后自动拒绝
// 4. 模糊搜索选择器 (FuzzyPicker)
// 用于 /mcp、/agents、/resume 等选择场景
// ⌕ 实时过滤 + 键盘导航
// 5. Diff 视图
// 文件变更的前后对比
// 最小 REPL 循环
async function replLoop() {
while (true) {
// 1. 获取用户输入
const userInput = await readLine()
// 2. 检查 Slash 命令
if (userInput.startsWith('/')) {
await executeCommand(userInput)
continue
}
// 3. 构建上下文
const messages = buildContext()
messages.push({ role: 'user', content: userInput })
// 4. 运行 Agent Loop
const result = await agentLoop.query({ messages })
// 5. 显示结果(流式)
for (const event of result.events) {
renderEvent(event)
}
}
}
Claude Code 的 /context 命令非常实用——它展示当前上下文的组成:
/context
────────────────────────────────
📋 Token 使用:
● 系统提示: 24,531 tokens
● 对话历史: 78,243 tokens
● 工具结果: 15,879 tokens
● 总计: 118,653 / 200,000 (59%)
📎 附件:
● CLAUDE.md (2,341 tokens)
● memory/default.md (1,028 tokens)
📌 注意:
● 缓存命中: 7,834 tokens 节约
● 自动压缩: 已就绪 (约 20K tokens 后触发)
当单个 Agent 不足以高效完成任务时,需要多 Agent 协作。Claude Code 设计了一套优雅的机制。
// AgentTool — 子 Agent 生成
// 当 LLM 调用 AgentTool 时,创建一个新的 Agent 会话
// forkSubagent.ts — 子 Agent 创建
async function createSubagent(params: {
prompt: string // 给子 Agent 的任务描述
tools?: string[] // 允许的工具列表
parentContext: ToolUseContext
}): Promise<AgentResult> {
// 1. 创建隔离上下文
const childContext = createSubagentContext({
...parentContext,
// 独立的中止控制器
abortController: new AbortController(),
// 共享基础设施状态(任务注册等)
setAppStateForTasks: parentContext.setAppStateForTasks,
// 独立的文件缓存
fileStateCache: cloneFileStateCache(parentContext, MAX_SIZE),
})
// 2. 过滤工具(子 Agent 只能使用部分工具)
childContext.options.tools = filterToolsForAgent(
childContext.options.tools,
params.tools // 允许的工具列表
)
// 3. 执行
return await queryEngine.query(childContext)
}
// coordinatorMode.ts — 协调者模式
function isCoordinatorMode(): boolean {
// 环境变量控制
return process.env.CLAUDE_CODE_COORDINATOR_MODE === 'true'
}
function filterToolsForCoordinator(tools: Tools): Tools {
// 协调者只持有:
// - AgentTool(生成 Worker)
// - TaskStopTool(停止任务)
// - SendMessageTool(通信)
// - SyntheticOutputTool(结构化输出)
return tools.filter(t => COORDINATOR_ALLOWED_TOOLS.has(t.name))
}
function filterToolsForWorker(tools: Tools): Tools {
// Worker 不能使用 AgentTool(不能继续分裂)
return tools.filter(t => WORKER_ALLOWED_TOOLS.has(t.name))
}
// SendMessageTool — Agent 间消息传递
// 一个 Agent 可以向另一个 Agent 或所有 Agent 广播消息
// 消息类型
type AgentMessage = {
target: 'coordinator' | 'worker:id' | 'broadcast'
content: string
attachments?: Attachment[]
}
// 通信流程
// Worker 1 ──[SendMessage("找到了 bug 在 file.ts:42 行")]──→ Coordinator
// Coordinator ──[AgentTool("修复这个 bug")]──→ Worker 2
// Worker 2 ──[SendMessage("已修复")]──→ Coordinator
// TeamCreateTool — 创建 Agent 团队
// TeamDeleteTool — 销毁 Agent 团队
// 团队 = 一组 Worker + 一个 Coordinator
// 团队支持并行执行和汇总结果
// 后端支持:
// - tmux:每个 Agent 在独立的 tmux 窗格中运行
// - InProcess:在主进程内运行(适合轻量任务)
// - iTerm:在 iTerm 分屏中运行
MCP 是 Anthropic 提出的开放协议,定义了 AI Agent 如何动态发现和调用外部工具。它是 Claude Code 可扩展性的核心。
// MCP 的核心思想:Agent 不需要预先知道所有工具
// 外部工具可以作为 MCP Server 注册到 Agent
// 架构:
┌──────────────┐ MCP Protocol ┌──────────────┐
│ │ ←──────────────→ │ MCP Server │
│ Agent (主) │ │ (外部工具) │
│ │ ←──────────────→ │ │
│ │ MCP Protocol │ MCP Server │
│ │ │ (数据库) │
│ │ ←──────────────→ │ │
│ │ MCP Protocol │ MCP Server │
│ │ │ (Slack) │
└──────────────┘ └──────────────┘
// MCP 协议定义了 3 种能力:
// 1. Tools — 可调用的工具(函数)
// 2. Resources — 可读取的资源(文件、数据)
// 3. Prompts — 可使用的提示词模板
// MCP 工具发现流程
// 1. 连接到 MCP Server
const connection = await mcpClient.connect(serverUrl)
// 2. 获取工具列表
const tools = await connection.listTools()
// 返回:
// [
// {
// name: "slack_send_message",
// description: "Send a message to a Slack channel",
// inputSchema: {
// type: "object",
// properties: {
// channel: { type: "string" },
// message: { type: "string" }
// }
// }
// },
// ...
// ]
// 3. 工具注册到 Agent 的工具池
// assembleToolPool() 会合并内置工具和 MCP 工具
// MCP 工具排序在内置工具之后(prompt cache 稳定性)
// 4. LLM 调用时,工具 Schema 自动注入到系统提示词
// Agent 不需要特殊处理,MCP 工具和内置工具一视同仁
// 5. 调用 MCP 工具
const result = await mcpClient.callTool('slack_send_message', {
channel: '#general',
message: 'Hello from Agent!'
})
// MCP Resources — 读取外部数据
// 示例:数据库 MCP Server
const resources = await mcpClient.listResources()
// [
// { uri: "db://users", name: "Users Table" },
// { uri: "db://orders", name: "Orders Table" }
// ]
// 读取资源
const data = await mcpClient.readResource('db://users')
// 返回:JSON 格式的用户数据
// Agent 可以在系统提示词中描述这些资源
// LLM 就知道可以从哪里获取数据
前面所有模块讨论的都是 Claude Code 作为终端原生 Agent 的内部设计。但在真实开发场景中,开发者大部分时间在 IDE 里工作——VS Code、JetBrains、甚至远程开发环境。Bridge 系统就是 Claude Code 与 IDE 之间的双向通信桥梁,它让 CLI Agent 的全部能力可以无缝嵌入到 IDE 的图形界面中。
Claude Code 的 Bridge 设计遵循一个核心原则:CLI 是大脑,IDE 是皮肤。CLI 进程持有完整的 Agent Loop、工具系统、权限模型;IDE 插件只负责 UI 渲染和用户交互。两者通过 JSON-RPC 协议经由 stdin/stdout 双向通信。
Bridge 系统由以下核心文件组成,每个文件负责通信链路中的一个关键环节:
bridge/
├── bridgeMain.ts ← Bridge 服务端入口(CLI 侧)
│ 启动 JSON-RPC 服务器,监听 stdin/stdout
│ 注册所有 RPC 方法(消息发送、权限确认、会话管理)
│ 管理 Bridge 生命周期(连接 → 认证 → 通信 → 断开)
│
├── bridgeMessaging.ts ← 消息传输层
│ 实现 JSON-RPC 2.0 协议的序列化/反序列化
│ 处理消息分帧(每条消息以换行符分隔)
│ 消息路由:按 method 字段分发到对应 handler
│
├── bridgePermissionCallbacks.ts ← IDE 内权限确认
│ 将权限确认请求转发到 IDE 侧(而非终端)
│ IDE 弹出图形化确认对话框
│ 支持 "允许一次" / "始终允许" / "拒绝"
│ 超时自动拒绝(与终端行为一致)
│
├── replBridge.ts ← REPL 与 Bridge 的衔接
│ 将 CLI 的 REPL 循环桥接到 IDE
│ 消息格式转换:CLI Message ↔ Bridge Message
│ 流式事件转发:将 Agent Loop 的 yield 事件实时推送到 IDE
│
├── jwtUtils.ts ← JWT 认证工具
│ 生成和验证 JWT Token
│ 确保只有授权的 IDE 实例可以连接
│ 防止恶意进程冒充 IDE 发送指令
│
├── sessionRunner.ts ← 会话运行器
│ 管理 Bridge 会话的完整生命周期
│ 创建 → 运行 → 暂停 → 恢复 → 销毁
│ 会话隔离:每个 IDE 窗口独立会话
│
├── remoteBridgeCore.ts ← 远程开发桥接
│ 支持 VS Code Remote SSH / JetBrains Gateway
│ 处理网络延迟和断线重连
│ 转发本地 stdin/stdout 到远程 IDE
│
└── trustedDevice.ts ← 可信设备管理
首次连接时的信任确认
已信任设备列表持久化
设备指纹识别(防止重放攻击)
Bridge 使用标准的 JSON-RPC 2.0 协议,通过 stdin/stdout 传输。每条消息是一行 JSON,以换行符 \n 分隔:
// JSON-RPC 2.0 消息格式
// ═══ 请求(IDE → CLI)═══
{
"jsonrpc": "2.0",
"method": "sendMessage", // RPC 方法名
"params": {
"content": "帮我重构这个函数",
"attachments": [
{ "type": "file", "path": "/src/utils.ts" },
{ "type": "selection", "path": "/src/main.ts", "range": [42, 58] }
]
},
"id": 1 // 请求 ID(用于匹配响应)
}
// ═══ 响应(CLI → IDE)═══
{
"jsonrpc": "2.0",
"result": { "status": "ok", "messageId": "msg_abc123" },
"id": 1
}
// ═══ 通知(双向,无 id)═══
// CLI → IDE:流式事件推送
{
"jsonrpc": "2.0",
"method": "streamEvent",
"params": {
"type": "assistant_text",
"delta": "我来分析一下这个函数的结构..."
}
}
// CLI → IDE:权限确认请求
{
"jsonrpc": "2.0",
"method": "requestPermission",
"params": {
"tool": "Bash",
"input": { "command": "npm install lodash" },
"description": "安装 lodash 依赖",
"timeout": 30000
}
}
在纯终端模式下,权限确认通过 stdin/stdout 的交互式提示完成(用户按 y/n)。但在 IDE 中,这种交互式提示是不可用的——IDE 的终端面板不支持逐字符读取。Bridge 系统通过 bridgePermissionCallbacks.ts 解决了这个问题:
// bridgePermissionCallbacks.ts — 权限桥接实现
class PermissionBridge {
// 待处理的权限请求队列
private pendingRequests = new Map<string, {
resolve: (allowed: boolean) => void
timeout: NodeJS.Timeout
}>()
// 工具系统调用此方法,而非直接读 stdin
async requestPermission(params: {
tool: string
input: unknown
description: string
timeout?: number
}): Promise<boolean> {
const requestId = `perm_${randomId()}`
const timeoutMs = params.timeout ?? 30_000
return new Promise((resolve) => {
// 设置超时自动拒绝
const timeout = setTimeout(() => {
this.pendingRequests.delete(requestId)
resolve(false) // 超时 = 拒绝(安全默认)
}, timeoutMs)
// 注册到队列
this.pendingRequests.set(requestId, { resolve, timeout })
// 通过 Bridge 发送请求到 IDE
bridgeMessaging.notify('requestPermission', {
requestId,
tool: params.tool,
input: params.input,
description: params.description,
timeout: timeoutMs,
})
})
}
// IDE 返回确认结果时调用
resolve(requestId: string, allowed: boolean): void {
const pending = this.pendingRequests.get(requestId)
if (!pending) return // 已超时或已处理
clearTimeout(pending.timeout)
this.pendingRequests.delete(requestId)
pending.resolve(allowed)
}
}
Bridge 的消息协议是双向的——IDE 和 CLI 都可以主动发送消息,而不只是请求-响应模式:
// 双向消息流全景
═══ IDE → CLI 方向 ═══
sendMessage → 用户发送对话消息(含附件)
cancelRequest → 取消当前请求
respondPermission → 返回权限确认结果
updateContext → 上下文变更通知(打开新文件、选中代码等)
changeMode → 切换模式(plan / default / auto)
executeCommand → 执行斜杠命令(/help, /clear, /compact 等)
updateSettings → 更新配置(模型、温度、最大 token 等)
resizeTerminal → 终端面板大小变更(影响换行计算)
═══ CLI → IDE 方向 ═══
streamEvent → Agent Loop 流式事件(text / thinking / tool_use / tool_result)
requestPermission → 请求权限确认
stateChanged → 状态变更(idle / running / waiting_permission)
costUpdate → 成本更新(token 使用量、费用)
errorOccurred → 错误通知(API 错误、工具错误等)
sessionCreated → 新会话创建通知
contextChanged → 上下文变更通知(文件被修改、CLAUDE.md 更新等)
backgroundTask → 后台任务通知(任务完成、失败等)
memorySaved → 记忆保存通知
Bridge 连接需要经过 JWT(JSON Web Token) 认证,防止恶意进程冒充 IDE 连接到 CLI 进程:
// jwtUtils.ts — JWT 认证流程
// ── 连接建立流程 ──
// Step 1: IDE 插件启动时生成 JWT
// JWT Payload:
// {
// iss: 'claude-code-vscode', // 发行者(IDE 标识)
// sub: 'bridge-connection', // 主题
// iat: timestamp, // 签发时间
// exp: timestamp + 5min, // 过期时间(5 分钟)
// ide: { name: 'vscode', version: '1.88.0' },
// machine: { machineId: 'abc123...', pid: 12345 },
// session: { nonce: 'random-uuid' } // 防重放随机数
// }
// Step 2: IDE 将 JWT 附加到连接请求
// 通过 CLI 的 --bridge-token 参数或环境变量传递
// Step 3: CLI 验证 JWT
class JWTVerifier {
private secret: string // 从系统 Keychain 获取
verify(token: string): boolean {
const payload = jwt.decode(token)
if (!jwt.verify(token, this.secret)) return false
if (payload.exp < Date.now() / 1000) return false
const validIssuers = ['claude-code-vscode', 'claude-code-jetbrains']
if (!validIssuers.includes(payload.iss)) return false
if (payload.machine.machineId !== getLocalMachineId()) return false
return true
}
}
// Step 4: 连接建立后
// - 每条 RPC 消息不需要单独签名(stdin/stdout 是本地管道)
// - 会话过期后需要重新认证
// - IDE 进程退出时连接自动断开
每个 IDE 窗口(或标签页)对应一个独立的 Bridge 会话。SessionRunner 管理会话的完整生命周期:
// sessionRunner.ts — 会话运行器
class SessionRunner {
private sessionId: string
private queryEngine: QueryEngine
private abortController: AbortController | null = null
private state: 'idle' | 'running' | 'paused' | 'destroyed' = 'idle'
constructor(params: {
model: string
permissionContext: ToolPermissionContext
cwd: string
}) {
this.sessionId = generateSessionId()
// 创建独立的 QueryEngine 实例
// 每个 Bridge 会话有独立的消息历史、权限上下文、文件缓存、Token 预算
this.queryEngine = new QueryEngine({
model: params.model,
permissionContext: params.permissionContext,
cwd: params.cwd,
sessionId: this.sessionId,
})
}
// 执行查询(IDE 发送消息时调用)
async query(content: string, attachments: Attachment[]): Promise<QueryResult> {
this.state = 'running'
this.abortController = new AbortController()
try {
const userMessage = buildUserMessage(content, attachments)
return await this.queryEngine.submitMessage(userMessage, {
abortController: this.abortController,
})
} finally {
this.state = 'idle'
this.abortController = null
}
}
abort(): void { this.abortController?.abort() }
pause(): void { if (this.state === 'running') this.state = 'paused' }
resume(): void { if (this.state === 'paused') this.state = 'running' }
destroy(): void {
this.state = 'destroyed'
this.abort()
this.queryEngine.cleanup()
}
}
现代 IDE 支持远程开发——VS Code Remote SSH、JetBrains Gateway、GitHub Codespaces。在这些场景中,IDE 前端在本地,但代码和终端运行在远程服务器上:
// 最小可行 Bridge 系统
// 1. 协议层:JSON-RPC over stdin/stdout
class SimpleBridge {
private handlers = new Map<string, Function>()
constructor() {
process.stdin.on('data', (chunk) => {
const lines = chunk.toString().split('\n').filter(Boolean)
for (const line of lines) {
const msg = JSON.parse(line)
this.handleMessage(msg)
}
})
}
send(method: string, params: unknown) {
process.stdout.write(
JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'
)
}
register(method: string, handler: Function) {
this.handlers.set(method, handler)
}
private async handleMessage(msg: JsonRpcMessage) {
const handler = this.handlers.get(msg.method)
if (handler) {
const result = await handler(msg.params)
if (msg.id !== undefined) {
process.stdout.write(JSON.stringify({
jsonrpc: '2.0', result, id: msg.id
}) + '\n')
}
}
}
}
// 2. 权限桥接:最简实现
class SimplePermissionBridge {
private bridge: SimpleBridge
private pending = new Map<string, Function>()
async confirm(tool: string, input: unknown): Promise<boolean> {
return new Promise((resolve) => {
const id = `perm_${Date.now()}`
this.pending.set(id, resolve)
this.bridge.send('requestPermission', {
requestId: id, tool, input, timeout: 30000,
})
setTimeout(() => {
if (this.pending.has(id)) {
this.pending.delete(id)
resolve(false) // 超时拒绝
}
}, 30000)
})
}
onResponse(requestId: string, allowed: boolean) {
const resolve = this.pending.get(requestId)
if (resolve) { this.pending.delete(requestId); resolve(allowed) }
}
}
// 3. 会话管理:最简实现
// 每个 IDE 连接 = 一个独立的 AgentLoop 实例
// 消息直接转发到 AgentLoop.query()
// 流式事件通过 bridge.send('streamEvent', ...) 推送
当 Agent 有 30+ 个工具时,将所有工具的 JSON Schema 注入系统提示词会消耗大量 token。Claude Code 的 ToolSearch 机制允许工具声明为"延迟加载"——只有当 LLM 主动搜索时才注入,而不是每次都带上所有工具定义。
// Tool.ts — 延迟加载属性
interface Tool {
// ... 其他属性 ...
/** 是否延迟加载(默认 false = 始终加载) */
readonly shouldDefer?: boolean
/** ToolSearch 关键词(3-10 词,帮助 LLM 搜索到此工具) */
searchHint?: string
/** 是否无条件加载(覆盖 shouldDefer) */
readonly alwaysLoad?: boolean
}
// 示例:NotebookEdit 工具
export const NotebookEditTool = buildTool({
name: 'NotebookEdit',
shouldDefer: true, // ← 延迟加载
searchHint: 'edit jupyter notebook cell',
// ...
})
// 示例:MCP 工具(默认延迟加载)
// mcp__slack__send_message
// mcp__github__create_pr
// 这些工具数量可能很多,全部加载会占用大量 token
// ToolSearchTool.ts — 搜索实现
// 两种搜索模式:
// 1. 精确选择(select: 前缀)
// LLM 已经知道要哪个工具,直接请求
// query: "select:NotebookEdit"
// → 返回 NotebookEdit 的完整定义
// 2. 关键词搜索(评分匹配)
// LLM 不确定工具名,用关键词描述需求
// query: "slack send message"
// → 解析工具名: mcp__slack__send_message
// → parts: ["slack", "send", "message"]
// → 评分:
// - 词匹配: "slack" 命中 → +10 分
// - 词匹配: "send" 命中 → +10 分
// - 词匹配: "message" 命中 → +10 分
// - searchHint 匹配: "send a message to slack" → +5 分
// - 完整名称匹配: → +20 分(精确匹配加分)
// → 返回得分最高的 top-5 工具
// MCP 工具名解析:
// mcp__slack__send_message
// → parts: ["slack", "send", "message"]
// → full: "slack send message"
// 普通工具名解析:
// NotebookEdit
// → parts: ["notebook", "edit"]
// → full: "notebook edit"
// prompt.ts — 延迟工具判定
export function isDeferredTool(tool: Tool): boolean {
// 1. alwaysLoad = true → 不延迟
if (tool.alwaysLoad) return false
// 2. shouldDefer = true → 延迟
if (tool.shouldDefer) return true
// 3. 默认不延迟
return false
}
// 启用 ToolSearch 的三种模式:
// ENABLE_TOOL_SEARCH = 'off' → 禁用,所有工具始终加载
// ENABLE_TOOL_SEARCH = 'on' → 启用,延迟工具需要 ToolSearch
// ENABLE_TOOL_SEARCH = 'optimistic' → 启用 + 推测性加载
当子 Agent 需要执行可能有破坏性的操作(如重构、大规模编辑)时,直接在主工作目录操作有风险——如果 Agent 出错,用户的代码可能被损坏。Claude Code 使用 Git Worktree 为子 Agent 创建隔离的工作副本,所有修改在独立分支上进行,不影响主目录。
// EnterWorktreeTool — 创建并进入 worktree
export const EnterWorktreeTool = buildTool({
name: 'EnterWorktree',
shouldDefer: true, // 延迟加载(不常用)
searchHint: 'create an isolated git worktree and switch into it',
async call(input) {
// 1. 检查是否已在 worktree 中
if (getCurrentWorktreeSession()) {
throw new Error('Already in a worktree session')
}
// 2. 创建 worktree
// git worktree add .claude/worktrees/feature-x -b feature-x
const worktree = await createWorktreeForSession({
name: input.name, // 可选名称
slug: getPlanSlug(), // 自动生成
})
// 3. 切换 CWD 到 worktree
setCwd(worktree.path)
setOriginalCwd(getCwd())
// 4. 清除缓存(文件状态已变)
clearSystemPromptSections()
clearMemoryFileCaches()
// 5. 保存 worktree 状态(用于恢复)
saveWorktreeState({
path: worktree.path,
branch: worktree.branch,
sessionId: getSessionId(),
})
return {
worktreePath: worktree.path,
worktreeBranch: worktree.branch,
message: `Switched to worktree: ${worktree.path}`,
}
},
})
// ExitWorktreeTool — 退出并清理 worktree
export const ExitWorktreeTool = buildTool({
name: 'ExitWorktree',
async call(input) {
const session = getCurrentWorktreeSession()
if (!session) throw new Error('Not in a worktree session')
if (input.action === 'keep') {
// 保留 worktree(用户可能稍后回来)
setCwd(session.originalCwd)
return { message: 'Worktree kept, returned to original directory' }
}
if (input.action === 'remove') {
// 检查是否有未提交的更改
if (!input.discard_changes && hasUncommittedChanges(session.path)) {
throw new Error('Worktree has uncommitted changes. Use discard_changes: true to force.')
}
// git worktree remove .claude/worktrees/feature-x
await removeAgentWorktree(session.path)
setCwd(session.originalCwd)
return { message: 'Worktree removed' }
}
},
})
// AgentTool.ts — 子 Agent 的 worktree 隔离
// 当调用 AgentTool 时指定 isolation: "worktree"
await AgentTool.call({
prompt: "重构 auth 模块,将所有函数重命名",
subagent_type: "general-purpose",
isolation: "worktree", // ← 自动创建 worktree
})
// AgentTool 内部流程:
// 1. 检测 isolation = "worktree"
// 2. 调用 createWorktreeForSession() 创建隔离目录
// 3. 子 Agent 在 worktree 中工作
// 4. 子 Agent 完成后:
// ├─ 无更改 → 自动清理 worktree
// └─ 有更改 → 保留 worktree,返回分支名供用户审查
// 5. 用户可以 git merge feature-x 合并更改
创建子 Agent 时,最大的成本之一是系统提示词的 token 消耗。每次创建新 Agent,都需要重新发送完整的系统提示词(工具定义、上下文、CLAUDE.md 等),这可能消耗数千 token。Claude Code 的 Fork Subagent 模式通过共享父级的已渲染系统提示词,实现了零额外 cache 成本的子 Agent 创建。
// forkSubagent.ts — Fork Agent 定义
export const FORK_AGENT = {
agentType: 'fork',
whenToUse: 'Implicit fork — inherits full conversation context',
tools: ['*'], // ← 继承父级的完整工具池
maxTurns: 200,
model: 'inherit', // ← 继承父级的模型
permissionMode: 'bubble', // ← 权限请求冒泡到父级终端
source: 'built-in',
getSystemPrompt: () => '', // ← 不使用!实际用 renderedSystemPrompt
} satisfies BuiltInAgentDefinition
// 关键:tools: ['*'] + useExactTools
// 子 Agent 拥有和父级完全相同的工具池
// → 系统提示词中的工具定义部分字节完全一致
// → API 的 prompt cache 直接命中
// forkSubagent.ts — 构建 Fork 子 Agent 的消息
function buildForkedMessages(
parentMessages: Message[],
forkDirective: string,
): Message[] {
// 1. 过滤掉 thinking 块(不传给子 Agent)
// 2. 过滤掉失败的工具调用(只保留成功的)
// 3. 过滤掉中断消息
const cleanMessages = parentMessages
.filter(m => m.type !== 'thinking')
.filter(m => !isInterruptedToolUse(m))
.filter(m => !isFailedToolResult(m))
// 4. 添加 fork 指令(用户消息)
// 包裹在 FORK_BOILERPLATE_TAG 中
const forkMessage = createUserMessage(
`${FORK_DIRECTIVE_PREFIX}\n${forkDirective}\n${FORK_BOILERPLATE_TAG}`
)
// 5. 返回:父级消息 + fork 指令
// 子 Agent 看到的是父级的完整上下文 + 新指令
return [...cleanMessages, forkMessage]
}
// 效果:
// - 子 Agent 看到父级的完整对话历史(上下文不丢失)
// - 系统提示词完全相同(cache 命中)
// - 只增加了 fork 指令的消息(几百 token)
// 防止无限递归 fork
export function isInForkChild(messages: Message[]): boolean {
return messages.some(m => {
if (m.type !== 'user') return false
// 检查消息中是否包含 FORK_BOILERPLATE_TAG
// 如果有,说明当前 Agent 本身就是 fork 出来的
return m.message.content.includes(FORK_BOILERPLATE_TAG)
})
}
// Fork Agent 调用时的检查:
// if (isInForkChild(parentMessages)) {
// // 当前 Agent 已经是 fork 子 Agent
// // 不允许再次 fork(防止无限递归)
// throw new Error('Cannot fork from a fork child')
// }
// Fork Agent 的权限处理:bubble 模式
// permissionMode: 'bubble' 意味着:
// - 子 Agent 不自行处理权限确认
// - 权限请求"冒泡"到父级终端
// - 用户在父级终端看到确认提示
// - 确认结果传回子 Agent
// 流程:
// 1. Fork 子 Agent 调用 BashTool("rm -rf temp/")
// 2. 权限检查 → 需要用户确认
// 3. 子 Agent 发送权限请求到父级
// 4. 父级终端显示: "子 Agent 请求执行: rm -rf temp/ (y/n)"
// 5. 用户确认 → 结果传回子 Agent
// 6. 子 Agent 继续执行
记忆系统是 Agent 实现跨会话知识保持的核心。Claude Code 设计了一套五层记忆架构,从用户手动管理的指令文件,到系统自动提取的持久化记忆,每一层解决不同的问题。
CLAUDE.md 是用户直接控制的"行为基因"。加载优先级从低到高:
// 加载顺序(低 → 高优先级)
1. Managed /etc/claude-code/CLAUDE.md ← 组织级全局(所有用户)
2. User ~/.claude/CLAUDE.md ← 用户级全局
3. Project .claude/CLAUDE.md ← 项目级(提交到 git)
.claude/rules/*.md ← 条件规则(按 glob 匹配文件)
4. Local .claude/CLAUDE.local.md ← 本地(不提交 git)
// 支持 @include 指令(递归最大 5 层)
// CLAUDE.md 中写:
// @./rules/typescript.md
// @~/global-rules/security.md
// @/absolute/path/to/rules.md
// 条件规则 — 仅对匹配 glob 的文件生效
// .claude/rules/no-console-log.md
// ---
// paths: ["src/**/*.ts", "!src/debug/**"]
// ---
// Do not use console.log, use the logger utility instead.
这是 Claude Code 最精巧的记忆层——系统自动从对话中提取持久化知识,存储为带 frontmatter 的 markdown 文件。
// 每个记忆文件都有 frontmatter 元数据
---
name: user-role-data-scientist
description: 用户是数据科学家,当前关注可观测性/日志
type: user ← 4 种类型之一
---
用户是数据科学家,当前专注于调查我们的日志基础设施。
对 Python 和 SQL 很熟悉,但第一次接触 TypeScript。
解释前端概念时用后端类比会更有效。
// ─────────────────────────────────────
// 4 种记忆类型:
type MemoryType = 'user' | 'feedback' | 'project' | 'reference'
// user — 用户画像
// 何时保存:了解到用户的角色、偏好、知识水平
// 用途:调整交互风格(资深工程师 vs 初学者)
// feedback — 行为反馈
// 何时保存:用户纠正或确认了某个非显而易见的做法
// 包含:规则本身 + Why(原因) + How to apply(适用场景)
// 示例:
// 规则:集成测试必须连接真实数据库,不要 mock
// Why:上季度 mock 测试通过但生产迁移失败
// How to apply:所有涉及数据库的测试
// project — 项目动态
// 何时保存:了解到正在进行的工作、目标、截止日期
// 时效性:变化较快,需要保持更新
// 示例:周四之后冻结所有非关键合并——移动端在切 release 分支
// reference — 外部资源指针
// 何时保存:了解到外部系统中的资源位置
// 示例:pipeline bug 在 Linear 的 INGEST 项目里追踪
// MEMORY.md 是自动记忆的入口点
// 限制:最多 200 行,25KB
// 格式:每行一条,指向一个记忆文件
// 示例内容:
- [用户偏好 - 名人思维模拟技能](user_preferences.md) — 用户希望安装模拟名人思维模式的技能
- [反馈 - 测试策略](feedback_testing.md) — 集成测试必须用真实数据库
- [项目 - 合并冻结](project_merge_freeze.md) — 周四后冻结非关键合并
- [参考 - Linear 追踪](reference_linear.md) — pipeline bug 在 Linear INGEST 项目
// 超出限制时自动截断,并在末尾添加 WARNING 标记
// 保存记忆的标准流程:
// Step 1: 写入记忆文件
// 路径: ~/.claude/projects/{sanitized-path}/memory/{filename}.md
// 文件内容 = frontmatter + 正文
---
name: feedback-testing-strategy
description: 集成测试必须连接真实数据库
type: feedback
---
集成测试必须连接真实数据库,不要使用 mock。
**Why:** 上季度 mock 测试全部通过,但生产环境迁移失败。
**How to apply:** 所有涉及数据库操作的测试用例。
// Step 2: 更新 MEMORY.md 索引
// 在 MEMORY.md 中添加一行指向新文件的链接
- [反馈 - 测试策略](feedback_testing.md) — 集成测试必须用真实数据库
// 路径解析:
// autoMemPath = ~/.claude/projects/{sanitized-git-root}/memory/
// 使用 findCanonicalGitRoot() 确保同一仓库的所有 worktree 共享记忆目录
Claude Code 在每次对话结束时自动运行一个后台 Agent 来提取记忆。这个设计非常精巧:
// 自动记忆提取流程
┌─────────────────────────────────────────────────────┐
│ 自动记忆提取流程 │
│ │
│ 1. 对话结束(handleStopHooks 触发) │
│ └─ 检查是否应该提取(互斥检查) │
│ │
│ 2. 互斥检查 │
│ ├─ 如果主 Agent 已经手动写了记忆文件 → 跳过 │
│ └─ 否则 → 继续 │
│ │
│ 3. 节流检查 │
│ └─ 每 N 轮对话才运行一次(默认每轮) │
│ │
│ 4. 预注入记忆目录清单 │
│ └─ 提取 Agent 不需要花一轮 ls 才知道有哪些文件 │
│ │
│ 5. 运行提取 Agent(forked agent 模式) │
│ ├─ 共享主对话的 prompt cache(零额外缓存成本) │
│ ├─ 最多 5 轮 │
│ ├─ 权限:只能在 memory/ 目录内写入 │
│ └─ 工具:Read/Grep/Glob + 只读 Bash + Edit/Write │
│ │
│ 6. 提取策略(高效 2 轮) │
│ ├─ 第 1 轮:并行读取现有记忆文件 + 对话历史 │
│ └─ 第 2 轮:并行写入新/更新的记忆文件 │
│ │
│ 7. 完成 │
│ ├─ 推进游标(lastMemoryMessageUuid) │
│ ├─ 记录分析指标(token 数、文件数、耗时) │
│ └─ 在主对话中注入 memorySavedMessage │
└─────────────────────────────────────────────────────┘
// 关键设计:Forked Agent 模式
// - 提取 Agent 是主对话的完美分叉,共享 prompt cache
// - 不需要重新发送完整对话历史给 LLM
// - 成本极低(只需处理新增的几轮对话)
// 权限隔离:
function createAutoMemCanUseTool(memoryDir) {
return (tool, input) => {
if (['FileRead', 'Grep', 'Glob'].includes(tool)) return 'allow'
if (tool === 'Bash' && isReadOnlyCommand(input)) return 'allow'
if (['FileEdit', 'FileWrite'].includes(tool)) {
return isPathWithinDir(input.path, memoryDir) ? 'allow' : 'deny'
}
return 'deny'
}
}
不是把所有记忆都塞进系统提示词——而是用一个轻量级 LLM 侧查询来选择最相关的记忆:
// 记忆检索流程
用户发送消息
│
├─ 1. 异步预取(startRelevantMemoryPrefetch)
│ └─ 在用户输入处理期间就开始搜索,不阻塞主流程
│
├─ 2. 扫描记忆目录(scanMemoryFiles)
│ ├─ 递归读取所有 .md 文件(排除 MEMORY.md)
│ ├─ 解析 frontmatter 的前 30 行
│ ├─ 按修改时间降序排列
│ └─ 最多 200 个文件
│
├─ 3. Sonnet 侧查询(selectRelevantMemories)
│ ├─ 输入:用户消息 + 记忆文件清单
│ ├─ 模型:轻量级 Sonnet(成本低)
│ ├─ 输出:最多 5 个最相关文件名
│ └─ 策略:不要选最近已用工具的文档,但要选包含警告/陷阱的记忆
│
├─ 4. 读取选中文件(readMemoriesForSurfacing)
│ ├─ 每文件最多 200 行 / 4KB
│ ├─ 超出时截断(不丢弃)
│ └─ 会话累计限制 60KB
│
└─ 5. 注入为附件(relevant_memories attachment)
├─ 去重:已在上下文中的不重复注入
├─ 追踪:标记 readFileState 防止重复
└─ 缓存友好:header 预计算,利于 prompt cache
// autoDream — 定期记忆整合
// 当多个会话积累后,自动运行一个整合 Agent
触发条件(按成本从低到高检查):
1. 时间门控:距上次整合 ≥ 24 小时
2. 会话门控:自上次整合后有 ≥ 5 个新会话
3. 锁门控:没有其他整合正在运行
整合流程:
1. 获取整合锁(防止并发)
2. 列出自上次整合后触碰过的会话
3. 构建整合提示(附带会话列表)
4. 运行 forked agent(共享 prompt cache)
5. Agent 读取会话日志,提炼主题,更新/合并记忆文件
6. 成功:完成 dream 任务,记录分析
7. 失败:回滚锁,记录错误(不通知用户,best-effort)
// 会话记忆 — 当前会话的结构化笔记
// 自动维护,不跨会话持久化
// 默认模板:
# Session Title
# Current State ← 当前正在做什么
# Task specification ← 任务描述
# Files and Functions ← 涉及的文件和函数
# Workflow ← 工作流程
# Errors & Corrections ← 遇到的错误和修正
# Codebase and System Documentation ← 代码库文档
# Learnings ← 学到的知识
# Key results ← 关键结果
# Worklog ← 工作日志
// 触发条件(三个条件满足任一):
// (当前 token 数 ≥ 10,000) AND (工具调用 ≥ 3 次)
// OR
// (距上次提取增长 ≥ 5,000 tokens) AND (上一轮没有工具调用)
// 提取方式:forked agent,只允许编辑会话记忆文件
// 每个 section 最多 2000 tokens,总计最多 12000 tokens
// 用途:
// 1. 压缩时注入 — AutoCompact 时作为上下文注入摘要
// 2. /summary 命令 — 用户手动查看当前会话笔记
// 最小可行记忆系统
// 1. CLAUDE.md 文件(L1)— 用户手动维护
// 最简单:读取项目根目录的 CLAUDE.md,注入系统提示词
// 2. MEMORY.md + 记忆文件(L2)— 两步法
class MemorySystem {
memoryDir: string // ~/.agent/projects/{project}/memory/
indexPath: string // memoryDir + '/MEMORY.md'
// 保存记忆
async save(name, content, type) {
// Step 1: 写文件
await writeFile(`${this.memoryDir}/${name}.md`, `---
name: ${name}
type: ${type}
---
${content}`)
// Step 2: 更新索引
await appendLine(this(indexPath, `- [${name}](${name}.md)`)
}
// 检索记忆(简化版:关键词匹配,不用 LLM)
async findRelevant(query) {
const files = await scanDir(this.memoryDir)
return files
.filter(f => f.name !== 'MEMORY.md')
.sort((a, b) => b.mtime - a.mtime)
.slice(0, 5) // 最近 5 个
}
// 自动提取(会话结束时)
async extractFromConversation(messages) {
// 用 forked agent 或直接用小模型提取
// 检查互斥:如果用户已手动写过,跳过
}
}
工具调用是 Agent 与外部世界交互的唯一通道。从 LLM 返回 tool_use 块到 tool_result 送回 LLM,中间经过 11 个阶段,每一步都有精心设计的逻辑。
// 工具查找 — 两步降级
function findToolByName(name, tools) {
// Step 1: 精确匹配
let tool = tools.find(t => t.name === name)
// Step 2: 别名映射(兼容旧名)
if (!tool) {
const alias = TOOL_ALIASES[name] // e.g., 'KillShell' → 'TaskStop'
if (alias) tool = tools.find(t => t.name === alias)
}
// Step 3: 兜底到 getAllBaseTools()(可能在延迟工具集中)
if (!tool) tool = getAllBaseTools().find(t => t.name === name)
return tool
}
// 输入验证 — 两层
// Layer 1: Zod Schema 验证
const parsed = tool.inputSchema.safeParse(input)
if (!parsed.success) {
return { is_error: true, content: buildValidationError(parsed.error) }
}
// Layer 2: 工具自定义验证
const customError = await tool.validateInput(parsed.data, context)
if (customError) {
return { is_error: true, content: customError }
}
// PreToolUse Hook 的 7 种输出
type PreToolUseHookResult = {
message?: Message // 附加消息
hookPermissionResult?: 'allow' | 'deny' | 'ask' // 权限决定
hookUpdatedInput?: Record // 修改后的输入
preventContinuation?: boolean // 阻止整个轮次继续
stopReason?: string // 停止原因
additionalContext?: Message[] // 额外上下文
stop?: boolean // 硬停止,中止工具执行
}
// 权限解析 — Hook 决定与规则系统的交互
function resolveHookPermissionDecision(hookResult, tool, input, context) {
if (hookResult.hookPermissionResult === 'allow') {
// Hook 说允许,但规则可能覆盖
const ruleResult = checkRuleBasedPermissions(tool, input, context)
if (ruleResult === 'deny' || ruleResult === 'ask') {
return ruleResult // 规则优先级高于 Hook
}
return 'allow' // 没有规则反对,接受 Hook 的决定
}
if (hookResult.hookPermissionResult === 'deny') {
return 'deny' // 直接拒绝
}
// Hook 没有决定或返回 ask → 进入标准权限检查
return canUseTool(tool, input, context)
}
// 权限检查的完整决策树
function hasPermissionsToUseToolInner(tool, input, context) {
// ── Step 1: 规则检查 ──
// 1a. 整个工具在 deny 列表 → deny
if (isToolInDenyList(tool.name, context)) return 'deny'
// 1b. 整个工具在 ask 列表 → ask(除非沙箱 bash)
if (isToolInAskList(tool.name, context)) return 'ask'
// 1c. 工具自定义权限检查
// 例如 BashTool 检查子命令规则
// 例如 FileTool 检查路径安全性
const toolResult = tool.checkPermissions(input, context)
// 1d. 工具返回 deny → deny
if (toolResult === 'deny') return 'deny'
// 1e. 需要用户交互 + 工具返回 ask → ask
if (tool.requiresInteraction && toolResult === 'ask') return 'ask'
// 1f. 内容级 ask 规则(按参数模式匹配)
if (hasContentAskRule(tool, input, context)) return 'ask'
// 1g. 安全检查(bypass 也不能跳过)
if (isSafetyCheck(tool, input)) return 'ask'
// ── Step 2: 模式检查 ──
// 2a. Bypass 模式 → allow
if (context.mode === 'bypassPermissions') return 'allow'
// 2b. 整个工具在 allow 列表 → allow
if (isToolInAllowList(tool.name, context)) return 'allow'
// ── Step 3: 默认行为 ──
return 'ask' // 没有匹配任何规则 → 询问用户
}
// ── Auto 模式分类器 ──
// 当 mode === 'auto' 且结果为 ask 时:
function handleAutoMode(tool, input) {
// 1. 安全检查可跳过分类器
if (isClassifierApprovable(tool)) return 'allow'
// 2. acceptEdits 快速路径
if (wouldBeAllowedInAcceptEditsMode(tool, input)) return 'allow'
// 3. 安全工具白名单
if (isSafeTool(tool)) return 'allow'
// 4. 运行 AI 分类器(classifyYoloAction)
const classification = await classifyYoloAction(tool, input)
if (classification === 'allow') return 'allow'
// 5. 分类器拒绝 → 追踪拒绝次数
trackDenial(tool.name)
if (denialCount >= MAX_DENIALS) return 'deny' // 连续拒绝自动停止
// 6. 降级到交互式确认
return promptUser(tool, input)
}
// ── 交互式确认的 5 路竞争 ──
// 当需要用户确认时,同时启动多个竞争者:
async function handleInteractivePermission(tool, input) {
const results = await Promise.race([
waitForUserInteraction(), // 用户在终端按 y/n
waitForPermissionRequestHooks(), // 自定义 hook 脚本
waitForBashClassifier(), // Bash 安全分类器(2秒超时)
waitForBridgePermission(), // 远程 IDE 权限
waitForChannelPermission(), // Telegram/iMessage 等渠道
])
// 第一个返回的结果生效(claim() 原子操作)
}
// 工具执行 — 权限通过后
async function executeTool(tool, input, context, onProgress) {
// 调用工具的 call 方法
const result = await tool.call(input, context, canUseTool, assistantMessage, onProgress)
// ToolResult 结构:
return {
data: string | ContentBlock[], // 工具输出
newMessages?: Message[], // 附加消息
contextModifier?: ContextModifier,// 修改后续上下文
mcpMeta?: MCPMeta, // MCP 元数据
}
}
// 进度回调 — 长时间运行的工具(如 Bash)
// 每行输出都通过 onProgress 流式显示
// 用户可以实时看到命令输出
// 两级结果大小管理
// ── Level 1: 单工具持久化(即时)──
// 每个工具声明 maxResultSizeChars(如 50,000)
function processToolResultBlock(result, toolUseId, tool) {
if (result.length > tool.maxResultSizeChars) {
// 大结果持久化到磁盘
const path = `${projectDir}/${sessionId}/tool-results/${toolUseId}.txt`
writeFile(path, result)
// 返回预览
return `
Output too large (${result.length} chars). Full output saved to: ${path}
Preview (first 2KB):
${result.slice(0, 2048)}...
`
}
return result
}
// ── Level 2: 每消息聚合预算(API 调用前)──
// applyToolResultBudget() 在每次 API 调用前运行
function applyToolResultBudget(messages) {
for (const group of groupToolResultsByMessage(messages)) {
if (group.totalSize > MAX_TOOL_RESULTS_PER_MESSAGE_CHARS) {
// 按优先级替换:
// mustReapply(之前已替换的)→ 保持
// frozen(之前见过但保留的)→ 保持
// fresh(新的)→ 按大小降序替换,直到低于预算
const toReplace = selectLargestFreshResults(group, budget)
for (const result of toReplace) {
persistAndReplace(result) // 持久化 + 替换为预览
}
}
}
}
// 空结果占位符
if (result.length === 0) {
return `(${toolName} completed with no output)`
}
// 分层 AbortController 树
toolUseContext.abortController ← 顶层(主查询控制器)
└─ siblingAbortController ← 兄弟工具控制器
└─ toolAbortController ← 单工具控制器
// 中止级联规则:
// 1. Bash 工具错误 → siblingAbortController.abort('sibling_error')
// → 杀死所有并发的兄弟 Bash 进程
// 2. 用户按 ESC → 主控制器中止
// → interruptBehavior === 'cancel' 的工具收到合成错误
// → interruptBehavior === 'block' 的工具继续运行
// 3. 权限对话框拒绝 → toolAbortController 中止
// → 向上冒泡到主控制器
// 4. Streaming 回退 → streamingToolExecutor.discard()
// → 所有待处理工具收到合成错误
// 每个工具声明中断行为:
interface Tool {
interruptBehavior(): 'cancel' | 'block'
// cancel: 用户中断时停止工具,返回错误结果
// block: 用户中断时工具继续运行,新消息等待
}
后台任务系统让 Agent 可以在不阻塞用户交互的情况下执行长时间运行的操作。Claude Code 设计了 7 种任务类型,每种有不同的执行模型和生命周期。
// 7 种任务类型
type TaskType =
| 'local_bash' // 后台 Shell 命令
| 'local_agent' // 本地子 Agent
| 'remote_agent' // 远程 Agent(云端执行)
| 'in_process_teammate' // 进程内队友(集群模式)
| 'local_workflow' // 后台工作流
| 'monitor_mcp' // MCP 监控器
| 'dream' // 记忆整合(autoDream)
// 任务状态机
type TaskStatus =
| 'pending' → 'running' → 'completed'
→ → 'failed'
→ → 'killed'
// 任务 ID 格式:类型前缀 + 8 位随机 base-36
// 例如: b7x9k2m4p (bash), a3f8n1q5r (agent)
// 框架层核心函数
// 1. 注册任务
function registerTask(task, setAppState) {
// 插入 AppState.tasks
// 如果是恢复(resume),携带保留的状态
// 发出 task_started SDK 事件
// 状态结构:
{
id: string,
type: TaskType,
status: TaskStatus,
description: string,
startTime: number,
outputFile: string, // 输出文件路径
outputOffset: number, // 已读取的输出偏移
notified: boolean, // 防止重复通知
}
}
// 2. 轮询任务(每 1 秒)
function pollTasks(getAppState, setAppState) {
for (const task of getAllTasks()) {
if (task.status === 'running') {
// 从磁盘读取新的输出增量
const delta = getTaskOutputDelta(task.outputFile, task.outputOffset)
if (delta) {
// 更新偏移,生成附件
updateTaskOffset(task.id, newOffset)
generateAttachment(task, delta)
}
}
if (isTerminal(task) && task.notified) {
// 已完成且已通知 → 标记为可驱逐
evictTerminalTask(task.id)
}
}
}
// 3. 停止任务
async function stopTask(taskId, context) {
const task = getTask(taskId)
if (task.status !== 'running') return { error: 'not running' }
// 根据类型分发到对应的 kill 方法
const impl = getTaskByType(task.type)
await impl.kill(taskId, setAppState)
// 更新状态为 killed
updateTaskStatus(taskId, 'killed')
emitTaskTerminatedSdk(taskId)
}
// 后台 Shell 命令的完整生命周期
// 创建方式 1:BashTool 参数
// { command: "npm test", run_in_background: true }
// 创建方式 2:用户按 Ctrl+B(后台化当前前台命令)
// 生命周期:
// ┌──────────┐ ┌──────────┐ ┌──────────┐
// │ register │───→│ background│───→│ running │
// │ (前台) │ │ (转后台) │ │ (输出中) │
// └──────────┘ └──────────┘ └──────────┘
// │
// ┌───────┼───────┐
// ↓ ↓ ↓
// completed failed killed
// 停滞看门狗(Stall Watchdog)
// 每 5 秒检查输出文件,如果 45 秒没有增长
// 且尾部看起来像交互式提示((y/n), Continue?)
// → 发送通知建议用户 kill 并用管道输入重跑
// 孤儿清理
// 当 Agent 退出时,自动 kill 它创建的所有后台 Shell
// 并清除该 Agent 的排队通知
// 后台 Agent 的生命周期
// 创建方式:AgentTool 参数
// { prompt: "重构这个模块", run_in_background: true }
// 状态结构(比 Shell 丰富得多):
{
agentId: string,
prompt: string,
model?: string,
abortController?: AbortController,
progress?: AgentProgress, // 进度追踪
messages?: Message[], // 对话历史
pendingMessages: string[], // 排队的中途消息
retain: boolean, // UI 正在显示,阻止驱逐
}
// 进度追踪(ProgressTracker)
// 追踪:工具调用次数、输入/输出 token 数、最近活动
// 活动描述:自动解析工具操作为人类可读描述
// 例如:BashTool("npm test") → "运行 npm test"
// 前台/后台切换
// - registerAsyncAgent() → 直接后台
// - registerAgentForeground() → 前台,可选自动后台超时
// - backgroundAgentTask() → 切到后台(通过 background signal)
// - Ctrl+B → 后台化所有前台任务
// 中途消息
// 用户可以在 Agent 运行时发送消息
// 消息加入 pendingMessages 队列
// Agent 当前轮次结束后处理排队消息
// Cron 任务 — 定时触发 Agent 操作
// 创建:
// CronCreateTool({ cron: "*/5 * * * *", prompt: "检查部署状态" })
// → 写入 .claude/scheduled_tasks.json
// 类型:
type CronTask = {
id: string
cron: string // 5 字段标准 cron
prompt: string // 触发时执行的提示词
createdAt: number
lastFiredAt?: number
recurring?: boolean // 默认 true(重复执行)
durable?: boolean // 默认 false(仅会话内)
permanent?: boolean // 系统逃逸标记(不过期)
agentId?: string // 创建者 Agent ID
}
// 持久化策略:
// durable: false → 仅内存,会话结束即消失
// durable: true → 写入 .claude/scheduled_tasks.json,重启后恢复
// 自动过期:
// recurring 任务在可配置的最大时长后自动删除
// permanent 标记豁免于自动过期
// 限制:
// - 最多 50 个 cron 任务
// - 队友不能创建 durable cron
// - CLAUDE_CODE_DISABLE_CRON 环境变量可禁用整个系统
// 结构化任务列表 — 与后台任务不同的系统
// 用于追踪"要做什么",而非"正在运行什么"
// 4 个工具:
TaskCreateTool → 创建任务(subject, description, activeForm)
TaskUpdateTool → 更新任务(status, owner, blocks/blockedBy)
TaskGetTool → 获取任务详情
TaskListTool → 列出所有任务
// 状态工作流:
// pending → in_progress → completed
// deleted → 永久移除
// 依赖关系:
// addBlocks: ["2"] → 任务 1 完成后,任务 2 才能开始
// addBlockedBy: ["1"] → 任务 2 被任务 1 阻塞
// 团队协作:
// - 自动分配 owner
// - 所有权变更时通知新 owner
// - 3+ 任务关闭未验证 → 建议生成验证 Agent
// 持久化:
// 存储在 .claude/ 目录下的 JSON 文件
// 支持文件锁(并发集群 Agent 安全)
// 信号通知(状态变更时通知订阅者)
// 最小后台任务系统
class TaskManager {
tasks = new Map<string, TaskState>()
// 注册
register(task: TaskState) {
this.tasks.set(task.id, task)
this.startPolling(task)
}
// 轮询(1秒间隔)
private startPolling(task) {
setInterval(async () => {
if (task.status !== 'running') return
const delta = await readOutputDelta(task.outputFile, task.outputOffset)
if (delta) {
task.outputOffset += delta.bytes
this.notify(task, delta) // 流式通知主对话
}
const exitCode = await checkExit(task)
if (exitCode !== null) {
task.status = exitCode === 0 ? 'completed' : 'failed'
task.endTime = Date.now()
this.notify(task, { summary: `Exit code: ${exitCode}` })
}
}, 1000)
}
// 停止
async kill(taskId: string) {
const task = this.tasks.get(taskId)
await task.kill()
task.status = 'killed'
}
// 生成通知(XML 格式)
private notify(task, data) {
const xml = `
${task.id}
${task.type}
${task.status}
${data.summary}
${task.outputFile}
`
enqueueNotification(xml)
}
}
前面介绍了 Agent Loop 的概念。这里深入到每一行代码的执行流程——从用户输入到最终返回,中间的每一步决策、错误恢复、上下文管理。
// queryLoop() — while(true) 循环的每次迭代
// ═══════════════════════════════════════════
// Phase 1: Pre-API 设置
// ═══════════════════════════════════════════
// 1.1 工具结果预算(防止一次对话中工具结果太多)
applyToolResultBudget(messages)
// 1.2 快照压缩(feature-gated HISTORY_SNIP)
snipCompactIfNeeded(messages)
// 1.3 微压缩(清理旧工具结果)
microcompact(messages)
// 策略:时间间隔超过阈值 → 清理旧结果为 "[Old tool result content cleared]"
// 1.4 上下文折叠(feature-gated CONTEXT_COLLAPSE)
contextCollapse(messages)
// 1.5 构建完整系统提示词
systemPrompt = appendSystemContext(systemPrompt, systemContext)
// 1.6 自动压缩检查
const threshold = effectiveContextWindow - 13_000 // AUTOCOMPACT_BUFFER_TOKENS
if (tokenCount(messages) > threshold) {
// 先尝试 Session Memory 压缩(不调用 LLM)
if (trySessionMemoryCompaction(messages)) {
// 成功:直接替换消息,不消耗 API
} else {
// 回退到完整压缩(调用 LLM 生成摘要)
compactConversation(messages)
}
}
// 1.7 阻塞限制检查(auto-compact 关闭时的硬限制)
if (!autoCompactEnabled && tokens > effectiveContextWindow - 3000) {
yield error("Context window exceeded")
return { reason: 'blocked' }
}
// ═══════════════════════════════════════════
// Phase 2: API 调用与流式处理
// ═══════════════════════════════════════════
// 2.1 调用 LLM(流式)
for await (const message of callModel(systemPrompt, messages, tools)) {
// 2.2 yield 每条消息给 UI
yield message
// 2.3 处理 assistant 消息
if (message.type === 'assistant') {
assistantMessages.push(message)
// 提取 tool_use 块
for (const block of message.tool_use_blocks) {
toolUseBlocks.push(block)
// 2.4 Streaming 模式:立即开始执行工具
streamingToolExecutor?.addTool(block, message)
}
}
// 2.5 处理 stream_event(usage 追踪)
if (message.type === 'stream_event') {
if (message.event.type === 'message_start') trackUsage(message)
if (message.event.type === 'message_delta') trackDelta(message)
}
// 2.6 错误扣留(不 yield,稍后尝试恢复)
if (isWithholdableError(message)) {
withheldErrors.push(message) // prompt-too-long, max-output-tokens
continue // 不 yield 给 UI
}
}
// ═══════════════════════════════════════════
// Phase 3: 后流式决策树
// ═══════════════════════════════════════════
if (!needsFollowUp) {
// ── 无工具调用路径 ──
// 3.1 Prompt-too-long 恢复
if (hasWithheldError('prompt_too_long')) {
// 尝试 1: 上下文折叠排水
if (recoverFromOverflow(messages)) continue
// 尝试 2: 响应式压缩
if (tryReactiveCompact(messages)) continue
// 都失败 → surface 错误
yield withheldError
}
// 3.2 Max-output-tokens 恢复
if (hasWithheldError('max_output_tokens')) {
// 尝试 1: 从 8k 升级到 64k
if (canEscalate) { maxTokens = 64_000; continue }
// 尝试 2: 多轮恢复(最多 3 次)
if (recoveryAttempts < 3) {
messages.push({ role: 'user', content: 'Resume directly...' })
recoveryAttempts++
continue
}
// 都失败 → surface 错误
yield withheldError
}
// 3.3 Stop hooks
handleStopHooks(messages) // 触发记忆提取、autoDream
// 3.4 Token 预算续接
if (outputTokens < budget && canContinue) {
messages.push({ role: 'user', content: 'Continue...' })
continue
}
return { reason: 'completed' }
} else {
// ── 有工具调用路径 ──
// 3.5 执行工具
const results = streamingToolExecutor
? streamingToolExecutor.getRemainingResults()
: runTools(toolUseBlocks, context)
for (const result of results) {
yield result
toolResults.push(result)
}
// 3.6 中止检查
if (abortController.signal.aborted) {
yield interruptionMessage
return { reason: 'aborted' }
}
// 3.7 获取附件消息(记忆、文件变更通知)
const attachments = await getAttachmentMessages(messages, context)
// 3.8 最大轮次检查
if (turnCount > maxTurns) {
yield maxTurnsReachedMessage
return { reason: 'max_turns' }
}
// 3.9 继续循环
state = {
messages: [...messages, ...assistantMessages, ...toolResults, ...attachments],
transition: { reason: 'next_turn' }
}
continue // → 回到 Phase 1
}
// 整个系统建立在嵌套的 AsyncGenerator 上
// 每个 yield 向上传播,实现流式处理
QueryEngine.submitMessage() ← async * SDKMessage
└─ query() ← async * StreamEvent | Message
└─ queryLoop() ← async * StreamEvent | Message
└─ callModel() ← async * StreamEvent | AssistantMessage
└─ queryModelWithStreaming() ← async * StreamEvent
└─ withRetry() ← async * ErrorMessage
// 消费方式:
for await (const message of queryEngine.submitMessage(input)) {
switch (message.type) {
case 'assistant': renderAssistant(message); break
case 'tool_result': renderToolResult(message); break
case 'progress': renderProgress(message); break
case 'stream_event': updateUsage(message); break
}
}
// 优势:
// 1. 流式处理 — 消息产生即消费,不等全部完成
// 2. 内存友好 — 不需要缓存所有消息
// 3. 可取消 — 随时 break 退出循环
// 4. 组合性 — yield* 委托实现层级传播
// 重试引擎(withRetry)
const DEFAULT_MAX_RETRIES = 10
const BASE_DELAY_MS = 500
async function* withRetry(apiCall) {
for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
try {
return yield* apiCall()
} catch (error) {
// ── 按错误类型分策略 ──
// 429 速率限制
if (error.status === 429) {
const retryAfter = error.headers['retry-after']
const delay = retryAfter
? parseInt(retryAfter) * 1000
: BASE_DELAY_MS * Math.pow(2, attempt - 1) // 指数退避
const jitter = delay * 0.25 * Math.random() // 25% 抖动
await sleep(delay + jitter)
continue
}
// 529 过载
if (error.status === 529) {
consecutive529Count++
if (consecutive529Count >= 3) {
// 切换到 fallback 模型
throw new FallbackTriggeredError()
}
await sleep(BASE_DELAY_MS * Math.pow(2, attempt))
continue
}
// 401/403 认证错误
if (error.status === 401 || error.status === 403) {
await refreshOAuthToken() // 刷新 OAuth
clearAWSCredentials() // 清除云凭证缓存
recreateClient() // 重建 API 客户端
continue
}
// ECONNRESET/EPIPE 连接错误
if (isConnectionError(error)) {
disableKeepAlive() // 禁用 keep-alive
continue
}
// 400 上下文溢出
if (error.status === 400 && isContextOverflow(error)) {
adjustMaxTokens(error) // 调整 token 限制
continue
}
// 不可重试错误 → 直接抛出
throw error
}
}
}
// Streaming 回退
// 如果流式 API 失败(超时、代理问题)
// → 回退到非流式 executeNonStreamingRequest()
// → 非流式超时 300s,最多 64K tokens
// → 流式空闲看门狗:90s 无数据 → 中止
// 8 种上下文管理机制协同工作
┌─────────────────────────────────────────────────────┐
│ 上下文窗口管理 │
│ │
│ Pre-API(每次循环迭代前) │
│ ├─ 1. 工具结果预算 限制每消息工具结果总量 │
│ ├─ 2. 快照压缩 移除旧消息,保留尾部 │
│ ├─ 3. 微压缩 清理旧工具结果为占位符 │
│ ├─ 4. 上下文折叠 投影折叠视图 │
│ ├─ 5. 自动压缩 LLM 生成对话摘要 │
│ ├─ 6. Session Memory 用提取的笔记替换旧消息 │
│ └─ 7. 阻塞限制 硬停止(auto-compact 关闭时) │
│ │
│ Post-API(API 调用后) │
│ └─ 8. 响应式压缩 413 错误时触发摘要重试 │
│ │
│ 压缩后恢复 │
│ └─ 重新注入最近读取的 5 个文件(50K token 预算) │
│ 确保压缩后 Agent 仍保有工作上下文 │
└─────────────────────────────────────────────────────┘
// 关键常量:
AUTOCOMPACT_BUFFER_TOKENS = 13_000 // 距窗口顶部的缓冲
WARNING_THRESHOLD_BUFFER_TOKENS = 20_000 // 警告阈值
MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3 // 熔断次数
MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3 // max_tokens 恢复次数
ESCALATED_MAX_TOKENS = 64_000 // 升级后的 token 上限
一个生产级 Agent 需要从多个来源读取配置——用户全局设置、项目级设置、企业策略、CLI 参数等。Claude Code 设计了一套5 层设置合并机制,使用 lodash 的 mergeWith 进行深度合并,并遵循deny 覆盖 allow的安全语义。
// settings.ts — 5 层设置来源定义
export const SETTING_SOURCES = [
'userSettings', // 用户全局 (~/.claude/settings.json)
'projectSettings', // 项目共享 (.claude/settings.json)
'localSettings', // 本地覆盖 (.claude/settings.local.json, gitignore)
'flagSettings', // CLI --settings 参数
'policySettings', // 企业策略 (managed-settings.json 或远程 API)
] as const
// 合并逻辑:按顺序逐层 mergeWith
function mergeAllSettings(): SettingsJson {
let merged: SettingsJson = {}
for (const source of SETTING_SOURCES) {
const settings = loadSettingsForSource(source)
if (settings) {
merged = mergeWith(merged, settings, settingsMergeCustomizer)
}
}
return merged
}
设置合并使用 lodash 的 mergeWith,但加了自定义合并器 settingsMergeCustomizer:
// settingsMergeCustomizer — 自定义合并规则
function settingsMergeCustomizer(objValue: unknown, srcValue: unknown,
key: string, object: unknown, source: unknown, stack: unknown
): unknown {
// 1. 数组:直接替换(不合并)
// 例: permissions.allow = ["Bash"] 覆盖 ["Bash", "Read"]
if (Array.isArray(srcValue)) {
return srcValue
}
// 2. 普通对象:递归合并(默认行为)
// 例: env 变量逐层合并
if (isPlainObject(srcValue) && isPlainObject(objValue)) {
return undefined // 让 lodash 默认递归合并
}
// 3. 基本类型:直接覆盖
// 例: model = "claude-sonnet-4-6" 覆盖 "claude-haiku-4-5"
return srcValue
}
// 特殊处理:policySettings(企业策略)
// 企业策略使用 "first source wins" 语义
// 即策略中定义的值不可被更低层覆盖
function mergePolicySettings(policy: SettingsJson, lower: SettingsJson): SettingsJson {
return mergeWith({}, lower, policy, (objValue, srcValue, key) => {
// 策略值优先,不被覆盖
if (srcValue !== undefined) return srcValue
return objValue
})
}
权限规则的合并遵循一个关键安全原则:deny 永远优先于 allow。无论 allow 在哪一层定义,只要任何一层有 deny 规则匹配,就拒绝执行。
// 权限规则合并后的评估逻辑
function evaluatePermission(
mergedSettings: SettingsJson,
tool: string,
input: unknown
): 'allow' | 'deny' | 'ask' {
const rules = mergedSettings.permissions ?? {}
const allowRules = rules.allow ?? []
const denyRules = rules.deny ?? []
// 1. 先检查 deny — 任何一层的 deny 都生效
for (const rule of denyRules) {
if (matchesRule(rule, tool, input)) {
return 'deny' // 一票否决
}
}
// 2. 再检查 allow
for (const rule of allowRules) {
if (matchesRule(rule, tool, input)) {
return 'allow'
}
}
// 3. 都不匹配 → 询问用户
return 'ask'
}
// 示例:
// userSettings: { permissions: { allow: ["Bash(npm *)"] } }
// projectSettings: { permissions: { deny: ["Bash(rm *)"] } }
// 合并后:
// allow: ["Bash(npm *)"] + deny: ["Bash(rm *)"]
// → npm install 允许, rm -rf 拒绝, git status 询问用户
企业策略(policySettings)中的 deny 规则不可被项目或用户设置覆盖。即使用户在自己的 settings.json 中 allow 了某个操作,如果企业策略 deny 了它,仍然会被拒绝。这是"纵深防御"的体现。
每个设置源加载后都会经过 Zod Schema 验证,确保类型安全:
// types.ts — Settings Schema 定义(简化版)
const PermissionRuleSchema = z.object({
tool: z.string(),
pattern: z.string().optional(), // Bash 命令模式
action: z.enum(['allow', 'deny']),
scope: z.enum(['user', 'project', 'policy']).optional(),
})
const SettingsSchema = z.object({
// 模型配置
model: z.string().optional(),
temperature: z.number().min(0).max(1).optional(),
maxTokens: z.number().positive().optional(),
// 权限配置
permissions: z.object({
allow: z.array(z.union([z.string(), PermissionRuleSchema])).optional(),
deny: z.array(z.union([z.string(), PermissionRuleSchema])).optional(),
}).optional(),
// 环境变量
env: z.record(z.string(), z.string()).optional(),
// Hooks
hooks: z.record(z.string(), z.array(HookSchema)).optional(),
// Feature flags
features: z.record(z.string(), z.boolean()).optional(),
})
// 验证失败时:
// - 记录错误但不阻止启动(graceful degradation)
// - 忽略无效字段,保留有效字段
// - 在 /doctor 命令中显示验证错误
当 Agent 需要执行一个写入操作(如编辑文件)并等待用户确认时,通常会阻塞等待。Claude Code 的推测性执行引擎在等待确认期间,预先执行只读工具(如 Glob、Grep、Read),将结果缓存起来。如果用户批准,结果立即可用;如果拒绝,结果被丢弃。这大幅减少了用户感知的延迟。
推测性执行只允许安全的只读工具,绝不允许写入操作:
// speculation.ts — 工具安全分类
// 安全的只读工具 — 可以推测性执行
const SAFE_READ_ONLY_TOOLS = new Set([
'Read', // 文件读取(不修改文件)
'Glob', // 文件模式匹配(只遍历目录)
'Grep', // 内容搜索(只读)
'ToolSearch', // 工具搜索(不执行工具)
'LSP', // 语言服务查询(只读)
'TaskGet', // 任务查询
'TaskList', // 任务列表
])
// 写入工具 — 绝不推测性执行
const WRITE_TOOLS = new Set([
'Edit', // 文件编辑
'Write', // 文件写入
'NotebookEdit', // Notebook 编辑
])
// Bash — 特殊处理
// 检查命令是否为只读(readOnlyValidation.ts)
// 只读命令如 ls、cat、git status → 可推测
// 写入命令如 rm、mv、npm install → 不可推测
推测性执行的工具可能读取文件,而这些文件可能在用户确认后被主 Agent 修改。为避免脏读,Claude Code 使用了Copy-on-Write (COW) 隔离:
// 推测性执行使用隔离的 overlay 文件系统
// 1. 创建 overlay 目录
const overlayPath = join(getClaudeTempDir(), 'speculation', String(process.pid), speculationId)
await mkdir(overlayPath, { recursive: true })
// 2. 文件读取时,先检查 overlay
async function readWithOverlay(path: string): Promise<string> {
// 如果 overlay 中有这个文件(之前推测性写入的),读 overlay
const overlayFile = join(overlayPath, relative(cwd, path))
if (existsSync(overlayFile)) {
return readFile(overlayFile, 'utf-8')
}
// 否则读真实文件
return readFile(path, 'utf-8')
}
// 3. 推测性写入时,写到 overlay
async function writeWithOverlay(path: string, content: string): Promise<void> {
const overlayFile = join(overlayPath, relative(cwd, path))
await mkdir(dirname(overlayFile), { recursive: true })
await writeFile(overlayFile, content)
writtenPaths.add(relative(cwd, path))
}
// 4. 用户批准后,将 overlay 复制到真实目录
async function commitOverlay(overlayPath: string, writtenPaths: Set<string>) {
for (const rel of writtenPaths) {
const src = join(overlayPath, rel)
const dest = join(cwd, rel)
await mkdir(dirname(dest), { recursive: true })
await copyFile(src, dest)
}
}
// 5. 用户拒绝后,删除 overlay
function discardOverlay(overlayPath: string) {
rm(overlayPath, { recursive: true, force: true })
}
推测性执行不能无限进行——需要知道什么时候"足够了"。Claude Code 使用完成边界来决定何时停止推测:
// 完成边界类型
type CompletionBoundary =
| { type: 'bash'; command: string } // 遇到 Bash 命令 → 停止
| { type: 'edit'; filePath: string } // 遇到文件编辑 → 停止
| { type: 'denied_tool'; toolName: string; detail: string } // 遇到拒绝的工具 → 停止
| { type: 'complete' } // 自然完成
// 边界检测逻辑
function detectBoundary(messages: Message[]): CompletionBoundary | null {
for (const msg of messages) {
if (msg.type === 'assistant') {
for (const block of msg.message.content) {
if (block.type === 'tool_use') {
// 遇到写入工具 → 停止推测
if (WRITE_TOOLS.has(block.name)) {
return { type: 'edit', filePath: block.input.file_path }
}
// 遇到 Bash → 检查是否只读
if (block.name === 'Bash') {
if (!checkReadOnlyConstraints(block.input.command).isReadOnly) {
return { type: 'bash', command: block.input.command }
}
}
}
}
}
}
return null // 没有边界,继续推测
}
Claude Code 最惊艳的优化之一——在模块加载阶段就开始并行 I/O:
// main.tsx — 在所有其他 import 之前
import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';
// 作为模块副作用执行
startMdmRawRead(); // 启动 MDM 子进程(plutil/reg query)
startKeychainPrefetch(); // 启动 Keychain 读取
// ... ~135ms 的模块加载 ...
// 当需要时,结果已经准备好了
await ensureKeychainPrefetchCompleted()
// "零等待"——I/O 在后台已经完成了
设计要点:
// Bun 专有:构建时消除死代码
import { feature } from 'bun:bundle'
// 当 feature('PROACTIVE') 为 false 时:
// 整段代码在编译输出中完全不存在
const SleepTool = feature('PROACTIVE')
? require('./tools/SleepTool/SleepTool.js').SleepTool
: null
// 条件模块加载
const coordinatorModeModule = feature('COORDINATOR_MODE')
? require('./coordinator/coordinatorMode.js')
: null
// 实际使用的 flag 列表:
// PROACTIVE — 主动模式
// KAIROS — 助手模式
// BRIDGE_MODE — IDE 桥接
// DAEMON — 守护进程
// VOICE_MODE — 语音输入
// AGENT_TRIGGERS — 定时触发器
// COORDINATOR_MODE — 多 Agent 协调
// WEB_BROWSER_TOOL — 浏览器控制
// TERMINAL_PANEL — 终端面板
// MONITOR_TOOL — 监控工具
// 运行时懒加载(替代方案)
const SleepTool = await (async () => {
if (config.isProactiveEnabled) {
const mod = await import('./tools/SleepTool/SleepTool.js')
return mod.SleepTool
}
return null
})()
但代价是:未使用的代码仍在最终构建产物中。
重型模块通过 require() 或 import() 延迟加载:
// 1. 循环依赖打破
const getTeammateUtils = () =>
require('./utils/teammate.js') as typeof import('./utils/teammate.js')
// 2. 重型模块延迟加载
const { App } = await import('./components/App.js')
const { REPL } = await import('./screens/REPL.js')
// 3. 功能门控加载
const analytics = await import('./services/analytics/index.js')
plugins/
├── bundled/ ← 内置插件
│ └── index.js
├── loader.ts ← 插件加载器
├── pluginCliCommands.ts ← 插件 CLI 命令
└── ...
// 插件可以:
// 1. 注册新工具(MCPTool 的实现)
// 2. 注册新命令(Slash 命令扩展)
// 3. 注入钩子(pre-tool-use hooks)
// 4. 修改主题
// 插件生命周期:
// 安装 → 加载 → 激活 → 执行 → 卸载
// 安装来源:
// - npm 包 (openclaw-plugin-xxx)
// - MCP 配置 (.mcp.json)
// - 本地路径
skills/
├── bundled/ ← 内置 Skill
│ └── index.js
├── SkillTool.tsx ← Skill 执行工具
└── ...
// Skill = 可复用工作流
// 通过 SkillTool 执行
// 可以被 LLM 发现和使用(ToolSearchTool)
// Skill 定义方式:
// 1. 在 skills/ 目录下创建 .md 文件
// 2. 描述执行步骤和工具调用
// 3. LLM 读取后按指示执行
Claude Code 的 Bash 安全系统是行业标杆级别的实现:
// bashSecurity.ts — 多层安全防御
// Layer 1: 命令解析
// 使用 tree-sitter 解析命令结构
// 识别管道、子 shell、重定向、后台执行
// Layer 2: 危险模式检测
const COMMAND_SUBSTITUTION_PATTERNS = [
/\$\(/, // $() 命令替换 — 常见的 bypass 手法
/\$\{/, // ${} 参数替换
/<\(/, // <() 进程替换
/>\(/, // >() 进程替换
...
// 防患于未然
/<#/, // PowerShell 注释语法(即使当前不用 PowerShell)
]
// Layer 3: Zsh 特定危险命令黑名单
const ZSH_DANGEROUS_COMMANDS = new Set([
'zmodload', // 模块加载 → sysopen/ztcp 等攻击向量
'emulate', // -c flag = eval 等价
'sysopen', // zsh/system 文件操作绕过
'ztcp', // zsh/net/tcp 网络外传
'zf_rm', // zsh/files 内置 rm(绕过二进制检查)
...
])
// Layer 4: 路径验证(目录穿越防护)
// Layer 5: 命令语义(只读 vs 写操作)
// Layer 6: 沙箱执行(高危命令隔离环境)
// 权限级别:
// 0: 完全允许(只读命令)
// 1: 询问(常规文件操作)
// 2: 危险(破坏性操作)
// 3: 禁止(永远不会允许的操作)
// 遥测安全设计
type AnalyticsMetadata = {
// 类型表示:显式声明"这不是代码或文件路径"
// 强制开发者确认不包含敏感信息
}
// 日志过滤
// - 不记录命令参数中的敏感内容
// - 不记录文件路径(仅记录操作类型计数)
// - 不上传代码内容(仅代码统计:行数、类型)
// 会话安全
// - 会话文件仅本地存储
// - OAuth Token 存储在系统 Keychain
// - 远程连接需要用户显式确认
// cost-tracker.ts — 全链路成本追踪
type StoredCostState = {
totalCostUSD: number // 总费用
totalAPIDuration: number // API 耗时
totalAPIDurationWithoutRetries: number
totalToolDuration: number // 工具执行耗时
totalLinesAdded: number // 新增行数
totalLinesRemoved: number // 删除行数
modelUsage: Record<string, ModelUsage> // 按模型统计
}
// 预算控制
// 启动时可设置 --max-budget-usd
// 达到预算上限时,Agent 停止执行新查询
// 按模型成本计算
// 不同模型有不同的输入/输出单价
// Cache 命中/创建也有不同价格
// /cost 命令显示:
// Total: $1.42 | Duration: 3m 42s
// Model: claude-sonnet-4 (42% of cost)
// ├─ Input: 124,832 tokens ($0.52)
// ├─ Output: 24,183 tokens ($0.88)
// └─ Cache: 12,340 tokens ($0.02)
// Lines changed: +312 / -45
AI Agent 系统的测试比传统软件更复杂——你需要测试确定性逻辑(工具执行、权限检查)和非确定性行为(LLM 响应)。Claude Code 的测试策略分为四层:单元测试 → 集成测试 → 回归测试 → 混沌测试。
// 工具单元测试示例
// 1. 测试 BashTool 的只读验证
describe('BashTool readOnlyValidation', () => {
it('应允许只读命令', () => {
expect(checkReadOnlyConstraints('ls -la').isReadOnly).toBe(true)
expect(checkReadOnlyConstraints('cat file.txt').isReadOnly).toBe(true)
expect(checkReadOnlyConstraints('git status').isReadOnly).toBe(true)
expect(checkReadOnlyConstraints('grep -r "foo" .').isReadOnly).toBe(true)
})
it('应拒绝写入命令', () => {
expect(checkReadOnlyConstraints('rm -rf /').isReadOnly).toBe(false)
expect(checkReadOnlyConstraints('mv a b').isReadOnly).toBe(false)
expect(checkReadOnlyConstraints('npm install').isReadOnly).toBe(false)
expect(checkReadOnlyConstraints('echo "hi" > file').isReadOnly).toBe(false)
})
it('应检测管道中的写入操作', () => {
expect(checkReadOnlyConstraints('cat file | sort > output').isReadOnly).toBe(false)
expect(checkReadOnlyConstraints('ls | grep foo').isReadOnly).toBe(true)
})
})
// 2. 测试设置合并逻辑
describe('Settings merge', () => {
it('应按层级合并', () => {
const user = { model: 'claude-haiku-4-5', env: { A: '1' } }
const project = { model: 'claude-sonnet-4-6' }
const result = mergeAllSettings([user, project])
expect(result.model).toBe('claude-sonnet-4-6') // 项目覆盖用户
expect(result.env.A).toBe('1') // 用户的 env 保留
})
it('数组应替换而非合并', () => {
const user = { permissions: { allow: ['Bash'] } }
const project = { permissions: { allow: ['Read'] } }
const result = mergeAllSettings([user, project])
expect(result.permissions.allow).toEqual(['Read']) // 替换,不是合并
})
it('deny 应覆盖 allow', () => {
const settings = {
permissions: {
allow: ['Bash(npm *)'],
deny: ['Bash(rm *)'],
}
}
expect(evaluatePermission(settings, 'Bash', { command: 'npm install' })).toBe('allow')
expect(evaluatePermission(settings, 'Bash', { command: 'rm -rf /' })).toBe('deny')
})
})
// 3. 测试 Zod Schema 验证
describe('Settings validation', () => {
it('应接受有效配置', () => {
const result = SettingsSchema.safeParse({ model: 'claude-sonnet-4-6' })
expect(result.success).toBe(true)
})
it('应拒绝无效配置', () => {
const result = SettingsSchema.safeParse({ temperature: 5.0 }) // 超出范围
expect(result.success).toBe(false)
})
})
// Agent Loop 集成测试(需要真实 API)
describe('Agent Loop integration', () => {
// 使用小模型(Haiku)降低测试成本
const TEST_MODEL = 'claude-haiku-4-5'
it('应完成简单的文件读取任务', async () => {
const agent = new AgentLoop({ model: TEST_MODEL })
const result = await agent.query({
messages: [createUserMessage('读取 package.json 的内容')],
tools: [ReadTool, GlobTool],
})
// 验证:Agent 应该调用 Read 或 Glob 工具
const toolCalls = extractToolCalls(result.messages)
expect(toolCalls.length).toBeGreaterThan(0)
expect(['Read', 'Glob']).toContain(toolCalls[0].name)
}, 30_000) // 30 秒超时
it('应在权限拒绝后停止', async () => {
const agent = new AgentLoop({
model: TEST_MODEL,
permissionContext: {
mode: 'default',
alwaysDenyRules: { Bash: ['rm *'] },
},
})
const result = await agent.query({
messages: [createUserMessage('删除 temp 目录')],
tools: [BashTool],
})
// 验证:Agent 尝试了 rm,被拒绝后应告知用户
const deniedCalls = result.messages.filter(m =>
m.type === 'user' && m.message.content.includes('denied')
)
expect(deniedCalls.length).toBeGreaterThan(0)
}, 30_000)
})
// Golden Prompt 回归测试
// 固定输入 → 验证预期的工具调用序列
describe('Golden Prompts', () => {
const GOLDEN_CASES = [
{
name: '查找 TODO 注释',
prompt: '列出所有 TODO 注释',
expectedTools: ['Grep'],
expectedPattern: /TODO/,
},
{
name: '创建新文件',
prompt: '创建一个 hello.js 文件,内容是 console.log("hello")',
expectedTools: ['Write'],
expectedFile: 'hello.js',
},
{
name: '运行测试',
prompt: '运行 npm test',
expectedTools: ['Bash'],
expectedCommand: /npm test/,
},
]
for (const tc of GOLDEN_CASES) {
it(`Golden: ${tc.name}`, async () => {
const agent = new AgentLoop({ model: TEST_MODEL })
const result = await agent.query({
messages: [createUserMessage(tc.prompt)],
tools: getAllTools(),
})
const toolCalls = extractToolCalls(result.messages)
expect(toolCalls.map(t => t.name)).toEqual(
expect.arrayContaining(tc.expectedTools)
)
}, 30_000)
}
})
// 混沌测试 — 模拟各种故障场景
describe('Chaos Testing', () => {
it('应处理 API 超时', async () => {
const agent = new AgentLoop({
model: TEST_MODEL,
// Mock: 第一次调用超时,第二次成功
apiClient: createMockClient({
responses: [
{ error: new TimeoutError('Request timed out') },
{ content: [{ type: 'text', text: 'Done' }] },
],
}),
})
const result = await agent.query({
messages: [createUserMessage('Hello')],
})
// 验证:Agent 重试后成功
expect(result.messages[result.messages.length - 1].message.content)
.toContain('Done')
})
it('应处理 429 限流', async () => {
const agent = new AgentLoop({
apiClient: createMockClient({
responses: [
{ error: { status: 429, headers: { 'retry-after': '1' } } },
{ content: [{ type: 'text', text: 'OK' }] },
],
}),
})
const startTime = Date.now()
await agent.query({ messages: [createUserMessage('Hello')] })
// 验证:等待了 retry-after 时间
expect(Date.now() - startTime).toBeGreaterThanOrEqual(1000)
})
it('应处理畸形 API 响应', async () => {
const agent = new AgentLoop({
apiClient: createMockClient({
responses: [
// 返回没有 content 的响应
{ content: null },
],
}),
})
// 验证:不崩溃,返回错误信息
const result = await agent.query({
messages: [createUserMessage('Hello')],
})
expect(result.error).toBeDefined()
})
it('应处理工具执行超时', async () => {
const agent = new AgentLoop({
tools: [{
...BashTool,
execute: async () => {
await sleep(60_000) // 模拟超时
return 'done'
},
}],
})
const result = await agent.query({
messages: [createUserMessage('运行一个很慢的命令')],
timeout: 5_000, // 5 秒超时
})
// 验证:超时后 Agent 不崩溃
expect(result.error).toContain('timeout')
})
})
// 权限系统测试矩阵
describe('Permission Matrix', () => {
const MODES = ['default', 'plan', 'bypassPermissions', 'auto']
const TOOLS = ['Bash', 'Read', 'Edit', 'Write']
const INPUTS = [
{ tool: 'Bash', input: { command: 'ls' } }, // 只读
{ tool: 'Bash', input: { command: 'rm -rf /' } }, // 危险
{ tool: 'Edit', input: { file_path: '/src/a.ts' } }, // 写入
{ tool: 'Read', input: { file_path: '/src/a.ts' } }, // 只读
]
for (const mode of MODES) {
for (const { tool, input } of INPUTS) {
it(`mode=${mode}, tool=${tool}, input=${JSON.stringify(input)}`, () => {
const result = evaluatePermission(mode, tool, input)
// plan 模式:写入工具应被拦截
if (mode === 'plan' && ['Edit', 'Write'].includes(tool)) {
expect(result).toBe('deny')
}
// bypass 模式:所有工具应被允许
if (mode === 'bypassPermissions') {
expect(result).toBe('allow')
}
// 只读工具在所有模式下都应允许
if (tool === 'Read') {
expect(result).toBe('allow')
}
})
}
}
})
这是一个逐阶段的检查清单,你可以按顺序参考:
🤖 愿你的 Agent 稳定运行,永不爆 token
基于 Claude Code 源码 (2026-03-31) 架构逆向分析
仅供学习与参考