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

Hands 系统概述 (Hands Overview)

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

✅ 实现状态更新: 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 格式

[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 核心接口

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 状态管理

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

• 11 个 Hand 定义
• HAND.toml 配置格式
• 触发执行
• 审批流程
• 状态追踪
• Hand 列表 UI
• Hand 详情面板
• Browser Hand 完整实现 (Fantoccini WebDriver)
• 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 风险与挑战

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