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

Hands 系统概述 (Hands Overview)

分类: Hands 系统 优先级: P1 - 重要 成熟度: L3 - 成熟 最后更新: 2026-03-16

---

一、功能概述

1.1 基本信息

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

属性	值
分类	Hands 系统
优先级	P1
成熟度	L3
依赖	handStore, GatewayClient

1.2 相关文件

文件	路径	用途
配置文件	hands/*.HAND.toml	7 个 Hand 定义
状态管理	desktop/src/store/handStore.ts	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 自动化	定时/事件	是

3.2 核心接口

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+	7
执行成功率	50%	95%	90%
审批响应时间	-	<5min	3min

---

五、实际效果

5.1 已实现功能

• 7 个 Hand 定义
• HAND.toml 配置格式
• 触发执行
• 审批流程
• 状态追踪
• Hand 列表 UI
• Hand 详情面板

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 风险与挑战

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