311 lines
9.6 KiB
Markdown
311 lines
9.6 KiB
Markdown
# 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秒]
|
||
```
|