zclaw_openfang/docs/features/00-architecture/02-state-management.md

状态管理 (State Management)

分类: 架构层 优先级: P0 - 决定性 成熟度: L4 - 生产 最后更新: 2026-04-06 验证状态: ✅ 代码已验证

---

一、功能概述

1.1 基本信息

状态管理系统基于 Zustand 5.x，管理 ZCLAW 应用的全部业务状态，实现 UI 与业务逻辑的解耦。

属性	值
分类	架构层
优先级	P0
成熟度	L4
依赖	无
Store 数量	18
Domains 数量	4 (chat, hands, intelligence, saas)
持久化策略	localStorage + IndexedDB (chatStore sub-stores 使用 IDB)

1.2 Store 清单 (18 个实际存在的 Zustand Store)

Store	路径	用途	验证状态
agentStore	desktop/src/store/agentStore.ts	Agent 克隆管理	✅ 存在
artifactStore	desktop/src/store/artifactStore.ts	生成物（Artifact）管理	✅ 存在
browserHandStore	desktop/src/store/browserHandStore.ts	Browser Hand 状态	✅ 存在
chatStore	desktop/src/store/chatStore.ts	聊天协调器（重构后为 4 sub-store 入口）	✅ 存在
classroomStore	desktop/src/store/classroomStore.ts	课堂/教学场景状态	✅ 存在
configStore	desktop/src/store/configStore.ts	配置持久化	✅ 存在
connectionStore	desktop/src/store/connectionStore.ts	连接状态管理	✅ 存在
conversationStore	desktop/src/store/conversationStore.ts	会话管理 (chatStore sub-store)	✅ 存在
handStore	desktop/src/store/handStore.ts	Hands 触发管理	✅ 存在
memoryGraphStore	desktop/src/store/memoryGraphStore.ts	记忆图谱状态	✅ 存在
messageStore	desktop/src/store/messageStore.ts	消息管理 (chatStore sub-store)	✅ 存在
offlineStore	desktop/src/store/offlineStore.ts	离线模式管理	✅ 存在
saasStore	desktop/src/store/saasStore.ts	SaaS 平台集成 (登录/配置/Prompt OTA)	✅ 存在
securityStore	desktop/src/store/securityStore.ts	安全配置管理	✅ 存在
sessionStore	desktop/src/store/sessionStore.ts	会话持久化	✅ 存在
streamStore	desktop/src/store/streamStore.ts	流式响应管理 (chatStore sub-store)	✅ 存在
workflowBuilderStore	desktop/src/store/workflowBuilderStore.ts	工作流构建器状态	✅ 存在
workflowStore	desktop/src/store/workflowStore.ts	工作流管理	✅ 存在

注: ChatStore 经历了结构性重构，从单一大 Store 拆分为 4 个专职 sub-store：chatStore（协调器）、streamStore（流式响应）、messageStore（消息管理）、conversationStore（会话管理）。拆分后各 Store 职责单一，支持独立持久化（conversationStore/messageStore 使用 IndexedDB）。

以下 Store 在早期文档中出现但已被移除或合并: teamStore (多 Agent 功能 feature-gated), meshStore, personaStore (合并到 identity 系统), activeLearningStore, skillMarketStore, gatewayStore (功能合并到 connectionStore)

1.3 Domain Stores (领域状态)

Domain	路径	用途
Chat Domain	desktop/src/domains/chat/	聊天领域状态和 hooks
Hands Domain	desktop/src/domains/hands/	Hands 领域状态和状态机
Intelligence Domain	desktop/src/domains/intelligence/	智能层状态 (Valtio)
Shared Utilities	desktop/src/shared/	共享类型和错误处理

---

二、设计初衷

2.1 问题背景

用户痛点:

1. 组件间状态共享困难，prop drilling 严重
2. 状态变化难以追踪和调试
3. 页面刷新后状态丢失

系统缺失能力:

• 缺乏统一的状态管理中心
• 缺乏状态持久化机制
• 缺乏状态变化的可观测性

为什么需要: 复杂应用需要可预测的状态管理，Zustand 提供了简洁的 API 和优秀的性能。

2.2 设计目标

1. 模块化: 每个 Store 职责单一
2. 持久化: 关键状态自动保存
3. 可观测: 状态变化可追踪
4. 类型安全: TypeScript 完整支持

2.3 竞品参考

项目	参考点
Redux	单向数据流思想
MobX	响应式状态
Jotai	原子化状态

2.4 设计约束

• 性能约束: 状态更新不能阻塞 UI
• 存储约束: localStorage 有 5MB 限制
• 兼容性约束: 需要支持 React 19 并发渲染

---

三、技术设计

3.1 Store 架构

store/
├── agentStore.ts           # Agent 克隆管理
├── artifactStore.ts        # 生成物管理
├── browserHandStore.ts     # Browser Hand 状态
├── chatStore.ts            # 聊天协调器 (sub-store 入口)
├── classroomStore.ts       # 课堂/教学场景
├── configStore.ts          # 配置持久化
├── connectionStore.ts      # 连接状态管理
├── conversationStore.ts    # 会话管理 (chatStore sub-store)
├── handStore.ts            # Hand 触发管理
├── memoryGraphStore.ts     # 记忆图谱
├── messageStore.ts         # 消息管理 (chatStore sub-store)
├── offlineStore.ts         # 离线模式
├── saasStore.ts            # SaaS 平台集成
├── securityStore.ts        # 安全配置
├── sessionStore.ts         # 会话持久化
├── streamStore.ts          # 流式响应 (chatStore sub-store)
├── workflowBuilderStore.ts # 工作流构建器
└── workflowStore.ts        # 工作流管理

3.2 核心 Store 设计

chatStore (最复杂的 Store):

interface ChatState {
  // 消息
  messages: Message[];
  conversations: Conversation[];
  currentConversationId: string | null;

  // Agent
  agents: Agent[];
  currentAgent: Agent | null;

  // 流式
  isStreaming: boolean;

  // 模型
  currentModel: string;
  sessionKey: string | null;
}

interface ChatActions {
  // 消息操作
  sendMessage(content: string): Promise<void>;
  addMessage(message: Message): void;
  clearMessages(): void;

  // 会话操作
  createConversation(): string;
  switchConversation(id: string): void;
  deleteConversation(id: string): void;

  // Agent 操作
  setCurrentAgent(agent: Agent): void;
  syncAgents(): Promise<void>;

  // 流式处理
  appendStreamDelta(delta: string): void;
  finishStreaming(): void;
}

workflowBuilderStore (工作流构建器):

interface WorkflowBuilderState {
  // Canvas state
  canvas: WorkflowCanvas | null;
  workflows: WorkflowCanvas[];

  // Selection
  selectedNodeId: string | null;
  selectedEdgeId: string | null;

  // UI state
  isDragging: boolean;
  isDirty: boolean;
  isPreviewOpen: boolean;
  validation: ValidationResult | null;

  // Templates
  templates: WorkflowTemplate[];

  // Available items for palette
  availableSkills: Array<{ id: string; name: string; description: string }>;
  availableHands: Array<{ id: string; name: string; actions: string[] }>;
}

meshStore (自适应智能网格):

interface MeshState {
  recommendations: WorkflowRecommendation[];
  patterns: BehaviorPattern[];
  config: MeshConfig;
  isLoading: boolean;
  error: string | null;
  lastAnalysis: string | null;

  // Actions
  analyze: () => Promise<void>;
  acceptRecommendation: (recommendationId: string) => Promise<void>;
  dismissRecommendation: (recommendationId: string) => Promise<void>;
  recordActivity: (activity: ActivityType, context: PatternContext) => Promise<void>;
  getPatterns: () => Promise<void>;
  updateConfig: (config: Partial<MeshConfig>) => Promise<void>;
  decayPatterns: () => Promise<void>;
}

personaStore (Persona 演化):

interface PersonaEvolutionStore {
  currentAgentId: string;
  proposals: EvolutionProposal[];
  history: EvolutionResult[];
  isLoading: boolean;
  error: string | null;
  config: PersonaEvolverConfig | null;
  state: PersonaEvolverState | null;
  showProposalsPanel: boolean;

  // Actions
  runEvolution: (memories: MemoryEntryForAnalysis[]) => Promise<EvolutionResult | null>;
  loadEvolutionHistory: (limit?: number) => Promise<void>;
  applyProposal: (proposal: EvolutionProposal) => Promise<boolean>;
  dismissProposal: (proposalId: string) => void;
}

3.3 Store 协调器

// store/index.ts
export function initializeStores(client: GatewayClientInterface) {
  // 注入客户端依赖
  connectionStore.getState().setClient(client);
  chatStore.getState().setClient(client);
  configStore.getState().setClient(client);
  // ... 其他 Store

  // 建立跨 Store 通信
  connectionStore.subscribe((state) => {
    if (state.connectionState === 'connected') {
      chatStore.getState().syncAgents();
      configStore.getState().loadConfig();
    }
  });
}

3.4 持久化策略

// 使用 Zustand persist 中间件
export const useChatStore = create<ChatState & ChatActions>()(
  persist(
    (set, get) => ({
      // ... state and actions
    }),
    {
      name: 'zclaw-chat',
      partialize: (state) => ({
        conversations: state.conversations,
        currentModel: state.currentModel,
        // messages 不持久化，太大
      }),
    }
  )
);

---

四、预期作用

4.1 用户价值

价值类型	描述
效率提升	状态共享无需 prop drilling
体验改善	页面刷新后状态保留
能力扩展	跨组件协作成为可能

4.2 系统价值

价值类型	描述
架构收益	UI 与业务逻辑解耦
可维护性	状态变化可预测
可扩展性	新功能只需添加 Store

4.3 成功指标

指标	基线	目标	当前
测试覆盖	50%	80%	85%
Store 数量	5	10+	18
持久化比例	30%	70%	65%

---

五、实际效果

5.1 已实现功能

• 18 个专用 Zustand Store (含 ChatStore 4 sub-store 拆分)
• 持久化中间件
• 依赖注入模式
• 跨 Store 通信
• TypeScript 类型安全
• 内部 Kernel 状态同步
• Gateway 客户端状态管理

5.2 测试覆盖

• chatStore: 42 tests
• gatewayStore: 35 tests
• teamStore: 28 tests
• 总覆盖率: ~85%

5.3 已知问题

问题	严重程度	状态	计划解决
消息不持久化	低	设计决策	不修复

5.4 用户反馈

状态管理清晰，调试方便。

---

六、演化路线

6.1 短期计划（1-2 周）

• 添加 Redux DevTools 支持

6.2 中期计划（1-2 月）

• 迁移到 IndexedDB 持久化

6.3 长期愿景

• 状态同步到云端

---

七、头脑风暴笔记

7.1 待讨论问题

1. 是否需要引入状态机 (XState)？
2. 大消息列表是否需要虚拟化？

7.2 创意想法

• 时间旅行调试：记录状态变更历史
• 状态快照：支持状态回滚

7.3 风险与挑战

• 技术风险: localStorage 容量限制
• 缓解措施: 只持久化关键状态