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 环境检查

```powershell
# 检查依赖
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（可选）

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

### 1.3 依赖安装

```powershell
cd desktop
pnpm install
pnpm playwright install chromium
```

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

---

## Phase 2: 基础验证

### 2.1 Gateway 连接测试

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

**自动验证**：
```powershell
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. 观察流式响应

**自动验证**：
```powershell
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 触发测试

**自动验证**：
```powershell
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 记忆持久化测试

**自动验证**：
```powershell
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. 验证状态持久

**自动验证**：
```powershell
pnpm playwright test --project=chromium --grep "INT-"
```

---

## Phase 5: 自动化验证

### 5.1 运行完整E2E测试

```powershell
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](desktop/src/lib/gateway-client.ts) | WebSocket/REST客户端（1155行） |
| [connectionStore.ts](desktop/src/store/connectionStore.ts) | 连接状态管理 |
| [chatStore.ts](desktop/src/store/chatStore.ts) | 聊天状态和流式响应 |
| [handStore.ts](desktop/src/store/handStore.ts) | Hands触发和审批 |
| [core-features.spec.ts](desktop/tests/e2e/specs/core-features.spec.ts) | 核心E2E测试 |
| [start-all.ps1](start-all.ps1) | 启动脚本 |
| [config.toml](config/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小时** |