AppState 全局状态

概述

AppState 是 Claude Code 的中央状态容器，包含 UI 状态、工具配置、MCP 连接、任务状态等所有运行时信息。

Source: src/state/AppStateStore.ts (454 行), src/state/AppState.tsx (200 行)

AppState 类型

AppState 包含两类字段：

深层不可变字段

// Source: src/state/AppStateStore.ts:89-158
{
  settings: SettingsJson
  verbose: boolean
  mainLoopModel: ModelSetting | null
  statusLineText: string | undefined
  isBriefOnly: boolean
  toolPermissionContext: ToolPermissionContext
  kairosEnabled: boolean
  
  // 视图状态
  expandedView: 'none' | 'tasks' | 'teammates'
  viewSelectionMode: 'none' | 'selecting-agent' | 'viewing-agent'
  footerSelection: FooterItem | null
  
  // 远程会话
  remoteSessionUrl?: string
  remoteConnectionStatus?: string
  remoteBackgroundTaskCount?: number
}

可变字段

// Source: src/state/AppStateStore.ts:159-452
{
  // 任务系统
  tasks: { [taskId: string]: TaskState }
  foregroundedTaskId?: string
  
  // 代理名称注册
  agentNameRegistry: Map<string, AgentId>
  
  // MCP 服务器
  mcp: {
    clients: MCPServerConnection[]
    tools: Tool[]
    commands: Command[]
    resources: MCPResource[]
  }
  
  // 插件
  plugins: {
    enabled: Plugin[]
    disabled: Plugin[]
    commands: Command[]
    errors: string[]
  }
  
  // 推测执行
  speculation: SpeculationState
  
  // Computer Use
  computerUseMcpState?: {
    appAllowlist: string[]
    grantedApps: string[]
    screenshotDims: { width: number; height: number }
  }
  
  // 收件箱
  inbox: {
    messages: InboxMessage[]
  }
}

Provider 与 Hooks

Source: src/state/AppState.tsx

AppStateProvider

const AppStateProvider = ({ initialState, onChangeAppState, children }) => {
  const [store] = useState(() => createStore(initialState, onChangeAppState));
  
  return (
    <AppStoreContext.Provider value={store}>
      {children}
    </AppStoreContext.Provider>
  );
};

useAppState — 读取状态

// 选择性订阅，只在选中值变化时重渲染
function useAppState<R>(selector: (state: AppState) => R): R {
  const store = useContext(AppStoreContext);
  
  return useSyncExternalStore(
    store.subscribe,
    () => selector(store.getState()),
    () => selector(store.getState()),
  );
}

使用 useSyncExternalStore（React 18+）实现外部 store 集成，selector 基于 Object.is 判断是否需要重渲染。

useSetAppState — 写入状态

function useSetAppState(): (updater: (prev: AppState) => AppState) => void {
  const store = useContext(AppStoreContext);
  return store.setState;
  // 只写入不订阅，组件不因状态变化而重渲染
}

useAppStateMaybeOutsideOfProvider

function useAppStateMaybeOutsideOfProvider<R>(
  selector: (state: AppState) => R
): R | undefined {
  // 安全版本 — Provider 未挂载时返回 undefined
  // 使用 NOOP_SUBSCRIBE 作为降级
}

状态更新流程

下一步

• Store 实现 — Zustand 风格 Store 的实现细节
• 会话级单例 — bootstrap/state.ts 中的模块级状态