# 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 格式

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

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

---

## 五、实际效果

### 5.1 已实现功能

- [x] 7 个 Hand 定义
- [x] HAND.toml 配置格式
- [x] 触发执行
- [x] 审批流程
- [x] 状态追踪
- [x] Hand 列表 UI
- [x] 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 风险与挑战
- **技术风险**: 后端实现完整性
- **安全风险**: 自动化操作的权限控制
- **缓解措施**: 审批流程，审计日志