# 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. [建议]
```