IT架构师

奔赴山海，保持热爱

0%

Claude Code 源码解析 (20)：状态管理的架构设计

发表于 分类于 ，
本文字数： 21k 阅读时长 ≈ 39 分钟
深入分析 Claude Code 状态管理系统的设计思想，揭秘响应式状态、状态持久化、多端同步等核心技术。

Claude Code 源码解析 (20)：状态管理的架构设计

导读： 这是 Claude Code 20 个功能特性源码解析系列的第 20 篇，深入分析状态管理系统的架构设计。

📋 目录

  1. 问题引入：为什么需要状态管理？
  2. 技术原理：状态管理架构
  3. 设计思想：为什么这样设计
  4. 解决方案：完整实现详解
  5. OpenClaw 最佳实践
  6. 总结

问题引入：为什么需要状态管理？

痛点场景

场景 1：状态不一致

1
2
3
4
5
6
7
UI 显示：等待中...
实际状态：已完成

用户：？？？

→ UI 状态与实际状态不同步
→ 用户体验混乱

场景 2：状态丢失

1
2
3
4
5
6
7
8
9
用户正在输入：
"帮我分析这个项..."
   ↓
页面刷新/应用重启
   ↓
输入内容丢失

→ 状态未持久化
→ 用户需要重新输入

场景 3：多端状态不同步

1
2
3
4
5
手机：对话进行到第 10 轮
电脑：对话还是第 5 轮

→ 多端状态不同步
→ 用户体验割裂

核心问题

设计 AI 助手的状态管理系统时，面临以下挑战：

  1. 一致性问题

    • 如何保证状态一致性？
    • 如何避免状态冲突？

  2. 持久化问题

    • 哪些状态需要持久化？
    • 如何高效持久化？

  3. 同步问题

    • 如何多端同步状态？
    • 如何处理同步冲突？

  4. 性能问题

    • 如何避免过度渲染？
    • 如何优化状态更新？

Claude Code 用响应式状态 + 智能持久化解决了这些问题。

技术原理：状态管理架构

整体架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
┌─────────────────────────────────────────────────────────────┐
│                    用户界面                                  │
│              (UI Components)                                 │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  State Store (状态存储)                                     │
│  - 单一数据源 (Single Source of Truth)                      │
│  - 响应式更新                                               │
│  - 状态历史                                                 │
└─────────────┬───────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│  State Actions (状态动作)                                   │
│  - 同步动作                                                 │
│  - 异步动作                                                 │
│  - 动作组合                                                 │
└─────────────┬───────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│  State Persistence (状态持久化)                             │
│  - 自动保存                                                 │
│  - 增量同步                                                 │
│  - 冲突解决                                                 │
└─────────────┬───────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│  State Sync (状态同步)                                      │
│  - 多端同步                                                 │
│  - 实时同步                                                 │
│  - 离线支持                                                 │
└─────────────────────────────────────────────────────────────┘

状态定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
interface AppState {
  // 用户状态
  user: UserState;
  
  // 会话状态
  session: SessionState;
  
  // 对话状态
  conversation: ConversationState;
  
  // UI 状态
  ui: UIState;
  
  // 配置状态
  config: ConfigState;
  
  // 工具状态
  tools: ToolsState;
  
  // 元状态
  meta: MetaState;
}

interface UserState {
  id?: string;
  name?: string;
  email?: string;
  preferences: UserPreferences;
  isAuthenticated: boolean;
}

interface SessionState {
  id: string;
  createdAt: Date;
  lastActiveAt: Date;
  deviceInfo?: DeviceInfo;
}

interface ConversationState {
  messages: Message[];
  isLoading: boolean;
  currentTool?: ToolCall;
  pendingPermissions: PermissionRequest[];
}

interface UIState {
  theme: 'light' | 'dark' | 'auto';
  sidebarOpen: boolean;
  activePanel: PanelType;
  notifications: Notification[];
  modal?: ModalConfig;
}

interface ConfigState {
  model: string;
  temperature: number;
  maxTokens: number;
  autoSave: boolean;
}

interface ToolsState {
  available: ToolDefinition[];
  enabled: string[];
  states: Record<string, ToolState>;
}

interface MetaState {
  version: string;
  lastSyncAt?: Date;
  syncStatus: 'idle' | 'syncing' | 'error';
}

响应式状态存储

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
class StateStore<S> {
  private state: S;
  private listeners: Set<StateListener<S>> = new Set();
  private history: S[] = [];
  private historyIndex = -1;
  
  constructor(initialState: S) {
    this.state = initialState;
    this.history.push(initialState);
    this.historyIndex = 0;
  }
  
  // 获取状态
  getState(): S {
    return this.state;
  }
  
  // 获取状态片段
  getSelector<T>(selector: (state: S) => T): T {
    return selector(this.state);
  }
  
  // 更新状态
  setState(updater: StateUpdater<S>): void {
    const prevState = this.state;
    
    // 应用更新
    if (typeof updater === 'function') {
      this.state = updater(prevState);
    } else {
      this.state = { ...prevState, ...updater };
    }
    
    // 记录历史
    this.historyIndex++;
    this.history = this.history.slice(0, this.historyIndex);
    this.history.push(this.state);
    
    // 通知监听者
    this.notifyListeners(prevState);
  }
  
  // 订阅状态变化
  subscribe(listener: StateListener<S>): () => void {
    this.listeners.add(listener);
    
    // 返回取消订阅函数
    return () => {
      this.listeners.delete(listener);
    };
  }
  
  // 撤销
  undo(): void {
    if (this.historyIndex > 0) {
      this.historyIndex--;
      this.state = this.history[this.historyIndex];
      this.notifyListeners();
    }
  }
  
  // 重做
  redo(): void {
    if (this.historyIndex < this.history.length - 1) {
      this.historyIndex++;
      this.state = this.history[this.historyIndex];
      this.notifyListeners();
    }
  }
  
  // 重置状态
  reset(initialState: S): void {
    this.state = initialState;
    this.history = [initialState];
    this.historyIndex = 0;
    this.notifyListeners();
  }
  
  private notifyListeners(prevState?: S): void {
    for (const listener of this.listeners) {
      listener(this.state, prevState);
    }
  }
}

type StateUpdater<S> = Partial<S> | ((prevState: S) => S);
type StateListener<S> = (state: S, prevState?: S) => void;

状态动作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
class ActionDispatcher {
  private store: StateStore<AppState>;
  private actions: Map<string, Action> = new Map();
  
  constructor(store: StateStore<AppState>) {
    this.store = store;
    this.registerActions();
  }
  
  // 注册动作
  registerAction(name: string, action: Action): void {
    this.actions.set(name, action);
  }
  
  // 分发行动
  async dispatch<T>(name: string, payload?: T): Promise<void> {
    const action = this.actions.get(name);
    
    if (!action) {
      throw new Error(`Action not found: ${name}`);
    }
    
    // 记录动作开始
    console.log(`[Action] ${name} started`);
    
    try {
      // 执行准备
      if (action.prepare) {
        await action.prepare(payload, this.store.getState());
      }
      
      // 执行动作
      const result = await action.execute(payload, this.store);
      
      // 执行后续
      if (action.then) {
        await action.then(result, this.store.getState());
      }
      
      console.log(`[Action] ${name} completed`);
      
    } catch (error) {
      // 错误处理
      if (action.catch) {
        await action.catch(error, this.store);
      }
      
      console.error(`[Action] ${name} failed:`, error);
      throw error;
    }
  }
  
  private registerActions(): void {
    // 添加消息
    this.registerAction('addMessage', {
      prepare: async (payload, state) => {
        // 验证消息
        if (!payload.content) {
          throw new Error('Message content required');
        }
      },
      execute: async (payload, store) => {
        const message: Message = {
          id: generateId(),
          role: payload.role,
          content: payload.content,
          timestamp: new Date(),
        };
        
        store.setState(prev => ({
          ...prev,
          conversation: {
            ...prev.conversation,
            messages: [...prev.conversation.messages, message],
          },
        }));
        
        return message;
      },
    });
    
    // 设置加载状态
    this.registerAction('setLoading', {
      execute: async (payload: boolean, store) => {
        store.setState(prev => ({
          ...prev,
          conversation: {
            ...prev.conversation,
            isLoading: payload,
          },
        }));
      },
    });
    
    // 更新配置
    this.registerAction('updateConfig', {
      execute: async (payload: Partial<ConfigState>, store) => {
        store.setState(prev => ({
          ...prev,
          config: { ...prev.config, ...payload },
        }));
      },
    });
    
    // 显示通知
    this.registerAction('showNotification', {
      execute: async (payload: Notification, store) => {
        store.setState(prev => ({
          ...prev,
          ui: {
            ...prev.ui,
            notifications: [...prev.ui.notifications, payload],
          },
        }));
        
        // 自动消失
        if (payload.autoHide !== false) {
          setTimeout(() => {
            this.dispatch('dismissNotification', { id: payload.id });
          }, payload.duration || 5000);
        }
      },
    });
    
    // 关闭通知
    this.registerAction('dismissNotification', {
      execute: async (payload: { id: string }, store) => {
        store.setState(prev => ({
          ...prev,
          ui: {
            ...prev.ui,
            notifications: prev.ui.notifications.filter(
              n => n.id !== payload.id
            ),
          },
        }));
      },
    });
  }
}

interface Action {
  prepare?: (payload: any, state: AppState) => Promise<void>;
  execute: (payload: any, store: StateStore<AppState>) => Promise<any>;
  then?: (result: any, state: AppState) => Promise<void>;
  catch?: (error: Error, store: StateStore<AppState>) => Promise<void>;
}

状态持久化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
class StatePersistence {
  private store: StateStore<AppState>;
  private storage: StorageAdapter;
  private saveQueue: SaveQueue;
  private syncManager: SyncManager;
  
  constructor(
    store: StateStore<AppState>,
    storage: StorageAdapter
  ) {
    this.store = store;
    this.storage = storage;
    this.saveQueue = new SaveQueue();
    this.syncManager = new SyncManager();
    
    this.setupAutoSave();
  }
  
  // 设置自动保存
  private setupAutoSave(): void {
    // 订阅状态变化
    this.store.subscribe((state, prevState) => {
      // 计算变化的部分
      const changes = this.calculateChanges(state, prevState);
      
      if (changes.length > 0) {
        // 加入保存队列
        this.saveQueue.enqueue(changes);
      }
    });
    
    // 定期刷新队列
    setInterval(() => this.saveQueue.flush(), 5000);
    
    // 页面关闭前保存
    if (typeof window !== 'undefined') {
      window.addEventListener('beforeunload', () => {
        this.saveQueue.flush();
      });
    }
  }
  
  // 计算变化
  private calculateChanges(state: AppState, prevState?: AppState): Change[] {
    if (!prevState) {
      return [{ path: '', value: state }];
    }
    
    const changes: Change[] = [];
    
    // 深度比较
    this.diffRecursive(state, prevState, '', changes);
    
    return changes;
  }
  
  private diffRecursive(
    current: any,
    previous: any,
    path: string,
    changes: Change[]
  ): void {
    if (typeof current !== typeof previous) {
      changes.push({ path, value: current, type: 'update' });
      return;
    }
    
    if (Array.isArray(current)) {
      if (current.length !== previous.length) {
        changes.push({ path, value: current, type: 'update' });
        return;
      }
      
      for (let i = 0; i < current.length; i++) {
        this.diffRecursive(current[i], previous[i], `${path}[${i}]`, changes);
      }
      return;
    }
    
    if (typeof current === 'object' && current !== null) {
      const allKeys = new Set([...Object.keys(current), ...Object.keys(previous)]);
      
      for (const key of allKeys) {
        const newPath = path ? `${path}.${key}` : key;
        
        if (!(key in previous)) {
          changes.push({ path: newPath, value: current[key], type: 'add' });
        } else if (!(key in current)) {
          changes.push({ path: newPath, value: undefined, type: 'remove' });
        } else {
          this.diffRecursive(current[key], previous[key], newPath, changes);
        }
      }
      return;
    }
    
    if (current !== previous) {
      changes.push({ path, value: current, type: 'update' });
    }
  }
  
  // 加载状态
  async load(): Promise<AppState | null> {
    try {
      const saved = await this.storage.get('app_state');
      
      if (saved) {
        // 合并保存的状态和默认状态
        const defaultState = this.getDefaultState();
        const merged = this.deepMerge(defaultState, saved);
        
        return merged;
      }
    } catch (error) {
      console.error('Failed to load state:', error);
    }
    
    return null;
  }
  
  // 深度合并
  private deepMerge(target: any, source: any): any {
    const result = { ...target };
    
    for (const key of Object.keys(source)) {
      if (source[key] instanceof Object && key in target) {
        result[key] = this.deepMerge(target[key], source[key]);
      } else {
        result[key] = source[key];
      }
    }
    
    return result;
  }
  
  private getDefaultState(): AppState {
    return {
      user: { preferences: {}, isAuthenticated: false },
      session: { id: generateId(), createdAt: new Date(), lastActiveAt: new Date() },
      conversation: { messages: [], isLoading: false, pendingPermissions: [] },
      ui: { theme: 'auto', sidebarOpen: true, activePanel: 'chat', notifications: [] },
      config: { model: 'default', temperature: 0.7, maxTokens: 4096, autoSave: true },
      tools: { available: [], enabled: [], states: {} },
      meta: { version: '1.0.0', syncStatus: 'idle' },
    };
  }
}

interface Change {
  path: string;
  value: any;
  type: 'add' | 'remove' | 'update';
}

interface StorageAdapter {
  get(key: string): Promise<any>;
  set(key: string, value: any): Promise<void>;
  remove(key: string): Promise<void>;
}

class SaveQueue {
  private queue: Change[][] = [];
  private flushing = false;
  
  enqueue(changes: Change[]): void {
    this.queue.push(changes);
  }
  
  async flush(): Promise<void> {
    if (this.flushing || this.queue.length === 0) {
      return;
    }
    
    this.flushing = true;
    
    try {
      // 合并所有变化
      const allChanges = this.queue.flat();
      this.queue = [];
      
      // 保存到存储
      await storage.set('app_state_changes', allChanges);
      
    } finally {
      this.flushing = false;
    }
  }
}

多端状态同步

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
class SyncManager {
  private store: StateStore<AppState>;
  private syncChannel: BroadcastChannel | null;
  private lastSyncAt: Date = new Date();
  
  constructor(store: StateStore<AppState>) {
    this.store = store;
    
    // 浏览器多标签同步
    if (typeof BroadcastChannel !== 'undefined') {
      this.syncChannel = new BroadcastChannel('openclaw_sync');
      this.setupChannelListener();
    }
  }
  
  // 广播状态变化
  broadcast(changes: Change[]): void {
    if (this.syncChannel) {
      this.syncChannel.postMessage({
        type: 'state_changes',
        changes,
        timestamp: Date.now(),
      });
    }
  }
  
  // 设置频道监听
  private setupChannelListener(): void {
    this.syncChannel?.addEventListener('message', (event) => {
      const { type, changes, timestamp } = event.data;
      
      if (type === 'state_changes') {
        // 避免循环同步
        if (timestamp <= this.lastSyncAt.getTime()) {
          return;
        }
        
        // 应用变化
        this.applyChanges(changes);
        this.lastSyncAt = new Date(timestamp);
      }
    });
  }
  
  // 应用变化
  private applyChanges(changes: Change[]): void {
    this.store.setState(prev => {
      const newState = { ...prev };
      
      for (const change of changes) {
        this.setByPath(newState, change.path, change.value);
      }
      
      return newState;
    });
  }
  
  // 通过路径设置值
  private setByPath(obj: any, path: string, value: any): void {
    const keys = path.split('.');
    let current = obj;
    
    for (let i = 0; i < keys.length - 1; i++) {
      const key = keys[i];
      if (!(key in current)) {
        current[key] = {};
      }
      current = current[key];
    }
    
    const lastKey = keys[keys.length - 1];
    current[lastKey] = value;
  }
  
  // 云端同步
  async syncWithCloud(): Promise<void> {
    this.store.setState(prev => ({
      ...prev,
      meta: { ...prev.meta, syncStatus: 'syncing' },
    }));
    
    try {
      // 获取本地变化
      const localChanges = await this.getLocalChanges();
      
      // 获取远程变化
      const remoteChanges = await this.fetchRemoteChanges();
      
      // 解决冲突
      const resolved = await this.resolveConflicts(localChanges, remoteChanges);
      
      // 应用 resolved 变化
      this.applyChanges(resolved);
      
      // 更新同步时间
      this.lastSyncAt = new Date();
      
      this.store.setState(prev => ({
        ...prev,
        meta: { 
          ...prev.meta, 
          syncStatus: 'idle',
          lastSyncAt: this.lastSyncAt,
        },
      }));
      
    } catch (error) {
      console.error('Cloud sync failed:', error);
      
      this.store.setState(prev => ({
        ...prev,
        meta: { ...prev.meta, syncStatus: 'error' },
      }));
    }
  }
  
  private async getLocalChanges(): Promise<Change[]> {
    // 从存储获取本地变化
    return await storage.get('pending_changes') || [];
  }
  
  private async fetchRemoteChanges(): Promise<Change[]> {
    // 从云端获取变化
    const response = await fetch('/api/sync/changes', {
      headers: {
        'If-Modified-Since': this.lastSyncAt.toISOString(),
      },
    });
    
    if (response.status === 304) {
      return [];
    }
    
    return await response.json();
  }
  
  private async resolveConflicts(
    local: Change[],
    remote: Change[]
  ): Promise<Change[]> {
    // 简单的冲突解决策略：远程优先
    // 实际应该更复杂
    
    const allChanges = [...local, ...remote];
    
    // 去重（同一路径保留最新的）
    const byPath = new Map<string, Change>();
    
    for (const change of allChanges) {
      byPath.set(change.path, change);
    }
    
    return Array.from(byPath.values());
  }
}

设计思想：为什么这样设计

思想 1：单一数据源

问题： 状态分散多处导致不一致。

解决： 单一数据源。

1
2
3
4
5
6
7
8
// 所有状态集中在 StateStore
const store = new StateStore<AppState>(initialState);

// UI 从状态读取
const isLoading = store.getSelector(state => state.conversation.isLoading);

// 更新通过 Action
dispatch('setLoading', true);

设计智慧：

单一数据源让状态可预测。

思想 2：响应式更新

问题： 手动更新 UI 容易遗漏。

解决： 响应式订阅。

1
2
3
4
5
6
7
8
9
10
// 订阅状态变化
store.subscribe((state) => {
  // 自动重新渲染
  render();
});

// 更新状态
store.setState(prev => ({ ...prev, count: prev.count + 1 }));

// UI 自动更新

思想 3：增量持久化

问题： 全量保存效率低。

解决： 增量保存。

1
2
3
4
5
6
7
8
// 计算变化
const changes = calculateChanges(prevState, currentState);

// 只保存变化的部分
await storage.save('changes', changes);

// 恢复时重放变化
const state = replayChanges(defaultState, changes);

思想 4：离线优先

问题： 网络不稳定导致数据丢失。

解决： 离线优先。

1
2
3
4
5
6
7
8
// 操作先保存到本地
await localSave(operation);

// 后台同步到云端
syncManager.queueSync();

// 网络恢复时同步
network.on('reconnect', () => syncManager.sync());

思想 5：时间旅行

问题： 状态错误无法回溯。

解决： 状态历史。

1
2
3
4
5
6
7
8
// 记录所有状态
history.push(state);

// 撤销
store.undo();  // 回到上一个状态

// 重做
store.redo();  // 前进到下一个状态

解决方案：完整实现详解

App 状态管理实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
class App {
  private store: StateStore<AppState>;
  private dispatcher: ActionDispatcher;
  private persistence: StatePersistence;
  private syncManager: SyncManager;
  
  constructor() {
    // 初始化状态存储
    this.store = new StateStore<AppState>(this.getDefaultState());
    
    // 初始化动作分发器
    this.dispatcher = new ActionDispatcher(this.store);
    
    // 初始化持久化
    this.persistence = new StatePersistence(this.store, localStorageAdapter);
    
    // 初始化同步管理器
    this.syncManager = new SyncManager(this.store);
    
    // 加载保存的状态
    this.loadPersistedState();
    
    // 设置定期同步
    setInterval(() => this.syncManager.syncWithCloud(), 60000);
  }
  
  private async loadPersistedState(): Promise<void> {
    const savedState = await this.persistence.load();
    
    if (savedState) {
      this.store.reset(savedState);
      console.log('[App] State loaded from persistence');
    }
  }
  
  // 获取状态
  getState(): AppState {
    return this.store.getState();
  }
  
  // 订阅状态
  subscribe(selector: (state: AppState) => any, callback: (value: any) => void): () => void {
    let currentValue = selector(this.store.getState());
    
    return this.store.subscribe((state) => {
      const newValue = selector(state);
      
      if (newValue !== currentValue) {
        currentValue = newValue;
        callback(newValue);
      }
    });
  }
  
  // 分发行动
  dispatch<T>(name: string, payload?: T): Promise<void> {
    return this.dispatcher.dispatch(name, payload);
  }
  
  // 撤销
  undo(): void {
    this.store.undo();
  }
  
  // 重做
  redo(): void {
    this.store.redo();
  }
  
  private getDefaultState(): AppState {
    return {
      user: { preferences: {}, isAuthenticated: false },
      session: { id: generateId(), createdAt: new Date(), lastActiveAt: new Date() },
      conversation: { messages: [], isLoading: false, pendingPermissions: [] },
      ui: { theme: 'auto', sidebarOpen: true, activePanel: 'chat', notifications: [] },
      config: { model: 'default', temperature: 0.7, maxTokens: 4096, autoSave: true },
      tools: { available: [], enabled: [], states: {} },
      meta: { version: '1.0.0', syncStatus: 'idle' },
    };
  }
}

// 使用示例
const app = new App();

// 订阅对话状态
app.subscribe(
  state => state.conversation.messages,
  (messages) => {
    renderMessages(messages);
  }
);

// 添加消息
await app.dispatch('addMessage', {
  role: 'user',
  content: 'Hello',
});

配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# ~/.openclaw/config/state.yaml

# 状态持久化
persistence:
  # 启用自动保存
  auto_save: true
  
  # 保存间隔 (ms)
  save_interval: 5000
  
  # 历史版本数
  history_count: 50
  
  # 存储类型
  storage: localstorage  # localstorage / indexeddb / file

# 状态同步
sync:
  # 启用同步
  enabled: true
  
  # 同步间隔 (ms)
  sync_interval: 60000
  
  # 冲突解决策略
  conflict_resolution: remote_first  # remote_first / local_first / manual
  
  # 离线支持
  offline:
    enabled: true
    queue_size: 1000

# UI 状态
ui:
  # 默认主题
  theme: auto
  
  # 侧边栏状态
  sidebar:
    default_open: true
    remember_state: true
  
  # 通知设置
  notifications:
    enabled: true
    max_display: 5
    auto_dismiss: true
    dismiss_timeout: 5000

OpenClaw 最佳实践

实践 1：查看状态

1
2
3
4
5
6
7
8
# 查看当前状态
openclaw state get

# 查看特定状态
openclaw state get conversation

# 查看状态历史
openclaw state history --limit 10

实践 2：导出状态

1
2
3
4
5
6
7
8
# 导出状态
openclaw state export --output state.json

# 导入状态
openclaw state import --file state.json

# 清除状态
openclaw state clear --confirm

实践 3：状态同步

1
2
3
4
5
6
7
8
9
10
11
12
# 手动同步
openclaw state sync

# 查看同步状态
openclaw state sync status

# 输出：
同步状态:
─────────────────────────────────────
上次同步：2 分钟前
同步状态：正常
待同步变化：0

实践 4：状态恢复

1
2
3
4
5
6
7
8
# 撤销
openclaw state undo

# 重做
openclaw state redo

# 恢复到特定版本
openclaw state restore --version 5

实践 5：状态监控

1
2
3
4
5
6
7
# 监控状态变化
openclaw state watch

# 输出：
[21:45:00] conversation.messages: +1
[21:45:05] conversation.isLoading: true → false
[21:45:10] ui.notifications: +1

总结

核心要点

  1. 单一数据源 - 所有状态集中管理
  2. 响应式更新 - 状态变化自动通知
  3. 增量持久化 - 只保存变化的部分
  4. 离线优先 - 本地优先，后台同步
  5. 时间旅行 - 支持撤销/重做

设计智慧

好的状态管理让应用”始终一致且可靠”。

Claude Code 的状态管理设计告诉我们：

  • 单一数据源保证状态一致性
  • 响应式更新简化 UI 同步
  • 增量持久化提升性能
  • 离线优先保证可用性

状态分类

类别 持久化 同步 示例
用户状态 是 是 偏好设置
会话状态 是 是 当前会话
对话状态 是 是 消息历史
UI 状态 可选 否 侧边栏开关
临时状态 否 否 加载状态

下一步

  • 配置状态持久化
  • 启用多端同步
  • 设置状态监控
  • 优化状态更新

系列文章：

  • [1] Bash 命令执行的安全艺术 (已发布)
  • [2] 差异编辑的设计艺术 (已发布)
  • [3] 文件搜索的底层原理 (已发布)
  • [4] 多 Agent 协作的架构设计 (已发布)
  • [5] 技能系统的设计哲学 (已发布)
  • [6] MCP 协议集成的完整指南 (已发布)
  • [7] 后台任务管理的完整方案 (已发布)
  • [8] Web 抓取的 SSRF 防护设计 (已发布)
  • [9] 多层权限决策引擎设计 (已发布)
  • [10] 插件生命周期的设计智慧 (已发布)
  • [11] 会话持久化的架构设计 (已发布)
  • [12] 上下文压缩与恢复技术 (已发布)
  • [13] AI 记忆存储与检索机制 (已发布)
  • [14] 配置系统的分层设计 (已发布)
  • [15] 88+ 命令的架构设计 (已发布)
  • [16] 启动性能优化的技巧 (已发布)
  • [17] AI 安全模型的设计思想 (已发布)
  • [18] Terminal UI 的设计哲学 (已发布)
  • [19] 日志与遥测系统的设计 (已发布)
  • [20] 状态管理的架构设计 (本文)

进度：20/N (Phase 1 & 2 完成！) 🎉

上一篇： Claude Code 源码解析 (19)：日志与遥测系统的设计

关于作者： John，OpenClaw 平台开发者，专注 AI 助手架构设计与实现。