REPL 界面

screens/REPL.tsx 是整个代码库中最大且最重要的文件。 这是 React 组件 is Claude Code 会话。 屏幕上可见的所有内容——对话历史记录、旋转器、权限提示、输入框——都是在这里精心安排的。

该文件由大约 5,000 行编译而成，并导出一个函数： REPL(props)。 尽管文件很大，但该文件具有清晰的内部结构，可以分层读取：

每个用户交互都经过一系列三个功能。 了解链条是整个文件的万能钥匙。

onSubmit — 入口点

onSubmit 击键变成了 API 调用。 函数签名揭示了它的职责：

const onSubmit = useCallback(async (
  input: string,
  helpers: PromptInputHelpers,
  speculationAccept?: ActiveSpeculationState,
  options?: { fromKeybinding?: boolean }
) => {
  repinScroll();          // snap to bottom on any submit

  // Fast path: immediate local-jsx commands run NOW even while Claude is busy
  if (shouldTreatAsImmediate) {
    void executeImmediateCommand();
    return;
  }

  // Idle-return gate: if user has been gone 75+ min, show dialog first
  // Add to shell/history, restore stashed prompt, clear input field
  // Route remote mode through WebSocket, not local query

  await awaitPendingHooks();   // block until SessionStart hooks resolve
  await handlePromptSubmit(...); // shell mode, command routing, onQuery
}, [/* ~25 deps */]);

onQuery — 并发防护

onQuery wraps onQueryImpl 使用关键状态机： QueryGuard。 与简单的布尔标志不同，守卫使用了一个陈旧的生成计数器 finally 取消查询的块不会错误地更新状态。

const thisGeneration = queryGuard.tryStart();
if (thisGeneration === null) {
  // Already running — extract user text and enqueue it
  newMessages.filter(isUserMessage).forEach(msg => enqueue({ value, mode: 'prompt' }));
  return;
}
try {
  await onQueryImpl(messagesRef.current, newMessages, abortController, ...);
} finally {
  if (queryGuard.end(thisGeneration)) {
    // Only the latest generation cleans up
    resetLoadingState();
    await mrOnTurnComplete(messagesRef.current, aborted);
  }
  // Auto-restore runs OUTSIDE the generation check
  // (forceEnd bumps generation; end() returns false for Esc path)
  if (abortController.signal.reason === 'user-cancel' && !queryGuard.isActive ...) {
    restoreMessageSync(lastUserMsg);
  }
}

onQueryImpl — API 调用

onQueryImpl 实际工作：构建系统提示符，调用 query()，并通过流式传输响应 onQueryEvent。 关键步骤：

// 1. Haiku title extraction (one-shot, first real user message only)
if (!titleDisabled && !haikuTitleAttemptedRef.current) {
  void generateSessionTitle(text, signal).then(t => setHaikuTitle(t));
}

// 2. Write skill-scoped allowedTools to store BEFORE the API call
store.setState(prev => ({ ...prev, toolPermissionContext: { ...prev.toolPermissionContext,
  alwaysAllowRules: { ...prev.toolPermissionContext.alwaysAllowRules, command: additionalAllowedTools }
}}));

// 3. Build full context — all reads from store.getState() not render closure
const toolUseContext = getToolUseContext(messages, newMessages, abortController, model);

// 4. Parallel async: system prompt + user context + killswitch checks
const [,, defaultSystemPrompt, userContext, systemContext] = await Promise.all([
  checkAndDisableBypassPermissionsIfNeeded(...),
  getSystemPrompt(freshTools, model, workingDirs, mcpClients),
  getUserContext(),
  getSystemContext()
]);

// 5. Stream the query
for await (const event of query({ messages, systemPrompt, canUseTool, toolUseContext, ... })) {
  onQueryEvent(event);
}

REPL.tsx 中更微妙的设计决策之一是它如何跟踪“Claude 目前在工作吗？” 三个独立的来源都可以使微调器出现：

const isLoading = isQueryActive || isExternalLoading;
const showSpinner = (!toolJSX || toolJSX.showSpinner === true)
  && toolUseConfirmQueue.length === 0
  && promptQueue.length === 0
  && (isLoading || userInputOnProcessing || hasRunningTeammates || getCommandQueueLength() > 0)
  && !pendingWorkerRequest
  && !onlySleepToolActive
  && (!visibleStreamingText || isBriefOnly);

当多个事物同时需要用户注意时（权限提示、空闲返回提示、IDE 入门对话框），REPL.tsx 通过单个解决冲突 getFocusedInputDialog() 返回所有可能的对话框类型的字符串并集的函数：

function getFocusedInputDialog():
  'message-selector' | 'sandbox-permission' | 'tool-permission' |
  'prompt' | 'worker-sandbox-permission' | 'elicitation' |
  'cost' | 'idle-return' | 'ide-onboarding' | ... | undefined

  // Priority order (highest to lowest):
  if (isMessageSelectorVisible) return 'message-selector';    // always
  if (isPromptInputActive) return undefined;                   // suppress while typing
  if (sandboxPermissionRequestQueue[0]) return 'sandbox-permission';
  // ... permission/interactive dialogs ...
  // ... onboarding dialogs ...
  // ... callouts (effort, remote, LSP rec) ...
  return undefined;

The isPromptInputActive 防护特别值得注意：中断对话框是 suppressed 当用户打字时。 1.5 秒去抖 (PROMPT_SUPPRESSION_MS = 1500) 在最后一次击键后重置标志。 这可以防止用户在说话时意外取消权限。

对话存储在 messages: MessageType[] 状态数组，但它是 not 用简单的方式管理 useState。 使用的包装器模式与 Zustand 相同：ref 保存实时值，React 状态是渲染投影：

const [messages, rawSetMessages] = useState<MessageType[]>(initialMessages ?? []);
const messagesRef = useRef(messages);

const setMessages = useCallback((action) => {
  const prev = messagesRef.current;
  const next = typeof action === 'function' ? action(messagesRef.current) : action;
  messagesRef.current = next;             // sync update — no await needed
  if (next.length > prev.length && userMessagePendingRef.current) {
    // Track whether the submitted user message has landed yet
    // to control the placeholder text visibility
  }
  rawSetMessages(next);
}, []);

三种相关机制使消息数组保持一致：

1. 短暂的进步替代 — Sleep 和 Bash 每秒都会发出进度滴答声。 REPL.tsx 不是追加（这会使数组增加到 13,000 多个条目），而是就地替换了同一工具使用 ID 的前一个刻度。
2. 紧凑的边界处理 - 什么时候 query() 发出紧凑边界消息，消息数组仅替换为压缩后消息。 在全屏模式下，预压缩消息将保留以供回滚，但上限为一个压缩间隔。
3. 延迟渲染 — useDeferredValue(messages) produces deferredMessages，其中 Messages 组件以转换优先级渲染。 这可以使输入框在流式传输期间保持响应。 当流文本可见时，延迟路径将被绕过（因此最终消息出现在流文本清除的同一帧中）。

工具和斜线命令可以通过调用呈现自定义 UI setToolJSX()。 REPL 跟踪两个独立的覆盖槽：

const [toolJSX, setToolJSXInternal] = useState<{
  jsx: React.ReactNode | null;
  shouldHidePromptInput: boolean;
  shouldContinueAnimation?: true;
  showSpinner?: boolean;
  isLocalJSXCommand?: boolean;
  isImmediate?: boolean;
} | null>(null);

const localJSXCommandRef = useRef(...); // preserves /btw and similar while Claude streams

The setToolJSX 包装器强制执行一个重要的不变量： 本地 JSX 命令无法被工具更新覆盖。 如果用户运行 /btw （在 Claude 继续处理时显示覆盖），后续工具更新将被默默忽略，直到用户明确使用 clearLocalJSX: true.

在全屏模式下，本地 JSX 命令呈现在 模态槽 （绝对定位，底部锚定）而不是在可滚动区域中内联。 这可以防止对话框在新消息到达时抖动。

REPL 有两个屏幕，通过以下方式切换 screen: 'prompt' | 'transcript' state:

转录模式早期返回（第 4392 课 行左右）的存在是出于关键的性能原因：没有虚拟滚动，将所有消息呈现在 ScrollBox 将为长会话分配约 250 MB。 转录模式使 VirtualMessageList 仅呈现可见行的路径。

转录模式还可以提供较少风格的搜索体验 / 打开搜索栏， n/N 用于导航， v 打开于 $VISUAL/$EDITOR， 和 [ 转储到终端回滚。

The resume() 回调处理 /resume 命令。 它是文件中最复杂的操作之一，协调一长串状态重置：

// 1. Deserialize messages (clean up unresolved tool uses)
// 2. Fire SessionEnd hooks for the current session
// 3. Fire SessionStart hooks for the resumed session
// 4. Copy or reuse the plan slug (fork vs resume)
// 5. Restore file history snapshots
// 6. Restore agent definition (name, color, type)
// 7. Restore standalone agent context
// 8. Save current session costs before switchSession()
// 9. Reset cost state, then restore target session costs
// 10. Atomically switch sessionId + project dir
// 11. Rename asciicast recording to match new session ID
// 12. Clear then restore session metadata (ordering matters)
// 13. Exit current worktree, enter resumed session's worktree
// 14. Reconstruct contentReplacementState for the new session
// 15. setMessages → setToolJSX(null) → setInputValue('')

当用户按 Escape 打断 Claude 并且查询没有产生有意义的响应时，REPL.tsx 会自动倒回对话并恢复他们的输入。 此功能有几个保护措施：

// Inside the onQuery finally block:
if (
  abortController.signal.reason === 'user-cancel'  // Esc, not background/interrupt
  && !queryGuard.isActive                             // no newer query racing in
  && inputValueRef.current === ''                   // user hasn't typed anything
  && getCommandQueueLength() === 0                   // no queued commands (don't undo B while A was loading)
  && !store.getState().viewingAgentTaskId             // not viewing a teammate's transcript
) {
  const lastUserMsg = msgs.findLast(selectableUserMessagesFilter);
  if (lastUserMsg && messagesAfterAreOnlySynthetic(msgs, idx)) {
    removeLastFromHistory();  // undo the history entry too
    restoreMessageSync(lastUserMsg);
  }
}

这运行 outside the queryGuard.end() 检查因为 onCancel calls queryGuard.forceEnd()，这会增加生成计数器。 end(thisGeneration) returns false 对于退出路径 - 但自动恢复仍必须运行。

最终的 JSX 树组装了所有部分。 简化结构：

<AlternateScreen mouseTracking>
  <KeybindingSetup>                        // provides keybinding context
    <AnimatedTerminalTitle />               // 960ms tick, isolated leaf
    <GlobalKeybindingHandlers />            // ctrl+o transcript toggle, etc.
    <ScrollKeybindingHandler />             // PgUp/PgDn/g/G — BEFORE CancelRequest
    <CancelRequestHandler />               // Esc / ctrl+c
    <MCPConnectionManager>                  // manages MCP server lifecycle
      <FullscreenLayout
        scrollRef={scrollRef}              // shared with ScrollKeybindingHandler
        overlay={toolPermissionOverlay}    // PermissionRequest floats above messages
        modal={centeredModal}              // local-jsx commands in fullscreen
        scrollable={<>
          <TeammateViewHeader />
          <Messages messages={displayedMessages} />
          {placeholderText && <UserTextMessage param={placeholderText} />}
          {toolJSX && <Box>{toolJSX.jsx}</Box>}
          {showSpinner && <SpinnerWithVerb />}
          <PromptInputQueuedCommands />
        </>}
        bottom={<Box>
          {permissionStickyFooter}
          {focusedInputDialog === 'sandbox-permission' && <SandboxPermissionRequest />}
          {focusedInputDialog === 'tool-permission' && <PermissionRequest />}
          // ... other dialogs keyed to focusedInputDialog ...
          <FeedbackSurvey />
          <PromptInput onSubmit={onSubmit} />
          <SessionBackgroundHint />
          {cursor && <MessageActionsBar />}
          {focusedInputDialog === 'message-selector' && <MessageSelector />}
        </Box>}
      />
    </MCPConnectionManager>
  </KeybindingSetup>
</AlternateScreen>

// messages is read via messagesRef.current inside the callback to
// keep onSubmit stable across message updates (see L2384/L2400/L2662).
// Without this, each setMessages call (~30× per turn) recreates
// onSubmit, pinning the REPL render scope (1776B) + that render's
// messages array in downstream closures (PromptInput, handleAutoRunIssue).
// Heap analysis showed ~9 REPL scopes and ~15 messages array versions
// accumulating after #20174/#20175, all traced to this dep.

function AnimatedTerminalTitle({ isAnimating, title, disabled, noPrefix }) {
  const [frame, setFrame] = useState(0);
  useEffect(() => {
    if (!isAnimating) return;
    const interval = setInterval(() => setFrame(f => (f + 1) % frames.length), 960);
    return () => clearInterval(interval);
  }, [isAnimating]);
  useTerminalTitle(disabled ? null : `${prefix} ${title}`);
  return null;  // zero render cost
}