zclaw_openfang/plans/foamy-imagining-sun.md

ZCLAW 端到端可用性验证计划

背景

ZCLAW 项目架构设计出色（68个Skills、7个Hands、智能层lib），但端到端可用性未经验证。317个单元测试通过不代表产品可用，需要真实跑通核心闭环。

目标：验证从用户启动应用 → 连接后端 → 对话 → 触发自动化 → 记忆持久化的完整流程。

---

验证阶段概览

阶段	内容	预计时间
1. 前置准备	环境检查、配置验证	15分钟
2. 基础验证	Gateway连接、基础对话	25分钟
3. 功能验证	Hands触发、记忆持久化	30分钟
4. 集成验证	飞书集成、端到端工作流	25分钟
5. 自动化验证	E2E测试套件	60分钟

---

Phase 1: 前置准备

1.1 环境检查

# 检查依赖
pnpm --version          # >= 8.x
pnpm tauri --version    # 2.x

# 检查 OpenFang Runtime
dir desktop\src-tauri\resources\openfang-runtime\

# 检查 Playwright
cd desktop && pnpm playwright --version

1.2 配置验证

检查文件：

• config/config.toml - 端口4200、CORS配置
• config/chinese-providers.toml - API Keys（可选）

# 验证配置
type config\config.toml | findstr /C:"port" /C:"cors_origins"

1.3 依赖安装

cd desktop
pnpm install
pnpm playwright install chromium

成功标准：所有依赖安装完成，无错误

---

Phase 2: 基础验证

2.1 Gateway 连接测试

手动步骤：

1. 启动应用：.\start-all.ps1 -Dev
2. 等待 Tauri 窗口打开
3. 观察连接状态指示器（绿色=已连接）

自动验证：

cd desktop
pnpm playwright test --project=chromium --grep "GW-CONN"

验证点：

测试ID	描述	成功标准
GW-CONN-01	健康检查	{ status: 'ok' }
GW-CONN-02	连接状态	Store显示connected
GW-CONN-03	模型列表	返回模型数组
GW-CONN-04	Agent列表	返回Agent数组

连接参数（gateway-client.ts）：

• 心跳间隔：30秒
• 最大丢失心跳：3次
• 重连尝试：最多10次（指数退避）

2.2 基础对话测试

手动步骤：

1. 在输入框输入消息
2. 点击发送按钮
3. 观察流式响应

自动验证：

pnpm playwright test --project=chromium --grep "CHAT-MSG"

验证点：

测试ID	描述	成功标准
CHAT-MSG-01	发送接收消息	用户+AI消息可见
CHAT-MSG-02	Store状态更新	消息计数增加
CHAT-MSG-03	流式响应指示	isStreaming正确切换

成功标准：消息2秒内显示，流式指示器正常，无错误

---

Phase 3: 功能验证

3.1 Hands 触发测试

自动验证：

pnpm playwright test --project=chromium --grep "HAND-TRIG"

验证点：

测试ID	描述	成功标准
HAND-TRIG-01	Hands列表加载	返回Hands数组
HAND-TRIG-02	激活Hand	返回runId
HAND-TRIG-03	审批流程	审批/拒绝正常
HAND-TRIG-04	取消执行	状态变为cancelled

可用的Hands：

• Browser（浏览器自动化）
• Collector（数据收集）
• Researcher（深度研究）
• Predictor（预测分析）

3.2 记忆持久化测试

自动验证：

pnpm playwright test --project=chromium --grep "MEM-"

验证点：

测试ID	描述	成功标准
MEM-PERSIST-01	localStorage保存	数据持久化
MEM-PERSIST-02	页面重载恢复	数据恢复
MEM-PERSIST-03	会话切换	切换正常
MEM-PERSIST-04	删除会话	正确移除

---

Phase 4: 集成验证

4.1 飞书集成（可选）

前置条件：飞书应用已配置，[channels.feishu].enabled = true

验证点：

• OAuth授权流程
• 消息接收
• Agent回复

4.2 端到端工作流

测试场景：

1. 启动应用 → 2. 验证连接 → 3. 发送消息 → 4. 导航到Hands → 5. 触发Hand → 6. 验证执行 → 7. 返回聊天 → 8. 验证状态持久

自动验证：

pnpm playwright test --project=chromium --grep "INT-"

---

Phase 5: 自动化验证

5.1 运行完整E2E测试

cd desktop

# 运行所有测试
pnpm playwright test

# 生成HTML报告
pnpm playwright test --reporter=html
pnpm playwright show-report test-results/html-report

测试文件：

文件	测试数	重点
core-features.spec.ts	20+	Gateway、聊天、Hands
data-flow.spec.ts	25+	数据流验证
store-state.spec.ts	30+	Store状态
edge-cases.spec.ts	25+	边界情况
memory.spec.ts	25+	记忆持久化

成功标准：所有测试通过，无flaky测试

---

关键文件

文件	用途
gateway-client.ts	WebSocket/REST客户端（1155行）
connectionStore.ts	连接状态管理
chatStore.ts	聊天状态和流式响应
handStore.ts	Hands触发和审批
core-features.spec.ts	核心E2E测试
start-all.ps1	启动脚本
config.toml	主配置文件

---

故障排除

问题	可能原因	解决方案
连接超时	OpenFang未运行	运行 .\start-all.ps1 -Dev
健康检查失败	端口4200被占用	检查防火墙，终止占用进程
聊天不工作	无可用Agent	检查 /api/agents 端点
Hand不触发	依赖未满足	检查 requirements_met 字段
记忆不持久	localStorage禁用	检查浏览器设置

---

验证清单总结

Phase 1: 前置准备

• Node.js/pnpm 已安装
• Rust/Tauri CLI 已安装
• OpenFang runtime 存在
• Playwright 浏览器已安装
• 配置文件已验证

Phase 2: 基础验证

• 健康检查返回 ok
• 连接状态正确转换
• 模型列表加载
• Agent列表加载
• 聊天消息发送接收
• 流式响应工作

Phase 3: 功能验证

• Hands列表显示
• Hand激活工作
• 审批流程工作
• 取消执行工作
• 记忆跨重载持久
• 会话切换工作

Phase 4: 集成验证

• （可选）飞书集成工作
• 完整工作流完成
• 状态跨导航持久

Phase 5: 自动化验证

• 所有Playwright测试通过
• HTML报告生成
• 无flaky测试

---

预计总时间

阶段	时长
Phase 1	15分钟
Phase 2	25分钟
Phase 3	30分钟
Phase 4	25分钟
Phase 5	60分钟
总计	2.5-3小时