---
title: Hands + Skills
updated: 2026-04-11
status: active
tags: [module, hands, skills]
---

# Hands + Skills

> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]] [[butler]]

## 设计思想

**Hands = 自主能力 (行动层), Skills = 知识技能 (认知层)**

- Hands: 浏览器自动化、数据收集、Twitter 操作等 — **执行动作**
- Skills: 75 个 SKILL.md 文件 — **语义路由匹配**，增强 LLM 的领域知识
- 触发: 用户请求 → LLM 判断需要执行 → 选择 Hand/Skill → 执行

## 代码逻辑

### Hands (9 启用)

每个 Hand 有独立的 `hands/<Name>.HAND.toml` 配置和 `crates/zclaw-hands/src/hands/` 下的 Rust 实现。

| Hand | 功能 | 依赖 | 测试数 | 配置 |
|------|------|------|--------|------|
| Browser | 浏览器自动化 (23 Tauri命令) | WebDriver | 8 | `hands/browser.HAND.toml` |
| Collector | 数据收集聚合 | — | 8 | `hands/collector.HAND.toml` |
| Researcher | 深度研究 | LLM | 22 | `hands/researcher.HAND.toml` |
| Clip | 视频处理 | FFmpeg | 30 | `hands/clip.HAND.toml` |
| Twitter | Twitter 自动化 (12 API v2) | OAuth 1.0a | 25 | `hands/twitter.HAND.toml` |
| Whiteboard | 白板演示 | — | — | `hands/whiteboard.HAND.toml` |
| Slideshow | 幻灯片生成 | — | 13 | `hands/slideshow.HAND.toml` |
| Speech | 语音合成 | Browser TTS | — | `hands/speech.HAND.toml` |
| Quiz | 测验生成 | — | — | `hands/quiz.HAND.toml` |

Hands 测试分布（前 5）: Clip(30), Twitter(25), Researcher(22), Slideshow(13), Browser(8)

### 禁用 Hands

| Hand | 状态 | 说明 |
|------|------|------|
| Predictor | 禁用 | 无 TOML/无 Rust 实现，仅概念定义 |
| Lead | 禁用 | 无 TOML/无 Rust 实现，仅概念定义 |

### 触发流

```
UI 触发 → handStore.trigger(handName, params)
  → Tauri invoke('hand_execute', { handName, params })
    → Kernel → Hand 执行
    → needs_approval? → 等待 approvalStore 确认
    → 执行结果 → Tauri Event emit
    → handStore 更新状态 + 记录日志
```

Hand 相关 Tauri 命令 (8 个):
`hand_list, hand_execute, hand_approve, hand_cancel, hand_get, hand_run_status, hand_run_list, hand_run_cancel`

### Skills (75 个目录)

```
skills/
├── accessibility-auditor/       api-tester/
├── agentic-identity-trust/      app-store-optimizer/
├── agents-orchestrator/         backend-architect/
├── ai-engineer/                 brand-guardian/
├── analytics-reporter/          chart-visualization/
├── chinese-writing/             classroom-generator/
├── code-review/                 consulting-analysis/
├── content-creator/             data-analysis/
├── data-consolidation-agent/    deep-research/
├── devops-automator/            evidence-collector/
├── ... (75 个目录，每个含 SKILL.md)
```

每个 SKILL.md 定义:
- 技能名称和描述
- 触发条件
- 执行步骤
- 输入/输出格式

### 语义路由

`crates/zclaw-skills/src/semantic_router.rs`

```
用户消息 → SemanticSkillRouter
  → TF-IDF 计算消息与 75 个技能的相似度
  → 返回 { skill_id, confidence }
  → ButlerRouter 使用 RoutingHint 增强 system prompt
```

在 kernel 中通过 `SemanticRouterAdapter` 桥接到 `ButlerRouterBackend` trait。

## 关联模块

- [[chat]] — 消息流中可能触发 Hand/Skill
- [[butler]] — ButlerRouter 使用语义路由匹配技能
- [[middleware]] — SkillIndex 中间件注入技能索引

## 关键文件

| 文件 | 职责 |
|------|------|
| `crates/zclaw-hands/src/hands/` | 9 个 Hand 实现 |
| `crates/zclaw-skills/src/semantic_router.rs` | TF-IDF 语义路由 |
| `crates/zclaw-skills/src/` | 技能解析和索引 |
| `skills/*/SKILL.md` | 75 个技能定义 |
| `hands/*.HAND.toml` | 9 个 Hand 配置 |
| `desktop/src/store/handStore.ts` | 前端 Hand 状态 |
| `desktop/src/store/browserHandStore.ts` | Browser Hand 专用 |
| `desktop/src-tauri/src/kernel_commands/hand.rs` | Hand Tauri 命令 (8) |