zclaw_openfang/docs/features/05-hands-system/00-hands-overview.md

# Hands 系统概述 (Hands Overview)

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

> ✅ **实现状态更新**: 11 个 Hands 中有 **9 个** 已有完整 Rust 后端实现。所有 9 个已实现 Hands 均已在 Kernel 中注册并可通过 `hand_execute` 命令调用。
>
> **已实现 Hands**: Browser, Slideshow, Speech, Quiz, Whiteboard, Researcher, Collector, Clip, Twitter
> **规划中 Hands**: Predictor, Lead

---

## 一、功能概述

### 1.1 基本信息

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

| 属性 | 值 |
|------|-----|
| 分类 | Hands 系统 |
| 优先级 | P1 |
| 成熟度 | L4 |
| 依赖 | handStore, KernelClient, HandRegistry (Rust) |
| Hand 配置数 | 11 |
| **已实现后端** | **9 (82%)** |
| **Kernel 注册** | **9/9 (100%)** |
| **Crate 完整度** | **85%** |

### 1.2 Crate 架构

```
crates/zclaw-hands/
├── src/
│   ├── lib.rs           # Crate 入口
│   ├── registry.rs      # HandRegistry (RwLock HashMap)
│   ├── trigger.rs       # Trigger 管理
│   └── hands/
│       ├── mod.rs
│       ├── browser.rs   # ✅ Fantoccini WebDriver
│       ├── slideshow.rs # ✅ 演示控制
│       ├── speech.rs    # ✅ 语音合成 (SSML)
│       ├── quiz.rs      # ✅ 问答生成
│       ├── whiteboard.rs# ✅ 白板绘图
│       ├── researcher.rs# ✅ 深度研究
│       ├── collector.rs # ✅ 数据采集
│       ├── clip.rs      # ✅ 视频处理 (需 FFmpeg)
│       └── twitter.rs   # ✅ Twitter API (需 API Key)
└── Cargo.toml
```

### 1.3 实现状态

| Hand | 配置文件 | 后端实现 | Kernel 注册 | 可用性 | 代码位置 |
|------|---------|---------|-------------|--------|---------|
| **browser** | ✅ browser.HAND.toml | ✅ Rust impl | ✅ | ✅ **可用** | `crates/zclaw-hands/src/hands/browser.rs` |
| **slideshow** | ✅ slideshow.HAND.toml | ✅ Rust impl | ✅ | ✅ **可用** | `crates/zclaw-hands/src/hands/slideshow.rs` |
| **speech** | ✅ speech.HAND.toml | ✅ Rust impl | ✅ | ✅ **可用** | `crates/zclaw-hands/src/hands/speech.rs` |
| **quiz** | ✅ quiz.HAND.toml | ✅ Rust impl | ✅ | ✅ **可用** | `crates/zclaw-hands/src/hands/quiz.rs` |
| **whiteboard** | ✅ whiteboard.HAND.toml | ✅ Rust impl | ✅ | ✅ **可用** | `crates/zclaw-hands/src/hands/whiteboard.rs` |
| **researcher** | ✅ researcher.HAND.toml | ✅ Rust impl | ✅ | ✅ **可用** | `crates/zclaw-hands/src/hands/researcher.rs` |
| **collector** | ✅ collector.HAND.toml | ✅ Rust impl | ✅ | ✅ **可用** | `crates/zclaw-hands/src/hands/collector.rs` |
| **clip** | ✅ clip.HAND.toml | ✅ Rust impl | ✅ | ⚠️ **需 FFmpeg** | `crates/zclaw-hands/src/hands/clip.rs` |
| **twitter** | ✅ twitter.HAND.toml | ✅ Rust impl | ✅ | ⚠️ **需 API Key** | `crates/zclaw-hands/src/hands/twitter.rs` |
| predictor | ✅ predictor.HAND.toml | ❌ 规划中 | ❌ | ❌ 不可用 | - |
| lead | ✅ lead.HAND.toml | ❌ 规划中 | ❌ | ❌ 不可用 | - |

### 1.3 相关文件

| 文件 | 路径 | 用途 |
|------|------|------|
| 配置文件 | `hands/*.HAND.toml` | 11 个 Hand 定义 |
| Rust Hand 实现 | `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 状态 |
| Browser Hand Store | `desktop/src/store/browserHandStore.ts` | Browser Hand 专用状态 |
| UI 组件 | `desktop/src/components/HandList.tsx` | Hand 列表 |
| 详情面板 | `desktop/src/components/HandTaskPanel.tsx` | Hand 详情 |

---

## 二、设计初衷

### 2.1 问题背景

**用户痛点**:
1. 重复性任务需要手动执行
2. 定时任务缺乏统一管理
3. 事件触发难以配置

**系统缺失能力**:
- 缺乏自动化任务包
- 缺乏多种触发方式
- 缺乏审批流程

**为什么需要**:
Hands 提供了可复用的自主能力包，让 Agent 能够自动化执行各类任务。

### 2.2 设计目标

1. **可复用**: 封装通用能力
2. **多触发**: 手动、定时、事件
3. **可控**: 审批流程
4. **可观测**: 状态追踪和日志

### 2.3 HAND.toml 格式

```toml
[hand]
name = "researcher"
version = "1.0.0"
description = "深度研究和分析能力包"
type = "research"
requires_approval = false
timeout = 300
max_concurrent = 3
tags = ["research", "analysis", "web-search"]

[hand.config]
search_engine = "auto"
max_search_results = 10
depth = "standard"

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

[hand.permissions]
requires = ["web.search", "web.fetch", "file.read", "file.write"]
roles = ["operator.read", "operator.write"]

[hand.rate_limit]
max_requests = 20
window_seconds = 3600

[hand.audit]
log_inputs = true
log_outputs = true
retention_days = 30
```

### 2.4 设计约束

- **安全约束**: 敏感操作需要审批
- **资源约束**: 并发执行限制
- **审计约束**: 所有操作需要记录

---

## 三、技术设计

### 3.1 Hands 列表

| Hand | 类型 | 功能 | 触发方式 | 需审批 |
|------|------|------|---------|-------|
| researcher | research | 深度研究和分析 | 手动/事件 | 否 |
| browser | automation | 浏览器自动化、网页抓取 | 手动/Webhook | 是 |
| lead | automation | 销售线索发现和筛选 | 定时/手动 | 是 |
| clip | automation | 视频处理、剪辑、竖屏生成 | 手动/定时 | 否 |
| collector | data | 数据收集和聚合 | 定时/事件/手动 | 否 |
| predictor | data | 预测分析、回归/分类/时间序列 | 手动/定时 | 否 |
| twitter | communication | Twitter/X 自动化 | 定时/事件 | 是 |
| whiteboard | collaboration | 白板协作和绘图 | 手动 | 否 |
| slideshow | presentation | 幻灯片生成和演示 | 手动 | 否 |
| speech | communication | 语音合成和识别 | 手动/事件 | 否 |
| quiz | education | 问答和测验生成 | 手动 | 否 |

### 3.2 高级 Hand 功能

**支持参数的 Hands:**
- `collector`: targetUrl, selector, outputFormat, pagination
- `predictor`: dataSource, model, targetColumn, featureColumns
- `clip`: inputPath, outputFormat, trimStart, trimEnd
- `twitter`: action, content, schedule, mediaUrls

**支持工作流步骤的 Hands:**
- `researcher`: search → extract → analyze → report
- `collector`: fetch → parse → transform → export
- `predictor`: load → preprocess → train → evaluate → predict → report

**支持 Actions 的 Hands:**
- `whiteboard`: draw_text, draw_shape, draw_line, draw_chart, draw_latex, draw_table, clear, export
- `slideshow`: next_slide, prev_slide, goto_slide, spotlight, laser, highlight, play_animation
- `speech`: speak, speak_ssml, pause, resume, stop, list_voices, set_voice
- `quiz`: generate, grade, analyze, hint, explain, adaptive_next, generate_report

### 3.3 核心接口

```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;
  approvedBy?: string;
}

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

### 3.3 执行流程

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

### 3.4 状态管理

```typescript
interface HandState {
  hands: Hand[];
  handRuns: Record<string, HandRun[]>;
  triggers: Trigger[];
  approvals: Approval[];
}

// handStore actions
const useHandStore = create<HandState>((set, get) => ({
  hands: [],
  handRuns: {},
  triggers: [],
  approvals: [],

  fetchHands: async () => { /* ... */ },
  triggerHand: async (name, input) => { /* ... */ },
  approveRun: async (runId) => { /* ... */ },
  rejectRun: async (runId, reason) => { /* ... */ },
}));
```

---

## 四、预期作用

### 4.1 用户价值

| 价值类型 | 描述 |
|---------|------|
| 效率提升 | 自动化重复任务 |
| 灵活控制 | 多种触发方式 |
| 安全可控 | 审批流程保障 |

### 4.2 系统价值

| 价值类型 | 描述 |
|---------|------|
| 架构收益 | 可扩展的自动化框架 |
| 可维护性 | 标准化配置格式 |
| 可扩展性 | 易于添加新 Hand |

### 4.3 成功指标

| 指标 | 基线 | 目标 | 当前 |
|------|------|------|------|
| Hand 数量 | 0 | 10+ | 11 |
| 执行成功率 | 50% | 95% | 90% |
| 审批响应时间 | - | <5min | 3min |

---

## 五、实际效果

### 5.1 已实现功能

- [x] 11 个 Hand 定义
- [x] HAND.toml 配置格式
- [x] 触发执行
- [x] 审批流程
- [x] 状态追踪
- [x] Hand 列表 UI
- [x] Hand 详情面板
- [x] Browser Hand 完整实现 (Fantoccini WebDriver)
- [x] Rust 后端集成

### 5.2 测试覆盖

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

### 5.3 已知问题

| 问题 | 严重程度 | 状态 | 计划解决 |
|------|---------|------|---------|
| 定时触发 UI 待完善 | 中 | 待处理 | Q2 |
| 部分Hand后端未实现 | 低 | 已知 | - |

### 5.4 用户反馈

Hand 概念清晰，但需要更多实际可用的能力包。

---

## 六、演化路线

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

### 6.2 中期计划（1-2 月）
- [ ] Hand 市场 UI
- [ ] 用户自定义 Hand

### 6.3 长期愿景
- [ ] Hand 共享社区
- [ ] 复杂工作流编排

---

## 七、头脑风暴笔记

### 7.1 待讨论问题
1. 是否需要支持 Hand 链式调用？
2. 如何处理 Hand 之间的依赖？

### 7.2 创意想法
- Hand 模板：预定义常用 Hand
- Hand 组合：多个 Hand 组成工作流
- Hand 市场：共享和下载 Hand

### 7.3 风险与挑战
- **技术风险**: 后端实现完整性
- **安全风险**: 自动化操作的权限控制
- **缓解措施**: 审批流程，审计日志