state management

Claude Code 使用极简的状态管理方案，仅 30 行代码实现完整的状态管理功能。

设计理念

为什么不用 Redux/MobX？

Claude Code 选择自己实现状态管理，原因：

1. 极简: 只需要基本的订阅/通知功能

2. 性能: 避免额外的依赖和运行时开销

3. 类型安全: 与 TypeScript 深度集成

4. 不可变: 强制不可变更新

核心实现

AppStateStore

// src/state/store.ts
class AppStateStore {
  private state: DeepImmutable<AppState>;
  private listeners = new Set<Listener>();
  
  getState(): DeepImmutable<AppState> {
    return this.state;
  }
  
  setState(updater: (state: AppState) => AppState): void {
    const newState = updater(this.state as AppState);
    this.state = newState as DeepImmutable<AppState>;
    this.notify();
  }
  
  subscribe(listener: Listener): () => void {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }
  
  private notify(): void {
    this.listeners.forEach(listener => listener(this.state));
  }
}

export const store = new AppStateStore();

DeepImmutable 类型

type DeepImmutable<T> = {
  readonly [K in keyof T]: T[K] extends object
    ? DeepImmutable<T[K]>
    : T[K];
};

确保状态树的每一层都是只读的。

状态结构

AppState 定义

interface AppState {
  // 当前会话
  session: {
    id: string;
    messages: Message[];
    tokenCount: number;
    status: 'idle' | 'running' | 'error';
  };
  
  // 工具执行
  tools: {
    executing: string[];  // 正在执行的工具
    results: Map<string, ToolResult>;
    errors: Map<string, Error>;
  };
  
  // 权限
  permissions: {
    mode: 'auto' | 'manual' | 'supervised';
    pending: PermissionRequest[];
    approved: string[];
  };
  
  // UI 状态
  ui: {
    activeView: 'chat' | 'spec' | 'settings';
    sidebarOpen: boolean;
    theme: 'light' | 'dark';
  };
  
  // 配置
  config: {
    model: string;
    temperature: number;
    maxTokens: number;
    autoCompact: boolean;
  };
  
  // 扩展
  extensions: {
    skills: Skill[];
    plugins: Plugin[];
    mcpServers: MCPServer[];
    hooks: Hook[];
  };
}

状态更新

不可变更新

// ❌ 错误 - 直接修改
store.getState().session.messages.push(newMessage);

// ✅ 正确 - 不可变更新
store.setState(state => ({
  ...state,
  session: {
    ...state.session,
    messages: [...state.session.messages, newMessage],
  },
}));

辅助函数

// src/state/actions.ts

export function addMessage(message: Message): void {
  store.setState(state => ({
    ...state,
    session: {
      ...state.session,
      messages: [...state.session.messages, message],
    },
  }));
}

export function updateToolStatus(
  toolId: string,
  status: 'running' | 'success' | 'error'
): void {
  store.setState(state => ({
    ...state,
    tools: {
      ...state.tools,
      executing: status === 'running'
        ? [...state.tools.executing, toolId]
        : state.tools.executing.filter(id => id !== toolId),
    },
  }));
}

React 集成

useStore Hook

// src/hooks/useStore.ts
function useStore<T>(
  selector: (state: AppState) => T
): T {
  const [value, setValue] = useState(() => selector(store.getState()));
  
  useEffect(() => {
    const unsubscribe = store.subscribe(state => {
      setValue(selector(state));
    });
    return unsubscribe;
  }, [selector]);
  
  return value;
}

使用示例

// 组件中使用
function ChatView() {
  const messages = useStore(state => state.session.messages);
  const status = useStore(state => state.session.status);
  
  return (
    <Box flexDirection="column">
      {messages.map(msg => <Message key={msg.id} {...msg} />)}
      {status === 'running' && <Spinner />}
    </Box>
  );
}

性能优化

选择器优化

// ❌ 每次都创建新对象
const data = useStore(state => ({
  messages: state.session.messages,
  status: state.session.status,
}));

// ✅ 使用 useMemo
const selector = useMemo(
  () => (state: AppState) => state.session,
  []
);
const session = useStore(selector);

批量更新

// 批量更新避免多次通知
store.setState(state => {
  // 一次性更新多个字段
  return {
    ...state,
    session: { ...state.session, status: 'running' },
    tools: { ...state.tools, executing: [...toolIds] },
    ui: { ...state.ui, activeView: 'chat' },
  };
});

持久化

保存状态

// src/state/persistence.ts
export async function saveState(state: AppState): Promise<void> {
  const serialized = JSON.stringify({
    session: state.session,
    config: state.config,
    permissions: {
      mode: state.permissions.mode,
      approved: state.permissions.approved,
    },
  });
  
  await fs.writeFile(
    path.join(os.homedir(), '.claude-code', 'state.json'),
    serialized
  );
}

恢复状态

export async function loadState(): Promise<Partial<AppState>> {
  try {
    const data = await fs.readFile(
      path.join(os.homedir(), '.claude-code', 'state.json'),
      'utf-8'
    );
    return JSON.parse(data);
  } catch {
    return {}; // 使用默认状态
  }
}

状态迁移

版本管理

interface PersistedState {
  version: number;
  data: AppState;
}

// 迁移函数
const migrations = {
  1: (state: any) => ({ ...state, newField: 'default' }),
  2: (state: any) => ({ ...state, renamedField: state.oldField }),
};

function migrate(state: PersistedState): AppState {
  let current = state.data;
  for (let v = state.version + 1; v <= CURRENT_VERSION; v++) {
    current = migrations[v](current);
  }
  return current;
}

调试支持

状态快照

// 开发模式下记录状态变化
if (process.env.NODE_ENV === 'development') {
  store.subscribe(state => {
    console.log('State updated:', state);
  });
}

时间旅行

// 保存历史状态
const history: AppState[] = [];

store.subscribe(state => {
  history.push(state);
  if (history.length > 50) {
    history.shift(); // 保留最近 50 个状态
  }
});

// 回退到之前的状态
function undo(): void {
  if (history.length > 1) {
    history.pop(); // 移除当前状态
    const previous = history[history.length - 1];
    store.setState(() => previous);
  }
}

最佳实践

1

1. 保持状态扁平

// ❌ 深层嵌套
state.ui.panels.left.tabs[0].content.data

// ✅ 扁平结构
state.leftPanelContent

2

2. 使用派生状态

// 不要在状态中存储可计算的值
const tokenCount = useMemo(
  () => estimateTokens(messages),
  [messages]
);

3

3. 避免冗余状态

// ❌ 冗余
{
  messages: [...],
  messageCount: 10,  // 可以从 messages.length 计算
}

// ✅ 单一来源
{
  messages: [...],
}

下一步

• 了解 消息流转 如何使用状态

• 查看 Query Loop 如何更新状态

• 探索 工具系统 如何访问状态