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>
2026-03-14 23:16:32 +08:00
parent 67e1da635d
commit 07079293f4
126 changed files with 36229 additions and 1035 deletions
--- a/desktop/E2E_TEST_REPORT.md
+++ b/desktop/E2E_TEST_REPORT.md
@@ -0,0 +1,381 @@
+# ZCLAW Desktop E2E 测试报告
+
+**测试日期**: 2026-03-13
+**测试环境**: Windows 11 Pro, Chrome DevTools MCP
+**测试范围**: 前端 UI 组件、OpenFang 集成、设置页面
+
+---
+
+## 测试概览
+
+| 测试类别 | 通过 | 失败 | 总计 |
+|---------|------|------|------|
+| 前端页面加载 | 5 | 0 | 5 |
+| 设置页面功能 | 6 | 0 | 6 |
+| OpenFang UI 组件 | 5 | 0 | 5 |
+| TypeScript 编译 | 1 | 0 | 1 |
+| **总计** | **17** | **0** | **17** |
+
+---
+
+## 详细测试结果
+
+### 1. 前端页面加载测试
+
+#### 1.1 主页面加载 ✓
+- **状态**: 通过
+- **验证点**:
+  - 页面标题显示 "ZCLAW"
+  - 左侧边栏显示分身、IM 频道、定时任务按钮
+  - 右侧面板显示会话统计和运行概览
+  - Gateway 连接状态正确显示
+
+#### 1.2 设置页面导航 ✓
+- **状态**: 通过
+- **验证点**:
+  - 点击侧边栏底部设置按钮可进入设置页面
+  - 设置页面左侧显示导航菜单
+  - 右侧显示设置内容区域
+
+#### 1.3 设置页面路由 ✓
+- **状态**: 通过
+- **验证点**:
+  - 通用、用量统计、积分详情、模型与 API 等页面可切换
+  - 审计日志页面可访问
+  - 关于页面可访问
+
+---
+
+### 2. 设置页面功能测试
+
+#### 2.1 后端设置 UI ✓
+- **状态**: 通过
+- **验证项**:
+  - Gateway 类型选择器 (OpenClaw/OpenFang) 正常工作
+  - 切换到 OpenFang 时：
+    - 默认端口显示 4200
+    - 协议显示 "WebSocket + REST API"
+    - 配置格式显示 "TOML"
+    - 显示 OpenFang 特有功能提示
+  - 切换到 OpenClaw 时：
+    - 默认端口显示 18789
+    - 协议显示 "WebSocket RPC"
+    - 配置格式显示 "JSON/YAML"
+
+#### 2.2 外观与行为设置 ✓
+- **状态**: 通过
+- **验证项**:
+  - 主题模式切换按钮存在
+  - 开机自启开关存在
+  - 显示工具调用开关存在
+
+#### 2.3 Gateway 连接设置 ✓
+- **状态**: 通过
+- **验证项**:
+  - 连接状态显示正确
+  - 地址输入框存在
+  - Token 输入框存在
+  - 当前模型显示正确 (glm-5)
+  - 错误信息正确显示
+
+#### 2.4 本地 Gateway 管理 ✓
+- **状态**: 通过
+- **验证项**:
+  - 运行环境显示 "浏览器预览"
+  - 本地状态显示 "当前模式不支持"
+  - CLI 状态显示 "当前模式不支持"
+  - 服务注册显示 "未注册"
+  - 提示信息正确显示
+
+#### 2.5 审计日志页面 ✓
+- **状态**: 通过
+- **验证项**:
+  - 标题显示 "审计日志"
+  - 每页条数选择器 (25/50/100/200) 存在
+  - 刷新按钮存在
+  - 空状态提示 "暂无审计日志" 正确显示
+
+#### 2.6 关于页面 ✓
+- **状态**: 通过
+- **验证项**:
+  - 版本号显示 "0.2.0"
+  - 检查更新按钮存在
+  - 更新日志按钮存在
+  - 版权信息显示正确
+
+---
+
+### 3. OpenFang UI 组件测试
+
+#### 3.1 Hands 面板 ✓
+- **状态**: 通过
+- **位置**: 右侧面板 "Hands" 按钮
+- **验证项**:
+  - 按钮可点击
+  - 空状态提示 "暂无可用的 Hands" 显示
+  - 安全状态指示器存在
+
+#### 3.2 触发器面板 ✓
+- **状态**: 通过
+- **验证项**:
+  - 标题 "触发器 (Triggers)" 显示
+  - 刷新按钮存在
+  - 空状态提示 "暂无可用的触发器" 显示
+
+#### 3.3 Workflows 显示 ✓
+- **状态**: 通过
+- **验证项**:
+  - 空状态提示 "暂无可用的 Workflows" 显示
+
+#### 3.4 审计日志组件 ✓
+- **状态**: 通过
+- **验证项**:
+  - 右侧面板集成审计日志组件
+  - 每页条数选择器正常
+  - 刷新按钮正常
+  - 空状态提示正常
+
+#### 3.5 安全状态指示器 ✓
+- **状态**: 通过
+- **验证项**:
+  - 显示 "连接后可用" 提示
+  - 组件位置正确
+
+---
+
+### 4. TypeScript 编译测试
+
+#### 4.1 类型检查 ✓
+- **状态**: 通过
+- **修复内容**:
+  - 添加 `Hand` 接口的 `currentRunId` 可选属性
+  - 添加 `cancelWorkflow` 方法到 `gatewayStore.ts`
+  - 添加 `cancelWorkflow` 方法到 `gateway-client.ts`
+- **结果**: `pnpm tsc --noEmit` 无错误
+
+---
+
+## 代码变更摘要
+
+### 新增功能
+1. **后端设置 UI** (`General.tsx`)
+   - 添加 OpenClaw/OpenFang 后端类型选择器
+   - 显示后端特性信息（端口、协议、配置格式）
+   - OpenFang 特有功能提示
+
+2. **TypeScript 类型修复**
+   - `gatewayStore.ts`: 添加 `Hand.currentRunId` 和 `cancelWorkflow`
+   - `gateway-client.ts`: 添加 `cancelWorkflow` API 方法
+
+### 文件修改
+- `desktop/src/components/Settings/General.tsx` - 添加后端设置 UI
+- `desktop/src/store/gatewayStore.ts` - 类型修复
+- `desktop/src/lib/gateway-client.ts` - API 方法添加
+
+---
+
+## 测试环境信息
+
+```
+操作系统: Windows 11 Pro 10.0.26200
+Node.js: v20.x
+包管理器: pnpm
+开发服务器: Vite 7.3.1
+测试工具: Chrome DevTools MCP
+```
+
+---
+
+## 待后续测试
+
+1. **Tauri 桌面端测试**
+   - 本地 Gateway 启动/停止功能
+   - CLI 检测功能
+   - 服务注册功能
+
+2. **连接真实 OpenFang 后测试**
+   - Hands 触发和审批流程
+   - Workflow 执行
+   - 审计日志获取
+   - 安全状态显示
+
+3. **集成测试**
+   - 聊天功能
+   - 流式响应
+   - 模型切换
+
+---
+
+## 结论
+
+本次 E2E 测试覆盖了 ZCLAW Desktop 的主要前端功能，所有测试项目均通过。OpenFang 相关 UI 组件已正确集成并显示，后端类型切换功能正常工作。
+
+**测试状态**: ✅ 全部通过
+
+---
+
+## 5. WebSocket 流式聊天测试 (2026-03-14)
+
+### 5.1 OpenFang 协议发现 ✅
+
+**测试方法:** 直接 WebSocket 连接到 `ws://127.0.0.1:50051/api/agents/{agentId}/ws`
+
+**发现:**
+- OpenFang 实际使用的消息格式与文档不同
+- 正确的消息格式: `{ type: 'message', content, session_id }`
+- 错误的文档格式: `{ type: 'chat', message: { role, content } }`
+
+**流式事件类型:**
+| 事件类型 | 说明 | 数据格式 |
+|---------|------|----------|
+| `connected` | 连接成功 | `{ agent_id, type }` |
+| `agents_updated` | Agent 列表更新 | `{ agents, type }` |
+| `typing` | 输入状态 | `{ state: 'start'/'stop' }` |
+| `phase` | 阶段变化 | `{ phase: 'streaming'/'done' }` |
+| `text_delta` | 文本增量 | `{ content }` |
+| `response` | 完整响应 | `{ content, input_tokens, output_tokens }` |
+| `error` | 错误 | `{ content }` |
+
+### 5.2 流式聊天测试 ✅
+
+**测试消息:** "Hello! Please count from 1 to 5, one number per line"
+
+**测试结果:**
+```
+📤 发送消息...
+📥 收到: typing (state: start)
+📥 收到: phase (streaming)
+📥 收到: text_delta "1\n2\n3\n4\n5"
+📥 收到: phase (done)
+📥 收到: typing (state: stop)
+📥 收到: response (input_tokens: 13555, output_tokens: 11)
+```
+
+**结论:** 流式聊天工作正常 ✅
+
+### 5.3 代码修复
+
+**修复内容:**
+1. `gateway-client.ts`:
+   - 更新 `chatStream()` 使用正确的消息格式
+   - 更新 `handleOpenFangStreamEvent()` 处理实际的事件类型
+   - 添加 `setDefaultAgentId()` 和 `getDefaultAgentId()` 方法
+
+2. `chatStore.ts`:
+   - 更新 `sendMessage()` 使用流式 API
+   - 添加 `onDelta`、`onTool`、`onHand`、`onComplete`、`onError` 回调
+
+3. `gatewayStore.ts`:
+   - 在 `loadClones()` 中自动设置默认 Agent
+
+4. `vite.config.ts`:
+   - 添加 `ws: true` 启用 WebSocket 代理
+
+---
+
+## 6. API 端点测试 (2026-03-14)
+
+### 6.1 Health API ✅
+```bash
+curl http://127.0.0.1:50051/api/health
+# {"status":"ok","version":"0.4.0"}
+```
+
+### 6.2 Agents API ✅
+```bash
+curl http://127.0.0.1:50051/api/agents
+# 返回 10 个 Agent
+```
+
+### 6.3 Hands API ✅
+```bash
+curl http://127.0.0.1:50051/api/hands
+# 返回 8 个 Hands
+```
+
+### 6.4 REST Chat API ✅
+```bash
+curl -X POST http://127.0.0.1:50051/api/agents/{id}/message \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Hello"}'
+# 返回 AI 响应
+```
+
+---
+
+## 7. Tauri 桌面端 E2E 测试 (2026-03-14)
+
+### 7.1 后端 API 测试 ✅
+
+| 测试项 | 状态 | 详情 |
+|--------|------|------|
+| OpenFang 健康检查 | ✅ PASS | 版本 0.4.0 |
+| Agent 列表 | ✅ PASS | 10 个 Agent |
+| Hands 列表 | ✅ PASS | 8 个 Hands |
+| WebSocket 流式聊天 | ✅ PASS | 正确接收 text_delta 事件 |
+
+### 7.2 WebSocket 流式聊天验证 ✅
+
+**测试命令:**
+```javascript
+const ws = new WebSocket('ws://127.0.0.1:50051/api/agents/{agentId}/ws');
+ws.send(JSON.stringify({
+  type: 'message',
+  content: 'Say hello',
+  session_id: 'test_session'
+}));
+```
+
+**收到的事件序列:**
+1. `connected` - 连接成功
+2. `typing` (state: start) - 开始输入
+3. `agents_updated` - Agent 状态更新
+4. `phase` (streaming) - 流式输出开始
+5. `text_delta` - 文本增量 ✅
+6. `phase` (done) - 流式输出完成
+7. `typing` (state: stop) - 输入结束
+8. `response` - 完整响应 (含 token 统计)
+
+### 7.3 服务运行状态
+
+| 服务 | 端口 | 状态 |
+|------|------|------|
+| Tauri Desktop | - | ✅ 运行中 (PID 72760) |
+| Vite Dev Server | 1420 | ✅ 运行中 |
+| OpenFang Backend | 50051 | ✅ 运行中 (v0.4.0) |
+
+### 7.4 前端功能待验证
+
+请在 Tauri 桌面窗口中进行以下手动测试：
+
+#### 聊天功能
+- [ ] 发送消息测试流式响应
+- [ ] 验证消息内容实时更新
+- [ ] 测试切换 Agent
+- [ ] 测试新建/切换/删除对话
+
+#### Hands 面板
+- [ ] 验证 8 个 Hands 显示
+- [ ] 测试触发一个 requirements_met: true 的 Hand
+- [ ] 测试取消执行
+
+#### 设置页面
+- [ ] 验证后端切换功能
+- [ ] 验证 Agent 列表显示
+
+---
+
+## 8. 注意事项
+
+### LLM 提供商配置
+
+部分 Agent 使用的 LLM 提供商可能未配置 API Key：
+
+| Agent | 提供商 | 模型 | 状态 |
+|-------|--------|------|------|
+| General Assistant | zhipu | glm-4-flash | ✅ 可用 |
+| sales-assistant | bailian | qwen3.5-plus | ⚠️ 需配置 |
+| test-engineer | gemini | gemini-2.5-flash | ⚠️ 需配置 |
+| researcher | gemini | gemini-2.5-flash | ⚠️ 需配置 |
+
+**推荐测试 Agent:** `General Assistant` (zhipu/glm-4-flash)