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:
185
docs/knowledge-base/hands-integration-lessons.md
Normal file
185
docs/knowledge-base/hands-integration-lessons.md
Normal 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*
|
||||
Reference in New Issue
Block a user