zclaw_openfang/docs/superpowers/plans/2026-03-21-phase2-CHANGELOG.md

Phase 2: 领域重组 - 变更日志

完成日期: 2026-03-21

概述

Phase 2 完成了 ZCLAW 项目的领域驱动重组，创建了新的 domains/ 目录结构，引入了 Valtio 状态管理和 XState 状态机。

已完成任务

1. 依赖安装 ✅

• valtio@2.3.1 - Proxy-based 状态管理
• xstate@5.28.0 - 状态机
• @xstate/react@6.1.0 - React 集成

2. 目录结构 ✅

desktop/src/
├── domains/
│   ├── chat/           # 聊天领域
│   │   ├── index.ts
│   │   ├── types.ts
│   │   ├── store.ts
│   │   └── hooks.ts
│   └── hands/          # 自动化领域
│       ├── index.ts
│       ├── types.ts
│       ├── store.ts
│       ├── machine.ts
│       └── hooks.ts
└── shared/             # 共享模块
    ├── index.ts
    ├── types.ts
    └── error-handling.ts

3. Chat Domain ✅

类型定义 (types.ts):

• Message - 消息类型
• Conversation - 对话类型
• Agent - 分身类型
• ChatState - 聊天状态

Valtio Store (store.ts):

• chatStore - Proxy 响应式状态
• Actions: addMessage, updateMessage, setCurrentAgent, etc.

React Hooks (hooks.ts):

• useChatState() - 完整状态快照
• useMessages() - 消息列表
• useIsStreaming() - 流式状态
• useCurrentAgent() - 当前分身
• useChatActions() - Actions 引用

4. Hands Domain ✅

类型定义 (types.ts):

• Hand - Hand 定义
• HandStatus - 状态枚举
• HandRun - 执行记录
• Trigger - 触发器
• ApprovalRequest - 审批请求
• HandContext - 状态机上下文
• HandsEvent - 状态机事件

XState Machine (machine.ts):

• 状态: idle → running → needs_approval | success | error | cancelled
• 事件: START, APPROVE, REJECT, COMPLETE, ERROR, CANCEL, RESET
• Actions: setRunId, setError, setResult, setProgress, resetContext
• Guards: hasError, isApproved

Valtio Store (store.ts):

• handsStore - Proxy 响应式状态
• Actions: loadHands, triggerHand, approveHand, loadTriggers, etc.

React Hooks (hooks.ts):

• useHandsState() - 完整状态快照
• useHands() - Hands 列表
• useHand(id) - 单个 Hand
• useApprovalQueue() - 审批队列
• useTriggers() - 触发器列表
• useHandsActions() - Actions 引用

5. Shared 模块 ✅

类型定义 (types.ts):

• Result<T, E> - 函数式错误处理
• AsyncResult<T, E> - 异步结果
• PaginatedResponse<T> - 分页响应
• AsyncStatus - 异步状态
• AsyncState<T, E> - 异步状态包装
• Entity / NamedEntity - 实体基类

错误处理 (error-handling.ts):

• AppError - 基础错误类
• NetworkError - 网络错误
• ValidationError - 验证错误
• AuthError - 认证错误
• Type guards: isAppError, isNetworkError, isValidationError, isAuthError
• Helpers: getErrorMessage, wrapError

6. TypeScript 类型修复 ✅

修复 Valtio useSnapshot 返回 readonly 类型的问题:

• 使用类型断言 as readonly Type[] 处理数组返回值
• 移除 machine.ts 中未使用的 fromPromise 导入

提交记录

1. 7ffd5e1 - feat(domains): add Phase 2 domain structure with Valtio and XState
2. 5513d5d - fix(domains): resolve TypeScript type errors in domain hooks

验证结果

• ✅ TypeScript 编译通过 (pnpm typecheck)
• ⚠️ 单元测试: 139 passed, 27 failed (预先存在的问题)
• 预先存在的测试失败与 Phase 2 更改无关

下一步

Phase 2 已完成基础领域结构。后续工作:

1. 渐进式迁移 - 将现有组件逐步迁移到新 domain hooks
2. 向后兼容 - 更新旧 stores 重导出 domains
3. Intelligence Domain - 添加 intelligence 领域模块
4. Skills Domain - 添加 skills 领域模块

架构对比

之前 (Zustand)

// store/chatStore.ts
export const useChatStore = create<ChatState>((set, get) => ({
  messages: [],
  addMessage: (msg) => set((s) => ({ messages: [...s.messages, msg] })),
}));

// 组件中
const messages = useChatStore((s) => s.messages);
const addMessage = useChatStore((s) => s.addMessage);

之后 (Valtio)

// domains/chat/store.ts
export const chatStore = proxy<ChatStore>({
  messages: [],
  addMessage: (msg) => { chatStore.messages.push(msg); },
});

// domains/chat/hooks.ts
export function useMessages() {
  const { messages } = useSnapshot(chatStore);
  return messages as readonly Message[];
}

// 组件中
const messages = useMessages();
const { addMessage } = useChatActions();

技术决策

决策	选择	原因
状态管理	Valtio	Proxy 细粒度响应，减少不必要渲染
Hands 状态机	XState	可预测的状态转换，复杂流程管理
类型组织	按领域	高内聚低耦合，便于独立演进
向后兼容	保留旧 stores	渐进式迁移，降低风险