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

Hands 集成经验总结

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

---

一、任务概述

1.1 目标

将 OpenFang 的 Hands（自主能力包）功能深度集成到 ZClaw 桌面客户端，提供与 OpenFang 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 状态管理选中项

实现:

// 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

关键字段:

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

---

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

3.1 未使用导入错误

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

解决: 及时清理未使用的导入

// 移除未使用的 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 调用（目前使用模拟数据）

---

六、参考资料

• OpenFang 技术参考
• 功能清单
• 前端集成指南
• OpenFang WebSocket 协议

---

文档创建: 2026-03-14