zclaw_openfang/plans/sequential-napping-dolphin.md

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

执行命令:

cd g:/ZClaw_openfang
cargo test --workspace --all-features

1.2 TypeScript 单元测试

Store	关键测试项
chatStore	消息添加/更新、对话管理、流式状态
agentStore	Agent CRUD、使用统计
handStore	Hand 列表、状态跟踪
workflowStore	工作流状态、执行
connectionStore	连接状态转换、重连

执行命令:

cd g:/ZClaw_openfang/desktop
pnpm vitest run --coverage

---

第二阶段：集成层验证

2.1 Kernel → Runtime → Memory 数据流

测试路径:
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 → 后端

验证路径:
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 测试执行

执行命令:

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: 基础验证

# 1. Rust 单元测试
cargo test --workspace

# 2. TypeScript 单元测试
cd desktop && pnpm vitest run --coverage

# 3. 检查覆盖率报告

Day 2: 集成验证

# 1. 启动开发环境
pnpm start:dev

# 2. 手动验证核心流程
# - 聊天发送/接收
# - Agent 创建/切换
# - Hand 触发

# 3. 检查日志和错误

Day 3-4: E2E 验证

# 1. 运行 Playwright 测试
cd desktop && pnpm playwright test

# 2. 验证技能加载
# 检查 skills/ 目录所有文件

# 3. 验证 Hands 功能
# 逐个触发并检查结果

Day 5: 有效性验证

# 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 验证
文档与实现不一致	低	同步更新文档

---

验证报告模板

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