zclaw_openfang/plans/mossy-dreaming-umbrella.md

ZCLAW Store 优化实施计划

Context

ZCLAW 项目正在从 monolithic gatewayStore.ts 迁移到 domain-specific stores。当前存在以下问题：

1. useCompositeStore 是死代码（0 处使用），订阅 59 个状态
2. 34 处组件仍使用 useGatewayStore 兼容层
3. 部分组件已迁移，部分仍需迁移
4. 存在未使用的类型定义

目标: 清理死代码，逐步迁移组件到 domain stores，减少不必要的 re-render。

---

Phase 1: 死代码清理 (5 min)

1.1 删除 useCompositeStore

文件: desktop/src/store/index.ts

• 删除第 92-284 行的 useCompositeStore 函数
• 保留 initializeStores 和 re-exports

1.2 删除未使用类型

文件: desktop/src/store/gatewayStore.ts

• 删除 HandRunStore, ScheduledJob, EventTrigger, RunHistoryEntry

验证:

pnpm tsc --noEmit && pnpm vitest run

---

Phase 2: 简单组件迁移 (30 min)

2.1 只读状态组件

组件	迁移到
components/Sidebar.tsx	useConfigStore
components/Settings/SecurityStatus.tsx	useSecurityStore
components/Settings/AuditLogsPanel.tsx	useSecurityStore
components/Settings/SecurityLayersPanel.tsx	useSecurityStore
components/Settings/UsageStats.tsx	useAgentStore

2.2 迁移模式

Before:

const userName = useGatewayStore((state) => state.quickConfig.userName);

After:

import { useConfigStore } from '../store/configStore';
const userName = useConfigStore((s) => s.quickConfig?.userName) || '用户';

---

Phase 3: 单一领域组件迁移 (45 min)

组件	迁移到
components/HandList.tsx	useHandStore
components/ApprovalsPanel.tsx	useHandStore
components/TriggersPanel.tsx	useHandStore
components/WorkflowList.tsx	useWorkflowStore
components/WorkflowHistory.tsx	useWorkflowStore

---

Phase 4: 复杂组件迁移 (40 min)

4.1 App.tsx

当前:

const { connect, hands, approveHand, loadHands } = useGatewayStore();

迁移到:

import { useConnectionStore } from '../store/connectionStore';
import { useHandStore } from '../store/handStore';

const connect = useConnectionStore((s) => s.connect);
const hands = useHandStore((s) => s.hands);
const approveHand = useHandStore((s) => s.approveHand);
const loadHands = useHandStore((s) => s.loadHands);

4.2 CloneManager.tsx → useAgentStore

4.3 HandTaskPanel.tsx → 统一使用 useHandStore

---

Phase 5: 测试与验证 (30 min)

5.1 运行现有测试

pnpm vitest run

5.2 手动验证

pnpm start:dev

验证点：

• App 启动正常，连接 Gateway
• 聊天功能正常
• Hands 触发和审批正常
• Workflows 执行正常
• 设置页面正常

5.3 类型检查

pnpm tsc --noEmit

---

关键文件

文件	操作
desktop/src/store/index.ts	删除 useCompositeStore
desktop/src/store/gatewayStore.ts	删除未使用类型，标记 @deprecated
desktop/src/App.tsx	迁移到 domain stores
desktop/src/components/Sidebar.tsx	迁移到 useConfigStore
desktop/src/components/HandList.tsx	迁移到 useHandStore
desktop/src/components/WorkflowList.tsx	迁移到 useWorkflowStore

---

风险与缓解

风险	缓解措施
迁移后功能异常	每个组件迁移后立即手动测试
类型错误	严格 TypeScript 检查
Post-connect 逻辑丢失	connectionStore 已有协调逻辑

---

预计时间

阶段	时间
Phase 1: 死代码清理	5 min
Phase 2: 简单组件	30 min
Phase 3: 单一领域	45 min
Phase 4: 复杂组件	40 min
Phase 5: 测试验证	30 min
总计	~2.5 h