zclaw_openfang/wiki/hands-skills.md

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

# Hands + Skills + MCP

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

## 设计思想

**Hands = 自主能力 (行动层), Skills = 知识技能 (认知层), MCP = 外部工具协议**

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

## 代码逻辑

### 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。

### Skill 调用链路（LLM Tool Calling）

```
Skills 目录 → SkillRegistry 加载 → SkillIndexMiddleware(P200) 注入系统提示
  → LLM 看到 skill_load + execute_skill 工具定义
  → LLM 生成 ToolUse{skill_load} → AgentLoop 执行 → 返回技能详情
  → LLM 生成 ToolUse{execute_skill} → AgentLoop 执行 → KernelSkillExecutor
  → Skill 执行结果 → ToolResult → LLM 继续对话
```

关键路径：
- `kernel/mod.rs:create_tool_registry()` 注册 7 个内置工具（含 skill_load, execute_skill）
- `runtime/loop_runner.rs` 检测 `ContentBlock::ToolUse` → 调用 `Tool::execute()`
- `runtime/tool/builtin/execute_skill.rs` → `KernelSkillExecutor::execute_skill()`
- Anthropic Driver: ToolResult 必须用 `ContentBlock::ToolResult{tool_use_id, content}` 格式

## MCP (Model Context Protocol)

### 概述

MCP 允许 ZCLAW 在运行时连接外部工具服务器（如 filesystem、database、custom tools），让 LLM 在对话中直接调用这些工具。

### 架构

```
前端 UI (MCPServices.tsx)
  → mcp-client.ts → Tauri invoke('mcp_start_service', {config})
    → McpManagerState → McpServiceManager → BasicMcpClient (stdio transport)
      → MCP Server 进程 → list_tools → 注册 adapters

LLM 对话调用:
  Kernel.create_tool_registry()
    → 遍历 mcp_adapters (Arc<RwLock<Vec<McpToolAdapter>>>)
    → McpToolWrapper 包装为 Tool trait
    → 注册到 ToolRegistry → LLM API tool definitions

  LLM 生成 ToolUse{filesystem.read_file}
    → AgentLoop → McpToolWrapper.execute()
    → McpToolAdapter.execute() → MCP Server → 结果返回
```

### 关键桥接机制

`McpManagerState` 和 `Kernel` 共享同一个 `Arc<RwLock<Vec<McpToolAdapter>>>`：
- Kernel boot 时，`kernel_init` 将 `McpManagerState.kernel_adapters` Arc 注入到 Kernel
- MCP 服务启动/停止时，`sync_to_kernel()` 更新共享列表
- `create_tool_registry()` 每次对话时读取最新 adapters

### MCP Tauri 命令 (4 个)

| 命令 | 功能 |
|------|------|
| `mcp_start_service` | 启动 MCP 服务 + 发现工具 + 同步到 Kernel |
| `mcp_stop_service` | 停止服务 + 从 Kernel 移除工具 |
| `mcp_list_services` | 列出所有运行中的服务和工具 |
| `mcp_call_tool` | 手动调用 MCP 工具（支持 service_name 精确路由） |

### 限定名规则

MCP 工具在 ToolRegistry 中使用限定名 `service_name.tool_name` 避免冲突。
例如：`filesystem.read_file`, `database.query`。

## 关联模块

- [[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 配置 |
| `crates/zclaw-protocols/src/mcp_tool_adapter.rs` | MCP 工具适配器 + 服务管理 |
| `crates/zclaw-protocols/src/mcp.rs` | MCP 协议类型 + BasicMcpClient |
| `crates/zclaw-runtime/src/tool/builtin/mcp_tool.rs` | McpToolWrapper (Tool trait 桥接) |
| `crates/zclaw-runtime/src/driver/anthropic.rs` | Anthropic Driver (含 ToolResult 格式) |
| `desktop/src/store/handStore.ts` | 前端 Hand 状态 |
| `desktop/src/store/browserHandStore.ts` | Browser Hand 专用 |
| `desktop/src/lib/mcp-client.ts` | 前端 MCP 客户端 |
| `desktop/src-tauri/src/kernel_commands/mcp.rs` | MCP Tauri 命令 (4) + Kernel 桥接 |
| `desktop/src-tauri/src/kernel_commands/hand.rs` | Hand Tauri 命令 (8) |