zclaw_openfang/docs/knowledge-base/hands-integration-lessons.md

# Hands 集成经验总结

**完成日期**: 2026-03-14
**任务**: 将 ZCLAW Hands 功能集成到 ZClaw 桌面客户端

---

## 一、任务概述

### 1.1 目标

将 ZCLAW 的 Hands（自主能力包）功能深度集成到 ZClaw 桌面客户端，提供与 ZCLAW Web 界面对等的用户体验。

### 1.2 完成内容

1. **布局重构**：
   - 左侧 Sidebar 的 Hands 标签显示自主能力包列表
   - 中间区域显示选中 Hand 的任务清单和执行结果
   - 右侧面板移除 Hands 相关内容

2. **中文化**：
   - 所有 UI 文本改为中文
   - 状态标签、按钮、提示信息全部本地化

3. **新增组件**：
   - `HandList.tsx` - 左侧导航的 Hands 列表
   - `HandTaskPanel.tsx` - Hand 任务和结果面板

---

## 二、关键技术决策

### 2.1 组件拆分策略

**决策**: 将 Hands 功能拆分为列表展示和详情展示两个独立组件

**理由**:
- 符合单一职责原则
- 便于独立维护和测试
- 与现有布局结构匹配

**代码结构**:
```
desktop/src/components/
├── HandList.tsx          # 左侧列表组件
├── HandTaskPanel.tsx     # 中间详情面板
├── Sidebar.tsx           # 集成 HandList
└── App.tsx               # 路由和状态管理
```

### 2.2 状态管理

**决策**: 使用 App.tsx 中的 selectedHandId 状态管理选中项

**实现**:
```typescript
// App.tsx
const [selectedHandId, setSelectedHandId] = useState<string | undefined>(undefined);

// 传递给 Sidebar
<Sidebar
  selectedHandId={selectedHandId}
  onSelectHand={setSelectedHandId}
/>

// 中间区域根据状态显示不同内容
{mainContentView === 'hands' && selectedHandId ? (
  <HandTaskPanel handId={selectedHandId} onBack={() => setSelectedHandId(undefined)} />
) : ...}
```

### 2.3 类型定义

**决策**: 扩展 gatewayStore 中的 Hand 类型以支持新 UI

**关键字段**:
```typescript
interface Hand {
  id: string;
  name: string;
  description: string;
  status: 'idle' | 'running' | 'needs_approval' | 'error' | 'unavailable' | 'setup_needed';
  icon?: string;
  toolCount?: number;
  // ... 其他字段
}
```

---

## 三、遇到的问题与解决方案

### 3.1 未使用导入错误

**问题**: 创建组件时引入了未使用的依赖

**解决**: 及时清理未使用的导入
```typescript
// 移除未使用的 useState
// 移除未使用的类型 HandRun, RefreshCw
```

### 3.2 布局一致性

**问题**: 新组件需要与现有 UI 风格保持一致

**解决**:
- 使用 Tailwind CSS 类保持样式一致
- 参考 ChatArea.tsx 等现有组件的结构
- 使用 lucide-react 图标库保持图标一致

### 3.3 状态同步

**问题**: 选中 Hand 后需要同时更新左侧高亮和中间内容

**解决**:
- 通过 props 传递 selectedHandId
- 在 Sidebar 中处理点击事件并通知父组件
- 使用回调函数 `onSelectHand` 实现状态提升

---

## 四、最佳实践

### 4.1 组件设计

1. **保持组件精简**: 每个组件不超过 300 行
2. **使用 TypeScript 接口**: 明确定义 Props 类型
3. **添加文档注释**: 说明组件用途和关键参数

### 4.2 状态管理

1. **状态提升**: 共享状态放在最近的共同父组件
2. **单向数据流**: 通过 props 传递，通过回调更新
3. **使用 Zustand**: 全局状态通过 store 管理

### 4.3 UI 开发

1. **中文化优先**: 所有用户可见文本使用中文
2. **状态反馈**: 加载中、错误、空状态都要有明确提示
3. **可访问性**: 添加 title 属性，使用语义化标签

---

## 五、后续工作

### 5.1 待完成功能

根据 `plans/fancy-sprouting-teacup.md` 计划：

1. **Phase 1**: HandsPanel 增强
   - 详情弹窗 (Details Modal)
   - Requirements 状态可视化
   - 工具和指标列表展示

2. **Phase 2**: WorkflowList 增强
   - 创建/编辑 Workflow
   - 执行历史查看

3. **Phase 3**: SchedulerPanel
   - 定时任务管理
   - 事件触发器

4. **Phase 4**: ApprovalsPanel
   - 独立审批页面
   - 筛选功能

### 5.2 技术债务

- [ ] 添加单元测试覆盖新组件
- [ ] 处理 gatewayStore.ts 中的预存 TypeScript 错误
- [ ] 实现真实的 API 调用（目前使用模拟数据）

---

## 六、参考资料

- [ZCLAW 技术参考](../zclaw-technical-reference.md)
- [功能清单](./feature-checklist.md)
- [前端集成指南](./frontend-integration.md)
- [ZCLAW WebSocket 协议](./zclaw-websocket-protocol.md)

---

*文档创建: 2026-03-14*