消息系统与渲染

在 Claude Code 这款终端原生 AI 编程助手中，消息系统是整个用户交互体验的基石。与 Web 应用不同，终端环境的渲染能力极为有限——没有 DOM、没有 CSS 动画、只有固定宽度的字符网格。然而，Claude Code 却在这个受限的舞台上实现了消息队列管理、Markdown 富文本渲染、语法高亮、数学公式、表格排版乃至虚拟滚动等高级功能。本文将深入解析这套消息系统与渲染引擎的完整链路。

一、消息队列管理：utils/messages.ts

utils/messages.ts（193KB）是整个消息系统的"心脏"，负责消息的生命周期管理——创建、归一化、排序、查找和引用关系维护。

1.1 消息类型体系

Claude Code 的消息体系远比简单的"用户提问-AI 回答"二元模型复杂。源码中定义了四大核心消息类型：

// 来源：src/utils/messages.ts，约第 120-180 行（基于导入类型推断）
type Message =
  | UserMessage      // 用户消息（含 tool_result）
  | AssistantMessage // 助手消息（含 text/thinking/tool_use）
  | SystemMessage    // 系统消息（错误、权限、摘要等）
  | AttachmentMessage // 附件消息（文件、Hook 结果等）

UserMessage 不仅承载用户输入的纯文本，还通过 ContentBlockParam 支持多模态内容——文本块、图片块（ImageBlockParam）以及工具结果块（ToolResultBlockParam）。AssistantMessage 则包含文本、思考过程（ThinkingBlock）、已编辑的思考（RedactedThinkingBlock）和工具调用（ToolUseBlock）等多种内容块。

SystemMessage 是 Claude Code 消息系统的独特设计，它不是 API 层面的 system role，而是 UI 层面的系统通知，包含 20 余种 subtype：

// 来源：src/types/message.ts（由 messages.ts 导入的类型推断）
type SystemMessageSubtype =
  | 'api_error'        // API 错误（认证失败、速率限制等）
  | 'api_metrics'      // API 指标（TTFT、token 统计）
  | 'compact_boundary' // 会话压缩边界
  | 'permission_retry' // 权限重试提示
  | 'informational'    // 一般信息通知
  | 'local_command'    // 本地命令执行结果
  | 'memory_saved'     // 记忆保存确认
  | 'away_summary'     // 离开期间摘要
  | 'scheduled_task'   // 定时任务触发
  // ... 还有更多

1.2 消息创建工厂函数

messages.ts 提供了一系列工厂函数来创建不同类型的消息，确保消息对象的结构一致性：

// 来源：src/utils/messages.ts，约第 400-500 行
export function createAssistantMessage({
  content,
  usage,
  isVirtual,
}: {
  content: string | BetaContentBlock[]
  usage?: Usage
  isVirtual?: true
}): AssistantMessage {
  return baseCreateAssistantMessage({
    content:
      typeof content === 'string'
        ? [
            {
              type: 'text' as const,
              text: content === '' ? NO_CONTENT_MESSAGE : content,
            } as BetaContentBlock,
          ]
        : content,
    usage,
    isVirtual,
  })
}

export function createUserMessage({
  content,
  isMeta,
  isVisibleInTranscriptOnly,
  // ... 20+ 个可选参数
}): UserMessage {
  const m: UserMessage = {
    type: 'user',
    message: {
      role: 'user',
      content: content || NO_CONTENT_MESSAGE,
    },
    isMeta,
    isVisibleInTranscriptOnly,
    // ...
    uuid: (uuid as UUID | undefined) || randomUUID(),
    timestamp: timestamp ?? new Date().toISOString(),
  }
  return m
}

这些工厂函数的精妙之处在于对边缘情况的处理：空内容自动替换为 NO_CONTENT_MESSAGE，UUID 延迟生成，时间戳默认当前时刻。isMeta 标记用于区分"真正的人类输入"和系统注入的元消息（如本地命令的标准输出包装），这对后续的消息过滤至关重要。

1.3 消息归一化与排序

消息在传入渲染层之前需要经过**归一化（normalize）**处理。一个关键场景是将包含多个 ContentBlock 的用户消息拆分为多个独立的 NormalizedMessage，以便每个内容块都能独立渲染：

// 来源：src/utils/messages.ts，约第 800-900 行
// 将多 block 的用户消息拆分为每条一个 block 的归一化消息
.map((_, index) => {
  const isImage = _.type === 'image'
  const imageId =
    isImage && message.imagePasteIds
      ? message.imagePasteIds[imageIndex]
      : undefined
  if (isImage) imageIndex++
  return {
    ...createUserMessage({
      content: [_],
      // ... 保留原消息元数据
      imagePasteIds: imageId !== undefined ? [imageId] : undefined,
      origin: message.origin,
    }),
    uuid: isNewChain ? deriveUUID(message.uuid, index) : message.uuid,
  } as NormalizedMessage
})

另一个核心功能是 reorderMessagesInUI，它解决了工具调用（tool_use）与工具结果（tool_result）之间的显示顺序问题。在 API 层面，工具结果作为用户消息发送；但在 UI 层面，用户希望看到"调用-结果"的连贯呈现：

// 来源：src/utils/messages.ts，约第 850-950 行
export function reorderMessagesInUI(
  messages: NormalizedMessage[],
  syntheticStreamingToolUseMessages: NormalizedAssistantMessage[],
): NormalizedMessage[] {
  // 第一遍：按 toolUseID 分组
  const toolUseGroups = new Map<string, {
    toolUse: ToolUseRequestMessage | null
    preHooks: AttachmentMessage[]
    toolResult: NormalizedUserMessage | null
    postHooks: AttachmentMessage[]
  }>()

  // 第二遍：按正确顺序重建消息列表
  // tool_use → preHooks → tool_result → postHooks
}

1.4 消息查找表 buildMessageLookups

在 2800+ 消息的长会话中，线性查找的性能是不可接受的。buildMessageLookups 构建了一系列 Map/Set 结构，将消息查询的时间复杂度从 O(n) 降到 O(1)：

// 来源：src/utils/messages.ts，约第 1200-1400 行
export function buildMessageLookups(
  messages: Message[],
  normalizedMessages: NormalizedMessage[],
) {
  return {
    siblingToolUseIDs,        // Map<toolUseID, siblingIDs[]>
    progressMessagesByToolUseID, // Map<toolUseID, ProgressMessage[]>
    inProgressHookCounts,     // Map<toolUseID, Map<HookEvent, count>>
    resolvedHookCounts,       // Map<toolUseID, Map<HookEvent, count>>
    toolResultByToolUseID,    // Map<toolUseID, NormalizedUserMessage>
    toolUseByToolUseID,       // Map<toolUseID, ToolUseBlockParam>
    resolvedToolUseIDs,       // Set<string>
    erroredToolUseIDs,        // Set<string>
  }
}

这些查找表是渲染层判断"某个工具调用是否已完成""是否有错误""进度消息是什么"的数据基础。例如，erroredToolUseIDs 让 UI 可以将失败的工具调用以红色标记，而 progressMessagesByToolUseID 支持在长时间运行的工具调用上方显示实时进度更新。

1.5 消息 ID 与引用关系

Claude Code 实现了短消息 ID 系统，用于用户通过 snip 工具引用历史消息：

// 来源：src/utils/messages.ts，约第 170-190 行
export function deriveShortMessageId(uuid: string): string {
  // 从 UUID 取前 10 个十六进制字符（去掉横线）
  const hex = uuid.replace(/-/g, '').slice(0, 10)
  // 转 base36，取前 6 位
  return parseInt(hex, 16).toString(36).slice(0, 6)
}

这个函数是确定性的——相同的 UUID 总是产生相同的短 ID。这些短 ID 以 [id:xxxxx] 标签的形式注入到 API 绑定的消息中，使模型能够引用特定消息的内容。

消息系统的整体架构可以用下图概括：

flowchart TD
    A[API 原始消息] --> B[消息归一化
normalizeMessages]
    B --> C[消息排序
reorderMessagesInUI]
    C --> D[构建查找表
buildMessageLookups]
    D --> E{消息类型?}
    E -->|assistant| F[AssistantMessage
text/thinking/tool_use]
    E -->|user| G[UserMessage
text/image/tool_result]
    E -->|system| H[SystemMessage
error/metrics/boundary]
    E -->|attachment| I[AttachmentMessage
file/hook/progress]
    F --> J[渲染层]
    G --> J
    H --> J
    I --> J

二、消息渲染组件架构

渲染层由三个核心组件构成：Messages.tsx（147KB）作为消息列表容器，Message.tsx（79KB）作为单条消息的分发器，MessageRow.tsx 作为消息行的布局包装。

2.1 Messages.tsx：列表容器与消息过滤

Messages.tsx 是整个消息渲染的入口，它承担着多项职责：

消息过滤与折叠：在长会话中，Claude Code 会自动折叠某些类型的消息以减少视觉噪音。例如，连续的 ReadTool/GrepTool 调用会被折叠为一个"已折叠的读取/搜索组"：

// 来源：src/components/Messages.tsx，约第 60-120 行（基于导入推断）
import { collapseReadSearchGroups } from '../utils/collapseReadSearch.js'
import { collapseBackgroundBashNotifications } from '../utils/collapseBackgroundBashNotifications.js'
import { collapseHookSummaries } from '../utils/collapseHookSummaries.js'
import { collapseTeammateShutdowns } from '../utils/collapseTeammateShutdowns.js'

Brief 模式过滤：在 KAIROS 功能开启时，支持仅显示 Brief 工具调用及其结果：

// 来源：src/components/Messages.tsx，约第 120-180 行
export function filterForBriefTool<T extends { type: string }>(
  messages: T[],
  briefToolNames: string[],
): T[] {
  const nameSet = new Set(briefToolNames)
  const briefToolUseIDs = new Set<string>()
  return messages.filter(msg => {
    if (msg.type === 'system') return msg.subtype !== 'api_metrics'
    // 只保留 Brief tool_use、其 tool_result 和真实用户输入
    // 如果模型忘记调用 Brief，用户就看不到任何内容
  })
}

Logo Header 的 memo 优化：一个值得注意的性能优化细节是 Logo 区域的 memoization。在 2800 条消息的长会话中，如果 Logo Header 每次 Messages 重渲染时都失效，会导致 renderChildren 的 seenDirtyChild 级联失效，使得所有后续的 MessageRow 都无法使用 blit 优化，每帧产生 15 万+ 次写入，CPU 直接飙到 100%。

// 来源：src/components/Messages.tsx，约第 50-80 行
const LogoHeader = React.memo(function LogoHeader(t0) {
  const $ = _c(3)
  const { agentDefinitions } = t0
  // 只在 agentDefinitions 变化时重新渲染
  // 新 messages 数组不会使 Logo 子树失效
})

2.2 Message.tsx：单条消息分发器

Message.tsx 的职责相对纯粹——根据消息类型分发到对应的子组件：

// 来源：src/components/Message.tsx，约第 45-120 行
function MessageImpl(t0) {
  const { message, lookups, tools, commands, verbose, /* ... */ } = t0

  switch (message.type) {
    case "attachment":
      return <AttachmentMessage /* ... */ />
    case "assistant":
      return message.message.content.map((_, index) => (
        <AssistantMessageBlock
          key={index}
          param={_}
          tools={tools}
          commands={commands}
          // ...
          thinkingBlockId={`${message.uuid}:${index}`}
          lastThinkingBlockId={lastThinkingBlockId}
        />
      ))
    case "user":
      // 分发到 UserTextMessage / UserImageMessage / UserToolResultMessage
    case "system":
      // 分发到 SystemTextMessage
  }
}

对于 assistant 类型的消息，它遍历 message.message.content 数组，为每个 ContentBlock 创建对应的渲染组件。这种"一消息多 block"的渲染模式是归一化的反向操作——在数据层拆分，在渲染层聚合。

2.3 MessageRow：行级布局与交互

MessageRow.tsx 是消息列表中最细粒度的布局单元，它处理：

• 消息连续性判断：isUserContinuation 用于判断上一条消息是否也是用户消息，决定是否需要显示额外的分隔。
• 折叠组状态管理：isActiveCollapsedGroup 判断一个折叠的读取/搜索组是否仍有工具在执行中。
• 进度消息关联：通过 lookups 将进度消息与对应的工具调用关联。

// 来源：src/components/MessageRow.tsx，约第 70-130 行
export type Props = {
  message: RenderableMessage
  isUserContinuation: boolean
  hasContentAfter: boolean
  tools: Tools
  commands: Command[]
  verbose: boolean
  inProgressToolUseIDs: Set<string>
  streamingToolUseIDs: Set<string>
  // ...
}

消息渲染组件的层级关系如下：

flowchart LR
    subgraph 容器层
        A[Messages.tsx]
    end
    subgraph 分发层
        B[Message.tsx]
    end
    subgraph 行层
        C[MessageRow.tsx]
    end
    subgraph 内容层
        D[UserTextMessage]
        E[AssistantTextMessage]
        F[AssistantThinkingMessage]
        G[AssistantToolUseMessage]
        H[UserToolResultMessage]
        I[SystemTextMessage]
        J[AttachmentMessage]
    end
    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H
    C --> I
    C --> J

三、Markdown 渲染引擎

在终端中渲染 Markdown 是一个充满挑战的任务。Claude Code 的 components/Markdown.tsx（28KB）实现了一套混合渲染方案：表格使用 React + Ink 的 flexbox 布局，其他内容渲染为 ANSI 字符串。

3.1 Token 缓存策略

Markdown 解析是渲染流水线中的热点。marked.lexer() 单次调用在长内容上可能耗时约 3ms，而虚拟滚动中消息的反复挂载/卸载会导致重复解析。Markdown.tsx 实现了模块级 Token 缓存：

// 来源：src/components/Markdown.tsx，约第 25-75 行
const TOKEN_CACHE_MAX = 500
const tokenCache = new Map<string, Token[]>()

function cachedLexer(content: string): Token[] {
  // 快速路径：没有 Markdown 语法 → 直接构造单段落 Token
  if (!hasMarkdownSyntax(content)) {
    return [{
      type: 'paragraph',
      raw: content,
      text: content,
      tokens: [{ type: 'text', raw: content, text: content }]
    } as Token]
  }

  const key = hashContent(content)
  const hit = tokenCache.get(key)
  if (hit) {
    // MRU 提升：避免滚动回早期消息时恰好驱逐该条目
    tokenCache.delete(key)
    tokenCache.set(key, hit)
    return hit
  }

  const tokens = marked.lexer(content)
  if (tokenCache.size >= TOKEN_CACHE_MAX) {
    const first = tokenCache.keys().next().value
    if (first !== undefined) tokenCache.delete(first)
  }
  tokenCache.set(key, tokens)
  return tokens
}

缓存使用内容哈希作为键，避免保留完整内容字符串导致的内存泄漏。LRU 策略通过删除-重插实现。更关键的是快速路径：如果内容不包含任何 Markdown 语法标记（通过正则 /[#*|[>-_~]|\n\n|^\d+. |\n\d+. /` 检测），直接构造单段落 Token，跳过完整的 GFM 解析。

3.2 混合渲染策略

MarkdownBody 组件的核心渲染逻辑展示了"表格组件化 + 其余 ANSI 化"的混合策略：

// 来源：src/components/Markdown.tsx，约第 100-140 行
function MarkdownBody(t0) {
  const { children, dimColor, highlight } = t0
  const [theme] = useTheme()
  configureMarked()

  const tokens = cachedLexer(stripPromptXMLTags(children))
  const elements = []
  let nonTableContent = ""

  const flushNonTableContent = () => {
    if (nonTableContent) {
      elements.push(<Ansi key={elements.length} dimColor={dimColor}>
        {nonTableContent.trim()}
      </Ansi>)
      nonTableContent = ""
    }
  }

  for (const token of tokens) {
    if (token.type === "table") {
      flushNonTableContent()
      elements.push(<MarkdownTable key={elements.length}
        token={token as Tokens.Table} highlight={highlight} />)
    } else {
      nonTableContent += formatToken(token, theme, 0, null, null, highlight)
    }
  }
}

这种设计的原因在于：表格需要复杂的列宽计算和对齐处理，使用 Ink 的 Box 布局可以获得更好的控制；而段落、代码块、列表等内容可以直接格式化为 ANSI 转义序列字符串，减少 React 组件树的深度。

3.3 MarkdownTable：终端表格渲染

MarkdownTable.tsx（47KB）是渲染引擎中最复杂的单一组件之一。它需要在终端的固定宽度约束下，完成列宽分配、文本换行和对齐：

// 来源：src/components/MarkdownTable.tsx，约第 60-140 行
export function MarkdownTable({ token, highlight, forceWidth }: Props) {
  const [theme] = useTheme()
  const { columns: actualTerminalWidth } = useTerminalSize()
  const terminalWidth = forceWidth ?? actualTerminalWidth

  // Step 1: 计算每列的最小宽度（最长单词）和理想宽度（完整内容）
  const minWidths = token.header.map((header, colIndex) => {
    let maxMinWidth = getMinWidth(header.tokens)
    for (const row of token.rows) {
      maxMinWidth = Math.max(maxMinWidth, getMinWidth(row[colIndex]?.tokens))
    }
    return maxMinWidth
  })

  const idealWidths = token.header.map((header, colIndex) => {
    let maxIdeal = getIdealWidth(header.tokens)
    for (const row of token.rows) {
      maxIdeal = Math.max(maxIdeal, getIdealWidth(row[colIndex]?.tokens))
    }
    return maxIdeal
  })

  // Step 2: 计算可用空间（扣除边框和安全边距）
  const availableWidth = Math.max(
    terminalWidth - borderOverhead - SAFETY_MARGIN,
    numCols * MIN_COLUMN_WIDTH
  )

  // Step 3: 列宽分配算法
  if (totalIdeal <= availableWidth) {
    columnWidths = idealWidths  // 全部容纳
  } else if (totalMin <= availableWidth) {
    // 给每列最小宽度，按溢出比例分配剩余空间
  } else {
    // 需要 hard wrap：单词也会被截断
  }
}

SAFETY_MARGIN = 4 的设定尤为关键——它为父级缩进（如消息点前缀）和终端尺寸调整的竞争条件预留了余量。没有足够边距时，表格会溢出布局框，Ink 的裁剪在不同帧上表现不一致，导致滚动回溯中出现无限闪烁循环。

当某行换行后的高度超过 MAX_ROW_LINES = 4 时，表格会降级为"垂直（键值对）格式"，以换取更好的可读性。

3.4 KaTeX 数学公式渲染

虽然源码中没有直接看到 KaTeX 的调用，但从 utils/markdown.ts 的 formatToken 函数和 _config.yml 中配置的 markdown-it-katex 可以推断，Claude Code 通过 marked 的扩展支持行内和块级数学公式。终端中的数学公式渲染为纯文本近似，而非 Web 中的精美排版。

四、代码高亮系统

components/HighlightedCode.tsx（17KB）实现了终端环境下的语法高亮，这是将 IDE 体验带入终端的关键组件。

4.1 高亮架构

代码高亮采用"语法分析器 + 主题渲染"的两层架构：

// 来源：src/components/HighlightedCode.tsx，约第 25-85 行
export const HighlightedCode = memo(function HighlightedCode(t0) {
  const { code, filePath, width, dim } = t0
  const ref = useRef(null)
  const [measuredWidth, setMeasuredWidth] = useState(width || DEFAULT_WIDTH)
  const [theme] = useTheme()
  const settings = useSettings()
  const syntaxHighlightingDisabled = settings.syntaxHighlightingDisabled ?? false

  // 动态加载 ColorFile（语法着色引擎）
  const ColorFile = expectColorFile()
  const colorFile = ColorFile ? new ColorFile(code, filePath) : null

  // 测量元素宽度以适配
  useEffect(() => {
    if (!width && ref.current) {
      const { width: elementWidth } = measureElement(ref.current)
      if (elementWidth > 0) {
        setMeasuredWidth(elementWidth - 2)
      }
    }
  }, [width])

  // 渲染为带 ANSI 颜色的行数组
  const lines = colorFile?.render(theme, measuredWidth, dim)

  return (
    <Box ref={ref}>
      {lines ? (
        <Box flexDirection="column">
          {lines.map((line, i) => (
            gutterWidth > 0
              ? <CodeLine key={i} line={line} gutterWidth={gutterWidth} />
              : <Text key={i}><Ansi>{line}</Ansi></Text>
          ))}
        </Box>
      ) : (
        <HighlightedCodeFallback /* ... */ />
      )}
    </Box>
  )
})

4.2 行号 gutter

在全屏模式下（isFullscreenEnvEnabled()），代码块会显示行号 gutter：

// 来源：src/components/HighlightedCode.tsx，约第 85-110 行
const lineCount = countCharInString(code, "\n") + 1
const gutterWidth = lineCount.toString().length + 2

function CodeLine(t0) {
  const { line, gutterWidth } = t0
  const gutterText = sliceAnsi(line, 0, gutterWidth)
  // ... 渲染行号 + 代码内容
}

行号宽度根据总行数的位数动态计算，并用 sliceAnsi（ANSI 感知的字符串切片）处理。

4.3 回退机制

当语法高亮引擎未加载或被用户禁用时，组件优雅降级到 HighlightedCodeFallback，显示无着色的原始代码：

// 来源：src/components/HighlightedCode.tsx，约第 110-130 行
{lines ? (
  <Box flexDirection="column">{/* 高亮代码 */}</Box>
) : (
  <HighlightedCodeFallback
    code={code}
    filePath={filePath}
    dim={dim}
    skipColoring={syntaxHighlightingDisabled}
  />
)}

用户可以通过设置 syntaxHighlightingDisabled 完全关闭高亮功能，这在低性能终端或无障碍访问场景中很有用。

五、附件处理系统

utils/attachments.ts（127KB）处理所有非文本输入——文件引用、图片粘贴、Hook 结果、任务提醒等。

5.1 附件类型体系

附件系统定义了超过 30 种附件类型，构成一个庞大的联合类型：

// 来源：src/utils/attachments.ts，约第 300-600 行
export type Attachment =
  | FileAttachment                    // @引用文件
  | CompactFileReferenceAttachment   // 压缩后的文件引用
  | PDFReferenceAttachment           // PDF 文件
  | AlreadyReadFileAttachment        // 已读文件（避免重复读取）
  | { type: 'edited_text_file', filename, snippet }
  | { type: 'edited_image_file', filename, content }
  | { type: 'directory', path, content, displayPath }
  | { type: 'todo_reminder', content: TodoList }
  | { type: 'task_reminder', content: Task[] }
  | { type: 'queued_command', prompt, commandMode }
  | { type: 'plan_mode', reminderType, planFilePath }
  | { type: 'mcp_resource', server, uri, name }
  // ... 还有更多

其中 queued_command 类型特别值得关注——它处理"在工具执行期间用户输入的新消息"这种 mid-turn 场景。当 Claude 正在执行 BashTool 时，用户输入的内容不会立即发送给 API，而是作为 queued_command 附件暂存，在下一次对话轮次中排空（drain）：

// 来源：src/utils/attachments.ts（由类型定义推断使用场景）
{
  type: 'queued_command'
  prompt: string | Array<ContentBlockParam>
  source_uuid?: UUID
  imagePasteIds?: number[]
  commandMode?: string  // 'prompt' = 用户输入, 'task-notification' = 系统事件
  origin?: MessageOrigin
  isMeta?: boolean
}

5.2 图片粘贴与上传

图片处理是附件系统的另一个关键职责。当用户在终端中粘贴图片时，流程如下：

1. 剪贴板检测：监听终端的剪贴板事件，检测图片数据。
2. 图片验证：调用 validateImagesForAPI 检查图片格式、大小是否符合 API 限制。
3. 尺寸调整：通过 maybeResizeAndDownsampleImageBlock 对大图进行缩放和下采样，控制 token 消耗。
4. ID 分配：为每张图片分配唯一的 imagePasteId，用于在消息中追踪引用关系。
5. 消息注入：将 ImageBlockParam 注入到用户消息的 content 数组中。

// 来源：src/utils/attachments.ts，约第 150-250 行（基于导入推断）
import { maybeResizeAndDownsampleImageBlock } from './imageResizer.js'
import { validateImagesForAPI } from './imageValidation.js'

// 图片粘贴相关
import {
  getImagePasteIds,
  isValidImagePaste,
} from 'src/types/textInputTypes.js'

5.3 Hook 附件生命周期

Hook 系统是 Claude Code 的扩展机制，允许在工具调用的前后执行自定义脚本。Hook 附件记录了这些脚本的执行结果：

// 来源：src/utils/attachments.ts，约第 350-450 行
export type HookAttachment =
  | HookCancelledAttachment
  | { type: 'hook_blocking_error', blockingError, hookName, toolUseID, hookEvent }
  | HookNonBlockingErrorAttachment
  | HookErrorDuringExecutionAttachment
  | { type: 'hook_stopped_continuation', message, hookName, toolUseID, hookEvent }
  | HookSuccessAttachment
  | { type: 'hook_additional_context', content, hookName, toolUseID, hookEvent }
  | HookSystemMessageAttachment
  | HookPermissionDecisionAttachment

每种 Hook 结果类型都携带 toolUseID 和 hookEvent，使 UI 能够将 Hook 输出与特定的工具调用关联。HookPermissionDecisionAttachment 的 decision: 'allow' | 'deny' 则用于自动权限模式下的决策记录。

六、虚拟滚动：支撑万级消息的性能基石

components/VirtualMessageList.tsx（148KB）和 hooks/useVirtualScroll.ts 共同构成了 Claude Code 高性能渲染的最后一块拼图。

6.1 为什么需要虚拟滚动

Ink（Claude Code 使用的 React 终端渲染器）已经在输出层面实现了视口裁剪——不在可见窗口内的节点不会被写入屏幕。但问题在于：所有 React Fiber 和 Yoga 布局节点仍然会被分配。在 1000 条消息的会话中，每个 MessageRow 约占用 250KB RSS，总计约 250MB 的只增不减内存（包括 Ink 屏幕缓冲区、WASM 线性内存、JSC 页面保留等）。

6.2 虚拟滚动的核心设计

useVirtualScroll hook 只挂载视口内 + overscan 范围内的消息，其余位置用 spacer Box 占位：

// 来源：src/hooks/useVirtualScroll.ts，约第 30-80 行
const DEFAULT_ESTIMATE = 3        // 未测量项的高度估计（故意设低）
const OVERSCAN_ROWS = 80          // 视口上下额外渲染的行数
const COLD_START_COUNT = 30       // ScrollBox 布局完成前的初始渲染数
const SCROLL_QUANTUM = OVERSCAN_ROWS >> 1  // scrollTop 量化粒度
const PESSIMISTIC_HEIGHT = 1      // 未测量项的最坏情况高度
const MAX_MOUNTED_ITEMS = 300     // 单次挂载上限
const SLIDE_STEP = 25             // 单次提交最多新挂载的项数

这些常数的设定充满了工程权衡：

• DEFAULT_ESTIMATE = 3：故意设低。高估会导致空白区域（停止挂载过早，视口底部显示空 spacer），低估只会多挂载几个 overscan 项。
• SCROLL_QUANTUM = 40：没有量化时，每次滚轮事件（每格 3-5 次）都会触发完整 React commit + Yoga calculateLayout + Ink diff 循环，造成 CPU 峰值。量化后 React 只在挂载范围需要移动时才重渲染。
• PESSIMISTIC_HEIGHT = 1：保证无论实际项多小，挂载范围都能物理上覆盖到视口底部。代价是在项实际较大时会多挂载（overscan 吸收这个误差）。
• SLIDE_STEP = 25：防止滚动到全新范围时一次性挂载 194 个新项（每个 MessageRow 渲染约 1.5ms，总计约 290ms 的同步阻塞）。通过分多次提交逐步滑动范围，保持每次提交的挂载成本有界。

6.3 增量 Key 数组优化

虚拟滚动中的一个微妙优化是 Key 数组的增量更新：

// 来源：src/components/VirtualMessageList.tsx，约第 200-230 行
const keysRef = useRef<string[]>([])
const prevMessagesRef = useRef<typeof messages>(messages)
const prevItemKeyRef = useRef(itemKey)

if (prevItemKeyRef.current !== itemKey
    || messages.length < keysRef.current.length
    || messages[0] !== prevMessagesRef.current[0]) {
  keysRef.current = messages.map(m => itemKey(m))
} else {
  for (let i = keysRef.current.length; i < messages.length; i++) {
    keysRef.current.push(itemKey(messages[i]!))
  }
}

流式对话中消息是追加式的。重建整个 Key 数组每次提交都分配 O(n) 内存（27000 条消息时约 1MB 的内存抖动）。增量 push 只在追加场景下分配 O(1)，在压缩、清空或 Key 变化时才回退到全量重建。

6.4 搜索与跳转

VirtualMessageList 还集成了消息搜索功能，暴露了一个 JumpHandle 命令式句柄：

// 来源：src/components/VirtualMessageList.tsx，约第 80-120 行
export type JumpHandle = {
  jumpToIndex: (i: number) => void
  setSearchQuery: (q: string) => void
  nextMatch: () => void
  prevMatch: () => void
  setAnchor: () => void
  warmSearchIndex: () => Promise<number>
  disarmSearch: () => void
}

搜索文本在 Messages.tsx 中预先小写化并缓存，这样 setSearchQuery 的每按键循环只做 indexOf（零 toLowerCase 分配）。warmSearchIndex 方法在首次搜索前预提取所有消息的搜索文本，将"首次搜索的延迟"转化为显式的"索引中…"体验。

6.5 Sticky Prompt

在长会话中滚动历史消息时，Claude Code 实现了"Sticky Prompt"功能——将当前用户输入固定在屏幕顶部，方便用户随时看到自己在回复什么：

// 来源：src/components/VirtualMessageList.tsx，约第 140-200 行
function stickyPromptText(msg: RenderableMessage): string | null {
  const cached = promptTextCache.get(msg)
  if (cached !== undefined) return cached

  if (msg.type === 'user') {
    if (msg.isMeta || msg.isVisibleInTranscriptOnly) return null
    const block = msg.message.content[0]
    if (block?.type !== 'text') return null
    // 去掉 system-reminder 前缀后返回用户真正输入的文本
  }
  // ...
}

promptTextCache 使用 WeakMap 缓存结果——消息对象是追加不变的，缓存命中总是有效；而 WeakMap 在消息数组被替换时会自动垃圾回收。

七、总结

Claude Code 的消息系统与渲染引擎是一个在极端约束下精心设计的工程杰作。从 utils/messages.ts 中复杂的消息类型体系、归一化与排序算法，到 components/Markdown.tsx 中带有 MRU 缓存和快速路径的 Markdown 解析器；从 HighlightedCode.tsx 中支持动态测量和优雅降级的语法高亮，到 VirtualMessageList.tsx 中量化滚动、增量 Key 和分步挂载的高性能虚拟滚动——每一个模块都体现了终端应用特有的工程考量。

这套系统的核心设计哲学可以归纳为三点：

1. 数据层与渲染层分离：NormalizedMessage 和 buildMessageLookups 将原始 API 消息转化为渲染友好的形态，让渲染组件专注于展示而非数据转换。
2. 无处不在的缓存：Token 缓存、查找表、搜索文本缓存、Prompt 文本缓存……在终端这种每毫秒都影响交互响应的场景中，缓存不是优化而是必需。
3. 渐进降级：从高亮到无高亮、从表格到键值对、从精确测量到估计高度——系统在每个环节都准备了降级路径，确保即使是最低配置也能获得可用体验。

理解这套消息系统，不仅有助于我们掌握 Claude Code 的内部工作原理，也为构建其他终端原生应用提供了宝贵的架构参考。