iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: reorganize documentation structure

Browse Source 
- Create docs/README.md as documentation index
- Add WORK_SUMMARY_2026-03-16.md for today's work
- Move test reports to docs/test-reports/
- Move completed plans to docs/archive/completed-plans/
- Move research reports to docs/archive/research-reports/
- Move technical reference to docs/knowledge-base/
- Move all plans from root plans/ to docs/plans/

New structure:
docs/
├── README.md                         # Documentation index
├── DEVELOPMENT.md                    # Development guide
├── OPENVIKING_INTEGRATION.md         # OpenViking integration
├── USER_MANUAL.md                    # User manual
├── ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md
├── archive/                          # Archived documents
├── knowledge-base/                   # Technical knowledge
├── plans/                            # Execution plans
└── test-reports/                     # Test reports

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
2026-03-16 08:21:01 +08:00
parent c8202d04e0
commit 0eb30c0531
29 changed files with 7196 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

610
docs/plans/quiet-twirling-kettle.md Normal file
View File

@@ -0,0 +1,610 @@
# 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. **建议**: 优化和改进建议