Claude Code UI 组件系统与状态管理深度分析

// src/state/store.ts
type Store<T> = {
  getState: () => T
  setState: (updater: (prev: T) => T) => void
  subscribe: (listener: Listener) => () => void
}

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)
    },
  }
}

type AppState = DeepImmutable<{
  // === 核心配置 ===
  settings: SettingsJson           // 用户设置
  verbose: boolean                 // 详细模式
  mainLoopModel: ModelSetting      // 当前模型
  mainLoopModelForSession: ModelSetting
  statusLineText: string | undefined
  isBriefOnly: boolean             // Brief 模式

  // === UI 导航状态 ===
  expandedView: 'none' | 'tasks' | 'teammates'
  viewSelectionMode: 'none' | 'selecting-agent' | 'viewing-agent'
  footerSelection: FooterItem | null
  selectedIPAgentIndex: number
  coordinatorTaskIndex: number
  activeOverlays: ReadonlySet<string>

  // === 权限与安全 ===
  toolPermissionContext: ToolPermissionContext

  // === Agent/Team ===
  agent: string | undefined
  kairosEnabled: boolean
  teamContext?: { teamName, teammates, ... }
  standaloneAgentContext?: { name, color }
  agentNameRegistry: Map<string, AgentId>
  foregroundedTaskId?: string
  viewingAgentTaskId?: string

  // === 远程/Bridge ===
  remoteSessionUrl: string | undefined
  remoteConnectionStatus: 'connecting' | 'connected' | 'reconnecting' | 'disconnected'
  replBridgeEnabled: boolean
  replBridgeConnected: boolean
  replBridgeSessionActive: boolean

  // === MCP/插件 ===
  mcp: { clients, tools, commands, resources, pluginReconnectKey }
  plugins: { enabled, disabled, commands, errors, installationStatus }

  // === 通知/对话 ===
  notifications: { current, queue }
  elicitation: { queue }

  // === 推测执行 ===
  speculation: SpeculationState
  speculationSessionTimeSavedMs: number

  // === 提示建议 ===
  promptSuggestion: { text, promptId, shownAt, acceptedAt }
  skillImprovement: { suggestion }
}> & {
  // 非 DeepImmutable 字段（含函数类型）
  tasks: { [taskId: string]: TaskState }
  todos: { [agentId: string]: TodoList }
  inbox: { messages: [...] }
  workerSandboxPermissions: { queue, selectedIndex }
  // ... 更多
}

// 读取状态切片（自动订阅，Object.is 比较）
export function useAppState<T>(selector: (state: AppState) => T): T {
  const store = useAppStore()
  return useSyncExternalStore(store.subscribe, () => selector(store.getState()))
}

// 获取 setState（不订阅任何状态，引用稳定）
export function useSetAppState() {
  return useAppStore().setState
}

// 获取整个 store（用于非 React 代码）
export function useAppStateStore() {
  return useAppStore()
}

// 获取当前查看的 teammate 任务
getViewedTeammateTask(appState) → InProcessTeammateTaskState | undefined

// 确定用户输入应路由到哪个 agent
getActiveAgentForInput(appState) → 
  | { type: 'leader' }
  | { type: 'viewed', task }
  | { type: 'named_agent', task }

type UseTextInputProps = {
  value: string
  onChange: (value: string) => void
  onSubmit?: (value: string) => void
  onExit?: () => void
  focus?: boolean
  multiline?: boolean
  cursorChar: string
  columns: number
  // ... 20+ 个配置项
}

function useSettings(): ReadonlySettings {
  return useAppState(s => s.settings)
}

// 核心数据流
原始 messages[]
    ↓
normalizeMessages()     // 归一化
    ↓
getMessagesAfterCompactBoundary()  // 压缩边界
    ↓
collapseReadSearchGroups()         // 折叠 Read/Search
    ↓
collapseHookSummaries()            // 折叠 Hook 摘要
    ↓
collapseBackgroundBashNotifications()  // 折叠后台 Bash
    ↓
applyGrouping()                    // 工具调用分组
    ↓
filterForBriefTool()              // Brief 模式过滤
    ↓
VirtualMessageList                // 虚拟滚动渲染

useAppState(s => s.toolPermissionContext)   // 权限上下文
useAppState(s => s.mainLoopModel)           // 当前模型
useAppState(s => s.footerSelection)         // footer 选择
useAppState(s => s.viewingAgentTaskId)      // 查看的 Agent
useAppState(s => s.expandedView)            // 展开视图
useArrowKeyHistory()                        // 历史导航
useTextInput()                              // 文本输入核心
useTypeahead()                              // 前缀补全
useInputBuffer()                            // 输入缓冲
usePromptSuggestion()                       // 建议
useIdeAtMentioned()                         // IDE @提及

type StepId = 'preflight' | 'theme' | 'oauth' | 'api-key' | 'security' | 'terminal-setup'

// 步骤数组动态构建
const steps: OnboardingStep[] = [
  { id: 'preflight', component: <PreflightStep /> },
  { id: 'theme', component: <ThemePicker /> },
  { id: 'oauth', component: <ConsoleOAuthFlow /> },    // 条件
  { id: 'api-key', component: <ApproveApiKey /> },     // 条件
  { id: 'security', component: <SecurityStep /> },
  { id: 'terminal-setup', component: <TerminalSetup /> },
]

// Messages.tsx 中 LogoHeader 被 memo 包装
const LogoHeader = React.memo(function LogoHeader({ agentDefinitions }) {
  return <OffscreenFreeze>
    <Box flexDirection="column" gap={1}>
      <LogoV2 />
      <React.Suspense fallback={null}>
        <StatusNotices agentDefinitions={agentDefinitions} />
      </React.Suspense>
    </Box>
  </OffscreenFreeze>
})

// feature() 是编译时常量，bun:bundle 在构建时消除死代码
const useVoiceIntegration = feature('VOICE_MODE')
  ? require('../hooks/useVoiceIntegration.js').useVoiceIntegration
  : () => ({ stripTrailing: () => 0, ... })