《Claude Code 设计与实现》完整目录

• 前言
• 第1章 为什么需要理解 Claude Code
• 第2章 架构总览
• 第3章 CLI 启动与性能优化
• 第4章 Query 引擎：Agent 的心脏
• 第5章 流式消息与状态机（当前）
• 第6章 工具类型系统设计
• 第7章 工具编排与并发执行
• 第8章 核心工具实现剖析
• 第9章 多模式权限模型
• 第10章 Bash 安全与沙箱
• 第11章 MCP 协议集成
• 第12章 IDE Bridge 通信架构
• 第13章 LSP 与语言服务
• 第14章 多 Agent 协调与 Swarm
• 第15章 Skill 与插件系统
• 第16章 上下文管理与自动压缩
• 第17章 React + Ink 终端 UI
• 第18章 设计模式与架构决策

"In a stream, every drop of water knows the way." – Lao Tzu

:::tip 本章要点

• Claude Code 消息类型体系的完整层级：从核心四元组到上下文管理消息，再到流事件
• queryModelWithStreaming 中 API SSE 事件的逐块累积与 AssistantMessage 的构造过程
• handleMessageFromStream 如何将异构消息流映射为 React/Ink 组件可消费的状态更新
• CompactBoundaryMessage、TombstoneMessage、ToolUseSummaryMessage 三种特殊消息的设计意图
• 用户取消 (AbortController)、流式超时 (Idle Watchdog)、模型降级 (Fallback) 三条错误恢复路径
• 流式工具执行器 StreamingToolExecutor 如何实现工具与模型响应的并行流水线 :::

上一章我们深入剖析了 Query 引擎的循环架构，理解了 query.ts 如何以 while(true) 驱动整个 Agent 回合。但在那条宏观流水线上，有一个关键环节我们尚未展开：从 API 返回的原始 SSE (Server-Sent Events) 字节流，如何被解析为结构化的消息对象，再经过一系列变换最终呈现在用户面前？

这正是本章要回答的核心问题。流式消息系统是 Claude Code 的神经网络——它不只是简单地搬运数据，而是在搬运过程中完成类型判定、状态追踪、UI 驱动、错误拦截等多重职责。理解这套系统，是掌握 Claude Code 从"能用"到"好用"之间那道鸿沟的关键。

在传统的请求-响应模式中，客户端发送请求，等待服务器返回完整响应，然后一次性处理。这种模式对于短文本生成尚可接受，但当模型需要输出数千 token 的代码、执行多轮工具调用时，用户将面临漫长的白屏等待。流式处理彻底改变了这个范式：服务器在生成每个 token 时就立即推送给客户端，客户端在接收的同时就开始渲染。这不仅仅是体验优化——它从根本上改变了系统的架构约束，要求每个环节都能处理"不完整"的数据，并在数据逐步完善的过程中维护一致的状态。

以下类图展示了 Claude Code 消息类型体系的完整层级关系：

5.1.1 设计哲学：联合类型的分发艺术

Claude Code 的消息体系建立在 TypeScript 的判别联合类型 (Discriminated Union) 之上。所有消息通过 type 字段区分，每种类型携带与其职责严格匹配的字段集合。这种设计使得编译器能够在每个 switch 分支中自动收窄类型，消除运行时的类型断言需求。

从 src/utils/messages.ts 的导入声明中，我们可以看到完整的消息类型版图：

 
  
    
    
 
     
// 文件：src/utils/messages.ts（节选导入声明） 
 
     
import type { AssistantMessage, AttachmentMessage, Message, NormalizedAssistantMessage, NormalizedMessage, NormalizedUserMessage, ProgressMessage, RequestStartEvent, StreamEvent, SystemAgentsKilledMessage, SystemAPIErrorMessage, SystemApiMetricsMessage, SystemAwaySummaryMessage, SystemBridgeStatusMessage, SystemCompactBoundaryMessage, SystemInformationalMessage, SystemLocalCommandMessage, SystemMemorySavedMessage, SystemMessage, SystemMicrocompactBoundaryMessage, SystemPermissionRetryMessage, SystemScheduledTaskFireMessage, SystemStopHookSummaryMessage, SystemTurnDurationMessage, TombstoneMessage, ToolUseSummaryMessage, UserMessage, } from ‘../types/message.js’
 
    

 
这个导入列表揭示了一个关键的架构决策：消息类型并非简单的四元组 (System / User / Assistant / Tool Result)，而是一个经过精心分层的类型层级，包含核心消息类型 、系统消息子类型 、流事件类型 和上下文管理类型四个维度。
 

值得注意的是，这些类型定义在独立的 types/message.ts 文件中（编译后通过 .js 引用），然后被 utils/messages.ts 这个超过五千行的工具模块所消费。类型定义与工具函数的分离确保了类型可以被跨模块引用而不产生循环依赖------这在 Claude Code 这样的大型项目中是至关重要的架构纪律。整个消息系统遵循"类型在上、工具在中、组件在下"的三层结构：类型层定义数据的形状，工具层提供创建和变换消息的纯函数，组件层负责渲染和交互。

5.1.2 核心消息四元组

Claude Code 的核心消息类型与 Claude API 的消息角色模型一一对应，但在此基础上添加了大量元数据：

AssistantMessage 是模型响应的载体。每个 AssistantMessage 都包裹着一个完整的 API BetaMessage 对象，同时附加了 Claude Code 特有的状态字段：

 
  
    
    
 
     
// 文件：src/utils/messages.ts（baseCreateAssistantMessage 函数，展示字段结构） 
 
     
function baseCreateAssistantMessage({ content, isApiErrorMessage = false, apiError, error, errorDetails, isVirtual, usage = { /* 默认零值 */ }, }: { … }): AssistantMessage { return {
 
     
type: 'assistant', uuid: randomUUID(), timestamp: new Date().toISOString(), message: { id: randomUUID(), container: null, model: SYNTHETIC_MODEL, role: 'assistant', stop_reason: 'stop_sequence', stop_sequence: '', type: 'message', usage, content, context_management: null, }, requestId: undefined, apiError, // 'max_output_tokens' | 'prompt_too_long' 等 error, // SDK 层面的错误分类 errorDetails, // 人类可读的错误描述 isApiErrorMessage, // 标记此消息是否为合成错误消息 isVirtual, // 标记是否为非 API 产生的虚拟消息 
 
     
} }
 
    

 
这里有一个精妙的设计：apiError 字段的存在意味着 AssistantMessage 不仅承载模型的正常响应，还承载 API 层面的错误信息。当模型输出超过 max_output_tokens 限制、或请求超过上下文窗口时，系统不会抛出异常，而是生成一个带有 apiError 标记的 AssistantMessage。这让上层的恢复逻辑可以用统一的消息处理管道来处理正常响应和错误------第4章中分析的 "扣留-恢复" 机制正是建立在这个设计之上。
 

UserMessage 是用户输入和工具结果的统一载体：

 
  
    
    
 
     
// 文件：src/utils/messages.ts 
 
     
export function createUserMessage({ content, isMeta, isVisibleInTranscriptOnly, isVirtual, isCompactSummary, toolUseResult, mcpMeta, uuid, timestamp, imagePasteIds, sourceToolAssistantUUID, permissionMode, origin, … }: { … }): UserMessage { const m: UserMessage = {
 
     
type: 'user', message: { role: 'user', content: content || NO_CONTENT_MESSAGE, }, isMeta, // 元消息，不显示给用户 isVisibleInTranscriptOnly, // 仅在转录中可见 isVirtual, // 非真实用户输入 isCompactSummary, // 压缩摘要标记 toolUseResult, // 工具执行的结构化输出 sourceToolAssistantUUID, // 对应的 tool_use 所在 assistant 消息 permissionMode, // 发送时的权限模式快照 origin, // 消息来源：human / hook / slash_command uuid: (uuid as UUID) || randomUUID(), timestamp: timestamp ?? new Date().toISOString(), ... 
 
     
} return m }
 
    

 
UserMessage 的 content 字段可以是纯文本字符串，也可以是 ContentBlockParam[] 数组（包含 tool_result、image、text 等块类型）。当作为工具结果使用时，content 数组中会包含 tool_result 类型的块，并通过 sourceToolAssistantUUID 字段追溯到发起工具调用的那条 AssistantMessage。
 

SystemMessage 是系统内部信息的载体。与前两种消息不同，SystemMessage 通过 subtype 字段进一步细分为十余种子类型，每种子类型携带不同的附加字段。这种设计避免了创建过多顶层类型带来的 switch 分支爆炸问题。

5.1.3 系统消息的子类型谱系

系统消息的 subtype 字段构成了一个完整的运行时事件谱系：

每种子类型的工厂函数都确保了字段完整性------调用者无需手动组装 timestamp、uuid 等公共字段。例如 createCompactBoundaryMessage 函数：

 
  
    
    
 
     
// 文件：src/utils/messages.ts 
 
     
export function createCompactBoundaryMessage( trigger: ‘manual’ | ‘auto’, preTokens: number, lastPreCompactMessageUuid?: UUID, userContext?: string, messagesSummarized?: number, ): SystemCompactBoundaryMessage { return {
 
     
type: 'system', subtype: 'compact_boundary', content: 'Conversation compacted', isMeta: false, timestamp: new Date().toISOString(), uuid: randomUUID(), level: 'info', compactMetadata: { trigger, // 'manual' 或 'auto' preTokens, // 压缩前的 token 数 userContext, // 用户上下文快照 messagesSummarized, // 被摘要的消息数量 }, ...(lastPreCompactMessageUuid && { logicalParentUuid: lastPreCompactMessageUuid, }), 
 
     
} }
 
    

 
5.1.4 流事件与元消息
 

除了持久化的消息类型外，还有三种"短生命周期"的事件类型，它们在流式管道中流转，但不会被存入消息历史：

StreamEvent 是 API SSE 事件的薄包装。它携带原始的 BetaRawMessageStreamEvent（如 message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop），以及可选的 ttftMs（首 token 响应时间）字段。StreamEvent 的职责是驱动 UI 的实时更新------spinner 模式切换、流式文本显示、工具输入预览等。

RequestStartEvent 是查询循环每次迭代开始时发出的信号，类型为 { type: 'stream_request_start' }。它告知 UI 层新的 API 请求即将发起，触发 spinner 进入 "requesting" 状态。

ProgressMessage 是工具执行过程中的进度报告。每个 ProgressMessage 都绑定到一个特定的 toolUseID 和 parentToolUseID，UI 层据此将进度信息关联到对应的工具调用 UI 组件中：

 
  
    
    
 
     
// 文件：src/utils/messages.ts 
 
     
export function createProgressMessage
 
     
({ toolUseID, parentToolUseID, data, }: { toolUseID: string parentToolUseID: string data: P }): ProgressMessage
 
     
 { return {
 
     
type: 'progress', data, // 工具特定的进度数据 toolUseID, // 当前工具调用的 ID parentToolUseID, // 父级工具调用 ID（用于子代理场景） uuid: randomUUID(), timestamp: new Date().toISOString(), 
 
     
} }
 
    

 
AttachmentMessage 是附件信息的载体，用于在消息流中注入上下文信息------如记忆内容、技能发现结果、钩子执行结果、排队命令等。它通过 attachment.type 字段区分不同种类的附件。AttachmentMessage 在消息流中扮演着"侧信道"的角色：它不是对话的直接内容，而是为模型提供额外的决策依据。例如，当自动记忆系统检测到与当前对话相关的历史偏好时，会通过 AttachmentMessage 注入上下文；当钩子系统在工具执行前后产生输出时，同样通过 AttachmentMessage 传递给模型。这种设计将"核心对话"和"辅助上下文"清晰分离，使得压缩系统在需要精简上下文时，可以优先剔除附件而不影响对话的连贯性。
 

5.1.5 消息归一化：从多内容块到单内容块

一个 API 响应可能包含多个内容块（thinking + text + tool_use），但 UI 渲染需要每条消息对应一个内容块。normalizeMessages 函数承担了这个拆分职责：

// 文件：src/utils/messages.ts export function normalizeMessages(messages: Message[]): NormalizedMessage[] { let isNewChain = false return messages.flatMap(message => { switch (message.type) { case 'assistant': { isNewChain = isNewChain || message.message.content.length > 1 return message.message.content.map((_, index) => { const uuid = isNewChain ? deriveUUID(message.uuid, index) : message.uuid return { type: 'assistant' as const, message: { ...message.message, content: [_] }, uuid, // ...其他字段 } as NormalizedAssistantMessage }) } // ...user 消息类似处理 } }) }

deriveUUID 函数通过将索引编码到 UUID 的末12位来生成确定性的派生 UUID，确保同一条消息在不同渲染周期中始终获得相同的 key------这对 React 的 reconciliation 至关重要。

以下时序图展示了从 API SSE 事件到 UI 渲染的完整流式数据通路：

5.2.1 AsyncGenerator：数据流的脊柱

Claude Code 的流式架构建立在 JavaScript 的 AsyncGenerator 协议之上。这不是偶然的技术选择，而是经过深思熟虑的架构决策。

从最底层的 API 调用到最上层的 UI 消费，整条数据管道由三层嵌套的异步生成器组成：

queryModelWithStreaming() 底层：API SSE -> StreamEvent | AssistantMessage | v queryLoop() 中层：编排工具执行、错误恢复、续行判断 | v REPL.tsx onQueryEvent() 上层：React 状态更新

这里选择 AsyncGenerator 而非 RxJS Observable 或 Node.js Stream 有着明确的理由。AsyncGenerator 是语言原语，不需要任何库依赖；它的 pull-based 语义天然适合需要精确流控的场景；它可以用标准的 try/finally 进行资源清理，用 yield* 进行生成器组合。而 Observable 的 push-based 模型虽然在事件组合方面更强大，但对背压的处理更加复杂，且 TypeScript 对 Observable 操作符链的类型推断不如对 Generator 的 yield 类型推断精确。

每一层的 yield 语句都是一个"发布点"，而 for await...of 循环则是对应的"订阅点"。这种设计的优势在于：

1. 天然的背压控制 ：消费者不调用 next()，生产者就不会继续执行。当 UI 渲染跟不上数据产生速度时，流自动暂停。
2. 惰性求值：工具执行等昂贵操作只在消费者拉取时才真正执行。
3. 统一的取消机制 ：通过 generator.return() 可以从任意层级关闭整条管道。
4. 类型安全的多态流 ：每层生成器的 yield 类型声明清晰地定义了该层可以产生的消息种类。

中层 queryLoop 的类型签名精确地表达了它可以产生的所有消息类型：

// 文件：src/query.ts async function* queryLoop( params: QueryParams, consumedCommandUuids: string[], ): AsyncGenerator< | StreamEvent | RequestStartEvent | Message | TombstoneMessage | ToolUseSummaryMessage, Terminal > { // ... }

返回类型 Terminal 是查询循环的终结原因（如 'completed'、'aborted_streaming'、'model_error'、'prompt_too_long' 等），它被上层用于决定后续行为。

5.2.2 SSE 事件的逐块累积

以下状态机图展示了 SSE 事件的逐块累积过程，从原始事件流到结构化消息的构建：

底层的 queryModel 函数（位于 src/services/api/claude.ts）负责将 Anthropic API 的原始 SSE 事件流转换为结构化的 AssistantMessage 和 StreamEvent。这个过程的核心是一个逐块累积状态机：

// 文件：src/services/api/claude.ts（queryModel 函数核心循环，简化展示） let partialMessage: BetaMessage | undefined const contentBlocks: BetaContentBlock[] = [] let usage: Usage = EMPTY_USAGE for await (const part of stream) { switch (part.type) { case 'message_start': partialMessage = part.message ttftMs = Date.now() - start usage = updateUsage(usage, part.message?.usage) break case 'content_block_start': switch (part.content_block.type) { case 'tool_use': contentBlocks[part.index] = { ...part.content_block, input: '' } break case 'text': contentBlocks[part.index] = { ...part.content_block, text: '' } break case 'thinking': contentBlocks[part.index] = { ...part.content_block, thinking: '', signature: '', } break } break case 'content_block_delta': switch (part.delta.type) { case 'input_json_delta': contentBlock.input += delta.partial_json break case 'text_delta': contentBlock.text += delta.text break case 'thinking_delta': contentBlock.thinking += delta.thinking break case 'signature_delta': contentBlock.signature = delta.signature break } break case 'content_block_stop': { const m: AssistantMessage = { message: { ...partialMessage, content: normalizeContentFromAPI( [contentBlock], tools, options.agentId, ), }, type: 'assistant', uuid: randomUUID(), requestId: streamRequestId ?? undefined, timestamp: new Date().toISOString(), } newMessages.push(m) yield m // <-- 每完成一个内容块就立即 yield break } case 'message_delta': usage = updateUsage(usage, part.usage) stopReason = part.delta.stop_reason // 直接修改已 yield 的最后一条消息的 usage（引用共享） const lastMsg = newMessages.at(-1) if (lastMsg) { lastMsg.message.usage = usage lastMsg.message.stop_reason = stopReason } break } // 每个 SSE 事件都会作为 StreamEvent yield 出去 yield { type: 'stream_event', event: part, ...(ttftMs ? { ttftMs } : {}) } }

这段代码揭示了几个重要的设计决策：

决策一：每个内容块独立 yield，而非等待整个消息完成 。API 响应的一个 message 可能包含多个 content_block（例如先是 thinking，然后是 text，最后是 tool_use）。Claude Code 在每个 content_block_stop 事件到达时就立即构造并 yield 一个 AssistantMessage，而不是等到 message_stop。这使得 UI 可以在 thinking 完成后立即渲染 thinking 内容，无需等待后续的 text 或 tool_use 块。这个决策还有一个更深层的影响：它使得 StreamingToolExecutor 能够在模型还在输出后续内容块时，就开始执行已完成的 tool_use 块------这是流水线并行的基础。

决策二：原始事件和结构化消息双流并行 。queryModel 既 yield AssistantMessage（完整的结构化消息，用于消息历史），又 yield StreamEvent（原始 SSE 事件包装，用于驱动实时 UI 更新）。消费者通过 message.type 判别来选择性地处理两种数据。

决策三：usage 的引用修改而非对象替换 。message_delta 事件到达时，代码直接修改已经 yield 的消息对象的 usage 和 stop_reason 属性，而不是创建新对象。源码注释明确解释了原因：转录写入队列持有消息对象的引用并延迟序列化（100ms 刷新间隔），对象替换会导致队列引用断裂，丢失���终的 token 计数。

5.2.3 流式管道的完整数据流图

 
  
    
    
 
     
API Server (SSE) 
 
     
| | message_start / content_block_start / content_block_delta | content_block_stop / message_delta / message_stop v queryModel() [src/services/api/claude.ts] | | yield StreamEvent (每个 SSE 事件) | yield AssistantMessage (每个 content_block_stop) | yield SystemAPIErrorMessage (API 错误、超限等) v queryLoop() [src/query.ts] | | yield* 透传 StreamEvent / AssistantMessage | yield UserMessage (工具结果) | yield ProgressMessage (工具执行进度) | yield TombstoneMessage (Fallback 时删除孤儿消息) | yield SystemMessage (压缩边界、模型切换等) | yield ToolUseSummaryMessage (工具批次摘要) | yield AttachmentMessage (上下文附件) | yield RequestStartEvent (新请求开始) v REPL.tsx onQueryEvent() [src/screens/REPL.tsx] | | handleMessageFromStream() 路由分发 | | | |– StreamEvent -> 更新 spinner/streaming 状态 | |– AssistantMessage -> 追加到 messages 数组 | |– TombstoneMessage -> 从 messages 数组移除 | |– ProgressMessage -> 替换或追加进度消息 | |– CompactBoundaryMessage -> 重置 messages 数组 | |– 其他 -> 追加到 messages 数组 v React/Ink 渲染管线 | | normalizeMessages() -> 拆分多内容块消息 | buildMessageLookups() -> O(1) 关系查询表 | Message.tsx -> 按类型分发到子组件 v 终端输出
 
    

5.3.1 handleMessageFromStream：流事件路由器

handleMessageFromStream 是连接底层数据流与上层 UI 状态的关键函数。它接收混合类型的消息流，并通过回调函数将不同类型的消息分发到对应的状态更新器：

 
  
    
    
 
     
// 文件：src/utils/messages.ts 
 
     
export function handleMessageFromStream( message: Message | TombstoneMessage | StreamEvent
 
     
| RequestStartEvent | ToolUseSummaryMessage, 
 
     
onMessage: (message: Message) => void, onUpdateLength: (newContent: string) => void, onSetStreamMode: (mode: SpinnerMode) => void, onStreamingToolUses: (
 
     
f: (streamingToolUse: StreamingToolUse[]) => StreamingToolUse[], 
 
     
) => void, onTombstone?: (message: Message) => void, onStreamingThinking?: ( … ) => void, onApiMetrics?: (metrics: { ttftMs: number }) => void, onStreamingText?: (f: (current: string | null) => string | null) => void, ): void {
 
    

 
函数的处理逻辑分为两个主要分支：
 

分支一：非流事件（完成的消息） 。当收到的不是 stream_event 也不是 stream_request_start 时，说明这是一条完整的消息。对于 tombstone 类型，调用 onTombstone 回调移除目标消息；对于 tool_use_summary 类型，直接忽略（SDK 专用）；对于 assistant 类型，提取其中的 thinking 块更新流式思考状态；最终清除流式文本状态并调用 onMessage 将消息追加到 React 状态中。

分支二：流事件（SSE 事件） 。这是实时性要求最高的路径。函数根据 event.type 进行二级分发：

 
  
    
    
 
     
// 文件：src/utils/messages.ts（handleMessageFromStream 流事件处理部分） 
 
     
switch (message.event.type) { case ‘content_block_start’:
 
     
switch (message.event.content_block.type) { case 'thinking': case 'redacted_thinking': onSetStreamMode('thinking') // Spinner 显示 "Thinking..." return case 'text': onSetStreamMode('responding') // Spinner 显示 "Responding..." return case 'tool_use': { onSetStreamMode('tool-input') // Spinner 显示工具名称 onStreamingToolUses(_ => [..._, { index, contentBlock, unparsedToolInput: '', }]) return } } 
 
     
case ‘content_block_delta’:
 
     
switch (message.event.delta.type) { case 'text_delta': onUpdateLength(deltaText) onStreamingText?.(text => (text ?? '') + deltaText) return case 'input_json_delta': onUpdateLength(delta) onStreamingToolUses(_ => { /* 追加 JSON 片段 */ }) return case 'thinking_delta': onUpdateLength(message.event.delta.thinking) return case 'signature_delta': // 不计入长度------密码学签名不是模型输出 return } 
 
     
case ‘message_stop’:
 
     
onSetStreamMode('tool-use') onStreamingToolUses(() => []) // 清空流式工具状态 return 
 
     
}
 
    

 
5.3.2 REPL 中的消息消费
 

REPL 组件通过 useCallback 创建 onQueryEvent 回调，将 handleMessageFromStream 的各个回调参数绑定到 React 状态更新器上：

 
  
    
    
 
     
// 文件：src/screens/REPL.tsx（简化展示核心消费逻辑） 
 
     
for await (const event of query()) { onQueryEvent(event) }
 
    

 
onQueryEvent 内部的 onMessage 回调根据消息类型执行不同的状态更新策略：
 

• CompactBoundaryMessage ：重置整个 messages 数组，仅保留边界消息及其后的内容。同时递增 conversationId 以迫使 React 重新挂载所有消息组件，避免缓存的组件引用到过期数据。
• ProgressMessage（临时型） ：如 sleep_progress 或 bash_progress，采用替换策略而非追加。每秒一次的进度 tick 如果全部追加，长时间运行的 Bash 命令会导致消息数组膨胀到 13000+ 条，转录文件暴涨至 120MB。
• ProgressMessage（状态型） ：如 agent_progress、hook_progress、skill_progress，仍采用追加策略，因为每条进度消息都承载着不同的状态信息（如子代理的工具调用历史）。
• TombstoneMessage：从消息数组中过滤掉目标消息，并同步从转录文件中移除。
• 其他消息：简单追加到消息数组末尾。

5.3.3 Message.tsx 的类型分发渲染

消息到达 React 状态后，Message.tsx 组件根据消息类型分发到对应的渲染子组件：

 
  
    
    
 
     
// 文件：src/components/Message.tsx（核心 switch 逻辑） 
 
     
switch (message.type) { case "attachment":
 
     
return 
     
       
        
 
     
case "assistant":
 
     
// 根据 content[0] 的类型进一步分发 // thinking -> AssistantThinkingMessage // redacted_thinking -> AssistantRedactedThinkingMessage // text -> AssistantTextMessage（含 StreamingMarkdown） // tool_use -> AssistantToolUseMessage // advisor -> AdvisorMessage 
 
     
case "system":
 
     
// compact_boundary -> CompactBoundaryMessage // 其他 -> SystemTextMessage 
 
     
case "user":
 
     
// image -> UserImageMessage // tool_result -> UserToolResultMessage // text -> UserTextMessage 
 
     
case "grouped_tool_use":
 
     
return 
     
       
        
 
     
case "collapsed_read_search":
 
     
return 
     
       
        
 
     
}
 
    

 
这里 normalizeMessages 的拆分效果体现了出来：由于每条归一化后的消息只有一个内容块，Message.tsx 的 switch 逻辑只需处理单块场景，大幅降低了渲染复杂度。
 

5.3.4 MessageLookups：O(1) 的关系查询

消息之间存在复杂的关系——tool_use 对应 tool_result，tool_use 与同一 assistant 消息中的其他 tool_use 是"兄弟"关系，progress 消息需要关联到对应的 tool_use。如果每个组件在渲染时都遍历整个消息数组来查找这些关系，复杂度将是 O(n * m)，在长对话中不可接受。

buildMessageLookups 函数在每次渲染前做一次 O(n) 的预计算，构建多个查找表：

 
  
    
    
 
     
// 文件：src/utils/messages.ts 
 
     
export type MessageLookups = { siblingToolUseIDs: Map 
      
        > // tool_use 的兄弟关系 progressMessagesByToolUseID: Map 
       
         // 进度消息 inProgressHookCounts: Map 
        
          > // 运行中的钩子 toolResultByToolUseID: Map 
         
           // 工具结果 toolUseByToolUseID: Map 
          
            // 工具调用 resolvedToolUseIDs: Set 
           
             // 已完成的工具调用 erroredToolUseIDs: Set 
            
              // 出错的工具调用 normalizedMessageCount: number // 归一化后的消息总数 } 
              
             
            
           
          
         
        
      
 
    

 
渲染时每个 MessageRow 组件只需 O(1) 地从 lookups 中读取所需数据，避免了 O(n^2) 的性能陷阱。这个优化对长会话至关重要：在一个包含 2800 条消息的会话中，如果每条消息都遍历全部消息来查找关系，单次渲染就需要约 800 万次比较。预计算将其降低到 2800 次遍历加上 N 次 O(1) 查找，性能提升了三个数量级。
 

源码中 Messages.tsx 文件头部的注释也佐证了这个性能关注点：当 Logo 组件意外地在每次渲染时标记为 dirty，会触发所有后续 MessageRow 从零开始重写，在 2800 条消息的会话中产生 15 万次以上的写操作，将 CPU 利用率推到 100%。Claude Code 的工程师通过 React.memo 和精心设计的依赖数组来避免这种级联失效。

5.4.1 CompactBoundaryMessage：历史的分水岭

CompactBoundaryMessage 是 Claude Code 上下文管理系统最关键的标记消息。当对话长度接近模型的上下文窗口限制时，自动压缩（Auto-Compact）机制会触发：将当前所有消息发送给一个辅助模型生成摘要，然后用摘要替换原始消息。CompactBoundaryMessage 就是这个替换操作的分界线。

它在消息流中的位置具有双重语义：

对 API 来说 ，getMessagesAfterCompactBoundary 函数会找到最后一个 CompactBoundary，只将其之后的消息发送给模型。Boundary 本身是 system 类型，会在 normalizeMessagesForAPI 阶段被过滤掉，不会进入 API 请求。

 
  
    
    
 
     
// 文件：src/utils/messages.ts 
 
     
export function getMessagesAfterCompactBoundary< T extends Message | NormalizedMessage, >(messages: T[], options?: { includeSnipped?: boolean }): T[] { const boundaryIndex = findLastCompactBoundaryIndex(messages) const sliced = boundaryIndex === -1 ? messages : messages.slice(boundaryIndex) // … }
 
    

 
对 UI 来说，CompactBoundaryMessage 渲染为一条简洁的分隔线，提示用户对话已被压缩，并显示查看历史的快捷键：
 
  
    
    
 
     
// 文件：src/components/messages/CompactBoundaryMessage.tsx 
 
     
export function CompactBoundaryMessage(): React.ReactNode { const historyShortcut = useShortcutDisplay(
 
     
'app:toggleTranscript', 'Global', 'ctrl+o', 
 
     
) return (
 
     
 
     
       
        
        
          Conversation compacted ({historyShortcut} for history) 
         
        
 
     
) }
 
    

 
CompactBoundary 的设计体现了一个重要的架构原则：标记而非删除 。压缩操作不会从消息数组中物理删除旧消息，而是在旧消息和新摘要之间插入一个边界标记。上层代码通过 getMessagesAfterCompactBoundary 做逻辑切片，只取边界之后的消息发送给 API。这意味着原始消息仍然保留在内存中（直到 REPL 主动清理），转录文件中也有完整记录，用户随时可以通过 Ctrl+O 查看完整历史。这种设计在数据完整性和运行时效率之间取得了平衡。
 

在全屏模式下，REPL 会保留最近一个压缩区间的消息用于滚动回看，而非简单地丢弃：

 
  
    
    
 
     
// 文件：src/screens/REPL.tsx 
 
     
if (isFullscreenEnvEnabled()) ),
 
     
newMessage, 
 
     
]) } else 
 
    

 
5.4.2 CompactMetadata：压缩操作的完整记录
 

每个 CompactBoundaryMessage 都携带 compactMetadata 结构体，记录了压缩操作的关键信息：

• trigger：触发方式，'auto' 或 'manual'（用户执行 /compact 命令）
• preTokens：压缩前的 token 数量
• userContext：用户上下文的快照
• messagesSummarized：被摘要的消息数量
• preservedSegment：保留段信息（当使用部分压缩时）

在 SDK 层面，这些元数据通过 toSDKCompactMetadata / fromSDKCompactMetadata 进行驼峰/蛇形命名转换，确保内部使用驼峰命名，对外接口使用蛇形命名。

5.4.3 MicrocompactBoundaryMessage：轻量级的上下文回收

除了全量压缩外，Claude Code 还有一种更轻量的上下文管理机制------微压缩（Microcompact）。它不生成摘要，而是直接将超出一定大小的工具结果替换为简短的占位符。微压缩边界消息记录了操作的统计信息：

 
  
    
    
 
     
// 文件：src/utils/messages.ts 
 
     
export function createMicrocompactBoundaryMessage( trigger: ‘auto’, preTokens: number, tokensSaved: number, compactedToolIds: string[], clearedAttachmentUUIDs: string[], ): SystemMicrocompactBoundaryMessage { return {
 
     
type: 'system', subtype: 'microcompact_boundary', content: 'Context microcompacted', microcompactMetadata: { trigger, preTokens, tokensSaved, // 节省的 token 数 compactedToolIds, // 被清理的工具调用 ID 列表 clearedAttachmentUUIDs, // 被清理的附件 UUID 列表 }, // ... 
 
     
} }
 
    

 
微压缩在查询循环中运行在自动压缩之前。如果微压缩已经将 token 数降到阈值以下，自动压缩就不需要触发，从而保留了更细粒度的上下文信息。
 

5.4.4 TombstoneMessage：幽灵消息的清理

TombstoneMessage 是一种"删除指令"——它不代表新内容，而是指示消费者移除一条已存在的消息。它的结构很简单：

 
  
    
    
 
     
// TombstoneMessage 的使用场景： 
 
     
yield { type: ‘tombstone’ as const, message: msg }
 
    

 
TombstoneMessage 最重要的使用场景是模型降级（Streaming Fallback）。当主模型的流式响应中途失败，系统切换到降级模型重试时，已经 yield 出去的部分消息（特别是 thinking 块）必须被撤回。如果不撤回，这些部分消息中的 thinking 签名是无效的，在下次 API 调用中会导致 "thinking blocks cannot be modified" 错误。
 
  
    
    
 
     
// 文件：src/query.ts（Streaming Fallback 场景） 
 
     
if (streamingFallbackOccured) { // 为所有孤儿消息发出墓碑标记 for (const msg of assistantMessages) {
 
     
yield { type: 'tombstone' as const, message: msg } 
 
     
} // 清空累积状态，准备接收降级模型的新响应 assistantMessages.length = 0 toolResults.length = 0 toolUseBlocks.length = 0 needsFollowUp = false }
 
    

 
在 REPL 端，tombstone 的处理包含两个动作：
 
  
    
    
 
     
// 文件：src/screens/REPL.tsx 
 
     
tombstonedMessage => 
 
    

 
不仅从内存中的消息数组移除，还从磁盘上的转录文件中移除，确保一致性。
 

5.4.5 ToolUseSummaryMessage：给移动端的贴心翻译

ToolUseSummaryMessage 是一种仅在 SDK 层面可见的消息类型，不参与终端 UI 渲染。它的目的是为移动端等无法显示完整工具交互细节的客户端，提供一段人类可读的工具执行摘要：

 
  
    
    
 
     
// 文件：src/utils/messages.ts 
 
     
export function createToolUseSummaryMessage( summary: string, precedingToolUseIds: string[], ): ToolUseSummaryMessage { return {
 
     
type: 'tool_use_summary', summary, // 如 "Read 3 files and edited main.ts" precedingToolUseIds, // 关联的 tool_use ID 列表 uuid: randomUUID(), timestamp: new Date().toISOString(), 
 
     
} }
 
    

 
摘要的生成是异步的------在当前工具批次完成后，系统将工具调用信息发送给一个轻量模型（如 Haiku），让它生成自然语言摘要。这个 Promise 被存入 pendingToolUseSummary，在下一次循环迭代开始时 await：
 
  
    
    
 
     
// 文件：src/query.ts 
 
     
// 上一轮的摘要在流式响应期间并行生成 if (pendingToolUseSummary) }
 
    

 
这种"先发起、后收割"的模式使得摘要生成的耗时（约1秒的 Haiku 调用）完全被模型的流式响应时间（5-30秒）所遮盖。需要注意的是，ToolUseSummaryMessage 只在主线程中生成，子代理的工具调用不会产生摘要------因为子代理的工具交互不会直接显示在移动端 UI 中，生成摘要只是浪费 Haiku 调用配额。
 

从更宏观的视角来看，ToolUseSummaryMessage 体现了 Claude Code 在多客户端场景下的适配策略。终端 CLI 有足够的屏幕空间显示工具调用的完整细节，而移动端屏幕有限，需要更高密度的信息摘要。通过在流式管道中注入摘要消息，Claude Code 将"信息密度适配"的责任交给了生产端（后端），而非消费端（各客户端独立实现摘要逻辑）。这是一个符合"胖服务端"理念的设计选择。

5.5.1 用户取消：AbortController 的三层传导

Claude Code 使用标准的 AbortController / AbortSignal 机制来处理用户取消（Ctrl+C 或 Escape）。取消信号从 REPL 层向下传导：

 
  
    
    
 
     
REPL.tsx 
 
     
|– abortController.abort(‘interrupt’) | v query.ts / queryLoop() |– toolUseContext.abortController.signal.aborted === true |– 检测时机：流式响应完成后、工具执行完成后 | v StreamingToolExecutor |– siblingAbortController（子级，用于取消并行工具） |– 为未完成的工具生成合成 tool_result
 
    

 
取消后的关键操作是确保tool_use / tool_result 配对完整。如果模型已经发出了 tool_use 块但工具还没执行完，系统必须为每个孤儿 tool_use 生成一个错误类型的 tool_result，否则下次 API 调用会因为配对不完整而报错。
 

在使用 StreamingToolExecutor 的场景下，执行器会自动处理这个问题：

 
  
    
    
 
     
// 文件：src/query.ts 
 
     
if (toolUseContext.abortController.signal.aborted)
 
     
} 
 
     
} else {
 
     
yield* yieldMissingToolResultBlocks( assistantMessages, 'Interrupted by user', ) 
 
     
} yield createUserInterruptionMessage({ toolUse: true }) return { reason: ‘aborted_tools’ } }
 
    

 
yieldMissingToolResultBlocks 是一个辅助生成器，为每个 tool_use 块生成对应的错误 tool_result：
 
  
    
    
 
     
// 文件：src/query.ts 
 
     
function* yieldMissingToolResultBlocks( assistantMessages: AssistantMessage[], errorMessage: string, ) { for (const assistantMessage of assistantMessages) {
 
     
const toolUseBlocks = assistantMessage.message.content.filter( content => content.type === 'tool_use', ) as ToolUseBlock[] for (const toolUse of toolUseBlocks) { yield createUserMessage({ content: [{ type: 'tool_result', content: errorMessage, is_error: true, tool_use_id: toolUse.id, }], toolUseResult: errorMessage, sourceToolAssistantUUID: assistantMessage.uuid, }) } 
 
     
} }
 
    

 
5.5.2 流式超时：Idle Watchdog
 

网络连接可能在流式传输中悄然断裂------TCP keepalive 检测到连接丢失需要数分钟，而用户看到的是界面无响应。Claude Code 通过一个空闲看门狗（Idle Watchdog）来解决这个问题：

 
  
    
    
 
     
// 文件：src/services/api/claude.ts 
 
     
const STREAM_IDLE_TIMEOUT_MS = 90_000 // 90 秒 const STREAM_IDLE_WARNING_MS = STREAM_IDLE_TIMEOUT_MS / 2 // 45 秒
 
     
function resetStreamIdleTimer(): void , STREAM_IDLE_WARNING_MS)
 
     
// 90 秒无事件：主动终止流 streamIdleTimer = setTimeout(() => {
 
     
streamIdleAborted = true releaseStreamResources() // 释放 TLS/Socket 原生内存 
 
     
}, STREAM_IDLE_TIMEOUT_MS) }
 
     
// 每次收到 SSE 事件时重置定时器 for await (const part of stream) 
 
    

 
当看门狗触发后，streamIdleAborted 标志会被设置。流循环退出后会检测到这个标志，并抛出错误触发非流式降级重试：
 
  
    
    
 
     
if (streamIdleAborted) { 
 
     
throw new Error(‘Stream idle timeout - no chunks received’) }
 
    

 
值得注意的是 releaseStreamResources() 函数显式释放了 Response 对象的 body stream，这是为了避免 Node.js TLS 缓冲区导致的原生内存泄漏------这些内存生活在 V8 堆之外，GC 无法自动回收。
 

5.5.3 模型降级与非流式重试

除了 Idle Watchdog 外，Claude Code 还处理另一种流式失败：API 返回了有效的 SSE 流，但内容不完整（没有 message_start、或有 message_start 但没有 content_block_stop）。这通常是代理服务器或 CDN 层面的故障：

 
  
    
    
 
     
// 文件：src/services/api/claude.ts 
 
     
if (!partialMessage || (newMessages.length === 0 && !stopReason)) { throw new Error(‘Stream ended without receiving any events’) }
 
    

 
这个 throw 会被外层的 withRetry 重试框架捕获。withRetry 在流式尝试全部失败后，会切换到非流式 API 调用作为最终降级方案。非流式请求的超时时间独立配置（本地 300 秒、远程 120 秒），确保在 CDN 抽风时也能获得响应。
 

当发生流式到非流式的降级切换时，系统通过 onStreamingFallback 回调通知查询循环。循环检测到降级后，会：

1. 对已 yield 的 assistant 消息发出 tombstone 标记
2. 清空所有累积状态
3. 丢弃 StreamingToolExecutor 中的待处理结果并创建新实例
4. 继续处理降级模型返回的响应

// 文件：src/query.ts if (streamingFallbackOccured) { for (const msg of assistantMessages) { yield { type: 'tombstone' as const, message: msg } } assistantMessages.length = 0 toolResults.length = 0 toolUseBlocks.length = 0 needsFollowUp = false if (streamingToolExecutor) { streamingToolExecutor.discard() streamingToolExecutor = new StreamingToolExecutor( toolUseContext.options.tools, canUseTool, toolUseContext, ) } }

5.5.4 StreamingToolExecutor：流水线并行

传统的工具执行模式是"等模型响应完全结束，再依次执行所有工具"。Claude Code 的 StreamingToolExecutor 将这个过程优化为流水线模式------模型每 yield 出一个 tool_use 块，执行器就立即开始执行（如果并发条件允许）：

 
  
    
    
 
     
// 文件：src/services/tools/StreamingToolExecutor.ts 
 
     
export class StreamingToolExecutor { private tools: TrackedTool[] = []
 
     
addTool(block: ToolUseBlock, assistantMessage: AssistantMessage): void {
 
     
// 判断工具是否支持并发（isConcurrencySafe） // 如果支持且当前无排他工具在执行，立即启动 // 否则加入队列等待 
 
     
}
 
     
getCompletedResults(): MessageUpdate[] {
 
     
// 按添加顺序返回已完成的工具结果 // 保证结果顺序与 tool_use 块顺序一致 
 
     
}
 
     
async *getRemainingResults(): AsyncGenerator 
      
        { 
      
 
     
// 等待所有剩余工具完成（含取消场景的合成结果） 
 
     
} }
 
    

 
每个被追踪的工具有四种状态：queued（等待执行）、executing（执行中）、completed（已完成）、yielded（已被消费）。并发安全的工具（如文件读取）可以与其他并发安全工具同时执行；非并发安全的工具（如 Bash 命令）则需要独占执行权。
 

在查询循环中，这两个阶段交织进行：

 
  
    
    
 
     
// 文件：src/query.ts（流式响应循环内部） 
 
     
for await (const message of deps.callModel({ … })) }
 
     
// 收割已完成的工具结果 for (const result of streamingToolExecutor.getCompletedResults()) } }
 
    

 
这种设计使得模型还在输出下一个 tool_use 块时，上一个工具可能已经完成执行。对于 "读取5个文件" 这种常见场景，工具执行时间可以完全隐藏在模型的 token 生成时间内，显著降低了端到端延迟。
 

值得一提的是，StreamingToolExecutor 内部维护了一个子级 AbortController（siblingAbortController），它是 toolUseContext.abortController 的子控制器。当一个 Bash 工具执行出错时，这个子控制器会被触发，立即终止正在并行执行的其他工具（如正在等待的文件读取），但不会影响父级控制器------这意味着查询循环本身不会终止，模型可以看到工具错误并决定下一步行动。这种"局部取消而非全局取消"的策略，是 Claude Code 在鲁棒性和响应性之间精心设计的平衡点。

5.6.1 为何选择联合类型而非类继承

Claude Code 的消息类型全部使用 TypeScript 的联合类型（union type）而非类继承。这个选择有几个深层原因：

序列化友好 。消息需要频繁地在进程间传递（主线程与子代理）、持久化到磁盘（转录文件）、通过网络发送（SDK 协议）。纯数据对象可以直接 JSON.stringify，类实例则需要自定义序列化逻辑。

模式匹配的人体工学 。TypeScript 的类型收窄在 switch 语句中工作得非常好——每个 case 分支中编译器自动知道具体类型的所有字段。如果使用类继承加 instanceof 检查，在处理从 JSON 反序列化回来的对象时会失效（因为反序列化产生的是纯对象，不是类实例）。

扩展性 。添加新的消息类型只需在联合中添加一个成员，不需要修改任何基类或接口，也不会影响现有的处理逻辑——未匹配的 default 分支自然处理了新类型。

5.6.2 StreamEvent 与 AssistantMessage 的双流设计

为什么 queryModel 既 yield StreamEvent 又 yield AssistantMessage，而不是只选其一？

答案在于两类消费者的需求差异。StreamEvent 承载的是过程信息——text_delta 的每个字符增量、thinking 的逐步展开、tool_use 输入的 JSON 片段。这些信息是 UI 实时动画（打字机效果、spinner 模式切换）的驱动力，但它们是易失的、增量的，不适合存入消息历史。

AssistantMessage 承载的是结果信息——一个完整的内容块，包含解析后的 tool input、完整的 thinking 文本等。这些信息需要被存入消息数组、发送给 API（作为历史上下文）、序列化到转录文件。

将两者合一会导致消费者不得不做大量的"这是增量还是终态"的判断；将两者分离则让每个消费者只处理自己关心的数据形态。

5.6.3 引用修改 vs 对象替换的权衡

message_delta 事件的处理中对已 yield 消息的引用修改，是整个消息系统中最"不纯"的设计。它违反了不可变数据的原则，但源码注释详细解释了为什么这是正确的选择：

转录写入队列异步运行，使用 100ms 的刷新间隔。如果在 message_delta 到达时创建新的消息对象，队列持有的旧引用将永远看不到最终的 usage 和 stop_reason 值。用引用修改确保了所有持有该消息引用的消费者（转录队列、分析系统、SDK 输出管道）都能看到最终值，而不需要复杂的同步机制。

这是一个务实的工程决策——在需要跨异步边界共享可变状态时，直接修改有时比构建精巧的通知机制更可靠。Claude Code 的代码库中对此类设计有严格的注释规范：每处引用修改都附有详细的理由说明，解释为什么在该场景下不可变原则让位于实际需求。这种"带理由的例外"模式比教条式地坚持不可变性更有工程价值。

5.6.4 SDK 消息转换层的隔离设计

Claude Code 的消息类型系统存在内部表示和外部表示两套体系。内部使用驼峰命名（compactMetadata、preTokens），外部 SDK 使用蛇形命名（compact_metadata、pre_tokens）。两套体系之间通过 src/utils/messages/mappers.ts 中的转换函数桥接：

toSDKMessages 函数将内部消息数组转换为 SDK 协议格式，而 toInternalMessages 则执行反向转换。这种隔离的好处是显而易见的：内部类型可以自由演进（添加字段、重命名、调整结构），只需在转换层做适配，不影响外部 SDK 消费者。同时，转换层也是过滤敏感信息的天然关卡——例如 local_command 类型的系统消息中的命令输入元数据不会泄漏到 SDK 输出中，只有实际的标准输出和标准错误内容才会被转换。

这种分层转换的设计模式在 Claude Code 中被广泛运用：除了消息转换外，权限类型、配置类型、钩子类型都有类似的内部/外部表示分离。这让 Claude Code 能够在保持内部重构自由的同时，向外部承诺稳定的 API 契约。

本章从消息类型定义出发，沿着数据流的方向，完整地追踪了一条 API 响应如何经历 SSE 解析、逐块累积、状态机分发、React 状态更新，最终呈现在终端屏幕上的全过程。

核心要点回顾：

1. 消息类型层级：以判别联合类型为基础，分为核心四元组（Assistant / User / System / Progress）、流事件（StreamEvent / RequestStartEvent）和管理消息（Tombstone / ToolUseSummary / CompactBoundary）三个层次。
2. 流式架构 ：三层嵌套的 AsyncGenerator 提供了天然的背压控制和类型安全的多态流。底层 queryModel 在每个 content_block_stop 时 yield 结构化消息，同时双流并行输出原始 SSE 事件。
3. UI 消费 ：handleMessageFromStream 作为路由器，将异构消息流分发到对应的 React 状态更新器。normalizeMessages 拆分多内容块消息，buildMessageLookups 预计算 O(1) 查找表。
4. 上下文管理 ：CompactBoundaryMessage 是压缩的分水岭，TombstoneMessage 是消息撤回的机制，ToolUseSummaryMessage 是给移动端的语义翻译。
5. 错误恢复：AbortController 三层传导处理用户取消，Idle Watchdog 处理网络断裂，Streaming Fallback 处理流式降级，三条路径协同确保系统的鲁棒性。
6. 流式工具执行 ：StreamingToolExecutor 实现了模型响应与工具执行的流水线并行，将工具执行延迟隐藏在模型生成时间内。

从全局视角审视，本章揭示的流式消息系统是整个 Claude Code 架构中"高内聚、低耦合"原则的典范实践。消息类型定义、流式传输管道、UI 渲染组件、错误恢复逻辑——每个子系统都有清晰的职责边界和明确的接口契约。它们之间通过 AsyncGenerator 的 yield/for-await 协议松散耦合，任何一层的实现变更都不会波及其他层次。这种架构弹性，正是 Claude Code 能够在快速迭代中保持代码质量的根基。

下一章，我们将进入工具系统的设计与实现，看看 Claude Code 如何将 "能读文件、能写代码、能执行命令" 这些核心能力抽象为统一的工具协议。