zclaw_openfang/docs/features/01-core-features/02-hands-system.md

Hands 系统 (Hands System)

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

📋 详细文档: 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 核心接口

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 配置格式

[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 已实现功能

• 11 个 Hand 配置定义
• 9 个 Rust 后端实现
• 9/9 Kernel 注册
• HAND.toml 配置解析
• 触发执行
• 审批流程
• 状态追踪
• Hand 列表 UI
• 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