【Claude Code源码剖析】06-终端 UI 与 React Ink

Claude Code 使用 React Ink 在终端中渲染富交互界面。这是一个 “React for Terminal” 的应用。

---

一、技术原理

React Ink 是什么？

传统 React:  React → Virtual DOM → 浏览器 DOM → 像素
React Ink:   React → Virtual DOM → 终端字符 → ANSI escape codes

React Ink 把 React 的组件模型映射到终端：

• <Box> → Flexbox 布局（类似 <div>）
• <Text> → 带样式的文本（类似 <span>）
• useState/useEffect → 完全一致
• 但没有浏览器 API（无 DOM、无 CSS）

---

二、UI 架构层次

┌─────────────────────────────────────────┐
│ App.tsx (根组件)                         │
│  ├─ StoreProvider (状态)                 │
│  ├─ ThemeProvider (主题)                 │
│  ├─ NotificationProvider (通知)          │
│  └─ children                             │
│      └─ REPL.tsx (主屏幕, 5006 行!)      │
│          ├─ Messages (消息列表)           │
│          │   ├─ MessageRow → Message     │
│          │   ├─ ToolUseLoader            │
│          │   ├─ FileEditToolDiff         │
│          │   └─ ...                      │
│          ├─ StatusLine (底部状态栏)       │
│          ├─ PromptInput (输入框)         │
│          └─ 各种 Dialog (权限/配置/...)   │
└─────────────────────────────────────────┘

---

三、REPL.tsx — 主屏幕 (5006 行)

这是整个 UI 的 超级组件，管理着：

3.1 核心状态

// REPL.tsx 内的主要 state
const [messages, setMessages] = useState<Message[]>([]);
const [isLoading, setIsLoading] = useState(false);
const [toolJSX, setToolJSX] = useState<React.ReactNode | null>(null);
const [permissionRequest, setPermissionRequest] = useState(null);
const [elicitation, setElicitation] = useState(null);
const [inputValue, setInputValue] = useState('');
const [promptMode, setPromptMode] = useState<PromptInputMode>('normal');

3.2 消息处理循环

// 当用户提交输入时
async function handleSubmit(text: string) {
  // 1. 处理斜杠命令
  if (isSlashCommand(text)) {
    await processCommand(text);
    return;
  }

  // 2. 创建用户消息
  const userMessage = createUserMessage({ content: text });
  setMessages(prev => [...prev, userMessage]);

  // 3. 进入 Agentic Loop
  setIsLoading(true);
  for await (const event of query(userMessage, messages, ...)) {
    handleMessageFromStream(event, setMessages);
  }
  setIsLoading(false);
}

3.3 React Hooks 集成 (~90 个 hooks!)

REPL.tsx 使用了大量自定义 hooks：

// 工具与命令
const tools = useMergedTools(...);        // 合并内置+MCP+插件工具
const commands = useMergedCommands(...);  // 合并内置+MCP 命令
const canUseTool = useCanUseTool(...);    // 权限检查 hook

// 桥接与远程
useReplBridge(...);           // WebSocket 远程桥接
useRemoteSession(...);        // 远程会话管理
useDirectConnect(...);        // 直接连接管理
useSSHSession(...);           // SSH 会话

// UI 交互
useTerminalSize();            // 终端尺寸监听
useSearchInput();             // 搜索输入
useVimInput();                // Vim 模式输入
useArrowKeyHistory();         // 方向键历史
useCopyOnSelect();            // 选择复制
useVirtualScroll();           // 虚拟滚动

// 状态与通知
useLogMessages();             // 日志消息
useUpdateNotification();      // 更新通知
useApiKeyVerification();      // API Key 验证
useCostSummary();             // 费用统计

---

四、组件库详解

4.1 消息渲染

Message.tsx
├─ UserMessage     → 蓝色 "You:" 前缀
├─ AssistantMessage → 紫色 "Claude:" 前缀
│   ├─ 文本内容 → Markdown 渲染
│   ├─ 代码块 → 语法高亮 (HighlightedCode)
│   └─ 工具调用 → ToolUseLoader
├─ SystemMessage   → 灰色系统消息
└─ ToolResult      → 工具结果展示
    ├─ FileEditToolDiff → diff 视图
    ├─ BashToolResult   → 命令输出
    └─ 其他工具结果

4.2 PromptInput — 输入组件

// components/PromptInput/PromptInput.tsx
// 支持的输入模式:
type PromptInputMode =
  | 'normal'       // 普通文本输入
  | 'vim-normal'   // Vim 正常模式
  | 'vim-insert'   // Vim 插入模式
  | 'vim-visual'   // Vim 可视模式
  | 'search'       // 搜索模式
  | 'command'      // 命令模式 (/)

// 功能:
// - 多行输入
// - 自动补全 (命令、文件路径)
// - 历史浏览 (↑/↓)
// - Vim 键绑定
// - 粘贴图片检测
// - 拖拽文件引用

4.3 StatusLine — 状态栏

┌─────────────────────────────────────────────────────┐
│ claude-4-sonnet │ $0.042 │ 2.1k tokens │ ⠋ 思考中... │
└─────────────────────────────────────────────────────┘

显示：模型名、累计费用、token 用量、当前状态动画

4.4 权限对话框

// components/permissions/PermissionRequest.tsx
// 当工具需要权限时显示:
//
// ┌──────────────────────────────────────┐
// │ Claude wants to run:                 │
// │                                      │
// │   npm install lodash                 │
// │                                      │
// │ [Allow] [Always Allow] [Deny] [Edit] │
// └──────────────────────────────────────┘

4.5 Diff 视图

// components/StructuredDiff.tsx / FileEditToolDiff.tsx
// 文件编辑时显示结构化 diff:
//
//  file.ts
// -  const x = 1;
// +  const x = 2;
//    const y = 3;

---

五、虚拟滚动

// components/VirtualMessageList.tsx
// 对话历史可能非常长（数百条消息），使用虚拟滚动优化性能:

// 原理:
// 1. 只渲染可见区域的消息（终端高度内的消息）
// 2. 维护一个 "虚拟窗口" 跟踪滚动位置
// 3. 滚动时动态计算应该渲染哪些消息
// 4. 不可见的消息不渲染（不占终端资源）

---

六、Spinner 动画

// components/Spinner.tsx
type SpinnerMode =
  | 'thinking'   // ⠋ 思考中...
  | 'tool'       // ⠋ 执行工具...
  | 'compact'    // ⠋ 压缩中...
  | 'streaming'  // ⠋ 生成中...

// Spinner 使用 Unicode Braille 字符动画:
// ⠋ → ⠙ → ⠹ → ⠸ → ⠼ → ⠴ → ⠦ → ⠧ → ⠇ → ⠏

---

七、主题系统

// utils/theme.ts
type Theme = {
  name: ThemeName;
  colors: {
    primary: string;
    secondary: string;
    error: string;
    warning: string;
    success: string;
    muted: string;
    // ...
  };
};

// 支持多种终端主题
type ThemeName = 'dark' | 'light' | 'high-contrast' | 'custom';

---

八、Store 系统 (React Ink 的状态管理)

// state/store.ts — 极简的发布/订阅 Store
function createStore<T>(initialState: T, onChange?: OnChange<T>): Store<T> {
  let state = initialState;
  const listeners = new Set<Listener>();

  return {
    getState: () => state,
    setState: (updater) => {
      const prev = state;
      const next = updater(prev);
      if (Object.is(next, prev)) return;  // 引用相等时跳过
      state = next;
      onChange?.({ newState: next, oldState: prev });
      for (const listener of listeners) listener();
    },
    subscribe: (listener) => {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
  };
}

为什么不用 Redux/Zustand？

1. 包体积：Claude Code 是 CLI 工具，每多一个依赖都增加启动时间
2. 简单够用：只需要 getState/setState/subscribe 三个操作
3. 与 React Ink 配合：React Ink 的渲染模型比浏览器简单，不需要复杂的状态管理

---

九、AppState — 应用状态 (570 行)

// state/AppStateStore.ts
type AppState = DeepImmutable<{
  // 模型与设置
  settings: SettingsJson;
  verbose: boolean;
  mainLoopModel: ModelSetting;

  // 对话状态
  messages: Message[];
  statusLineText: string | undefined;
  expandedView: 'none' | 'tasks' | 'teammates';

  // 工具权限
  toolPermissionContext: ToolPermissionContext;

  // MCP
  mcpClients: MCPServerConnection[];
  mcpTools: Tool[];

  // 任务
  tasks: Map<string, TaskState>;

  // Agent 协作
  agents: AgentDefinition[];
  agentColors: Map<string, AgentColorName>;

  // 投机执行状态
  speculationState: SpeculationState;

  // 归因 (commit 追踪)
  attributionState: AttributionState;

  // 文件历史 (撤销)
  fileHistoryState: FileHistoryState;

  // 通知
  notifications: Notification[];

  // 插件
  loadedPlugins: LoadedPlugin[];
  pluginErrors: PluginError[];

  // ... 更多字段
}>;

DeepImmutable<T> 的作用

所有 AppState 的属性都是深度只读的。修改必须通过 setAppState(prev => ({ ...prev, field: newValue })) 创建新对象。这保证了：

• React 的引用比较能正确检测变化
• 防止工具执行期间意外修改状态
• 状态变更可追踪

---

十、渲染性能优化

10.1 FPS 监控

// utils/fpsTracker.ts
// 终端渲染帧率追踪（目标 60fps，实际受终端限制约 30fps）
type FpsMetrics = {
  fps: number;
  maxFrameTime: number;
  jank: number;  // 卡顿次数
};

10.2 内存使用监控

// components/MemoryUsageIndicator.tsx
// 显示 Node.js 堆内存使用量
// 超过阈值时显示警告

10.3 终端输出优化

// ink/termio/dec.ts
// 使用 DEC (Digital Equipment Corporation) 转义序列
const SHOW_CURSOR = '\x1b[?25h';
const HIDE_CURSOR = '\x1b[?25l';
// 批量更新时隐藏光标，减少闪烁