输入交互：PromptInput 与多模式支持

PromptInput 组件是 Claude Code CLI 中用户与系统交互的核心入口，它不仅处理基础文本输入，还集成了语音识别、图片粘贴、Vim 编辑、Bash 命令模式等多种交互方式。该组件采用分层架构设计，将复杂的输入处理逻辑拆分为独立的模块，通过 React Hooks 和状态管理实现高度可扩展的输入系统。其核心价值在于为开发者提供流畅、智能的命令行交互体验，支持多行编辑、历史导航、实时建议、语法高亮等高级特性。

Sources: PromptInput.tsx

架构概览：组件层次与职责分离

PromptInput 系统采用三层架构：顶层是 PromptInput.tsx 负责协调多种输入模式和管理全局状态；中间层是 TextInput.tsx 和 VimTextInput.tsx 处理特定编辑模式的逻辑；底层是 BaseTextInput.tsx 提供统一的渲染和基础输入处理能力。这种设计使得不同输入模式（标准文本、Vim、语音）可以共享底层的渲染和粘贴处理逻辑，同时保持各自独立的编辑行为。

graph TB
    A[PromptInput.tsx<br/>协调器层] --> B[TextInput.tsx<br/>标准模式]
    A --> C[VimTextInput.tsx<br/>Vim 模式]
    
    B --> D[BaseTextInput.tsx<br/>渲染层]
    C --> D
    
    D --> E[useTextInput Hook<br/>输入状态管理]
    D --> F[usePasteHandler Hook<br/>粘贴处理]
    D --> G[useTypeahead Hook<br/>自动补全]
    
    A --> H[PromptInputFooter.tsx<br/>底部状态栏]
    A --> I[VoiceIndicator.tsx<br/>语音状态]
    A --> J[Notifications.tsx<br/>提示通知]
    
    H --> K[建议列表]
    H --> L[快捷键提示]
    H --> M[状态指示器]
    
    subgraph 多模式支持
        N[文本模式]
        O[Bash 模式 !]
        P[Vim 模式]
        Q[语音模式]
        R[图片粘贴]
    end
    
    A --> N
    A --> O
    A --> P
    A --> Q
    A --> R

组件职责分离确保了系统的可维护性和可测试性。PromptInput.tsx 作为协调器管理 input 状态、cursorOffset 光标位置、pastedContents 粘贴内容、mode 输入模式等核心状态；它通过 useTextInput、useTypeahead、useArrowKeyHistory 等 Hooks 封装了复杂的输入处理逻辑；底部通过 PromptInputFooter 展示实时建议、快捷键提示和状态信息。Sources: PromptInput.tsx, BaseTextInput.tsx, textInputTypes.ts

多模式输入：文本、Bash 与 Vim

PromptInput 支持三种主要输入模式，通过前缀字符或状态切换实现模式转换。文本模式是默认模式，处理普通对话输入；Bash 模式通过输入 ! 前缀激活，将输入视为 Shell 命令直接执行；Vim 模式提供完整的 Vim 编辑体验，包括 Normal、Insert、Visual 等子模式。inputModes.ts 模块提供了模式判断和转换的实用函数，getModeFromInput 检测输入字符串的模式类型，getValueFromInput 提取去除模式前缀的实际内容。

PromptInput 组件通过 mode 和 vimMode 两个状态管理输入模式：mode 的类型是 PromptInputMode（'prompt' | 'bash'），vimMode 的类型是 VimMode（'normal' | 'insert' | 'visual' | 'replace'）。当检测到输入以 ! 开头时，getModeFromInput 返回 'bash'，组件会切换到 Bash 模式并调整输入处理逻辑；Vim 模式则通过 VimTextInput 组件替代标准的 TextInput，提供完整的 Vim 键绑定和行为。Sources: inputModes.ts, PromptInput.tsx, textInputTypes.ts

语音输入：按住说话的语音识别

语音模式通过 按住特定快捷键 触发录音，松开后自动进行语音识别并将文本插入到输入框。该功能通过 useVoice Hook 实现，它管理录音状态（idle、recording、processing）、音频流处理、以及与 Anthropic voice_stream STT 服务的 WebSocket 连接。VoiceIndicator 组件在输入框底部显示语音状态提示，包括 “listening…” 录音中和 “processing…” 处理中的动态反馈。

语音识别流程包含语言检测和降级机制：useVoice 会读取系统语言设置（通过 getSystemLocaleLanguage），并映射到 BCP-47 语言代码（如 en、ja、zh）；如果系统语言不在支持列表中，会降级到默认的英语（en）。语言映射表 LANGUAGE_NAME_TO_CODE 支持英文名称和本地化名称（如 日本語 映射到 ja），确保多语言用户能够使用母语进行语音输入。语音数据通过 connectVoiceStream 建立 WebSocket 连接，实时流式传输音频数据到后端进行识别，识别结果通过 insertText 回调插入到光标当前位置。Sources: useVoice.ts, VoiceIndicator.tsx, PromptInput.tsx

图片粘贴：多平台剪贴板处理

图片粘贴功能允许用户通过 Ctrl+V / Cmd+V 直接粘贴剪贴板中的图片，或粘贴包含图片文件路径的文本。usePasteHandler Hook 拦截粘贴事件，通过 getImageFromClipboard 检测剪贴板是否包含图片数据。图片处理流程包括：格式检测（PNG、JPEG、WebP 等）、尺寸调整（通过 maybeResizeAndDownsampleImageBuffer 限制最大宽高）、Base64 编码、以及生成 [Image #N] 占位符引用。

// 图片粘贴核心流程（简化版）
function onImagePaste(image: string, mediaType?: string, ...) {
  const pasteId = nextPasteIdRef.current++;
  const newContent: PastedContent = {
    id: pasteId,
    type: 'image',
    content: image,
    mediaType: mediaType || 'image/png',
    dimensions,
  };
  
  // 立即缓存图片路径（快速）
  cacheImagePath(newContent);
  
  // 后台存储图片到磁盘
  void storeImage(newContent);
  
  // 更新 UI，插入占位符
  setPastedContents(prev => ({ ...prev, [pasteId]: newContent }));
  insertTextAtCursor(formatImageRef(pasteId));
}

跨平台兼容性通过 imagePaste.ts 中的平台特定命令实现：macOS 使用 osascript 读取剪贴板的 «class PNGf» 数据；Linux 支持 xclip 和 wl-paste（Wayland）；Windows 使用 PowerShell 的 Get-Clipboard -Format Image。图片会被自动调整到 IMAGE_MAX_WIDTH × IMAGE_MAX_HEIGHT 以内（默认 2048×2048），并在超过 IMAGE_TARGET_RAW_SIZE（5MB）时进行下采样，以优化 API 调用性能。Sources: PromptInput.tsx, usePasteHandler.ts, imagePaste.ts

文本高亮：实时语法着色

PromptInput 实现了强大的实时文本高亮系统，通过 TextHighlight 数组定义高亮区域，支持颜色、反色、暗淡等多种视觉效果。高亮类型包括：命令高亮（/commit、/review 等斜杠命令显示为蓝色）、关键词高亮（think、ultraplan 等触发词使用彩虹色逐字符着色）、团队提及高亮（@username 使用成员专属颜色）、图片引用高亮（[Image #N] 占位符在光标悬停时反色显示）、语音临时文本高亮（语音识别中的临时文本显示为暗淡色）。

高亮系统通过 combinedHighlights 计算属性合并所有高亮规则，每个高亮项包含 start、end 位置、color 颜色、inverse 反色标志、priority 优先级（用于解决重叠冲突）。BaseTextInput 组件接收 highlights 数组，通过 HighlightedInput（即 ShimmeredInput.tsx）渲染带高亮的文本。光标位置的特殊处理确保光标所在位置的高亮会被过滤（cursorFiltered），避免光标被高亮颜色覆盖。Sources: PromptInput.tsx, textInputTypes.ts, BaseTextInput.tsx

自动补全与建议：智能输入辅助

useTypeahead Hook 是自动补全系统的核心，它监听输入变化并实时生成建议列表。建议类型包括：命令补全（输入 /com 时提示 /commit）、文件路径补全（输入 ./src/ 时列出文件和目录）、Shell 历史补全（Bash 模式下提示历史命令）、Slack 频道补全（输入 # 时列出已知频道）、会话恢复补全（输入 /resume 时列出最近会话）。建议通过 PromptInputFooter 在底部显示，用户可通过 Tab 键接受建议或 ↑↓ 键浏览列表。

sequenceDiagram
    participant User
    participant PromptInput
    participant useTypeahead
    participant SuggestionService
    
    User->>PromptInput: 输入 "/"
    PromptInput->>useTypeahead: 触发输入变化
    useTypeahead->>SuggestionService: generateCommandSuggestions()
    SuggestionService-->>useTypeahead: 返回命令列表
    useTypeahead->>PromptInput: 更新 suggestionsState
    PromptInput->>User: 显示建议列表
    
    User->>PromptInput: 按 Tab 键
    PromptInput->>useTypeahead: 接受建议
    useTypeahead->>PromptInput: 更新 input 值
    PromptInput->>User: 完成补全

统一建议生成器 generateUnifiedSuggestions 整合了多种建议来源，通过优先级排序和上下文匹配选择最相关的建议。文件路径补全通过 startBackgroundCacheRefresh 在后台构建索引，实现快速响应；命令补全通过 parseArguments 解析命令参数并提供参数提示（如 /commit -m "message" 中的 -m 提示）。建议状态通过 setSuggestionsState 管理，包含 suggestions 数组、selectedSuggestion 索引、commandArgumentHint 参数提示。Sources: useTypeahead.tsx, PromptInput.tsx, unifiedSuggestions.ts

输入状态管理：光标、历史与撤销

useTextInput Hook 封装了复杂的输入状态管理逻辑，核心是 Cursor 类的实现。Cursor 提供了完整的文本编辑能力：光标移动（字符、单词、行、段落级别）、文本插入与删除（支持 kill-ring 剪切板）、撤销与重做（通过 yank 和 yank-pop 实现）、多行处理（自动换行计算、视口滚动）。光标位置通过 externalOffset 和 onOffsetChange 与 React 状态同步，确保组件重渲染时光标位置正确恢复。

历史导航通过 useArrowKeyHistory 和 useHistorySearch 实现。↑ 键在输入框为空或光标在第一行时触发历史向上导航，↓ 键在光标在最后一行时触发向下导航；历史记录存储在全局配置中（通过 addToHistory 添加），支持正则搜索和模糊匹配。撤销机制通过 pushToKillRing、recordYank、yankPop 实现 Emacs 风格的剪切环：Ctrl+K 剪切到行尾并压入剪切环，Ctrl+Y 粘贴最新项，Meta+Y 循环浏览剪切环历史。双击退出保护通过 useDoublePress 实现：首次按 Ctrl+C 显示 “Ctrl-C again to exit” 提示，第二次才真正退出；首次按 Esc 显示 “Esc again to clear”，第二次清空输入。Sources: useTextInput.ts, Cursor.ts, useArrowKeyHistory.tsx

文本粘贴与截断：大文本处理

当粘贴的文本超过 TRUNCATION_THRESHOLD（10000 字符）时，inputPaste.ts 中的 maybeTruncateMessageForInput 函数会自动截断文本并生成占位符。截断策略保留文本的开头和结尾各 500 字符（PREVIEW_LENGTH / 2），中间部分替换为 [...Truncated text #N +X lines...] 占位符，其中 N 是引用 ID，X 是被截断的行数。截断的内容存储在 pastedContents 中，与图片引用共享同一存储结构。

// 文本截断示例
输入: 15000 字符的长文本
输出: 
  前 500 字符 + 
  [...Truncated text #1 +120 lines...] + 
  后 500 字符
  
// pastedContents 存储
{
  1: {
    id: 1,
    type: 'text',
    content: '...中间 14000 字符...'
  }
}

粘贴状态管理通过 usePasteHandler 的 pasteState 追踪：当检测到快速连续的输入事件（chunks 数组累积）时，系统进入粘贴模式并延迟处理，等待 PASTE_COMPLETION_TIMEOUT_MS（100ms）后合并所有块并触发 onPaste 回调。这解决了终端粘贴大文本时产生大量独立输入事件的问题，避免了中间状态的频繁渲染。isPasting 状态会传递给 BaseTextInput，在粘贴过程中禁用 Enter 键提交，防止意外发送不完整的输入。Sources: inputPaste.ts, usePasteHandler.ts, PromptInput.tsx

底部状态栏：信息聚合与交互入口

PromptInputFooter 组件是输入框底部的信息中心，聚合了多种状态指示器和交互入口：建议列表（通过 PromptInputFooterSuggestions 显示自动补全建议）、快捷键提示（通过 ConfigurableShortcutHint 显示当前可用的快捷键）、状态指示器（API 密钥状态、自动更新状态、Vim 模式指示器）、任务面板入口（显示运行中的后台任务数量）、Bridge 连接状态（显示 IDE 连接状态）、通知消息（通过 Notifications 组件显示临时提示）。

底部栏通过 Footer 导航系统 支持键盘切换：↓ 或 → 键在可见的 footer 项之间导航（tasks → tmux → teams → bridge → companion），↑ 或 ← 键反向导航。当前选中项通过 footerSelection 状态管理，选中特定项时会触发对应操作（如选中 tasks 打开任务面板）。navigateFooter 函数处理导航逻辑，支持边界检测和退出行为（在第一项按 ↑ 可取消选中）。Sources: PromptInputFooter.tsx, PromptInput.tsx, Notifications.tsx

提交流程：从输入到处理

当用户按 Enter 键提交输入时，PromptInput 执行完整的提交流程：输入验证（检查输入是否为空、是否处于加载状态）、模式处理（根据 mode 决定提交到 Claude 还是直接执行 Bash 命令）、内容组装（合并 input 文本和 pastedContents 中的图片/截断文本）、状态清理（清空输入框、重置光标、清空粘贴内容）、回调触发（调用 onSubmit 或 onAgentSubmit）。提交通常通过 handlePromptSubmit 工具函数处理，它会构造 PromptInputHelpers 对象包含所有必要的上下文信息。

// 提交流程伪代码
async function handleSubmit(input: string, helpers: PromptInputHelpers) {
  // 1. 检查是否有语音识别的临时文本
  if (voiceInterimRange) {
    // 等待语音识别完成
  }
  
  // 2. 解析模式和内容
  const mode = getModeFromInput(input);
  const value = getValueFromInput(input);
  
  // 3. 组装消息内容
  const content = assembleContent(value, pastedContents);
  
  // 4. 根据模式分发
  if (mode === 'bash') {
    executeBashCommand(value);
  } else {
    await onSubmitProp(input, helpers);
  }
  
  // 5. 清理状态
  onInputChange('');
  setPastedContents({});
  onHistoryReset();
}

智能提示建议 usePromptSuggestion Hook 会在 Claude 响应时在后台生成下一步提示建议，当用户开始输入时显示为内联 ghost text。如果用户接受建议（通过 Tab 键），会记录 speculationAccept 事件并计算节省的时间；如果用户忽略建议继续输入，会记录 logOutcomeAtSubmission 用于改进建议质量。这实现了”预测性输入”功能，减少用户输入常见后续操作的按键次数。Sources: PromptInput.tsx, handlePromptSubmit.ts, usePromptSuggestion.ts

通知系统：即时反馈机制

Notifications 组件和 useNotifications Hook 提供了临时消息显示机制，用于在不打断用户输入的情况下提供即时反馈。通知类型包括：即时通知（priority: 'immediate'，如 “Effort set to high”）、持久通知（如错误消息）、条件通知（如剪贴板图片提示仅在终端获得焦点时显示）。通知通过 addNotification 添加，包含 key 唯一标识、text 消息内容、priority 优先级、timeoutMs 超时时间。

通知的典型使用场景：快捷键提示（双击 Esc 时显示 “Esc again to clear”）、模式切换提示（输入 think 时显示 “Effort set to high for this turn”）、功能发现提示（检测到剪贴板有图片时显示 “Paste image with Ctrl+V”）、警告提示（输入过长时显示截断警告）。通知系统通过 FOOTER_TEMPORARY_STATUS_TIMEOUT（5000ms）自动清理过期消息，确保界面不被历史通知污染。Sources: Notifications.tsx, PromptInput.tsx, notifications.tsx

Vim 模式集成：高级编辑体验

当用户启用 Vim 模式时，PromptInput 会渲染 VimTextInput 替代标准的 TextInput。VimTextInput 实现了完整的 Vim 编辑器模拟，包括 Normal 模式（导航和操作）、Insert 模式（文本插入）、Visual 模式（文本选择）、Replace 模式（字符替换）。Vim 的核心概念通过 motions.ts（移动命令如 w、b、e）、operators.ts（操作符如 d、c、y）、textObjects.ts（文本对象如 iw、aw、ip）模块实现。

Vim 模式通过 状态机 管理模式转换：transitions.ts 定义了按键序列到状态转换的映射（如 Normal 模式下按 i 进入 Insert 模式，按 v 进入 Visual 模式）。useVimInput Hook 封装了 Vim 状态管理，维护 vimMode、registers（Vim 寄存器）、macroRecording（宏录制状态）等状态。Vim 模式与标准输入系统共享底层的 Cursor 类和粘贴处理逻辑，但覆盖了键盘事件处理以实现 Vim 键绑定。Sources: VimTextInput.tsx, motions.ts, transitions.ts, PromptInput.tsx

性能优化：渲染与响应速度

PromptInput 通过多项优化确保流畅的输入体验：视口渲染（通过 maxVisibleLines 限制渲染的行数，只渲染光标周围的可见行）、高亮缓存（combinedHighlights 通过 useMemo 缓存计算结果，仅在依赖项变化时重新计算）、防抖处理（useTypeahead 中的建议生成使用防抖避免频繁计算）、后台索引（文件补全的索引构建在后台线程进行）、增量更新（Cursor 类支持局部更新而非全量重渲染）。

光标动画优化特别值得注意：在语音录制期间，光标显示为动态波形（通过 useAnimationFrame 每 50ms 更新一次），但仅在 needsAnimation 为 true 时启用动画帧；音频级别通过指数移动平均（EMA）平滑处理（SMOOTH = 0.7），避免波形抖动；reducedMotion 设置会禁用所有动画，满足无障碍需求。组件记忆化通过 React Compiler 的 _c 函数实现，避免不必要的子组件重渲染。Sources: TextInput.tsx, PromptInput.tsx, VoiceIndicator.tsx

相关页面：想了解 PromptInput 如何融入整体 REPL 界面，请阅读 REPL 界面：screens/REPL.tsx 核心组件剖析；想深入理解 Ink 框架的终端渲染原理，请参考 Ink 框架：React 终端渲染原理；想了解消息如何被处理和展示，请查看 消息渲染：虚拟列表与性能优化。