# Hands 系统 (Hands System)

> **分类**: 核心功能
> **优先级**: P1 - 重要
> **成熟度**: L4 - 生产
> **最后更新**: 2026-03-25
> **验证状态**: ✅ 代码已验证

> 📋 **详细文档**: [05-hands-system/00-hands-overview.md](../05-hands-system/00-hands-overview.md)

---

## 一、功能概述

### 1.1 基本信息

Hands 是 ZCLAW 的自主能力包系统，每个 Hand 封装了一类自动化任务，支持多种触发方式和审批流程。

| 属性 | 值 |
|------|-----|
| 分类 | 核心功能 |
| 优先级 | P1 |
| 成熟度 | L4 |
| 依赖 | handStore, KernelClient, HandRegistry (Rust) |
| **Hand 总数** | **11** |
| **已实现后端** | **9 (82%)** |
| **Kernel 注册** | **9/9 (100%)** |

### 1.2 已实现 Hands (9/11)

| Hand | 功能 | 状态 | 依赖 |
|------|------|------|------|
| **browser** | 浏览器自动化 | ✅ 可用 | Fantoccini WebDriver |
| **slideshow** | 演示控制 | ✅ 可用 | - |
| **speech** | 语音合成 | ✅ 可用 | SSML |
| **quiz** | 问答生成 | ✅ 可用 | - |
| **whiteboard** | 白板绘图 | ✅ 可用 | - |
| **researcher** | 深度研究 | ✅ 可用 | - |
| **collector** | 数据采集 | ✅ 可用 | - |
| **clip** | 视频处理 | ⚠️ 需 FFmpeg | FFmpeg |
| **twitter** | Twitter 自动化 | ⚠️ 需 API Key | Twitter API |

### 1.3 规划中 Hands (2/11)

| Hand | 功能 | 状态 |
|------|------|------|
| predictor | 预测分析 | ❌ 规划中 |
| lead | 销售线索发现 | ❌ 规划中 |

### 1.4 相关文件

| 文件 | 路径 | 用途 |
|------|------|------|
| 配置文件 | `hands/*.HAND.toml` | 11 个 Hand 定义 |
| Rust 实现 | `crates/zclaw-hands/src/hands/` | 9 个 Hand 实现 |
| Hand Registry | `crates/zclaw-hands/src/registry.rs` | 注册和执行 |
| Kernel 集成 | `crates/zclaw-kernel/src/kernel.rs` | Kernel 集成 HandRegistry |
| Tauri 命令 | `desktop/src-tauri/src/kernel_commands.rs` | hand_list, hand_execute |
| 状态管理 | `desktop/src/store/handStore.ts` | Hand 状态 |
| UI 组件 | `desktop/src/components/HandList.tsx` | Hand 列表 |

---

## 二、技术设计

### 2.1 核心接口

```typescript
interface Hand {
  name: string;
  version: string;
  description: string;
  type: HandType;
  requiresApproval: boolean;
  timeout: number;
  maxConcurrent: number;
  triggers: TriggerConfig;
  permissions: string[];
  rateLimit: RateLimit;
  status: HandStatus;
}

interface HandRun {
  id: string;
  handName: string;
  status: 'pending' | 'running' | 'completed' | 'failed' | 'needs_approval';
  input: any;
  output?: any;
  error?: string;
  startedAt: number;
  completedAt?: number;
}

type HandStatus = 'idle' | 'running' | 'needs_approval' | 'error' | 'unavailable' | 'setup_needed';
```

### 2.2 HAND.toml 配置格式

```toml
[hand]
name = "browser"
version = "1.0.0"
description = "浏览器自动化能力包"
type = "automation"
requires_approval = true
timeout = 300
max_concurrent = 3
tags = ["browser", "automation", "web"]

[hand.config]
browser = "chrome"
headless = true
timeout = 30

[hand.triggers]
manual = true
schedule = false
webhook = true

[hand.permissions]
requires = ["web.access", "file.write"]
roles = ["operator.write"]

[hand.rate_limit]
max_requests = 50
window_seconds = 3600
```

### 2.3 执行流程

```
触发 Hand
    │
    ▼
检查前置条件 (权限/并发/速率)
    │
    ▼
需要审批?
    │
    ├──► 是 → 创建审批请求 → 用户批准/拒绝
    │
    └──► 否 → 直接执行
    │
    ▼
调用后端 API (Rust HandRegistry)
    │
    ▼
更新状态 / 记录日志
    │
    ▼
完成/失败
```

---

## 三、高级功能

### 3.1 支持参数的 Hands

- `collector`: targetUrl, selector, outputFormat, pagination
- `browser`: url, actions[], selectors[], waitTime
- `clip`: inputPath, outputFormat, trimStart, trimEnd

### 3.2 支持 Actions 的 Hands

- `whiteboard`: draw_text, draw_shape, draw_line, draw_chart, draw_latex, clear, export
- `slideshow`: next_slide, prev_slide, goto_slide, spotlight, laser, highlight
- `speech`: speak, speak_ssml, pause, resume, stop, list_voices

### 3.3 支持工作流步骤的 Hands

- `researcher`: search → extract → analyze → report
- `collector`: fetch → parse → transform → export

---

## 四、实际效果

### 4.1 已实现功能

- [x] 11 个 Hand 配置定义
- [x] 9 个 Rust 后端实现
- [x] 9/9 Kernel 注册
- [x] HAND.toml 配置解析
- [x] 触发执行
- [x] 审批流程
- [x] 状态追踪
- [x] Hand 列表 UI
- [x] Hand 详情面板

### 4.2 测试覆盖

- **单元测试**: 10+ 项
- **集成测试**: 包含在 gatewayStore.test.ts
- **覆盖率**: ~70%

### 4.3 已知问题

| 问题 | 严重程度 | 状态 |
|------|---------|------|
| 定时触发 UI 待完善 | 中 | 待处理 |
| Predictor/Lead 未实现 | 低 | 规划中 |

---

## 五、演化路线

### 5.1 短期计划（1-2 周）
- [ ] 完善定时触发 UI
- [ ] 添加 Hand 执行历史

### 5.2 中期计划（1-2 月）
- [ ] 实现 Predictor Hand
- [ ] 实现 Lead Hand
- [ ] Hand 市场 UI

### 5.3 长期愿景
- [ ] 用户自定义 Hand
- [ ] Hand 共享社区

---

> 📋 **完整文档**: 详见 [05-hands-system/00-hands-overview.md](../05-hands-system/00-hands-overview.md)