zclaw_openfang/docs/features/audit-v12/M3-hands-system.md

# 模块 M3 Hands 自主能力 审计报告

> **审计版本**: V12
> **审计日期**: 2026-04-04
> **审计范围**: 11 个自主能力包触发/审批/执行/回调完整流程

---

## 1. 模块概况

### 功能描述
9 个已实现 Hand（Browser/Researcher/Collector/Clip/Twitter/Whiteboard/Slideshow/Speech/Quiz），含触发、审批、执行、事件回调全流程。

### 涉及文件清单

**前端**
- Store: `desktop/src/store/handStore.ts`, `desktop/src/store/browserHandStore.ts`
- Client: `desktop/src/lib/kernel-hands.ts`, `desktop/src/lib/browser-client.ts`
- 自主管理: `desktop/src/lib/autonomy-manager.ts`
- UI: `desktop/src/components/Automation/` (ApprovalQueue, AutomationPanel, ExecutionResult 等)

**后端 (Rust)**
- Tauri 命令: `desktop/src-tauri/src/kernel_commands/hand.rs`, `approval.rs`
- Kernel: `crates/zclaw-kernel/src/kernel/hands.rs`, `crates/zclaw-kernel/src/kernel/approvals.rs`
- Registry: `crates/zclaw-hands/src/registry.rs`
- Hand 实现: `crates/zclaw-hands/src/hands/` (9 个 .rs 文件)
- 配置: `hands/*.HAND.toml` (9 个)

### 调用链路图

```
用户触发 Hand
  → AutomationPanel.triggerHand(id, params)
    → handStore.triggerHand()
      → canAutoExecute('hand_trigger', 5) [前端自主性检查]
      → client.triggerHand(name, params, autonomyLevel)
        → KernelClient.triggerHand() → invoke('hand_execute', { id, input, autonomyLevel })
          → Rust hand_execute:
            ├─ supervised 模式 → 创建 ApprovalEntry → 返回 pending_approval
            ├─ needs_approval + 非 autonomous → 创建 ApprovalEntry
            └─ autonomous 或无需审批 → kernel.execute_hand()
              → HandRegistry.execute() → Hand::execute()
              → 创建 HandRun (Pending→Running→Completed/Failed)
              → emit("hand-execution-complete")

审批流程:
  ApprovalQueue → handStore.respondToApproval()
    → invoke('approval_respond', { id, approved, reason })
      → kernel.respond_to_approval()
        → tokio::spawn 异步执行 Hand + 轮询完成
        → emit("hand-execution-complete")

前端事件接收:
  kernel-hands.ts onHandExecutionComplete → listen("hand-execution-complete")
    → [问题: 前端未注册全局监听]
```

---

## 2. 五维检查结果

### 2.1 链路完整性

| 链路 | 起点 | 终点 | 状态 | 备注 |
|------|------|------|------|------|
| Hand 列举 | AutomationPanel | Registry.list() | ✅ 连通 | |
| Hand 触发（直接执行） | handStore | Hand::execute() | ⚠️ **run_id 丢失** | hand.rs:184 丢弃 _run_id |
| Hand 触发（需审批） | handStore | ApprovalEntry | ✅ 连通 | |
| 审批确认 | ApprovalQueue | Hand::execute() | ✅ 连通 | 两条重复路径 |
| hand-execution-complete 事件 | Rust emit | 前端 listen | ⚠️ **无人接收** | onHandExecutionComplete 未被调用 |
| Browser Hand (Rust) | BrowserHand::execute() | 浏览器操作 | ❌ **断裂** | 只返回结构化指令不执行 |
| Browser Hand (前端) | browserHandStore | browser-client → Rust browser_* 命令 | ✅ 连通 | 但绕过审批流程 |
| Hand 取消 | handStore | cancel_flag AtomicBool | ✅ 连通 | |
| Hand 运行状态查询 | handStore | Rust hand_run_status | ✅ 连通 | |

### 2.2 参数/类型一致性

| 接口 | 前端参数 | 后端参数 | 一致性 | 备注 |
|------|---------|---------|--------|------|
| hand_execute | `{ id, input, autonomyLevel }` | `id, input, autonomy_level` | ✅ | camelCase 正确转换 |
| hand_approve | `{ handName, runId, approved, reason }` | `hand_name, run_id, approved, reason` | ✅ | |
| approval_respond | `{ id, approved, reason }` | `id, approved, reason` | ✅ | |
| hand_execute 返回值 | 期望 `{ instance_id, status }` | 实际 `{ success, output, error, durationMs }` | ❌ **不匹配** | 前端拿不到 run_id |
| TOML permissions/rate_limit | 定义了但未使用 | HandConfig 只有基础字段 | ❌ **配置未生效** | |

### 2.3 边界与错误处理

| 场景 | 预期行为 | 实际行为 | 级别 |
|------|---------|---------|------|
| 触发不存在的 Hand | 返回错误 | ✅ ZclawError::NotFound | P4 正确 |
| 并发触发同一 Hand | 限流/拒绝 | ❌ 无保护，可无限并发 | **P1** |
| Hand 执行超时 | 超时终止 | ❌ `timeout_secs` 定义但未使用 | **P1** |
| 审批不响应 | 超时清理 | ❌ 永不过期，pending 无限积累 | P2 |
| Hand 执行失败 | 错误传播到 UI | ✅ 错误传播链路完整 | P4 正确 |
| max_concurrent 限制 | 限制并发数 | ❌ TOML 定义但未实现 | P2 |
| Clip Hand 路径含单引号 | 正常执行 | ⚠️ FFmpeg concat 文件解析可能异常 | P3 |

### 2.4 状态管理

| Store/组件 | 状态机完整性 | 持久化 | 竞态风险 |
|-----------|------------|--------|---------|
| handStore | ✅ idle/running/needs_approval/error/unavailable/setup_needed | ❌ 无持久化 | ⚠️ triggerHand 后依赖异步 loadHands 更新状态 |
| browserHandStore | ✅ sessions/execution/logs/templates | ❌ 无持久化 | ⚠️ 独立于 handStore，绕过审批 |
| autonomy-manager | ✅ 三级自主+三级风险 | ✅ localStorage | ❌ 仅前端，后端无强制 |

### 2.5 安全与资源

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 审批安全（跨 Hand 攻击防护） | ✅ | entry.hand_id == hand_name 校验 |
| Approval ID 不可预测 | ✅ | UUID v4 |
| Browser Hand 绕过审批 | ❌ **P1** | browserHandStore 完全绕过 autonomy-manager |
| TOML requires_approval 形同虚设 | ❌ **P1** | browserHandStore 不走审批流程 |
| 审批内存不释放 | ⚠️ P2 | Vec<ApprovalEntry> 无限增长 |
| Clip Hand 命令注入防护 | ✅ | 使用 Command::new + .args() 非 shell |

---

## 3. 问题清单

| ID | 描述 | 文件:行号 | 级别 | 修复建议 | 验证方法 |
|----|------|----------|------|---------|---------|
| M3-01 | **hand_execute 丢弃 run_id** — 前端拿不到执行 ID，无法追踪运行状态 | `hand.rs:184` | **P1** | 将 HandRunId 包含在返回结果中 | triggerHand 后检查返回值含 runId |
| M3-02 | **Browser Hand 双路径断裂** — Rust execute() 只返回结构化指令不执行实际操作 | `browser.rs:191-343` | **P1** | 统一路径：要么 Rust 端执行操作，要么移除 Rust BrowserHand | 通过 handStore 触发 browser 验证 |
| M3-03 | **browserHandStore 绕过审批** — 无视 TOML requires_approval = true | `browserHandStore.ts:222-339` | **P1** | browserHandStore 操作前检查 autonomy-manager | 在 autonomous=false 下执行浏览器操作 |
| M3-04 | **max_concurrent 未实现** — TOML 定义但运行时无检查 | `kernel/hands.rs` | **P1** | 在 execute_hand 中添加并发计数检查 | 并发触发同一 Hand |
| M3-05 | **timeout_secs 未实现** — Hand 可无限挂起 | `hand.rs:47` | **P1** | 在 execute 中使用 tokio::time::timeout 包装 | 启动长时间 Hand 验证超时 |
| M3-06 | hand_execute 返回值类型不匹配 | `kernel-hands.ts:94` vs Rust `HandResult` | **P2** | 统一返回类型定义 | 检查 triggerHand 返回值 |
| M3-07 | hand-execution-complete 事件前端无人监听 | `kernel-hands.ts:195` | **P2** | 应用初始化时注册全局监听 | 审批执行完成后检查 UI 更新 |
| M3-08 | 审批条目永不过期，内存不释放 | `approvals.rs:16-19` | **P2** | 添加 expires_at + 定期清理 | 检查长期运行后的 pending_approvals 大小 |
| M3-09 | 重复审批确认路径（hand_approve vs approval_respond） | `hand.rs:196-295` vs `approval.rs:54-142` | **P2** | 统一为单一审批路径 | 检查两路径是否行为一致 |
| M3-10 | tool_count/metric_count 硬编码为 0 | `hand.rs:82-83` | **P2** | 从 Hand 实际能力中计算 | 检查 hand_list 返回值 |
| M3-11 | TOML permissions/rate_limit/audit 配置未被读取 | `hands/*.HAND.toml` vs `hand.rs:10-32` | **P3** | 扩展 HandConfig 或在运行时解析 | 修改 TOML 验证行为无变化 |
| M3-12 | hand_trigger 在 autonomy-manager 中永远不自动允许 | `autonomy-manager.ts:268` | **P3** | 修正映射逻辑 | 设为 autonomous 后触发 Hand |
| M3-13 | Clip Hand concat 文件路径单引号未转义 | `clip.rs:448` | **P3** | 转义路径中的单引号 | 使用含单引号的路径执行 concat |

---

## 4. 改进建议

### 短期修复（按优先级）

1. **[P1]** 修复 `hand_execute` 返回 `run_id`：在 HandResult 中添加 `run_id` 字段
2. **[P1]** 统一 Browser Hand 路径：移除 Rust BrowserHand 的假执行，让 handStore 走 browserHandStore
3. **[P1]** browserHandStore 集成审批流程：在 executeTemplate 前检查 autonomy-manager
4. **[P1]** 实现 `max_concurrent` 并发限制
5. **[P1]** 实现 `timeout_secs` 超时保护

### 长期架构建议

- 注册 `hand-execution-complete` 全局监听器到 handStore
- 统一审批路径（移除重复的 hand_approve / approval_respond）
- 添加审批 TTL 和自动清理
- 扩展 HandConfig 解析 TOML 中的权限/限流/审计配置

---

## 5. 健康度评分

| 维度 | 评分 | 说明 |
|------|------|------|
| 链路完整性 | **55/100** | Browser Hand 断裂、事件无人接收、run_id 丢失 |
| 参数一致性 | **70/100** | invoke 参数匹配但返回值不匹配、TOML 配置未生效 |
| 边界处理 | **50/100** | 无并发限制、无超时、审批不过期 |
| 状态管理 | **60/100** | 基本状态机存在但 browserHandStore 独立运作 |
| 安全资源 | **55/100** | Browser Hand 绕过审批是核心安全问题 |

**综合健康度: 58/100**

5 个 P1 级问题集中在此模块（run_id 丢失、Browser 断裂、绕过审批、无并发限制、无超时）。修复 P1 后预计可提升至 75+。