d0c6319fc1
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
style: 格式化代码文件并修复样式问题 docs: 新增部署文档和系统要求文档 test: 更新测试截图和覆盖率报告 refactor: 重构SchedulerPanel加载状态逻辑 ci: 添加lint和format脚本到package.json build: 更新依赖项并添加开发工具 chore: 添加验证报告和上线审查计划
359 lines
9.9 KiB
Markdown
359 lines
9.9 KiB
Markdown
# ZCLAW 端到端功能完整性和有效性验证计划
|
|
|
|
## 背景
|
|
|
|
ZCLAW 是面向中文用户的 AI Agent 桌面端，采用 Rust Workspace + Tauri + React 架构。本计划旨在对系统进行全面端到端验证，确保功能完整性和有效性。
|
|
|
|
## 系统架构概览
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 前端 (React + Zustand) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ ChatArea │ CloneManager │ AutomationPanel │ WorkflowBuilder │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Tauri IPC / WebSocket Gateway │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ zclaw-kernel (L4) │
|
|
├──────────────┬──────────────┬──────────────┬───────────────┤
|
|
│ zclaw-skills │ zclaw-hands │zclaw-protocol│zclaw-pipeline │
|
|
├──────────────┴──────────────┴──────────────┴───────────────┤
|
|
│ zclaw-runtime (L3) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ zclaw-memory (L2) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ zclaw-types (L1) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 验证范围
|
|
|
|
### 当前状态
|
|
- **Rust Crates**: 9 个，~214+ 单元测试
|
|
- **前端测试**: Vitest 覆盖率 60%，目标 80%
|
|
- **E2E 测试**: Playwright 框架就绪，核心用例已实现
|
|
- **技能系统**: 78+ SKILL.md 文件
|
|
- **Hands 系统**: 11 个自主能力
|
|
|
|
---
|
|
|
|
## 第一阶段：单元层验证
|
|
|
|
### 1.1 Rust Crates 单元测试
|
|
|
|
| Crate | 优先级 | 关键测试项 |
|
|
|-------|--------|-----------|
|
|
| zclaw-types | CRITICAL | ID 生成/序列化、Message 构建、Error 类型 |
|
|
| zclaw-memory | HIGH | Agent CRUD、Session 管理、KV Store |
|
|
| zclaw-runtime | CRITICAL | Tool Registry、Agent Loop、Stream Events |
|
|
| zclaw-kernel | CRITICAL | Kernel Boot、Agent Spawn、Event Bus |
|
|
|
|
**执行命令:**
|
|
```bash
|
|
cd g:/ZClaw_openfang
|
|
cargo test --workspace --all-features
|
|
```
|
|
|
|
### 1.2 TypeScript 单元测试
|
|
|
|
| Store | 关键测试项 |
|
|
|-------|-----------|
|
|
| chatStore | 消息添加/更新、对话管理、流式状态 |
|
|
| agentStore | Agent CRUD、使用统计 |
|
|
| handStore | Hand 列表、状态跟踪 |
|
|
| workflowStore | 工作流状态、执行 |
|
|
| connectionStore | 连接状态转换、重连 |
|
|
|
|
**执行命令:**
|
|
```bash
|
|
cd g:/ZClaw_openfang/desktop
|
|
pnpm vitest run --coverage
|
|
```
|
|
|
|
---
|
|
|
|
## 第二阶段：集成层验证
|
|
|
|
### 2.1 Kernel → Runtime → Memory 数据流
|
|
|
|
```text
|
|
测试路径:
|
|
1. agent_create → Kernel.spawn_agent() → MemoryStore.save_agent()
|
|
2. agent_chat → Kernel.send_message_stream() → AgentLoop.run_streaming()
|
|
3. skill_execute → Kernel.execute_skill() → SkillRegistry.execute()
|
|
4. hand_execute → Kernel.execute_hand() → HandRegistry.execute()
|
|
```
|
|
|
|
### 2.2 Tauri Commands 集成
|
|
|
|
关键命令验证清单:
|
|
- [ ] `kernel_init` → Kernel.boot()
|
|
- [ ] `agent_list` → Kernel.list_agents()
|
|
- [ ] `agent_create` → Kernel.spawn_agent()
|
|
- [ ] `agent_chat_stream` → Kernel.send_message_stream()
|
|
- [ ] `hand_list` → Kernel.list_hands()
|
|
- [ ] `skill_list` → Kernel.list_skills()
|
|
|
|
### 2.3 前端 Store → Client → 后端
|
|
|
|
```text
|
|
验证路径:
|
|
chatStore.sendMessage() → KernelClient.chatStream()
|
|
agentStore.loadClones() → KernelClient.listClones()
|
|
handStore.triggerHand() → KernelClient.executeHand()
|
|
```
|
|
|
|
---
|
|
|
|
## 第三阶段：端到端验证
|
|
|
|
### 3.1 关键用户流程
|
|
|
|
#### 流程 1: 完整聊天交互
|
|
```
|
|
用户输入 → chatStore → KernelClient → Kernel → AgentLoop → LLM
|
|
→ 流式响应 → chatStore 更新 → UI 渲染
|
|
```
|
|
|
|
**验证点:**
|
|
- [ ] 消息立即出现在 store
|
|
- [ ] 流式状态正确设置
|
|
- [ ] Delta 事件更新消息内容
|
|
- [ ] 工具调用创建工具消息
|
|
- [ ] 完成事件重置流式状态
|
|
|
|
#### 流程 2: Agent/分身管理
|
|
```
|
|
创建分身 → agentStore → Kernel.spawn_agent() → SQLite 持久化
|
|
```
|
|
|
|
**验证点:**
|
|
- [ ] Agent 出现在列表
|
|
- [ ] 配置持久化（重启后保留）
|
|
- [ ] 可选择用于聊天
|
|
|
|
#### 流程 3: Hand 执行
|
|
```
|
|
触发 Hand → handStore → Kernel.execute_hand() → Hand 执行 → 状态更新
|
|
```
|
|
|
|
**验证点:**
|
|
- [ ] Hand 列表正确加载
|
|
- [ ] 触发返回 run ID
|
|
- [ ] 状态转换 (idle → running → completed/error)
|
|
- [ ] 结果可获取
|
|
|
|
### 3.2 E2E 测试执行
|
|
|
|
**执行命令:**
|
|
```bash
|
|
cd g:/ZClaw_openfang/desktop
|
|
pnpm playwright test --project=chromium
|
|
```
|
|
|
|
**测试文件:**
|
|
- `tests/e2e/specs/core-features.spec.ts` - 核心功能
|
|
- `tests/e2e/specs/hands-*.spec.ts` - Hands 测试
|
|
- `tests/e2e/specs/workflow-*.spec.ts` - 工作流测试
|
|
|
|
---
|
|
|
|
## 第四阶段：功能完整性验证
|
|
|
|
### 4.1 技能系统 (78+ 技能)
|
|
|
|
**验证策略:**
|
|
1. 发现测试: 扫描 skills/ 目录，验证所有 SKILL.md 解析成功
|
|
2. 注册测试: 加载所有技能，验证 manifest 结构
|
|
3. 抽样执行测试: 执行 10-15 个代表性技能
|
|
|
|
**关键技能验证:**
|
|
- [ ] senior-developer (开发工程)
|
|
- [ ] web-search (外部 API)
|
|
- [ ] file-operations (文件系统)
|
|
- [ ] code-review (代码分析)
|
|
- [ ] data-analysis (数据处理)
|
|
|
|
### 4.2 Hands 系统 (11 Hands)
|
|
|
|
| Hand | 状态 | 验证方式 |
|
|
|------|------|---------|
|
|
| Browser | 可用 | 完整测试 |
|
|
| Collector | 可用 | 完整测试 |
|
|
| Researcher | 可用 | 完整测试 |
|
|
| Predictor | 可用 | 完整测试 |
|
|
| Whiteboard | 可用 | 完整测试 |
|
|
| Slideshow | 可用 | 完整测试 |
|
|
| Speech | 可用 | 完整测试 |
|
|
| Quiz | 可用 | 完整测试 |
|
|
| Clip | 需 FFmpeg | Mock 测试 |
|
|
| Twitter | 需 API Key | Mock 测试 |
|
|
| Lead | 规划中 | 跳过 |
|
|
|
|
### 4.3 多模型支持
|
|
|
|
验证 LLM 驱动:
|
|
- [ ] OpenAI (GPT-4, GPT-4o)
|
|
- [ ] Anthropic (Claude)
|
|
- [ ] Gemini (Pro, Flash)
|
|
- [ ] DashScope (Qwen)
|
|
- [ ] Local/Ollama
|
|
|
|
---
|
|
|
|
## 第五阶段：有效性验证
|
|
|
|
### 5.1 性能基准
|
|
|
|
| 指标 | 目标 |
|
|
|------|------|
|
|
| Kernel 启动 | < 2s |
|
|
| Agent 创建 | < 100ms |
|
|
| 首次响应 | < 5s |
|
|
| 流式首 token | < 100ms |
|
|
| SQLite 查询 | < 50ms |
|
|
|
|
### 5.2 错误恢复
|
|
|
|
- [ ] LLM API 限流 → 重试
|
|
- [ ] 网络断开 → 重连
|
|
- [ ] 工具执行失败 → 报告错误
|
|
- [ ] 数据库锁定 → 超时重试
|
|
|
|
### 5.3 并发处理
|
|
|
|
- [ ] 10 个并发聊天会话
|
|
- [ ] 100 个并发数据库写入
|
|
- [ ] 5 个并行 Hand 执行
|
|
|
|
---
|
|
|
|
## 执行计划
|
|
|
|
### Day 1: 基础验证
|
|
```bash
|
|
# 1. Rust 单元测试
|
|
cargo test --workspace
|
|
|
|
# 2. TypeScript 单元测试
|
|
cd desktop && pnpm vitest run --coverage
|
|
|
|
# 3. 检查覆盖率报告
|
|
```
|
|
|
|
### Day 2: 集成验证
|
|
```bash
|
|
# 1. 启动开发环境
|
|
pnpm start:dev
|
|
|
|
# 2. 手动验证核心流程
|
|
# - 聊天发送/接收
|
|
# - Agent 创建/切换
|
|
# - Hand 触发
|
|
|
|
# 3. 检查日志和错误
|
|
```
|
|
|
|
### Day 3-4: E2E 验证
|
|
```bash
|
|
# 1. 运行 Playwright 测试
|
|
cd desktop && pnpm playwright test
|
|
|
|
# 2. 验证技能加载
|
|
# 检查 skills/ 目录所有文件
|
|
|
|
# 3. 验证 Hands 功能
|
|
# 逐个触发并检查结果
|
|
```
|
|
|
|
### Day 5: 有效性验证
|
|
```bash
|
|
# 1. 性能测试
|
|
# 2. 并发测试
|
|
# 3. 错误恢复测试
|
|
# 4. 生成验证报告
|
|
```
|
|
|
|
---
|
|
|
|
## 验证成功标准
|
|
|
|
### 必须通过
|
|
- [ ] 所有 Rust 单元测试通过
|
|
- [ ] TypeScript 覆盖率 ≥ 60%
|
|
- [ ] E2E 核心流程测试通过
|
|
- [ ] 78+ 技能全部可加载
|
|
- [ ] 9 个核心 Hands 可执行
|
|
- [ ] 多模型切换正常工作
|
|
|
|
### 建议达到
|
|
- [ ] TypeScript 覆盖率 ≥ 80%
|
|
- [ ] 性能基准达标
|
|
- [ ] 无内存泄漏
|
|
- [ ] 并发处理正确
|
|
|
|
---
|
|
|
|
## 关键文件
|
|
|
|
| 文件 | 用途 |
|
|
|------|------|
|
|
| `crates/zclaw-kernel/src/kernel.rs` | 核心协调逻辑 |
|
|
| `crates/zclaw-runtime/src/loop_runner.rs` | Agent 循环执行 |
|
|
| `desktop/src/lib/kernel-client.ts` | Tauri IPC 层 |
|
|
| `desktop/src/store/chatStore.ts` | 聊天状态管理 |
|
|
| `desktop/tests/e2e/specs/core-features.spec.ts` | E2E 测试 |
|
|
|
|
---
|
|
|
|
## 风险与缓解
|
|
|
|
| 风险 | 影响 | 缓解措施 |
|
|
|------|------|---------|
|
|
| E2E mock 不完整 | 中 | 增强 mock-gateway fixtures |
|
|
| Clip/Twitter 需外部依赖 | 低 | 使用 mock 测试 |
|
|
| 配置验证不完整 | 中 | 添加 schema 验证 |
|
|
| 文档与实现不一致 | 低 | 同步更新文档 |
|
|
|
|
---
|
|
|
|
## 验证报告模板
|
|
|
|
```markdown
|
|
## ZCLAW 端到端验证报告
|
|
|
|
**日期**: YYYY-MM-DD
|
|
**版本**: x.x.x
|
|
|
|
### 1. 单元测试结果
|
|
- Rust: PASS/FAIL (xx/xx)
|
|
- TypeScript: PASS/FAIL (xx/xx, 覆盖率 xx%)
|
|
|
|
### 2. 集成测试结果
|
|
- Kernel 集成: PASS/FAIL
|
|
- Tauri Commands: PASS/FAIL
|
|
|
|
### 3. E2E 测试结果
|
|
- 核心流程: PASS/FAIL
|
|
- Hands: PASS/FAIL
|
|
- Skills: PASS/FAIL
|
|
|
|
### 4. 功能完整性
|
|
- 技能加载: xx/78+
|
|
- Hands 可用: xx/11
|
|
- 模型支持: xx/5
|
|
|
|
### 5. 有效性
|
|
- 性能基准: PASS/FAIL
|
|
- 错误恢复: PASS/FAIL
|
|
- 并发处理: PASS/FAIL
|
|
|
|
### 6. 发现的问题
|
|
1. [问题描述]
|
|
2. [问题描述]
|
|
|
|
### 7. 建议
|
|
1. [建议]
|
|
2. [建议]
|
|
```
|