zclaw_openfang/docs/testing/INTEGRATION-CHECKLIST.md

ZCLAW 真实集成测试清单

版本：1.0 更新日期：2026-03-20 状态：待验证

---

测试环境准备

前置条件

• ZCLAW Kernel 已安装并配置
• 至少一个中文模型 API Key 已配置（GLM/Qwen/Kimi/MiniMax）
• Tauri 桌面应用已构建
• 测试账号已准备

环境变量检查

# 检查 ZCLAW 配置
cat config/config.toml

# 检查中文模型配置
cat config/chinese-providers.toml

---

一、Gateway 连接测试

TEST-GW-01: ZCLAW Kernel 启动

项目	内容
前置条件	ZCLAW 已安装
测试步骤	1. 启动 Tauri 应用 2. 检查连接状态指示器 3. 确认显示"已连接"
预期结果	连接状态为 connected，无错误提示
验证方法	检查 ConnectionStatus 组件状态
当前状态	⏳ 待验证

TEST-GW-02: WebSocket 握手

项目	内容
前置条件	TEST-GW-01 通过
测试步骤	1. 打开浏览器开发者工具 2. 检查 Network 标签 3. 确认 WebSocket 连接建立
预期结果	WebSocket 状态为 101 Switching Protocols
验证方法	DevTools Network 面板
当前状态	⏳ 待验证

TEST-GW-03: 心跳保活

项目	内容
前置条件	TEST-GW-02 通过
测试步骤	1. 保持应用空闲 5 分钟 2. 检查连接状态 3. 发送一条测试消息
预期结果	连接保持活跃，消息正常发送
验证方法	检查 ping/pong 日志
当前状态	⏳ 待验证

TEST-GW-04: 断线重连

项目	内容
前置条件	TEST-GW-02 通过
测试步骤	1. 手动停止 ZCLAW 进程 2. 等待 10 秒 3. 重启 ZCLAW 4. 观察应用行为
预期结果	应用自动重连，状态正确更新
验证方法	检查重连日志和 UI 状态变化
当前状态	⏳ 待验证

---

二、真实模型对话测试

TEST-MODEL-01: 流式响应

项目	内容
前置条件	API Key 已配置，连接正常
测试步骤	1. 选择一个模型 2. 发送"请写一首关于春天的短诗" 3. 观察响应过程
预期结果	文字逐字/逐句显示，有流式效果
验证方法	观察 ChatArea 组件的渲染
当前状态	⏳ 待验证

TEST-MODEL-02: 模型切换

项目	内容
前置条件	配置了多个模型
测试步骤	1. 用模型 A 发送消息 2. 切换到模型 B 3. 再次发送消息
预期结果	两次响应来自不同模型
验证方法	检查消息元数据中的 model 字段
当前状态	⏳ 待验证

TEST-MODEL-03: 上下文管理

项目	内容
前置条件	TEST-MODEL-01 通过
测试步骤	1. 发送"我叫张三" 2. 等待响应 3. 发送"我叫什么名字？"
预期结果	模型正确回答"张三"
验证方法	检查对话历史和响应内容
当前状态	⏳ 待验证

TEST-MODEL-04: 长对话处理

项目	内容
前置条件	TEST-MODEL-03 通过
测试步骤	1. 连续发送 20+ 条消息 2. 观察响应时间 3. 检查最早消息是否被正确压缩
预期结果	对话流畅，无内存溢出
验证方法	检查 context-compactor 日志
当前状态	⏳ 待验证

TEST-MODEL-05: 错误处理

项目	内容
前置条件	API Key 配置正确
测试步骤	1. 临时使用无效 API Key 2. 发送消息 3. 观察错误处理
预期结果	显示友好错误提示，不崩溃
验证方法	检查错误 toast 和日志
当前状态	⏳ 待验证

---

三、飞书 Channel 测试

TEST-FEISHU-01: OAuth 授权

项目	内容
前置条件	飞书应用已创建
测试步骤	1. 进入设置 → IM Channels 2. 点击"连接飞书" 3. 完成授权流程
预期结果	授权成功，显示已连接状态
验证方法	检查 configStore 中的 token
当前状态	⏳ 待验证

TEST-FEISHU-02: 消息接收

项目	内容
前置条件	TEST-FEISHU-01 通过
测试步骤	1. 在飞书中 @机器人 2. 发送测试消息 3. 观察 ZCLAW 应用
预期结果	消息出现在对应 Channel
验证方法	检查 ChannelList 和消息列表
当前状态	⏳ 待验证

TEST-FEISHU-03: Agent 处理与回复

项目	内容
前置条件	TEST-FEISHU-02 通过
测试步骤	1. 在飞书发送问题 2. 等待 Agent 响应 3. 检查飞书收到的回复
预期结果	飞书收到 Agent 的回复
验证方法	飞书客户端验证
当前状态	⏳ 待验证

---

四、Hands 触发测试

TEST-HAND-01: 意图识别

项目	内容
前置条件	Hands 已启用
测试步骤	1. 发送"帮我打开百度搜索一下天气" 2. 观察是否触发 Browser Hand
预期结果	系统识别意图并建议触发 Browser Hand
验证方法	检查 HandApprovalModal 是否弹出
当前状态	⏳ 待验证

TEST-HAND-02: 参数收集

项目	内容
前置条件	TEST-HAND-01 通过
测试步骤	1. 触发一个需要参数的 Hand 2. 检查参数收集界面
预期结果	显示参数表单，可编辑参数
验证方法	检查参数输入 UI
当前状态	⏳ 待验证

TEST-HAND-03: 审批流程

项目	内容
前置条件	TEST-HAND-02 通过
测试步骤	1. 点击"批准" 2. 观察执行状态
预期结果	状态变为"执行中"，然后"完成"
验证方法	检查 handStore 中的 run 状态
当前状态	⏳ 待验证

TEST-HAND-04: 执行结果

项目	内容
前置条件	TEST-HAND-03 通过
测试步骤	1. 等待执行完成 2. 检查执行日志 3. 查看结果输出
预期结果	显示完整的执行日志和结果
验证方法	检查 AutomationPanel 日志
当前状态	⏳ 待验证

TEST-HAND-05: 取消执行

项目	内容
前置条件	有正在执行的 Hand
测试步骤	1. 触发一个长时间运行的 Hand 2. 点击"取消"
预期结果	执行被中止，状态变为"已取消"
验证方法	检查状态变化
当前状态	⏳ 待验证

---

五、记忆持久化测试

TEST-MEM-01: 重启后记忆保留

项目	内容
前置条件	有对话历史
测试步骤	1. 进行一些对话 2. 关闭应用 3. 重新启动 4. 检查对话历史
预期结果	对话历史完整保留
验证方法	检查 chatStore 中的 messages
当前状态	⏳ 待验证

TEST-MEM-02: 跨会话记忆命中

项目	内容
前置条件	TEST-MEM-01 通过
测试步骤	1. 在之前的对话中提及"我喜欢蓝色" 2. 重启应用 3. 问"我喜欢什么颜色？"
预期结果	Agent 引用之前的记忆回答
验证方法	检查响应内容和记忆检索日志
当前状态	⏳ 待验证

TEST-MEM-03: 向量记忆搜索（OpenViking）

项目	内容
前置条件	OpenViking 已配置
测试步骤	1. 添加一些文档到知识库 2. 问相关问题时
预期结果	系统检索到相关内容并引用
验证方法	检查 Viking 检索日志
当前状态	⏳ 待验证

---

六、端到端综合测试

TEST-E2E-01: 完整工作流

项目	内容
前置条件	所有前置测试通过
测试步骤	1. 启动应用并连接 2. 进行多轮对话 3. 触发一个 Hand 4. 检查记忆是否保存
预期结果	所有功能正常协作
验证方法	全流程验证
当前状态	⏳ 待验证

TEST-E2E-02: 多 Agent 协作

项目	内容
前置条件	TeamOrchestrator 可用
测试步骤	1. 创建团队 2. 添加多个 Agent 3. 分配任务 4. 观察协作过程
预期结果	Agents 协作完成任务
验证方法	检查 teamStore 和协作日志
当前状态	⏳ 待验证

---

测试结果汇总

最后更新: 2026-03-21

单元测试状态 (Vitest)

测试文件	测试数	状态
workflowStore.test.ts	32	✅ 通过
teamStore.test.ts	20	✅ 通过
zclaw-api.test.ts	30	✅ 通过
swarm-skills.test.ts	15	✅ 通过
heartbeat-reflection.test.ts	25	✅ 通过
总计	312	✅ 全部通过

E2E 测试状态 (Playwright)

状态	说明
⚠️ 需修复	测试代码存在语法错误（重复声明、字符串未闭合）

集成测试清单

类别	总数	通过	失败	待验证
Gateway 连接	4	0	0	4
模型对话	5	0	0	5
飞书 Channel	3	0	0	3
Hands 触发	5	0	0	5
记忆持久化	3	0	0	3
端到端	2	0	0	2
总计	22	0	0	22

环境验证 (2026-03-21)

项目	状态	说明
pnpm	✅	v10.30.2
ZCLAW Runtime	✅	v0.4.0 (57MB)
Playwright	✅	v1.58.2
配置文件	✅	config.toml, chinese-providers.toml

---

测试脚本模板

#!/bin/bash
# integration-test.sh - ZCLAW 集成测试脚本

set -e

echo "=== ZCLAW Integration Test Suite ==="
echo "Started at: $(date)"

# 1. 检查环境
echo "[1/5] Checking environment..."
command -v zclaw >/dev/null 2>&1 || { echo "ERROR: zclaw not found"; exit 1; }
command -v pnpm >/dev/null 2>&1 || { echo "ERROR: pnpm not found"; exit 1; }

# 2. 检查配置
echo "[2/5] Checking configuration..."
test -f config/config.toml || { echo "ERROR: config.toml not found"; exit 1; }
test -f config/chinese-providers.toml || { echo "ERROR: chinese-providers.toml not found"; exit 1; }

# 3. 启动 ZCLAW
echo "[3/5] Starting ZCLAW..."
zclaw start || { echo "ERROR: Failed to start ZCLAW"; exit 1; }
sleep 5

# 4. 运行 E2E 测试
echo "[4/5] Running E2E tests..."
cd desktop
pnpm test:e2e || { echo "WARNING: Some E2E tests failed"; }

# 5. 清理
echo "[5/5] Cleanup..."
zclaw stop

echo "=== Test completed at: $(date) ==="

---

附录：测试账号和凭证管理

重要： 所有测试凭证应存储在安全的位置，不要提交到代码库。

凭证类型	存储位置	负责人
飞书 App ID/Secret	1Password	开发团队
模型 API Keys	config/chinese-providers.toml (加密)	开发团队
测试账号	1Password	QA 团队