0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
462 lines
20 KiB
Markdown
462 lines
20 KiB
Markdown
# ZCLAW 自动化系统重设计方案
|
||
|
||
> **状态**: 待审核
|
||
> **作者**: Claude
|
||
> **日期**: 2026-03-18
|
||
> **版本**: 1.0
|
||
|
||
---
|
||
|
||
## 一、背景与目标
|
||
|
||
### 1.1 当前问题
|
||
|
||
| 问题 | 影响 | 严重程度 |
|
||
|------|------|---------|
|
||
| HandsPanel 使用 gatewayStore 而非 handStore | 状态管理混乱，新 store 未被使用 | 高 |
|
||
| HandParamsForm 参数未传递给 triggerHand | 用户填写的参数被丢弃 | 致命 |
|
||
| 缺少 WebSocket 实时状态更新 | 无法看到执行进度 | 高 |
|
||
| 无执行结果展示 | 用户不知道 Hand 执行结果 | 高 |
|
||
| 无执行历史查看 | 无法追溯过去的执行 | 中 |
|
||
| Hands 与 Workflows 分离 | 用户体验割裂 | 中 |
|
||
|
||
### 1.2 设计目标
|
||
|
||
基于用户需求确认：
|
||
|
||
1. **专业版功能** - 完整重构 + 工作流集成 + 批量操作 + 调度管理
|
||
2. **可视化调度器** - 图形化界面选择时间/频率，无需了解 cron 语法
|
||
3. **结果流展示** - Hand 输出作为对话消息显示在聊天区域
|
||
4. **批量操作** - 支持批量触发、批量审批、批量配置
|
||
5. **统一视图** - Hands 和 Workflows 合并到一个"自动化"视图，按任务类型分类
|
||
|
||
---
|
||
|
||
## 二、架构设计
|
||
|
||
### 2.1 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ UI Layer │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
||
│ │AutomationPanel│ │ScheduleEditor│ │ExecutionResultStream│ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ State Management │
|
||
│ ┌───────────────────────────────────────────────────────┐ │
|
||
│ │ automationStore.ts │ │
|
||
│ │ - hands: Hand[] │ │
|
||
│ │ - workflows: Workflow[] │ │
|
||
│ │ - runs: Run[] │ │
|
||
│ │ - schedules: Schedule[] │ │
|
||
│ │ - approvals: Approval[] │ │
|
||
│ │ - selectedIds: Set<string> │ │
|
||
│ └───────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Data Layer │
|
||
│ ┌───────────────────────────────────────────────────────┐ │
|
||
│ │ gateway-client.ts │ │
|
||
│ │ - listHands() / listWorkflows() │ │
|
||
│ │ - triggerHand() / executeWorkflow() │ │
|
||
│ │ - createSchedule() / updateSchedule() │ │
|
||
│ │ - WebSocket 事件监听 │ │
|
||
│ └───────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 数据流
|
||
|
||
```
|
||
用户操作 → AutomationPanel → automationStore → gateway-client → ZCLAW API
|
||
│
|
||
├── 更新 UI 状态
|
||
├── WebSocket 事件 → 更新执行状态
|
||
└── 执行完成 → 注入结果到 chatStore
|
||
```
|
||
|
||
### 2.3 文件结构
|
||
|
||
```
|
||
desktop/src/
|
||
├── components/
|
||
│ ├── Automation/ # 新建目录
|
||
│ │ ├── AutomationPanel.tsx # 统一入口（组合层）
|
||
│ │ ├── AutomationCard.tsx # Hand/Workflow 卡片
|
||
│ │ ├── AutomationFilters.tsx # 分类筛选
|
||
│ │ ├── ScheduleEditor.tsx # 可视化调度器
|
||
│ │ ├── ExecutionResult.tsx # 结果展示组件
|
||
│ │ ├── BatchActionBar.tsx # 批量操作栏
|
||
│ │ └── ApprovalQueue.tsx # 审批队列
|
||
│ └── HandsPanel.tsx # 重构为 AutomationPanel 入口
|
||
├── store/
|
||
│ ├── handStore.ts # 扩展：添加批量操作方法
|
||
│ ├── workflowStore.ts # 保留：工作流状态
|
||
│ └── automationCoordinator.ts # 新建：跨 store 协调层
|
||
├── types/
|
||
│ ├── hands.ts # 扩展：添加 CategoryType
|
||
│ └── automation.ts # 新建：类型适配器
|
||
└── hooks/
|
||
└── useAutomationEvents.ts # 新建：WebSocket 事件 Hook
|
||
```
|
||
|
||
> **设计决策**: 不创建新的 `automationStore.ts`，而是扩展现有的 `handStore.ts` 和 `workflowStore.ts`，
|
||
> 通过轻量级的 `automationCoordinator.ts` 进行跨 store 协调。这遵循了现有代码库的模式。
|
||
|
||
---
|
||
|
||
## 三、核心组件设计
|
||
|
||
### 3.1 AutomationPanel（统一入口）
|
||
|
||
```typescript
|
||
interface AutomationPanelProps {
|
||
initialCategory?: CategoryType;
|
||
onSelect?: (item: AutomationItem) => void;
|
||
}
|
||
|
||
interface AutomationPanelState {
|
||
items: AutomationItem[]; // Hands + Workflows 合并
|
||
categories: CategoryStats; // 各分类统计
|
||
filters: FilterState; // 当前筛选条件
|
||
selectedIds: string[]; // 批量选择
|
||
viewMode: 'grid' | 'list'; // 视图模式
|
||
}
|
||
|
||
type CategoryType = 'all' | 'research' | 'data' | 'automation' | 'communication';
|
||
```
|
||
|
||
**UI 布局**:
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 自动化 [新建] [调度] │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||
│ │ 全部 │ │ 研究 │ │ 数据 │ │ 自动化 │ ... │
|
||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ [AutomationCard] [AutomationCard] [AutomationCard] │
|
||
│ [AutomationCard] [AutomationCard] [AutomationCard] │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 AutomationCard（统一卡片）
|
||
|
||
```typescript
|
||
interface AutomationCardProps {
|
||
item: AutomationItem;
|
||
status: ExecutionStatus;
|
||
result?: ExecutionResult;
|
||
onSelect: (selected: boolean) => void;
|
||
onExecute: (params?: Record<string, unknown>) => void;
|
||
onSchedule: () => void;
|
||
}
|
||
|
||
interface AutomationItem {
|
||
id: string;
|
||
name: string;
|
||
description: string;
|
||
type: 'hand' | 'workflow';
|
||
category: CategoryType;
|
||
status: ItemStatus;
|
||
parameters: Parameter[];
|
||
lastRun?: RunInfo;
|
||
schedule?: ScheduleInfo;
|
||
requiresApproval: boolean;
|
||
}
|
||
```
|
||
|
||
### 3.3 ScheduleEditor（可视化调度器）
|
||
|
||
```typescript
|
||
interface ScheduleEditorProps {
|
||
schedule?: ScheduleInfo;
|
||
onSave: (schedule: ScheduleInfo) => void;
|
||
onCancel: () => void;
|
||
}
|
||
|
||
interface ScheduleInfo {
|
||
enabled: boolean;
|
||
frequency: 'once' | 'daily' | 'weekly' | 'monthly' | 'custom';
|
||
time: { hour: number; minute: number };
|
||
daysOfWeek?: number[]; // 0-6 for weekly
|
||
dayOfMonth?: number; // 1-31 for monthly
|
||
customCron?: string; // 高级模式可选
|
||
timezone: string;
|
||
endDate?: Date;
|
||
}
|
||
```
|
||
|
||
**UI 设计**:
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 调度设置 [保存] │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 频率: ○ 一次 ● 每天 ○ 每周 ○ 每月 ○ 自定义 │
|
||
│ 时间: [09] : [00] 时区: [Asia/Shanghai ▼] │
|
||
│ ┌─ 每周重复 (选中"每周"时显示) ───────────────────────┐ │
|
||
│ │ [一] [二] [三] [四] [五] [六] [日] │ │
|
||
│ └───────────────────────────────────────────────────────┘ │
|
||
│ 结束日期: [无结束日期 ▼] 或 选择日期: [____-__-__] │
|
||
│ 预览: "每天 09:00 (Asia/Shanghai)，无结束日期" │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 四、结果流设计
|
||
|
||
### 4.1 消息类型扩展
|
||
|
||
```typescript
|
||
interface ChatMessage {
|
||
id: string;
|
||
role: 'user' | 'assistant' | 'system' | 'hand' | 'workflow'; // 新增
|
||
content: string;
|
||
timestamp: number;
|
||
|
||
executionInfo?: {
|
||
type: 'hand' | 'workflow';
|
||
name: string;
|
||
runId: string;
|
||
status: 'running' | 'completed' | 'failed' | 'needs_approval';
|
||
duration?: number;
|
||
output?: unknown;
|
||
error?: string;
|
||
};
|
||
}
|
||
```
|
||
|
||
### 4.2 结果消息渲染
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 🔍 Researcher │
|
||
│ ─────────────────────────────────────────────────────── │
|
||
│ 状态: ✅ 完成 耗时: 2m 34s │
|
||
│ │
|
||
│ ## 研究结果摘要 │
|
||
│ ... │
|
||
│ │
|
||
│ [查看完整报告] [下载 PDF] [重新执行] │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 五、批量操作设计
|
||
|
||
### 5.1 批量操作接口
|
||
|
||
```typescript
|
||
interface BatchOperations {
|
||
selectedIds: Set<string>;
|
||
|
||
executeSelected: (params?: Record<string, unknown>) => Promise<void>;
|
||
approveSelected: () => Promise<void>;
|
||
rejectSelected: (reason: string) => Promise<void>;
|
||
updateConfigSelected: (config: Partial<Config>) => Promise<void>;
|
||
scheduleSelected: (schedule: ScheduleInfo) => Promise<void>;
|
||
}
|
||
```
|
||
|
||
### 5.2 批量操作栏 UI
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 已选择 3 项 [取消选择] │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ [▶ 执行选中] [✓ 批量审批] [✗ 批量拒绝] [⏰ 批量调度] │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 5.3 批量审批队列
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 审批队列 (5 待处理) [全部批准] [全部拒绝] │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ☐ Browser - 访问 github.com/search │
|
||
│ 请求者: Agent-1 | 请求时间: 2分钟前 │
|
||
│ ☐ Lead - 搜索 LinkedIn 销售线索 │
|
||
│ 请求者: Agent-2 | 请求时间: 5分钟前 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 六、实时状态与错误处理
|
||
|
||
### 6.1 状态流转
|
||
|
||
```
|
||
┌─────────┐ trigger ┌─────────┐ execute ┌───────────┐
|
||
│ idle │ ──────────► │ pending │ ──────────► │ running │
|
||
└─────────┘ └─────────┘ └───────────┘
|
||
▲ │
|
||
│ ┌──────────────┐ │
|
||
└──────────────│ completed │◄───────────────────┘
|
||
└──────────────┘
|
||
│
|
||
┌──────────────┐
|
||
│ failed │
|
||
└──────────────┘
|
||
│
|
||
┌──────────────┐
|
||
│needs_approval│ ──approve──► running
|
||
└──────────────┘
|
||
```
|
||
|
||
### 6.2 WebSocket 事件处理
|
||
|
||
```typescript
|
||
interface AutomationWebSocketHandlers {
|
||
onHandStatus: (data: { name: string; status: string; runId?: string }) => void;
|
||
onHandResult: (data: { name: string; runId: string; result: unknown }) => void;
|
||
onWorkflowStep: (data: { id: string; step: number; status: string }) => void;
|
||
onWorkflowComplete: (data: { id: string; result: unknown }) => void;
|
||
onApprovalRequest: (data: ApprovalRequest) => void;
|
||
onApprovalResolved: (data: { id: string; approved: boolean }) => void;
|
||
}
|
||
```
|
||
|
||
### 6.3 错误处理
|
||
|
||
```typescript
|
||
type ErrorCode =
|
||
| 'CONNECTION_LOST'
|
||
| 'HAND_UNAVAILABLE'
|
||
| 'PARAM_INVALID'
|
||
| 'PERMISSION_DENIED'
|
||
| 'RATE_LIMITED'
|
||
| 'TIMEOUT'
|
||
| 'APPROVAL_REQUIRED'
|
||
| 'APPROVAL_REJECTED'
|
||
| 'EXECUTION_FAILED';
|
||
|
||
interface AutomationError {
|
||
code: ErrorCode;
|
||
message: string;
|
||
recoverable: boolean;
|
||
suggestedAction?: string;
|
||
}
|
||
```
|
||
|
||
### 6.4 离线队列
|
||
|
||
```typescript
|
||
interface ConnectionState {
|
||
status: 'connected' | 'disconnected' | 'reconnecting';
|
||
pendingActions: PendingAction[];
|
||
}
|
||
|
||
// 离线时缓存操作，重连后批量执行
|
||
```
|
||
|
||
---
|
||
|
||
## 七、实现计划
|
||
|
||
### 7.1 分阶段实施
|
||
|
||
| 阶段 | 任务 | 交付物 | 预计时间 |
|
||
|------|------|--------|---------|
|
||
| **Phase 1** | 基础修复 | 可用的 Hands 系统 | 1-2 天 |
|
||
| **Phase 2** | UI 重构 | 统一自动化面板 | 2-3 天 |
|
||
| **Phase 3** | 高级功能 | 调度与批量操作 | 2-3 天 |
|
||
| **Phase 4** | 工作流集成 | 完整自动化系统 | 2-3 天 |
|
||
|
||
### 7.2 文件变更清单
|
||
|
||
**新建文件**:
|
||
- `desktop/src/components/Automation/` 目录（7 个组件）
|
||
- `desktop/src/store/automationStore.ts`
|
||
- `desktop/src/types/automation.ts`
|
||
- `desktop/src/hooks/useAutomationEvents.ts`
|
||
- `tests/desktop/automation/` 测试目录
|
||
|
||
**修改文件**:
|
||
- `desktop/src/components/HandsPanel.tsx` - 重构为入口
|
||
- `desktop/src/store/handStore.ts` - 合并到 automationStore
|
||
- `desktop/src/lib/gateway-client.ts` - 增强 WebSocket 事件
|
||
- `desktop/src/store/chatStore.ts` - 支持 hand/workflow 消息类型
|
||
- `desktop/src/components/ChatArea.tsx` - 渲染结果流消息
|
||
- `desktop/src/components/Sidebar.tsx` - 导航更新
|
||
|
||
---
|
||
|
||
## 八、测试策略
|
||
|
||
### 8.1 测试覆盖
|
||
|
||
| 测试类型 | 覆盖范围 | 工具 |
|
||
|---------|---------|------|
|
||
| 单元测试 | Store 逻辑、工具函数、组件 | Vitest |
|
||
| 集成测试 | API 调用、WebSocket 事件 | Vitest + MSW |
|
||
| E2E 测试 | 完整用户流程 | Playwright |
|
||
|
||
### 8.2 关键测试用例
|
||
|
||
1. 参数从表单正确传递到 API
|
||
2. WebSocket 事件正确更新 UI 状态
|
||
3. 批量选择和操作功能
|
||
4. 调度器生成正确的 cron 表达式
|
||
5. 结果流消息正确注入聊天
|
||
6. 离线队列在重连后执行
|
||
7. 错误状态正确显示和恢复
|
||
|
||
---
|
||
|
||
## 九、验收标准
|
||
|
||
| 功能 | 验收标准 |
|
||
|------|---------|
|
||
| Hand 执行 | 填写参数 → 执行 → 看到实时进度 → 结果显示在聊天流 |
|
||
| 批量操作 | 选择 3 个 Hand → 批量执行 → 全部成功 |
|
||
| 调度 | 设置"每天 9:00" → 保存 → 在调度列表看到正确预览 |
|
||
| 审批 | Hand 需要审批 → 弹出审批请求 → 批准 → 继续执行 |
|
||
| 离线 | 断网 → 触发 Hand → 重连 → 自动执行 |
|
||
|
||
---
|
||
|
||
## 十、风险评估
|
||
|
||
| 风险 | 可能性 | 影响 | 缓解措施 |
|
||
|------|--------|------|---------|
|
||
| 后端 API 不完整 | 中 | 高 | 使用 fallback 数据，明确标注未实现 |
|
||
| WebSocket 不稳定 | 低 | 高 | 心跳机制 + 自动重连 + 离线队列 |
|
||
| 迁移影响现有功能 | 中 | 中 | 分阶段迁移，保留旧组件作为 fallback |
|
||
| 调度器复杂度 | 低 | 中 | 先实现基础频率，高级功能后续迭代 |
|
||
|
||
---
|
||
|
||
## 附录 A：API 端点参考
|
||
|
||
| 端点 | 方法 | 用途 |
|
||
|------|------|------|
|
||
| `/api/hands` | GET | 列出所有 Hands |
|
||
| `/api/hands/{name}` | GET | 获取 Hand 详情 |
|
||
| `/api/hands/{name}/activate` | POST | 触发 Hand 执行 |
|
||
| `/api/hands/{name}/runs/{runId}` | GET | 获取执行状态 |
|
||
| `/api/hands/{name}/runs/{runId}/approve` | POST | 批准执行 |
|
||
| `/api/hands/{name}/runs/{runId}/cancel` | POST | 取消执行 |
|
||
| `/api/hands/{name}/runs` | GET | 列出执行历史 |
|
||
| `/api/workflows` | GET/POST | 工作流管理 |
|
||
| `/api/triggers` | GET/POST/PUT/DELETE | 触发器管理 |
|
||
|
||
---
|
||
|
||
## 附录 B：WebSocket 事件参考
|
||
|
||
| 事件类型 | 字段 | 说明 |
|
||
|---------|------|------|
|
||
| `hand` | hand_name, hand_status, hand_result | Hand 状态变更 |
|
||
| `workflow` | workflow_id, step, status | Workflow 步骤变更 |
|
||
| `approval` | approval_id, type, status | 审批请求/响应 |
|