adfd7024df
- Restructure §8 from "文档沉淀规则" to "文档管理规则" with 4 subsections - Add docs/ structure with features/ and knowledge-base/ directories - Add feature documentation template with 7 sections (概述/设计初衷/技术设计/预期作用/实际效果/演化路线/头脑风暴) - Add feature update trigger matrix (新增/修改/完成/问题/反馈) - Add documentation quality checklist - Add §16
266 lines
6.0 KiB
Markdown
266 lines
6.0 KiB
Markdown
# 状态管理 (State Management)
|
||
|
||
> **分类**: 架构层
|
||
> **优先级**: P0 - 决定性
|
||
> **成熟度**: L4 - 生产
|
||
> **最后更新**: 2026-03-16
|
||
|
||
---
|
||
|
||
## 一、功能概述
|
||
|
||
### 1.1 基本信息
|
||
|
||
状态管理系统基于 Zustand 5.x，管理 ZCLAW 应用的全部业务状态，实现 UI 与业务逻辑的解耦。
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 分类 | 架构层 |
|
||
| 优先级 | P0 |
|
||
| 成熟度 | L4 |
|
||
| 依赖 | 无 |
|
||
|
||
### 1.2 相关文件
|
||
|
||
| 文件 | 路径 | 用途 |
|
||
|------|------|------|
|
||
| Store 协调器 | `desktop/src/store/index.ts` | 初始化和连接所有 Store |
|
||
| 连接 Store | `desktop/src/store/connectionStore.ts` | 连接状态管理 |
|
||
| 聊天 Store | `desktop/src/store/chatStore.ts` | 消息和会话管理 |
|
||
| 配置 Store | `desktop/src/store/configStore.ts` | 配置持久化 |
|
||
| Agent Store | `desktop/src/store/agentStore.ts` | Agent 克隆管理 |
|
||
| Hand Store | `desktop/src/store/handStore.ts` | Hands 触发管理 |
|
||
| 工作流 Store | `desktop/src/store/workflowStore.ts` | 工作流管理 |
|
||
| 团队 Store | `desktop/src/store/teamStore.ts` | 团队协作管理 |
|
||
|
||
---
|
||
|
||
## 二、设计初衷
|
||
|
||
### 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/
|
||
├── index.ts # Store 协调器
|
||
├── connectionStore.ts # 连接状态
|
||
├── chatStore.ts # 聊天状态 (最复杂)
|
||
├── configStore.ts # 配置状态
|
||
├── agentStore.ts # Agent 状态
|
||
├── handStore.ts # Hand 状态
|
||
├── workflowStore.ts # 工作流状态
|
||
└── teamStore.ts # 团队状态
|
||
```
|
||
|
||
### 3.2 核心 Store 设计
|
||
|
||
**chatStore** (最复杂的 Store):
|
||
|
||
```typescript
|
||
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;
|
||
}
|
||
```
|
||
|
||
### 3.3 Store 协调器
|
||
|
||
```typescript
|
||
// 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 持久化策略
|
||
|
||
```typescript
|
||
// 使用 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 | 7 | 7 |
|
||
| 持久化比例 | 30% | 70% | 65% |
|
||
|
||
---
|
||
|
||
## 五、实际效果
|
||
|
||
### 5.1 已实现功能
|
||
|
||
- [x] 7 个专用 Store
|
||
- [x] Store 协调器
|
||
- [x] 持久化中间件
|
||
- [x] 依赖注入模式
|
||
- [x] 跨 Store 通信
|
||
- [x] TypeScript 类型安全
|
||
|
||
### 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 容量限制
|
||
- **缓解措施**: 只持久化关键状态
|