adfd7024df
- Restructure §8 from "文档沉淀规则" to "文档管理规则" with 4 subsections - Add docs/ structure with features/ and knowledge-base/ directories - Add feature documentation template with 7 sections (概述/设计初衷/技术设计/预期作用/实际效果/演化路线/头脑风暴) - Add feature update trigger matrix (新增/修改/完成/问题/反馈) - Add documentation quality checklist - Add §16
301 lines
6.5 KiB
Markdown
301 lines
6.5 KiB
Markdown
# 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 风险与挑战
|
||
- **技术风险**: 后端实现完整性
|
||
- **安全风险**: 自动化操作的权限控制
|
||
- **缓解措施**: 审批流程，审计日志
|