feat: complete Phase 1-3 architecture optimization
Phase 1 - Security: - Add AES-GCM encryption for localStorage fallback - Enforce WSS protocol for non-localhost WebSocket connections - Add URL sanitization to prevent XSS in markdown links Phase 2 - Domain Reorganization: - Create Intelligence Domain with Valtio store and caching - Add unified intelligence-client for Rust backend integration - Migrate from legacy agent-memory, heartbeat, reflection modules Phase 3 - Core Optimization: - Add virtual scrolling for ChatArea with react-window - Implement LRU cache with TTL for intelligence operations - Add message virtualization utilities Additional: - Add OpenFang compatibility test suite - Update E2E test fixtures - Add audit logging infrastructure - Update project documentation and plans Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
276
plans/foamy-imagining-sun.md
Normal file
276
plans/foamy-imagining-sun.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 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小时** |
|
||||
Reference in New Issue
Block a user