zclaw_openfang/docs/plans/quiet-twirling-kettle.md

ZCLAW 前端全面调试计划

调试目标

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

调试环境

前端服务

• URL: http://localhost:1420
• 框架: React + Vite + Tauri
• 代理: /api -> http://127.0.0.1:50051 (ZCLAW 后端)

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

步骤 0: 启动服务 (在测试前必须完成)

# 终端 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. 建议: 优化和改进建议