# ZCLAW 发布前功能测试方案

> 日期: 2026-04-08
> 状态: Draft
> 基于: 两轮头脑风暴产品愿景 + 25 轮 tauri-mcp 测试结果
> 目标: 全功能可用验证 — 所有 UI 入口点接通真实后端，允许有 bug 但不能 crash

---

## Context

ZCLAW 经过 12 轮审计修复，1048 个自动化测试通过，25 轮 tauri-mcp 实景测试已完成核心路径验证（SSE、多轮对话、话题切换）。但在发布前仍有：

1. **未验证的能力**：Pipeline 实际执行、Hand 触发、Skill 安装/卸载、Agent 完整创建流程、模型切换
2. **遗留问题**：6 个 P2/P3（Token 计数为 0、Kimi ENTITY bug、配额 429、对话列表冗余等）
3. **产品愿景验证**：两轮头脑风暴确立了"成长性问题解决者"定位，需要用真实行业场景验证

本方案旨在通过多角色真实 LLM 交互测试，全面验证系统发布就绪度。

---

## 0. 范围澄清

### 0.1 与 04-05 预发布审计的关系

本方案**补充而非替代** `2026-04-05-pre-launch-functional-audit-design.md`。04-05 方案是模块级功能审计（12 模块 T1-T12），本方案是角色驱动的端到端集成测试。

| 04-05 模块 | 本方案覆盖 | 状态 |
|------------|-----------|------|
| T1 Hands | 角色 A (Researcher/Collector/Browser) | 本方案 |
| T2 Intelligence | 角色 B (记忆+反思) | 本方案 |
| T3 Chat/SSE | 角色 A+B+C | 本方案 |
| T4 Agent | 角色 B (创建/切换/人格) | 本方案 |
| T5 Skills | 角色 B (执行+结果) | 本方案 |
| T6 Pipeline | 角色 A (模板+执行) | 本方案 |
| T7 Browser Hand | 角色 A (导航+截图) | 本方案 |
| T8 Memory | 角色 B (VikingPanel) | 本方案 |
| T9 Admin V2 | 不在本方案范围 | 已有 61 测试覆盖 |
| T10 Security | 角色 B (Audit 日志) | 部分 |
| T11 SaaS API | 角色 B (配额+计费) | 部分 |
| T12 E2E 集成 | 三角色本身就是 E2E | 本方案 |

### 0.2 前序测试基线

开始本方案前，确认以下自动化测试基线通过：

```bash
# Rust 全量（排除 SaaS）
cargo test --workspace --exclude zclaw-saas  # 580 tests passing

# SaaS 集成（需 PostgreSQL）
cargo test -p zclaw-saas -- --test-threads=1  # 138 tests passing

# 前端
cd desktop && pnpm vitest run  # 330 passed, 1 skipped

# 类型检查
pnpm tsc --noEmit  # 0 errors
```

### 0.3 Phase 0：环境就绪检查

在 Phase 1 开始前，确认以下环境就绪：

| # | 检查项 | 验证方法 | 通过标准 |
|---|--------|----------|----------|
| 0.1 | Tauri 开发服务 | `pnpm start:dev` | 应用窗口正常打开，无白屏 |
| 0.2 | tauri-mcp 连接 | Chrome DevTools MCP 连接 | `take_snapshot` 返回页面结构 |
| 0.3 | SaaS 后端 | Admin 页面可访问 | Dashboard 正常加载 |
| 0.4 | LLM API 冒烟测试 | 三模型各发一条消息 | Kimi/GLM/DeepSeek 均有响应 |
| 0.5 | 自动化基线 | 运行 §0.2 命令 | 全部通过 |

---

## 1. 测试策略

### 1.1 方案选择：角色驱动 + 功能矩阵混合式

以三个不同行业角色为主线驱动测试，同时用功能矩阵确保 100% UI 入口点覆盖：

```
Phase 1: 基础连接+认证（无角色，通用验证）
Phase 2: 角色 A — 玩具厂老板 + Kimi
Phase 3: 角色 B — 医院行政 + GLM-4-Flash
Phase 4: 角色 C — 高中教师 + DeepSeek-V3
Phase 5: 功能矩阵交叉验证（checklist 补漏）
Phase 6: 修复验证 + 发布评估
```

### 1.2 测试方式

- **工具**: tauri-mcp / tauri-devtools 真实 LLM 交互
- **执行方式**: 边测边修（发现问题当场修复或记录后当轮修复）
- **预计总轮次**: 60-72 轮（Phase 0: ~5, Phase 1: ~10, Phase 2: 18-22, Phase 3: 18-22, Phase 4: 15-18, Phase 5-6: ~5）

### 1.3 配额预算

| 角色 | 预计 API 调用 | 含 Hands/Skills 开销 | 总计 |
|------|-------------|---------------------|------|
| Phase 0-1 | ~15 | 0 | 15 |
| 角色 A (Kimi) | ~22 | Researcher(3) + Collector(2) + Browser(2) + Pipeline(3) | 32 |
| 角色 B (GLM) | ~22 | Skills(2) + 记忆(1) | 25 |
| 角色 C (DeepSeek) | ~18 | Quiz(2) + Slideshow(1) + TTS(1) | 22 |
| Phase 5-6 | ~5 | 0 | 5 |
| **总计** | | | **~99** |

**配额策略**:
- 使用付费套餐（非 free plan 100 次限制），或 Admin 后台将测试账号配额提升至 200 次
- 准备 2 个测试账号，一个主用（配额 200+），一个备用
- 如果主账号配额耗尽，切换到备用账号继续测试
- 每个 Phase 结束后检查剩余配额，低于 20 次时切换账号

### 1.4 测试数据隔离

- 三个角色使用**同一个 SaaS 账号**但**不同的 Agent 分身**，状态共享
- 角色 B 的记忆测试可以观察到角色 A 的对话（验证跨 Agent 记忆隔离）
- 配额在三个角色间共享，按角色 A → B → C 的顺序消耗
- 每个 Phase 开始前记录当前对话数和配额余量

---

## 2. 测试角色与功能分工

### 2.1 三个测试角色

| 角色 | 身份 | LLM 模型 | 测试重点 | 预计轮次 |
|------|------|----------|----------|----------|
| **A. 玩具厂老板** | 汕头澄海，盲盒+注塑 | Kimi (kimi-for-coding) | 核心聊天、Hands（Researcher/Collector/Browser）、Pipeline 行业模板、配额管理 | 18-22 轮 |
| **B. 医院行政** | 某三甲医院行政主任 | GLM-4-Flash | Agent 多分身管理、Skills 调用、记忆系统、SaaS 配额/计费、模型切换 | 18-22 轮 |
| **C. 高中教师** | 高二语文/班主任 | DeepSeek-V3 | 多轮对话深度、Classroom/Quiz 生成、Slideshow、Speech TTS、对话搜索 | 15-18 轮 |

### 2.2 功能覆盖矩阵

**B** = 主测，**X** = 交叉验证

| 功能域 | 角色 A | 角色 B | 角色 C |
|--------|--------|--------|--------|
| SaaS 登录/认证 | **B** | X | X |
| SSE 流式响应 | **B** | X | X |
| 多轮对话 | **B** | X | **B** |
| 话题切换 | **B** | X | X |
| 取消流式 | X | X | **B** |
| Agent 创建/切换 | X | **B** | X |
| Agent 人格编辑 | X | **B** | X |
| 记忆提取/回顾 | X | **B** | X |
| Skills 执行 | X | **B** | X |
| Hands 触发 | **B** | X | X |
| Pipeline 执行 | **B** | X | X |
| Classroom/Quiz | X | X | **B** |
| Slideshow | X | X | **B** |
| Speech TTS | X | X | **B** |
| Browser Hand | **B** | X | X |
| 模型切换 | X | **B** | X |
| 对话搜索 | X | X | **B** |
| 配额/计费 | X | **B** | X |
| Thinking 渲染 | **B** | X | X |
| 离线队列 | X | **B** | X |
| 侧边栏 Tab 切换 | **B** | **B** | **B** |

---

## 3. 六阶段执行流程

### Phase 1：基础连接与认证（~10 轮）

**目标**: 确保所有连接模式可用，不被底层问题干扰后续角色测试

| # | 测试项 | 验证方法 | Pass 标准 |
|---|--------|----------|-----------|
| 1.1 | SaaS 登录 | 通过 tauri-mcp 发送消息 | 成功获取 session + 模型列表加载 |
| 1.2 | 会话恢复 | 重启 Tauri 应用后检查 | 自动恢复登录态，无需重新认证 |
| 1.3 | SSE 流式响应 | 发送简单问题 | thinking + content 双流正常渲染 |
| 1.4 | 取消流式 | 发送长问题后点击取消 | 状态正确恢复，可立即发新消息 |
| 1.5 | 侧边栏 Tab 切换 | 逐个点击 Chat/Agent/Memory/Automation/Skills | 每个 Tab 内容区正确更新，无白屏 |
| 1.6 | 对话列表 | 创建新对话 → 切换 → 搜索关键词 | CRUD 完整，搜索结果准确 |
| 1.7 | 模型列表加载 | 打开模型选择器 | 显示当前 SaaS 账户可用模型 |
| 1.8 | 遗留问题重现 | 逐个检查上次 6 个 P2/P3 | 确认已修复/仍存在/部分改善 |

**Pass 条件**: 1.1-1.5 全部通过才能进入 Phase 2。1.6-1.8 允许有问题但不阻塞。

---

### Phase 2：角色 A — 玩具厂老板 + Kimi（18-22 轮）

**场景**: 汕头澄海玩具厂老板，想开发盲盒产品线，需要市场调研、供应商联系、展会信息。

| # | 测试项 | 场景动作 | 验证点 |
|---|--------|----------|--------|
| A1 | 多轮行业对话 | "我想做盲盒，市面上哪些品牌卖得好？" → "这些材质有什么区别？" → "注塑成本怎么算？" | 上下文连续、行业知识准确、无信息丢失 |
| A2 | 话题切换 | 盲盒 → 供应商采购 → 展会 → 回到盲盒话题 | 回溯准确，不丢失之前的讨论细节 |
| A3 | Hands: Researcher | "帮我调研一下 2026 年盲盒市场趋势" | 工具调用成功，返回结构化研究报告 |
| A4 | Hands: Collector | "整理一份注塑机供应商对比表，包含价格和产能" | 输出结构化表格，格式正确 |
| A5 | Pipeline 执行 | 触发"市场调研"行业模板 | Pipeline 步骤逐步执行，状态跟踪正确，结果可查看 |
| A6 | Thinking 渲染 | 观察含 thinking 的回复 | 折叠/展开正常，thinking 内容完整，不影响 content |
| A7 | 长消息处理 | "详细列出从设计到量产的完整开模流程" | 完整输出，不被截断，段落格式正确 |
| A8 | 中英文混合 | "帮我写一封给 Hasbro 的英文合作邮件" → 后续用中文讨论 | 语言切换自然，上下文不混乱 |
| A9 | 数学计算 | "月产 5 万个盲盒，每个成本 3.5 元，利润率 40%，月利润多少？" | 计算正确（70,000 元） |
| A10 | 配额边界 | 持续使用观察配额消耗 | 接近上限时有友好提示，429 响应处理正确 |
| A11 | Browser Hand | "打开 1688 搜一下注塑机价格" | 若 Fantoccini 已安装：触发自动化 + Approval 弹窗；若未安装：标注 KNOWN，跳过测试 |
| A12 | Kimi ENTITY bug | 切换到 Flash 模式测试 | 检查 `__ENTITY_N__` 是否仍出现，评估影响 |
| A13 | 侧边栏导航 | 在 Chat ↔ Hands ↔ Pipeline 间频繁切换 | 内容区更新正确，无白屏或残留 |

**Pass 条件**: 核心项 A1-A5 全部通过。A6-A10 为扩展项，允许 <= 2 项失败。A11 Browser Hand 若 Fantoccini 未安装则标注为 KNOWN，不计入 Pass/Fail。

---

### Phase 3：角色 B — 医院行政 + GLM-4-Flash（18-22 轮）

**场景**: 某三甲医院行政主任，管理多个科室文档，需要 AI 助手处理不同科室事务并记住各科室特殊要求。

| # | 测试项 | 场景动作 | 验证点 |
|---|--------|----------|--------|
| B1 | Agent 创建 | 创建"内科助手"、"外科助手"两个分身 | Agent 表单完整，保存成功，出现在列表 |
| B2 | Agent 人格编辑 | 给内科助手设置专业人格 + 科室术语 | 人格 prompt 生效，后续对话体现专业术语 |
| B3 | Agent 切换 | 在两个分身间切换对话 | 上下文独立不串台，各自记住自己的话题 |
| B4 | 记忆积累 | 多次提及"我们医院 ICU 床位 30 张" | 后续对话 AI 记住并引用这个事实 |
| B5 | 记忆回顾 | 打开 VikingPanel 查看记忆列表 | 显示已积累的记忆条目，可搜索 |
| B6 | Skills 执行 | 触发文档处理 skill | Skill 正确执行并返回结果 |
| B7 | 模型切换 | 从 GLM 切到 DeepSeek → 再切回 GLM | 切换立即生效，对话不中断，模型特性可感知 |
| B8 | SaaS 配额查看 | 打开账户/计费面板 | 用量正确显示（验证 Token 计数修复） |
| B9 | 离线测试 | 断网 → 发消息 → 恢复网络 | 离线队列缓存消息，恢复后自动发送 |
| B10 | 搜索对话 | 搜索"ICU"关键词 | 正确过滤出包含 ICU 的对话 |
| B11 | Thinking 模式 | 开启/关闭 Thinking | 状态正确切换，渲染正常 |
| B12 | 反思系统 | 多轮对话后检查反思日志 | reflection 自动触发并记录，日志可查看 |
| B13 | 安全面板 | 打开 Audit 日志 | 显示操作记录，内容完整 |

**Pass 条件**: 核心项 B1-B7 全部通过。B8-B13 为扩展项，允许 <= 2 项失败。B9 离线测试允许有已知限制。

---

### Phase 4：角色 C — 高中教师 + DeepSeek-V3（15-18 轮）

**场景**: 高二语文老师兼班主任，需要生成测验、制作课件、用语音朗读课文。

| # | 测试项 | 场景动作 | 验证点 |
|---|--------|----------|--------|
| C1 | 深度多轮对话 | 讨论文言文教学方法 15+ 轮 | 上下文持续积累无丢失，后续引用前文准确 |
| C2 | Quiz 生成 | "生成一套《赤壁赋》理解测验，10 道选择题" | 题目生成完整，格式正确，答案合理 |
| C3 | Slideshow | "帮我做一页《赤壁赋》赏析幻灯片" | 幻灯片生成并预览，可翻页 |
| C4 | Speech TTS | "朗读《赤壁赋》第一段" | 语音合成播放正常，中文发音准确 |
| C5 | Quiz 评估 | 模拟学生答题，系统评分 | 评分逻辑正确，反馈有针对性 |
| C6 | 取消流式 | 在长文生成过程中取消 | 干净取消，UI 状态恢复，可立即继续操作 |
| C7 | 对话搜索 | 搜索"赤壁赋" | 正确匹配相关对话 |
| C8 | 新建对话 | 创建新对话讨论班会方案 | 独立上下文，不与之前的讨论混淆 |
| C9 | 跨话题记忆 | "上次我们讨论的教学方法叫什么？" | 记忆回溯准确，能引用之前对话内容 |
| C10 | 长文本输出 | "写一份完整的家长会发言稿，800 字" | 完整输出，格式正确，不被截断 |
| C11 | DeepSeek 稳定性 | 持续使用 15+ 轮 | 无超时、无 crash、无异常中断 |
| C12 | Classroom 相关 | Classroom 面板查看生成结果 | 生成历史可查看，可复用 |
| C13 | Whiteboard | "在白板上画一个文言文知识图谱" | 白板渲染正常，可导出（允许标注 demo） |
| C14 | 记忆飞轮验证 | 不提关键词，问"我们医院有多少张病床？" | 如果角色 B 的记忆跨 Agent 可见则验证飞轮；否则验证本角色记忆 |

**Pass 条件**: 核心项 C1-C6 全部通过。C7-C12 为扩展项，允许 <= 2 项失败。C4 TTS 允许有浏览器兼容性限制。

---

### Phase 5：功能矩阵交叉验证（checklist）

逐项检查每个 UI 入口点，确保至少被一个角色覆盖。对照 Phase 2-4 的结果，标记未覆盖项并补充测试。

| 类别 | UI 入口点 | 覆盖角色 | 状态 |
|------|-----------|----------|------|
| **侧边栏** | Chat Tab | Phase 1 | ☐ |
| **侧边栏** | Agent Tab | B | ☐ |
| **侧边栏** | Memory Tab | B | ☐ |
| **侧边栏** | Automation Tab | A | ☐ |
| **侧边栏** | Skills Tab | B | ☐ |
| **聊天区** | 发送消息 | A+B+C | ☐ |
| **聊天区** | 取消流式 | C | ☐ |
| **聊天区** | Thinking 展开/折叠 | A | ☐ |
| **聊天区** | 代码块渲染 | A (中英文) | ☐ |
| **聊天区** | 消息搜索 | C | ☐ |
| **聊天区** | 对话切换 | A+B | ☐ |
| **聊天区** | 新建对话 | C | ☐ |
| **Agent** | 创建 Agent | B | ☐ |
| **Agent** | 编辑人格 | B | ☐ |
| **Agent** | 切换 Agent | B | ☐ |
| **Agent** | 删除 Agent | B (必测 — 安全相关) | ☐ |
| **Hands** | 列表展示 | A | ☐ |
| **Hands** | 触发执行 | A (Researcher/Collector) | ☐ |
| **Hands** | Approval 弹窗 | A (Browser) | ☐ |
| **Hands** | 执行日志 | A | ☐ |
| **Skills** | 列表展示 | B | ☐ |
| **Skills** | 执行 Skill | B | ☐ |
| **Skills** | 结果展示 | B | ☐ |
| **Pipeline** | 模板列表 | A | ☐ |
| **Pipeline** | 执行 Pipeline | A | ☐ |
| **Pipeline** | 进度跟踪 | A | ☐ |
| **Pipeline** | 结果查看 | A | ☐ |
| **Memory** | VikingPanel | B | ☐ |
| **Memory** | 记忆列表 | B | ☐ |
| **Memory** | 记忆搜索 | B | ☐ |
| **Browser** | 创建会话 | A | ☐ |
| **Browser** | 导航+截图 | A | ☐ |
| **Classroom** | Quiz 生成 | C | ☐ |
| **Classroom** | Quiz 评估 | C | ☐ |
| **Slideshow** | 生成+预览 | C | ☐ |
| **Speech** | TTS 播放 | C | ☐ |
| **Settings** | 连接配置 | B | ☐ |
| **Settings** | 模型选择 | B | ☐ |
| **Settings** | Autonomy 级别 | B (必测 — 安全相关) | ☐ |
| **SaaS** | 登录/登出 | A+B | ☐ |
| **SaaS** | 账户信息 | B | ☐ |
| **SaaS** | 配额/计费 | B | ☐ |
| **自动化** | Triggers | A | ☐ |
| **自动化** | Scheduled Tasks | A (如时间允许) | ☐ |
| **安全** | Audit 日志 | B | ☐ |
| **安全** | Approval 队列 | A (Browser) | ☐ |

---

### Phase 6：修复验证 + 发布评估

**流程**:

1. 汇总 Phase 1-5 所有发现的问题
2. 按缺陷分级处理：
   - P0: 已在测试过程中立即修复
   - P1: Phase 6 集中修复
   - P2/P3: 记录到发布说明的 known issues
3. 修复后回归验证（只测修复点相关的功能）
4. 生成发布评估报告

---

## 4. 缺陷分级标准

| 级别 | 定义 | 处理方式 | 例子 |
|------|------|----------|------|
| **P0 - Crash** | 应用崩溃、白屏、数据丢失 | 立即停止测试，当场修复 | 窗口崩溃、IndexedDB 损坏 |
| **P1 - 阻塞** | 核心功能不可用，无法继续测试 | 当轮修复后重新验证 | SSE 无响应、登录失败、Agent 无法切换 |
| **P2 - 功能缺陷** | 功能可用但结果不正确或不完整 | 记录，Phase 6 统一修复 | Token 计数为 0、Pipeline 步骤状态不更新 |
| **P3 - 体验问题** | 功能可用但体验不佳 | 记录，发布后迭代 | 对话列表冗余、动画卡顿 |
| **KNOWN** | 已知的外部限制 | 标注为 known limitation | Kimi `__ENTITY_N__`、模型 API 超时 |

---

## 5. 发布标准（Go/No-Go）

| 指标 | Go（可发布） | No-Go（不可发布） |
|------|-------------|-------------------|
| P0 缺陷 | 0 | >= 1 |
| P1 缺陷 | <= 2 且有 workaround | >= 3 或无 workaround |
| 核心路径 | 聊天+Agent+认证 100% 通过 | 任一核心路径未覆盖 |
| 功能矩阵覆盖 | >= 90% UI 入口点已测 | < 80% |
| 稳定性 | 单次 50+ 消息无 crash | 50 消息内 crash |
| 多模型验证 | >= 2 个模型完整通过 | 仅 1 个模型通过 |
| React 稳定性 | 无 Maximum update depth 异常 | 出现无限渲染 |

---

## 6. 测试报告模板

每个角色测试完成后生成一份结构化报告：

```markdown
## 角色 X 测试报告

### 基本信息
- 角色: [身份描述]
- 模型: [LLM Provider + Model]
- 执行日期: YYYY-MM-DD
- 轮次: X/Y (实际/计划)
- ZCLAW 版本: [git commit hash 前 8 位]
- Tauri 版本: [从 package.json 获取]
- OS: [Windows 11 / macOS / Linux]
- WebView2 版本: [Edge WebView2 Runtime 版本]
- LLM 套餐: [free / paid]

### 结果汇总
- Pass: X 项
- Fail: Y 项 (P0: _ P1: _ P2: _ P3: _ KNOWN: _)

### 新发现缺陷
| ID | 级别 | 测试项 | 描述 | 复现步骤 | 状态 |
|----|------|--------|------|----------|------|

### 已修复缺陷
| ID | 原级别 | 描述 | 修复方式 | 验证结果 |
|----|--------|------|----------|----------|

### 已知限制
| 描述 | 影响范围 | 建议处理 |
|------|----------|----------|

### 功能覆盖
- 已测 UI 入口点: [列表]
- 未测 UI 入口点: [列表] + 原因
```

---

## 7. 关键文件参考

| 用途 | 文件路径 |
|------|----------|
| Tauri 命令注册 | `desktop/src-tauri/src/lib.rs` |
| 前端 Store | `desktop/src/store/` (19 文件) |
| Gateway Client | `desktop/src/lib/gateway-client.ts` |
| SaaS Client | `desktop/src/lib/saas-client.ts` |
| Kernel Client | `desktop/src/lib/kernel-client.ts` |
| WebMCP 工具 | `desktop/src/lib/webmcp-tools.ts` |
| Hands 配置 | `hands/` (9 HAND.toml) |
| 技能定义 | `skills/` (75 SKILL.md) |
| Pipeline 模板 | `crates/zclaw-pipeline/templates/` (17 YAML) |
| 组件目录 | `desktop/src/components/` (~53 组件) |
| 系统真实状态 | `docs/TRUTH.md` |

---

## 8. 风险与缓解

| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| 模型 API 不稳定 | 高 | 测试轮次浪费 | 准备备用模型，Kimi 挂了切 GLM |
| 配额提前耗尽 | 高 | 无法完成测试 | Admin 预充值、准备多个测试账号 |
| Kimi ENTITY bug | 中 | 角色A数据被污染 | 测到即标注，不影响其他角色 |
| 底层 P0 阻塞 | 低 | 全部测试暂停 | Phase 1 先验证基础，尽早暴露 |
| Browser Hand 失败 | 高 | 11 个 browser 命令不可测 | 若 Fantoccini 未安装则标注 KNOWN 并跳过，不阻塞发布；若已安装则只测试简单导航（打开URL+截图），不测试复杂表单填写 |