# ZCLAW Hands & Workflow 集成开发方案

## 上下文

**目标**: 将 ZCLAW 的 Hands 和 Workflow 功能深度集成到 ZClaw 桌面客户端，提供与 ZCLAW Web 界面对等的用户体验。

**当前状态**:
- ZClaw 已有基础的 `HandsPanel.tsx` 和 `WorkflowList.tsx` 组件
- 这些组件功能有限，缺少 ZCLAW 的核心 UI 特性
- ZCLAW v0.4.0 提供了 8 个 Hands 和完整的 Workflow/Scheduler 系统

**参考界面**: http://127.0.0.1:50051 (ZCLAW Dashboard)

---

## 一、ZCLAW 界面分析总结

### 1.1 Hands 页面设计

```
┌─────────────────────────────────────────────────────────────────┐
│  Hands — Curated Autonomous Capability Packages                 │
│  Available 8 Active                                             │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 🌐 Browser Hand                              [READY]    │    │
│  │ Autonomous web browser — navigates sites...             │    │
│  │                                                         │    │
│  │ REQUIREMENTS                                            │    │
│  │ ✓ Python 3 must be installed                            │    │
│  │ ✓ Chromium or Google Chrome must be installed           │    │
│  │                                                         │    │
│  │ 18 tool(s) · 3 metric(s)  [productivity]               │    │
│  │                          [Details] [Activate]           │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
```

**详情弹窗内容**:
- AGENT CONFIG: Provider, Model
- REQUIREMENTS: 检查项和状态 (✓/✗)
- TOOLS: 工具名称列表
- DASHBOARD METRICS: 指标名称列表
- Activate 按钮

### 1.2 Workflows 页面设计

```
┌─────────────────────────────────────────────────────────────────┐
│  Workflows                                                      │
│  What are Workflows? Workflows chain multiple agents...         │
│  [List] [Visual Builder]                    [+ New Workflow]   │
├─────────────────────────────────────────────────────────────────┤
│  NAME              │ STEPS │ CREATED      │ ACTIONS            │
│  ──────────────────┼───────┼──────────────┼────────────────────│
│  测试工作流         │   1   │ 2026/3/14   │ [Run][Edit][Del]   │
└─────────────────────────────────────────────────────────────────┘
```

### 1.3 Scheduler 页面设计

```
┌─────────────────────────────────────────────────────────────────┐
│  Scheduler                                    [+ New Job]       │
│  [Scheduled Jobs] [Event Triggers]         [Run History]       │
├─────────────────────────────────────────────────────────────────┤
│  Scheduled Jobs                                                 │
│  Create cron-based scheduled jobs...                            │
│                                                                 │
│  [No scheduled jobs]                                            │
│  Create a cron job to run agents on a recurring schedule.       │
│  [+ Create Scheduled Job]                                       │
└─────────────────────────────────────────────────────────────────┘
```

### 1.4 Approvals 页面设计

```
┌─────────────────────────────────────────────────────────────────┐
│  Execution Approvals                          [Refresh]         │
│  [All] [Pending] [Approved] [Rejected]                          │
├─────────────────────────────────────────────────────────────────┤
│  [No approvals]                                                 │
│  When agents request permission for sensitive actions,          │
│  they'll appear here.                                           │
└─────────────────────────────────────────────────────────────────┘
```

---

## 二、ZClaw 现有实现分析

### 2.1 已有组件

| 文件 | 功能 | 完成度 |
|------|------|--------|
| `HandsPanel.tsx` | Hand 列表、触发、审批、取消 | 40% |
| `WorkflowList.tsx` | Workflow 列表、执行 | 30% |
| `TriggersPanel.tsx` | Trigger 列表 | 20% |
| `gatewayStore.ts` | 状态管理 (Hands/Workflow API) | 60% |

### 2.2 缺失功能

1. **Hands**:
   - ❌ 详情弹窗 (Details Modal)
   - ❌ Requirements 状态检查可视化
   - ❌ 工具和指标列表展示
   - ❌ Agent Config 显示 (Provider/Model)
   - ❌ 激活动画和状态反馈
   - ❌ 分类标签 (productivity/data/content/communication)

2. **Workflows**:
   - ❌ 创建/编辑 Workflow
   - ❌ Visual Builder
   - ❌ 执行历史查看
   - ❌ 步骤详情展示

3. **Scheduler**:
   - ❌ Scheduled Jobs 管理
   - ❌ Event Triggers 管理
   - ❌ Cron 表达式编辑器
   - ❌ Run History

4. **Approvals**:
   - ❌ 独立 Approvals 页面
   - ❌ 筛选功能 (All/Pending/Approved/Rejected)
   - ❌ 审批详情展示

---

## 三、开发方案

### 3.1 Phase 1: 增强 HandsPanel (优先级: 高)

**目标**: 提供与 ZCLAW 对等的 Hands 管理体验

**文件修改**:
- `desktop/src/components/HandsPanel.tsx` (重写)
- `desktop/src/components/HandDetailsModal.tsx` (新建)
- `desktop/src/store/gatewayStore.ts` (扩展)

**UI 设计**:

```tsx
// HandCard 组件结构
<div className="hand-card">
  <div className="hand-header">
    <span className="hand-icon">{hand.icon}</span>
    <h3>{hand.name}</h3>
    <StatusBadge status={hand.status} /> {/* READY/SETUP NEEDED/RUNNING */}
  </div>

  <p className="hand-description">{hand.description}</p>

  {/* Requirements 检查 */}
  {hand.requirements && (
    <div className="hand-requirements">
      <span className="label">REQUIREMENTS</span>
      {hand.requirements.map(req => (
        <div className={req.met ? 'met' : 'unmet'}>
          <span>{req.met ? '✓' : '✗'}</span>
          <span>{req.description}</span>
        </div>
      ))}
    </div>
  )}

  {/* 元信息 */}
  <div className="hand-meta">
    <span>{hand.toolCount} tool(s)</span>
    <span>{hand.metricCount} metric(s)</span>
    <span className="category-tag">{hand.category}</span>
  </div>

  {/* 操作按钮 */}
  <div className="hand-actions">
    <Button variant="outline" onClick={onDetails}>Details</Button>
    <Button variant="primary" onClick={onActivate} disabled={!hand.requirementsMet}>
      {hand.status === 'running' ? 'Running...' : 'Activate'}
    </Button>
  </div>
</div>
```

**HandDetailsModal 组件**:

```tsx
// 详情弹窗
<Modal>
  <ModalHeader>
    <span className="icon">{hand.icon}</span>
    <h2>{hand.name}</h2>
    <StatusBadge status={hand.status} />
  </ModalHeader>

  <ModalBody>
    {/* Agent Config */}
    <Section title="AGENT CONFIG">
      <Row label="Provider" value={hand.provider} />
      <Row label="Model" value={hand.model} />
    </Section>

    {/* Requirements */}
    <Section title="REQUIREMENTS">
      {hand.requirements.map(req => (
        <RequirementItem {...req} />
      ))}
    </Section>

    {/* Tools */}
    <Section title="TOOLS">
      <ToolGrid tools={hand.tools} />
    </Section>

    {/* Dashboard Metrics */}
    <Section title="DASHBOARD METRICS">
      <MetricList metrics={hand.metrics} />
    </Section>
  </ModalBody>

  <ModalFooter>
    <Button variant="outline" onClick={onClose}>Close</Button>
    <Button variant="primary" onClick={onActivate}>Activate</Button>
  </ModalFooter>
</Modal>
```

**API 扩展**:

```typescript
// gatewayStore.ts 扩展
interface Hand {
  id: string;
  name: string;
  description: string;
  status: 'idle' | 'running' | 'needs_approval' | 'error' | 'unavailable';
  icon?: string;
  category?: string; // productivity, data, content, communication
  provider?: string;
  model?: string;
  requirements?: Array<{
    description: string;
    met: boolean;
    details?: string;
  }>;
  tools?: string[];
  metrics?: string[];
  toolCount?: number;
  metricCount?: number;
  currentRunId?: string;
}

// 新增 API 调用
getHandDetails: (name: string) => Promise<HandDetails>;
activateHand: (name: string, params?: Record<string, unknown>) => Promise<HandRun>;
deactivateHand: (name: string) => Promise<void>;
```

### 3.2 Phase 2: 增强 WorkflowList (优先级: 高)

**目标**: 提供完整的 Workflow 管理能力

**文件修改**:
- `desktop/src/components/WorkflowList.tsx` (重写)
- `desktop/src/components/WorkflowEditor.tsx` (新建)
- `desktop/src/components/WorkflowHistory.tsx` (新建)
- `desktop/src/store/gatewayStore.ts` (扩展)

**UI 设计**:

```tsx
// WorkflowList 组件结构
<div className="workflow-list">
  <div className="workflow-header">
    <h2>Workflows</h2>
    <div className="view-toggle">
      <Button active={view === 'list'}>List</Button>
      <Button active={view === 'visual'}>Visual Builder</Button>
    </div>
    <Button variant="primary" onClick={onCreate}>+ New Workflow</Button>
  </div>

  <p className="workflow-description">
    Workflows chain multiple agents into automated pipelines...
  </p>

  <table className="workflow-table">
    <thead>
      <tr>
        <th>NAME</th>
        <th>STEPS</th>
        <th>CREATED</th>
        <th>ACTIONS</th>
      </tr>
    </thead>
    <tbody>
      {workflows.map(wf => (
        <tr key={wf.id}>
          <td>{wf.name}</td>
          <td>{wf.steps}</td>
          <td>{formatDate(wf.createdAt)}</td>
          <td>
            <Button size="sm" onClick={() => onRun(wf.id)}>Run</Button>
            <Button size="sm" onClick={() => onEdit(wf.id)}>Edit</Button>
            <Button size="sm" onClick={() => onHistory(wf.id)}>History</Button>
            <Button size="sm" variant="danger" onClick={() => onDelete(wf.id)}>Delete</Button>
          </td>
        </tr>
      ))}
    </tbody>
  </table>
</div>
```

**WorkflowEditor 组件** (简化版):

```tsx
<WorkflowEditor workflow={workflow}>
  <div className="workflow-editor">
    <div className="workflow-info">
      <Input label="Name" value={workflow.name} onChange={...} />
      <Textarea label="Description" value={workflow.description} onChange={...} />
    </div>

    <div className="workflow-steps">
      <h3>Steps</h3>
      {workflow.steps.map((step, index) => (
        <WorkflowStep
          key={index}
          step={step}
          onEdit={() => editStep(index)}
          onDelete={() => deleteStep(index)}
        />
      ))}
      <Button onClick={addStep}>+ Add Step</Button>
    </div>

    <div className="workflow-actions">
      <Button variant="outline" onClick={onCancel}>Cancel</Button>
      <Button variant="primary" onClick={onSave}>Save Workflow</Button>
    </div>
  </div>
</WorkflowEditor>
```

**API 扩展**:

```typescript
// gatewayStore.ts 扩展
interface Workflow {
  id: string;
  name: string;
  description?: string;
  steps: WorkflowStep[];
  createdAt: string;
  updatedAt?: string;
}

interface WorkflowStep {
  id: string;
  agentId: string;
  promptTemplate: string;
  inputMapping?: Record<string, string>;
  outputMapping?: Record<string, string>;
  condition?: string;
  timeout?: number;
}

// 新增 API 调用
createWorkflow: (workflow: CreateWorkflowInput) => Promise<Workflow>;
updateWorkflow: (id: string, updates: Partial<Workflow>) => Promise<Workflow>;
getWorkflowHistory: (id: string) => Promise<WorkflowRun[]>;
getWorkflowDetails: (id: string) => Promise<Workflow>;
```

### 3.3 Phase 3: 新建 SchedulerPanel (优先级: 中)

**目标**: 提供定时任务和事件触发器管理

**文件新建**:
- `desktop/src/components/SchedulerPanel.tsx`
- `desktop/src/components/ScheduledJobEditor.tsx`
- `desktop/src/components/EventTriggerEditor.tsx`

**UI 设计**:

```tsx
<SchedulerPanel>
  <Tabs defaultValue="scheduled">
    <TabsList>
      <TabsTrigger value="scheduled">Scheduled Jobs</TabsTrigger>
      <TabsTrigger value="triggers">Event Triggers</TabsTrigger>
    </TabsList>

    <TabsContent value="scheduled">
      <div className="scheduled-jobs">
        <Button onClick={onCreateJob}>+ Create Scheduled Job</Button>

        {jobs.length === 0 ? (
          <EmptyState
            title="No scheduled jobs"
            description="Create a cron job to run agents on a recurring schedule."
            action="+ Create Scheduled Job"
            onAction={onCreateJob}
          />
        ) : (
          <JobList jobs={jobs} onEdit={onEditJob} onDelete={onDeleteJob} />
        )}
      </div>
    </TabsContent>

    <TabsContent value="triggers">
      <div className="event-triggers">
        <p>Event triggers fire agents in response to system events...</p>
        {triggers.length === 0 ? (
          <EmptyState title="No event triggers" />
        ) : (
          <TriggerList triggers={triggers} />
        )}
      </div>
    </TabsContent>
  </Tabs>
</SchedulerPanel>
```

### 3.4 Phase 4: 新建 ApprovalsPanel (优先级: 中)

**目标**: 提供审批管理界面

**文件新建**:
- `desktop/src/components/ApprovalsPanel.tsx`

**UI 设计**:

```tsx
<ApprovalsPanel>
  <div className="approvals-header">
    <h2>Execution Approvals</h2>
    <Button onClick={onRefresh}>Refresh</Button>
  </div>

  <div className="approvals-filters">
    <Button active={filter === 'all'}>All</Button>
    <Button active={filter === 'pending'}>Pending</Button>
    <Button active={filter === 'approved'}>Approved</Button>
    <Button active={filter === 'rejected'}>Rejected</Button>
  </div>

  <div className="approvals-list">
    {filteredApprovals.length === 0 ? (
      <EmptyState
        title="No approvals"
        description="When agents request permission for sensitive actions, they'll appear here."
      />
    ) : (
      filteredApprovals.map(approval => (
        <ApprovalCard
          key={approval.id}
          approval={approval}
          onApprove={() => onApprove(approval.id)}
          onReject={() => onReject(approval.id)}
        />
      ))
    )}
  </div>
</ApprovalsPanel>
```

### 3.5 Phase 5: 导航重构 (优先级: 中)

**目标**: 重构导航结构，匹配 ZCLAW 布局

**文件修改**:
- `desktop/src/components/Sidebar.tsx`
- `desktop/src/components/RightPanel.tsx`
- `desktop/src/App.tsx`

**新导航结构**:

```
┌────────────────────┐
│ ZCLAW              │
├────────────────────┤
│ CHAT               │
│   └─ Chat          │
│ MONITOR            │
│   └─ Overview      │
│   └─ Analytics     │
│   └─ Logs          │
│ AGENTS             │
│   └─ Sessions      │
│   └─ Approvals     │
│   └─ Comms         │
│ AUTOMATION         │
│   └─ Workflows     │
│   └─ Scheduler     │
│ EXTENSIONS         │
│   └─ Channels      │
│   └─ Skills        │
│   └─ Hands         │
│ SYSTEM             │
│   └─ Runtime       │
│   └─ Settings      │
└────────────────────┘
```

---

## 四、关键文件清单

### 4.1 需要修改的文件

| 文件路径 | 修改内容 |
|----------|----------|
| `desktop/src/components/HandsPanel.tsx` | 重写 HandCard，添加详情弹窗 |
| `desktop/src/components/WorkflowList.tsx` | 添加创建/编辑功能 |
| `desktop/src/store/gatewayStore.ts` | 扩展 Hand/Workflow 类型定义 |
| `desktop/src/components/Sidebar.tsx` | 重构导航结构 |
| `desktop/src/components/RightPanel.tsx` | 集成新组件 |
| `desktop/src/lib/gateway-client.ts` | 添加新 API 调用 |

### 4.2 需要新建的文件

| 文件路径 | 功能 |
|----------|------|
| `desktop/src/components/HandDetailsModal.tsx` | Hand 详情弹窗 |
| `desktop/src/components/WorkflowEditor.tsx` | Workflow 编辑器 |
| `desktop/src/components/WorkflowHistory.tsx` | Workflow 执行历史 |
| `desktop/src/components/SchedulerPanel.tsx` | Scheduler 管理面板 |
| `desktop/src/components/ScheduledJobEditor.tsx` | 定时任务编辑器 |
| `desktop/src/components/EventTriggerEditor.tsx` | 事件触发器编辑器 |
| `desktop/src/components/ApprovalsPanel.tsx` | 审批管理面板 |

---

## 五、验证方案

### 5.1 手动测试

1. **Hands 测试**:
   - 启动 ZClaw，连接 ZCLAW (端口 50051)
   - 打开 Hands 标签
   - 验证 8 个 Hands 正确显示
   - 点击 Details 查看详情弹窗
   - 点击 Activate 激活一个 Hand
   - 验证状态变化和反馈

2. **Workflow 测试**:
   - 打开 Workflow 标签
   - 创建新 Workflow
   - 编辑 Workflow 步骤
   - 执行 Workflow
   - 查看执行历史

3. **Scheduler 测试**:
   - 创建定时任务
   - 编辑 Cron 表达式
   - 验证任务触发

4. **Approvals 测试**:
   - 触发需要审批的 Hand
   - 验证 Approvals 页面显示
   - 批准/拒绝审批

### 5.2 自动化测试

```bash
# 运行相关测试
pnpm vitest run tests/desktop/handsPanel.test.tsx
pnpm vitest run tests/desktop/workflowList.test.tsx
pnpm vitest run tests/desktop/gatewayStore.test.ts

# 类型检查
pnpm tsc --noEmit
```

---

## 六、开发顺序 (根据用户确认)

**用户选择**:
- ✅ 优先实现 Hands 增强
- ✅ 需要完整实现 Scheduler 和 Approvals

**推荐开发顺序**:

| 顺序 | Phase | 工作量 | 说明 |
|------|-------|--------|------|
| 1 | Phase 1: HandsPanel 增强 | 2-3 天 | 最高优先级，核心功能 |
| 2 | Phase 4: ApprovalsPanel | 1 天 | Hand 执行需要审批流程 |
| 3 | Phase 2: WorkflowList 增强 | 2-3 天 | 完整工作流管理 |
| 4 | Phase 3: SchedulerPanel | 2 天 | 定时任务和事件触发器 |
| 5 | Phase 5: 导航重构 | 1-2 天 | 统一导航结构 |
| **总计** | - | **8-11 天** | - |

---

## 六-A、第一步实施细节: HandsPanel 增强

### 文件修改清单

1. **`desktop/src/components/HandsPanel.tsx`** (重写)
   - 添加 HandCard 组件重构
   - 添加状态徽章 (READY/SETUP NEEDED/RUNNING)
   - 添加 Requirements 可视化
   - 添加分类标签
   - 添加工具/指标计数

2. **`desktop/src/components/HandDetailsModal.tsx`** (新建)
   - Agent Config 显示 (Provider/Model)
   - Requirements 列表
   - Tools 列表
   - Dashboard Metrics 列表
   - Activate 按钮

3. **`desktop/src/store/gatewayStore.ts`** (扩展)
   - 扩展 Hand 类型定义
   - 添加 getHandDetails API

4. **`desktop/src/lib/gateway-client.ts`** (扩展)
   - 添加 getHandDetails 方法

### UI 组件设计

```tsx
// HandStatusBadge 组件
type HandStatus = 'idle' | 'running' | 'needs_approval' | 'error' | 'unavailable' | 'setup_needed';

const STATUS_CONFIG: Record<HandStatus, { label: string; className: string }> = {
  idle: { label: 'READY', className: 'bg-green-100 text-green-700' },
  running: { label: 'RUNNING', className: 'bg-blue-100 text-blue-700 animate-pulse' },
  needs_approval: { label: 'NEEDS APPROVAL', className: 'bg-yellow-100 text-yellow-700' },
  error: { label: 'ERROR', className: 'bg-red-100 text-red-700' },
  unavailable: { label: 'UNAVAILABLE', className: 'bg-gray-100 text-gray-500' },
  setup_needed: { label: 'SETUP NEEDED', className: 'bg-orange-100 text-orange-700' },
};

// RequirementItem 组件
function RequirementItem({ description, met, details }: Requirement) {
  return (
    <div className={`flex items-start gap-2 text-sm ${met ? 'text-green-700' : 'text-red-600'}`}>
      <span className="flex-shrink-0">{met ? '✓' : '✗'}</span>
      <span>{description}</span>
      {details && <span className="text-gray-400 text-xs">({details})</span>}
    </div>
  );
}
```

---

## 七、风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| ZCLAW API 变更 | 高 | 使用实际 API 测试验证，保持与 ZCLAW v0.4.0 兼容 |
| UI 复杂度 | 中 | 分阶段实现，先核心功能后高级功能 |
| 性能问题 | 低 | 使用虚拟列表处理大量数据 |

---

*计划创建时间: 2026-03-14*
*参考版本: ZCLAW v0.4.0*