# ZCLAW 前端全面调试计划

## 调试目标

从用户角度全面验证 ZCLAW 桌面应用前端的功能完整性、可用性，确保所有交互流程正常工作，数据流正确，UI 响应符合预期。

## 调试环境

### 前端服务
- **URL**: http://localhost:1420
- **框架**: React + Vite + Tauri
- **代理**: `/api` -> `http://127.0.0.1:50051` (OpenFang 后端)

### 启动步骤 (⚠️ 需要先启动服务)

**步骤 0: 启动服务** (在测试前必须完成)
```bash
# 终端 1: 启动后端服务
cd g:\ZClaw_openfang
pnpm dev
# 等待后端服务就绪 (看到 "Server started" 或类似消息)

# 终端 2: 启动前端开发服务器 (新开一个终端)
cd g:\ZClaw_openfang\desktop
pnpm dev
# 等待 Vite 服务就绪 (看到 "Local: http://localhost:1420")
```

**服务就绪标志**:
- 后端: 控制台显示服务启动成功，监听端口 50051 或 4200
- 前端: Vite 显示 `Local: http://localhost:1420/`

## 调试范围

### 模块概览
| 模块 | 文件位置 | 优先级 |
|------|----------|------|
| 聊天模块 | `desktop/src/components/chat/` | P0 |
| Agent/克隆管理 | `desktop/src/components/agents/`, `desktop/src/store/agentStore.ts` | P0 |
| Hands 系统 | `desktop/src/components/hands/`, `desktop/src/store/handStore.ts` | P1 |
| 工作流调度 | `desktop/src/components/workflows/`, `desktop/src/store/` | P1 |
| 团队协作 | `desktop/src/components/team/`, `desktop/src/store/teamStore.ts` | P1 |
| 内存系统 | `desktop/src/components/memory/`, `desktop/src/store/memoryStore.ts` | P1 |
| 设置管理 | `desktop/src/components/settings/` | P2 |
| 布局/导航 | `desktop/src/components/layout/` | P2 |

| 状态管理 | `desktop/src/store/` | P2 |

---

## 详细测试用例

### 1. 聊天模块 (ChatArea.tsx) [P0]

#### 1.1 消息发送
**步骤**:
1. 打开应用，导航到聊天页面
2. 在输入框中输入消息 "你好，请介绍一下你自己"
3. 点击发送按钮
4. 验证：
   - [ ] 消息显示在聊天区域
   - [ ] 发送后输入框被清空
   - [ ] 消息状态更新为"已发送"
   - [ ] 有响应返回（流式或完整)

   **网络请求验证**:
   - 检查是否发送 `POST /api/chat` 请求
   - 验证请求体格式: `{ message, agent_id?, session_id? }`

#### 1.2 流式响应
**步骤**:
1. 发送一条消息
2. 观察/验证流式响应:
   - [ ] 逐字/逐块显示文本
   - [ ] 有打字机效果
   - [ ] 滚动区域自动滚动到底部
   - [ ] 流式完成有正确标识

   **WebSocket 验证**:
   - 检查是否建立 WebSocket 连接
   - 验证消息格式符合预期

   - 检查是否有心跳/ping 机制

#### 1.3 Agent 切换
**步骤**:
1. 点击 Agent 选择下拉菜单
2. 选择不同的 Agent
3. 验证:
   - [ ] 下拉菜单正确显示
   - [ ] Agent 切换成功
   - [ ] 后续消息使用新 Agent
   - [ ] 状态正确更新
   **API 验证**:
   - 检查是否调用 `/api/agents` 获取列表
   - 验证切换时是否更新上下文

#### 1.4 模型选择
**步骤**:
1. 打开模型选择器
2. 选择不同的模型 (如 GPT-4, Claude)
3. 验证:
   - [ ] 选择器更新
   - [ ] 后续请求使用新模型
   - [ ] 设置持久化
   **API 验证**:
   - 检查是否调用 `/api/config` 或类似端点
   - 验证配置是否保存到后端

#### 1.5 会话管理
**步骤**:
1. 发送多条消息
2. 刷新页面
3. 验证:
   - [ ] 会话历史是否恢复
   - [ ] 可以继续对话
   - [ ] "新对话" 按钮可以开始新会话
   **持久化验证**:
   - 检查 localStorage 是否保存会话信息
   - 验证刷新后的恢复逻辑

#### 1.6 错误处理
**步骤**:
1. 断开后端连接
2. 尝试发送消息
3. 验证:
   - [ ] 显示错误消息
   - [ ] 有重试机制
   - [ ] 重连后恢复正常
   **错误边界**:
   - 验证网络超时处理
   - 验证服务器错误响应
   - 验证无效输入处理

#### 1.7 Markdown/代码渲染
**步骤**:
1. 发送包含 Markdown 格式的消息
   - 代码块: \`\`\`code\`\`\`
   - 粗体: **bold**
   - 列表: - item
2. 验证:
   - [ ] Markdown 正确渲染
   - [ ] 代码语法高亮
   - [ ] 列表格式正确
   **渲染库**:
   - 检查使用的渲染库 (react-markdown 或类似)
   - 验证 XSS 防护

---

### 2. Agent/克隆管理 (AgentMemoryPanel.tsx, CloneManager.tsx)

#### 2.1 Agent 列表
**步骤**:
1. 导航到 Agent 管理页面
2. 验证:
   - [ ] 显示 Agent 列表
   - [ ] 每个 Agent 显示名称、描述、状态
   - [ ] 可以搜索/过滤 Agent
   **API 验证**:
   - 检查是否调用 `/api/agents` 获取列表
   - 验证响应数据结构

#### 2.2 创建 Agent
**步骤**:
1. 点击"创建 Agent" 按钮
2. 填写表单 (名称、描述、模型等)
3. 提交表单
4. 验证:
   - [ ] 表单验证正确
   - [ ] 创建成功
   - [ ] 新 Agent 出现在列表中
   **API 验证**:
   - 检查是否发送 `POST /api/agents` 请求
   - 验证请求体格式

#### 2.3 编辑 Agent
**步骤**:
1. 选择一个 Agent
2. 点击编辑按钮
3. 修改信息
4. 保存
5. 验证:
   - [ ] 编辑表单正确预填充
   - [ ] 保存成功
   - [ ] 更新反映在列表中
   **API 验证**:
   - 检查是否发送 `PUT /api/agents/{id}` 请求

#### 2.4 删除 Agent
**步骤**:
1. 选择一个 Agent
2. 点击删除按钮
3. 确认删除
4. 验证:
   - [ ] 显示确认对话框
   - [ ] 删除成功
   - [ ] Agent 从列表中移除
   **API 验证**:
   - 检查是否发送 `DELETE /api/agents/{id}` 请求

#### 2.5 Agent 快速设置
**步骤**:
1. 打开 Agent 快速设置面板
2. 调整各种设置
3. 验证:
   - [ ] 设置项正确显示
   - [ ] 修改立即生效
   - [ ] 设置持久化
   **持久化验证**:
   - 检查设置是否保存到 localStorage
   - 验证重启后设置保持

---

### 3. Hands 系统 (HandsPanel.tsx)
#### 3.1 Hands 列表
**步骤**:
1. 导航到 Hands 面板
2. 验证:
   - [ ] 显示 7 个 Hand 卡片
   - [ ] 每个 Hand 显示名称、描述、状态
   - [ ] 可以查看 Hand 详情
   **Hands 列表验证**:
   - Clip: 视频处理
   - Lead: 销售线索发现
   - Collector: 数据收集
   - Predictor: 预测分析
   - Researcher: 深度研究
   - Twitter: Twitter 自动化
   - Browser: 浏览器自动化

#### 3.2 触发 Hand
**步骤**:
1. 选择一个 Hand
2. 点击"触发" 或 "执行" 按钮
3. 验证:
   - [ ] 显示执行参数表单 (如有)
   - [ ] 执行开始
   - [ ] 显示执行状态
   - [ ] 完成后显示结果
   **API 验证**:
   - 检查是否调用 `/api/hands/{name}/trigger` 请求
   - 验证执行结果

#### 3.3 Hand 审批流程
**步骤**:
1. 触发需要审批的 Hand
2. 验证:
   - [ ] 显示审批请求
   - [ ] 可以批准/拒绝
   - [ ] 审批状态正确更新
   **API 验证**:
   - 检查是否调用 `/api/hands/approvals` 获取列表
   - 验证审批操作

#### 3.4 Hand 执行历史
**步骤**:
1. 查看 Hand 执行历史
2. 验证:
   - [ ] 显示历史记录列表
   - [ ] 包含时间、状态、结果
   - [ ] 可以筛选/过滤
   **API 验证**:
   - 检查是否调用 `/api/hands/{name}/runs` 获取历史

---

### 4. 工作流调度 (WorkflowEditor.tsx)
#### 4.1 工作流列表
**步骤**:
1. 导航到工作流页面
2. 验证:
   - [ ] 显示工作流列表
   - [ ] 每个工作流显示名称、状态、进度
   - [ ] 可以搜索/过滤
   **API 验证**:
   - 检查是否调用 `/api/workflows` 获取列表

#### 4.2 创建工作流
**步骤**:
1. 点击"创建工作流" 按钮
2. 添加步骤/任务
3. 配置触发器
4. 保存
5. 验证:
   - [ ] 步骤可以拖拽排序
   - [ ] 可以添加条件分支
   - [ ] 触发器配置正确
   - [ ] 保存成功
   **API 验证**:
   - 检查是否发送 `POST /api/workflows` 请求
   - 验证工作流定义格式

#### 4.3 执行工作流
**步骤**:
1. 选择一个工作流
2. 点击"执行" 按钮
3. 验证:
   - [ ] 显示执行进度
   - [ ] 步骤状态正确更新
   - [ ] 完成后显示结果
   **WebSocket 验证**:
   - 检查是否收到工作流执行事件
   - 验证进度更新

#### 4.4 暂停/取消工作流
**步骤**:
1. 执行一个工作流
2. 中途点击"暂停" 或 "取消"
3. 验证:
   - [ ] 操作成功
   - [ ] 状态正确更新
   - [ ] 可以恢复执行
   **API 验证**:
   - 检查是否调用 `/api/workflows/{id}/pause` 或 `/api/workflows/{id}/cancel` 请求

---

### 5. 团队协作 (TeamCollaborationView.tsx)
#### 5.1 团队列表
**步骤**:
1. 导航到团队页面
2. 验证:
   - [ ] 显示团队列表
   - [ ] 每个团队显示成员数量、状态
   - [ ] 可以搜索团队
   **API 验证**:
   - 检查是否调用 `/api/teams` 获取列表

#### 5.2 创建团队
**步骤**:
1. 点击"创建团队" 按钮
2. 添加成员
3. 配置权限
4. 保存
5. 验证:
   - [ ] 可以添加多个 Agent
   - [ ] 权限配置正确
   - [ ] 保存成功
   **API 验证**:
   - 棹查是否发送 `POST /api/teams` 请求

#### 5.3 协调 Agent
**步骤**:
1. 选择一个团队
2. 点击"协调" 按钮
3. 分配任务
4. 验证:
   - [ ] 显示任务分配界面
   - [ ] 可以选择 Agent
   - [ ] 分配成功
   **API 验证**:
   - 检查是否调用协调相关 API

#### 5.4 查看协作状态
**步骤**:
1. 查看团队协作状态
2. 验证:
   - [ ] 显示各 Agent 状态
   - [ ] 显示任务进度
   - [ ] 可以发送消息
   **WebSocket 验证**:
   - 检查协作事件是否正确推送

---

### 6. 内存系统 (MemoryPanel.tsx, M/MemoryPanel.tsx)
#### 6.1 内存列表
**步骤**:
1. 导航到内存页面
2. 验证:
   - [ ] 显示记忆列表
   - [ ] 每条记忆显示类型、时间、重要性
   - [ ] 可以搜索记忆
   **API 验证**:
   - 检查是否调用 `/api/memory` 获取列表

#### 6.2 添加记忆
**步骤**:
1. 点击"添加记忆" 按钮
2. 输入记忆内容
3. 设置标签/分类
4. 保存
5. 验证:
   - [ ] 表单正确提交
   - [ ] 保存成功
   - [ ] 新记忆出现在列表中
   **API 验证**:
   - 检查是否发送 `POST /api/memory` 请求

#### 6.3 搜索记忆
**步骤**:
1. 在搜索框中输入关键词
2. 验证:
   - [ ] 搜索结果正确显示
   - [ ] 可以按相关性排序
   - [ ] 高亮匹配关键词
   **API 验证**:
   - 检查是否调用 `/api/memory/search` 请求

#### 6.4 记忆分类
**步骤**:
1. 查看记忆分类/标签
2. 验证:
   - [ ] 分类正确显示
   - [ ] 可以按分类筛选
   - [ ] 记忆数量统计正确
   **持久化验证**:
   - 检查分类数据结构

---

### 7. 设置管理 (GeneralSettings.tsx, ModelSettings.tsx)
#### 7.1 通用设置
**步骤**:
1. 打开设置页面
2. 验证:
   - [ ] 显示所有设置项
   - [ ] 当前值正确显示
   - [ ] 可以编辑并保存
   - [ ] 设置分组清晰
   **API 验证**:
   - 检查是否调用 `/api/config` 获取当前配置
   - 验证保存时发送 `PUT /api/config` 请求

#### 7.2 模型设置
**步骤**:
1. 导航到模型设置
2. 验证:
   - [ ] 显示可用模型列表
   - [ ] 可以选择默认模型
   - [ ] 可以配置模型参数
   - [ ] API Key 配置
   **API 验证**:
   - 检查是否调用 `/api/models` 获取列表
   - 验证 API Key 保存安全

#### 7.3 主题设置
**步骤**:
1. 切换主题 (亮色/暗色)
2. 验证:
   - [ ] 主题正确切换
   - [ ] 颜色/样式正确应用
   - [ ] 设置持久化
   **持久化验证**:
   - 检查 localStorage 是否保存主题设置

#### 7.4 语言设置
**步骤**:
1. 切换语言 (中文/英文)
2. 验证:
   - [ ] 界面语言正确切换
   - [ ] 日期/数字格式正确显示
   - [ ] 设置持久化
   **国际化验证**:
   - 检查 i18n 是否正确工作

---

### 8. 布局/导航 (Header.tsx, Sidebar.tsx)
#### 8.1 主导航
**步骤**:
1. 检查顶部导航栏
2. 验证:
   - [ ] 显示应用名称/Logo
   - [ ] 导航菜单正确
   - [ ] 当前页面高亮
   - [ ] 可以点击切换页面
   **路由验证**:
   - 检查路由配置是否正确

#### 8.2 侧边栏
**步骤**:
1. 点击侧边栏切换按钮
2. 验证:
   - [ ] 侧边栏正确展开/收起
   - [ ] 菜单项正确显示
   - [ ] 可以点击导航
   - [ ] 动画流畅
   **响应式验证**:
   - 检查在不同屏幕尺寸下的表现
   - 验证移动端适配

#### 8.3 响应式布局
**步骤**:
1. 调整浏览器窗口大小
2. 验证:
   - [ ] 布局正确适应
   - [ ] 没有元素溢出
   - [ ] 文字可读性良好
   - [ ] 侧边栏自动收起 (移动端)
   **CSS 验证**:
   - 检查媒体查询是否正确设置

---

### 9. 状态管理 (stores)
#### 9.1 Zustand Stores
**验证项目**:
1. 检查各个 store 的状态
2. 验证:
   - [ ] 初始状态正确
   - [ ] actions 可以正确触发
   - [ ] 状态更新正确
   - [ ] 选择器返回正确数据

#### 9.2 持久化
**步骤**:
1. 修改状态
2. 刷新页面
3. 验证:
   - [ ] 状态正确恢复
   - [ ] 没有数据丢失
   **存储验证**:
   - 检查 localStorage/sessionStorage 数据
   - 验证序列化/反序列化正确

---

### 10. 错误处理
#### 10.1 全局错误处理
**步骤**:
1. 触发各种错误场景
2. 验证:
   - [ ] 错误消息清晰
   - [ ] 有恢复机制
   - [ ] 可以重试操作
   - [ ] 错误日志正确记录

#### 10.2 网络错误
**步骤**:
1. 断开网络
2. 尝试操作
3. 验证:
   - [ ] 显示网络错误
   - [ ] 自动重连
   - [ ] 恢复后正常工作

#### 10.3 表单验证
**步骤**:
1. 输入无效数据
2. 验证:
   - [ ] 显示验证错误
   - [ ] 不能提交无效表单
   - [ ] 错误提示清晰

---

### 11. 性能测试
#### 11.1 消息列表虚拟滚动
**步骤**:
1. 发送大量消息
2. 滚动消息列表
3. 验证:
   - [ ] 滚动流畅
   - [ ] 没有卡顿
   - [ ] 内存稳定
   **虚拟列表验证**:
   - 检查是否使用 react-window 或类似库
   - 验证虚拟化实现

#### 11.2 大数据集渲染
**步骤**:
1. 加载大量 Agent/工作流
2. 验证:
   - [ ] 渲染流畅
   - [ ] 分页/虚拟滚动正常
   - [ ] 搜索/过滤响应快

---

### 12. 无障碍测试
#### 12.1 键盘导航
**步骤**:
1. 使用 Tab 键导航
2. 验证:
   - [ ] Tab 顺序正确
   - [ ] 焦点可见
   - [ ] 可以用 Enter 激活

#### 12.2 屏幕阅读器
**步骤**:
1. 使用屏幕阅读器
2. 验证:
   - [ ] 元素有正确的 aria 标签
   - [ ] 图片有 alt 文本
   - [ ] 表单有 label

---

## 测试工具配置
- **Chrome DevTools MCP**: 用于页面交互、快照、网络监控
- **控制台日志**: 监控错误和警告
- **网络面板**: 验证 API 请求/响应
- **性能面板**: 监控渲染性能

## 訡拟用户场景
1. **新用户首次使用**: 从空白状态开始，无历史数据
2. **日常使用**: 有历史会话和配置
3. **多任务场景**: 同时操作多个功能
4. **错误恢复**: 处理各种错误情况
5. **性能压力**: 大数据量操作

## 预期产出
1. **功能验证报告**: 每个功能的测试结果
2. **问题清单**: 发现的 bug 和改进建议
3. **性能报告**: 渲染和网络性能数据
4. **无障碍报告**: 无障碍测试结果
5. **建议**: 优化和改进建议