iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
36168d6978bae2bc2f3c94de0e970c0ca79cc1a2
zclaw_openfang/docs/plans/quiet-twirling-kettle.md
iven 0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details
refactor: 统一项目名称从OpenFang到ZCLAW 
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括：
- 配置文件中的项目名称
- 代码注释和文档引用
- 环境变量和路径
- 类型定义和接口名称
- 测试用例和模拟数据

同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
2026-03-27 07:36:03 +08:00

611 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ZCLAW 前端全面调试计划
## 调试目标
从用户角度全面验证 ZCLAW 桌面应用前端的功能完整性、可用性，确保所有交互流程正常工作，数据流正确，UI 响应符合预期。
## 调试环境
### 前端服务
- **URL**: http://localhost:1420
- **框架**: React + Vite + Tauri
- **代理**: `/api` -> `http://127.0.0.1:50051` (ZCLAW 后端)
### 启动步骤 (⚠️ 需要先启动服务)
**步骤 0: 启动服务** (在测试前必须完成)
```bash
# 终端 1: 启动后端服务
cd g:\ZClaw_zclaw
pnpm dev
# 等待后端服务就绪 (看到 "Server started" 或类似消息)
# 终端 2: 启动前端开发服务器 (新开一个终端)
cd g:\ZClaw_zclaw\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. **建议**: 优化和改进建议
Reference in New Issue View Git Blame Copy Permalink