feat(hands): restructure Hands UI with Chinese localization

Major changes:
- Add HandList.tsx component for left sidebar
- Add HandTaskPanel.tsx for middle content area
- Restructure Sidebar tabs: 分身/HANDS/Workflow
- Remove Hands tab from RightPanel
- Localize all UI text to Chinese
- Archive legacy OpenClaw documentation
- Add Hands integration lessons document
- Update feature checklist with new components

UI improvements:
- Left sidebar now shows Hands list with status icons
- Middle area shows selected Hand's tasks and results
- Consistent styling with Tailwind CSS
- Chinese status labels and buttons

Documentation:
- Create docs/archive/openclaw-legacy/ for old docs
- Add docs/knowledge-base/hands-integration-lessons.md
- Update docs/knowledge-base/feature-checklist.md
- Update docs/knowledge-base/README.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
2026-03-14 23:16:32 +08:00
parent 67e1da635d
commit 07079293f4
126 changed files with 36229 additions and 1035 deletions

View File

@@ -0,0 +1,185 @@
# 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 状态管理选中项
**实现**:
```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 调用(目前使用模拟数据)
---
## 六、参考资料
- [OpenFang 技术参考](../openfang-technical-reference.md)
- [功能清单](./feature-checklist.md)
- [前端集成指南](./frontend-integration.md)
- [OpenFang WebSocket 协议](./openfang-websocket-protocol.md)
---
*文档创建: 2026-03-14*