# UI 组件与前端分析

## UI 架构

Claude Code 使用 React + Ink 构建 Terminal UI，组件层次分明。

```mermaid
graph TB
    subgraph 入口层
        Main[main.tsx<br/>CLI 入口]
        Ink[ink.ts<br/>Ink 渲染器包装]
        App[App.tsx<br/>根组件]
    end

    subgraph 全屏界面
        Screens[screens/<br/>Doctor, REPL, Resume]
    end

    subgraph 布局组件
        Fullscreen[FullscreenLayout.tsx]
        StatusLine[StatusLine.tsx<br/>状态栏]
        TextInput[TextInput.tsx<br/>文本输入]
        VimInput[VimTextInput.tsx<br/>Vim 输入]
    end

    subgraph 消息组件
        Messages[Messages.tsx<br/>消息列表]
        MessageRow[MessageRow.tsx<br/>消息行]
        Message[Message.tsx<br/>单条消息]
        MessageResp[MessageResponse.tsx<br/>响应消息]
        VirtualList[VirtualMessageList.tsx<br/>虚拟滚动列表]
    end

    subgraph 工具组件
        ToolLoader[ToolUseLoader.tsx<br/>工具加载器]
        FileEditDiff[FileEditToolDiff.tsx<br/>编辑差异]
        BashProgress[BashModeProgress.tsx<br/>Bash 进度]
        NotebookReject[NotebookEditToolUseRejectedMessage.tsx]
    end

    subgraph 对话框组件
        TrustDialog[TrustDialog/<br/>信任对话框]
        MCPDialog[MCPServerApprovalDialog.tsx<br/>MCP 审批]
        ExportDialog[ExportDialog.tsx<br/>导出对话框]
        AutoMode[AutoModeOptInDialog.tsx<br/>自动模式确认]
        CostDialog[CostThresholdDialog.tsx<br/>成本阈值]
        BridgeDialog[BridgeDialog.tsx<br/>桥接对话框]
    end

    subgraph 输入组件
        PromptInput[PromptInput/<br/>提示输入]
        BaseInput[BaseTextInput.tsx<br/>基础文本输入]
        SearchBox[SearchBox.tsx<br/>搜索框]
    end

    Main --> Ink --> App
    App --> Screens
    App --> Fullscreen
    App --> StatusLine
    App --> TextInput
    App --> Messages
    Messages --> VirtualList --> MessageRow --> Message
    App --> ToolLoader
    App --> PromptInput
```

## 组件分类

### 核心布局组件
| 组件 | 文件 | 功能 |
|------|------|------|
| App | `App.tsx` | 应用根组件 |
| FullscreenLayout | `FullscreenLayout.tsx` | 全屏布局 |
| StatusLine | `StatusLine.tsx` | 底部状态栏 |
| TextInput | `TextInput.tsx` | 主输入框 |
| VimTextInput | `VimTextInput.tsx` | Vim 模式输入框 |
| PromptInput | `PromptInput/` | 提示输入组件 |
| VirtualMessageList | `VirtualMessageList.tsx` | 虚拟滚动消息列表 |

### 消息展示组件
| 组件 | 文件 | 功能 |
|------|------|------|
| Messages | `Messages.tsx` | 消息容器 |
| MessageRow | `MessageRow.tsx` | 消息行 |
| Message | `Message.tsx` | 单条消息 |
| MessageResponse | `MessageResponse.tsx` | 响应消息 |
| MessageModel | `MessageModel.tsx` | 模型信息 |
| MessageTimestamp | `MessageTimestamp.tsx` | 时间戳 |
| CompactSummary | `CompactSummary.tsx` | 压缩摘要 |
| Markdown | `Markdown.tsx` | Markdown 渲染 |

### 工具相关组件
| 组件 | 文件 | 功能 |
|------|------|------|
| ToolUseLoader | `ToolUseLoader.tsx` | 工具使用加载动画 |
| BashModeProgress | `BashModeProgress.tsx` | Bash 命令进度 |
| FileEditToolDiff | `FileEditToolDiff.tsx` | 文件编辑差异展示 |
| FileEditToolUpdatedMessage | `FileEditToolUpdatedMessage.tsx` | 编辑更新消息 |
| StructuredDiff | `StructuredDiff.tsx` | 结构化差异展示 |
| StructuredDiffList | `StructuredDiffList.tsx` | 差异列表 |

### 对话框组件
| 组件 | 功能 |
|------|------|
| TrustDialog/ | 信任确认对话框 |
| MCPServerApprovalDialog | MCP 服务器审批 |
| MCPServerMultiselectDialog | MCP 多选对话框 |
| ExportDialog | 导出对话框 |
| AutoModeOptInDialog | 自动模式选择 |
| AutoUpdater(AutoUpdaterWrapper) | 自动更新 |
| CostThresholdDialog | 成本阈值确认 |
| BridgeDialog | IDE 桥接对话框 |
| IdleReturnDialog | 空闲返回对话框 |
| BypassPermissionsModeDialog | 权限绕过确认 |
| WorktreeExitDialog | Worktree 退出对话框 |
| GlobalSearchDialog | 全局搜索 |
| HistorySearchDialog | 历史搜索 |
| QuickOpenDialog | 快速打开 |

### 导航和信息组件
| 组件 | 功能 |
|------|------|
| Stats | `Stats.tsx` 统计信息 |
| Spinner | `Spinner.tsx` 加载动画 |
| EffortIndicator | `EffortIndicator.ts` 思考力度指示 |
| ModelPicker | `ModelPicker.tsx` 模型选择器 |
| ThemePicker | `ThemePicker.tsx` 主题选择器 |
| LanguagePicker | `LanguagePicker.tsx` 语言选择器 |
| OutputStylePicker | `OutputStylePicker.tsx` 输出样式选择器 |
| ThinkingToggle | `ThinkingToggle.tsx` 思考模式切换 |
| FastIcon | `FastIcon.tsx` 快速模式图标 |
| ContextVisualization | `ContextVisualization.tsx` 上下文可视化 |

### 团队和代理组件
| 组件 | 功能 |
|------|------|
| CoordinatorAgentStatus | 协调器代理状态 |
| AgentProgressLine | 代理进度行 |
| TeammateViewHeader | 队友视图头部 |
| TaskListV2 | 任务列表 V2 |
| PrBadge | PR 徽章 |

### IDE 集成组件
| 组件 | 功能 |
|------|------|
| IdeStatusIndicator | IDE 状态指示器 |
| IdeAutoConnectDialog | IDE 自动连接 |
| IdeOnboardingDialog | IDE 新手引导 |
| ShowInIDEPrompt | 在 IDE 中显示提示 |
| FilePathLink | 文件路径链接 |
| LogSelector | 日志选择器 |

## Vim 模式

```mermaid
flowchart TD
    A[vim/] --> B[motions.ts<br/>移动操作]
    A --> C[operators.ts<br/>操作符]
    A --> D[textObjects.ts<br/>文本对象]
    A --> E[transitions.ts<br/>状态转换]
    A --> F[types.ts<br/>类型定义]

    G[VimTextInput.tsx] --> A
    H[useVimInput.ts] --> A

    I[vim 命令<br/>/commands/vim] --> J[切换 Vim 模式]
```

## 快捷键系统

```mermaid
flowchart TD
    A[keybindings/] --> B[defaultBindings.ts<br/>默认绑定]
    A --> C[parser.ts<br/>快捷键解析]
    A --> D[resolver.ts<br/>快捷键解析器]
    A --> E[match.ts<br/>快捷键匹配]
    A --> F[schema.ts<br/>Schema 定义]
    A --> G[template.ts<br/>模板]
    A --> H[validate.ts<br/>验证]
    A --> I[reservedShortcuts.ts<br/>保留快捷键]
    A --> J[shortcutFormat.ts<br/>格式化]
    A --> K[loadUserBindings.ts<br/>用户自定义]

    L[KeybindingContext.tsx] --> M[快捷键上下文]
    N[KeybindingProviderSetup.tsx] --> M
    O[useKeybinding.ts] --> P[使用快捷键]
    Q[useShortcutDisplay.ts] --> R[快捷键显示]
```

## React Hooks

项目包含约 70 个自定义 React Hooks：

### 核心 Hooks
| Hook | 功能 |
|------|------|
| `useCanUseTool` | 工具权限检查 |
| `useMergedTools` | 合并内置和 MCP 工具 |
| `useMergedCommands` | 合并命令列表 |
| `useMergedClients` | 合并客户端 |
| `useMainLoopModel` | 主循环模型管理 |
| `useGlobalKeybindings` | 全局快捷键 |
| `useCommandKeybindings` | 命令快捷键 |
| `useTextInput` | 文本输入管理 |

### 状态 Hooks
| Hook | 功能 |
|------|------|
| `useDynamicConfig` | 动态配置 |
| `useSettings` | 设置管理 |
| `useSettingsChange` | 设置变更监听 |
| `useTasksV2` | 任务管理 V2 |
| `useTaskListWatcher` | 任务列表监听 |
| `useMemoryUsage` | 内存使用 |
| `useScheduledTasks` | 定时任务 |

### IDE 集成 Hooks
| Hook | 功能 |
|------|------|
| `useIDEIntegration` | IDE 集成 |
| `useIdeSelection` | IDE 选择 |
| `useIdeAtMentioned` | IDE @ 提及 |
| `useIdeConnectionStatus` | IDE 连接状态 |
| `useIdeLogging` | IDE 日志 |

### 会话 Hooks
| Hook | 功能 |
|------|------|
| `useReplBridge` | REPL Bridge |
| `useRemoteSession` | 远程会话 |
| `useSSHSession` | SSH 会话 |
| `useSessionBackgrounding` | 会话后台化 |
| `useBackgroundTaskNavigation` | 后台任务导航 |

### 代理 Hooks
| Hook | 功能 |
|------|------|
| `useSwarmInitialization` | 集群初始化 |
| `useSwarmPermissionPoller` | 集群权限轮询 |
| `useTeammateViewAutoExit` | 队友视图自动退出 |

### 其他 Hooks
| Hook | 功能 |
|------|------|
| `useVoiceIntegration` / `useVoice` | 语音集成 |
| `useClipboardImageHint` | 剪贴板图片提示 |
| `usePasteHandler` | 粘贴处理 |
| `useTypeahead` | 自动补全 |
| `useHistorySearch` | 历史搜索 |
| `useDiffData` | 差异数据 |
| `useDiffInIDE` | IDE 差异显示 |
| `useVirtualScroll` | 虚拟滚动 |
| `useTerminalSize` | 终端尺寸 |
| `useCommandQueue` | 命令队列 |

## 设计系统 (design-system/)

内置组件库提供一致的 UI 基础：

| 组件 | 功能 |
|------|------|
| ThemedBox / ThemedText | 主题感知的容器/文本 |
| Dialog | 对话框组件 |
| Tabs | 标签页组件 |
| Button | 按钮组件 |
| ProgressBar | 进度条 |
| FuzzyPicker | 模糊选择器 |
| CheckboxInput | 复选框输入 |

### 布局系统

使用 **Yoga Layout**（Flexbox 引擎）进行终端布局计算，支持：
- Flexbox 弹性布局
- 响应式终端尺寸适配
- 基于 `useTerminalSize` 的动态调整

### 主题系统

```mermaid
flowchart TD
    A[ThemeProvider] --> B[themeSetting<br/>用户设置]
    A --> C[systemTheme<br/>系统检测]
    A --> D[currentTheme<br/>实际渲染主题]

    B --> E[light / dark / auto]
    C --> F[终端主题监听<br/>自动检测变化]
    D --> G[动态切换<br/>实时预览]
```

## Buddy 伙伴精灵 (buddy/)

终端伙伴精灵系统，提供视觉陪伴和交互反馈：

```mermaid
flowchart TD
    A[CompanionSprite<br/>主精灵组件] --> B[动画系统]
    A --> C[对话气泡]
    A --> D[交互功能]

    B --> E[idle<br/>空闲动画]
    B --> F[fidget<br/>活动动画]
    B --> G[blink<br/>眨眼动画]
    B --> H[15帧循环序列]

    C --> I[提示信息气泡<br/>~10秒显示]
    C --> J[淡出效果<br/>最后3秒渐暗]

    D --> K[pet<br/>抚摸交互]
    D --> L[burst<br/>Hearts 爆发动画<br/>~2.5秒]
```