zclaw_openfang/docs/superpowers/specs/2026-04-09-exploratory-test-suite-design.md

# ZCLAW 预发布探索性测试套件设计

> **日期**: 2026-04-09
> **目标**: 三端全链路探索式真实场景测试，体验流畅无阻断
> **范围**: 桌面端 + SaaS + Admin V2
> **画像**: 医院行政 / 教学教师 / 技术用户 / 零基础小白

## 设计理念

结构化的探索性测试套件，以四个角色驱动的用户故事线（Part 1）为核心，辅以功能模块矩阵（Part 2）全面覆盖，加上执行框架（Part 3）确保严格性。

---

## Part 1: 用户故事线（4 条）

### 故事线 1: 医院行政"小李" — 管家模式日常行政

**画像**: 28岁医院行政，医务科，处理会议纪要/数据报告/政策合规。无技术背景。

---

#### 场景 1.1: 首次启动 — 冷启动问候

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 启动 ZCLAW | 简洁 UI 模式（SimpleTopBar + SimpleSidebar） |
| 2 | 观察初始屏幕 | FirstConversationPrompt 欢迎屏 + 5个快速操作 chip |
| 3 | 验证问候消息 | 显示 agent 名称 + emoji + 领域介绍 |
| 4 | 检查冷启动状态 | localStorage('zclaw-cold-start-state') = "idle" |

**三级验证**:
- Desktop: SimpleSidebar 显示对话 tab + 搜索框
- SaaS: 无网络调用（纯本地状态）
- Admin: N/A

**体验检查**: 首次渲染 < 2s, 无闪烁/布局偏移

**边界探测**: 关闭重开 → 冷启动状态是否持久？切换专业模式 → 问候语行为？

---

#### 场景 1.2: 首次对话 — 科室识别

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 输入"我是医务科的，主要负责医疗质量管理和会诊安排" | 消息作为用户气泡出现，流式指示器开始 |
| 2 | 等待响应 | AI 流式响应，确认科室和职责。ButlerRouter 分类为 healthcare 域 |
| 3 | 验证流式完整性 | 响应完成，无残留"发送中..." |
| 4 | 检查侧边栏 | 对话出现在 SimpleSidebar 列表中 |
| 5 | 检查记忆提取 | (等30s防抖) memory-extractor 触发存储科室信息 |

**三级验证**:
- Desktop: streamStore.isStreaming true→false, messageStore 2条消息
- SaaS: relay 收到请求, Token pool 选择 key, PostgreSQL 记录遥测
- Admin: 使用量页面显示新 token 消耗

**体验检查**: 首 token < 3s(GLM-4-Flash), 无空助手消息, 无 UI 冻结

**边界探测**: 流式中途发第二条消息, 断网, 500+字符超长输入

---

#### 场景 1.3: 生成会议纪要（Pipeline）

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 输入"帮我整理今天的会议纪要：[3段会议记录]" | ButlerRouter 分类为 meeting 域 |
| 2 | 等待 AI 响应 | 生成结构化纪要（出席/讨论/决议/行动项） |
| 3 | 切换到专业模式 | UI 平滑切换，完整 TopBar + Sidebar + RightPanel |
| 4 | 导航到 Pipelines 面板 | `pipelines/healthcare/meeting-minutes.yaml` 模板可见 |
| 5 | 触发管道 | 输入会议内容，执行 DAG: 提取→结构化→格式化 |

**体验检查**: 模式切换动画流畅(AnimatePresence), Pipeline 步骤实时可见

---

#### 场景 1.4: 数据报告生成（Collector Hand）

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 输入"帮我收集这个月各科室的门诊量和住院数据" | ButlerRouter 分类为 data_report 域 |
| 2 | 观察 Hand 触发 | Collector Hand 触发, 批准提示出现 |
| 3 | 批准执行 | Hand 运行，"收集中..."状态 |
| 4 | 等待完成 | 结果在聊天中显示为结构化格式 |

**体验检查**: 批准模态框清晰, Hand 执行有加载指示器, 失败有描述性错误

---

#### 场景 1.5: 政策合规检查

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 输入"请帮我检查这份新的住院患者转科管理制度是否符合最新规定：[政策文本]" | ButlerRouter 分类为 policy 域 |
| 2 | 等待 AI 分析 | 逐点合规分析 + 法规引用 |
| 3 | 请求格式化报告 | 生成正式合规审查报告 |
| 4 | "把报告要点做成PPT" | Slideshow Hand 触发 |

**体验检查**: PPT 输出正确渲染

**后端验证**: DataMasking 中间件应剥离患者敏感数据 — 通过 Rust 日志(log::info!)确认 LLM 提示中身份证号被替换为 [REDACTED]，或查看 SQLite trajectory_store 中记录的实际 prompt

---

#### 场景 1.6: 痛点持久化与记忆召回

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 关闭并重启 ZCLAW | 之前对话在侧边栏列出 |
| 2 | 输入"上周的会议纪要能帮我调出来吗？" | FTS5 搜索记忆，回忆上下文 |
| 3 | 验证记忆注入 | AI 引用过去科室信息无需重新询问 |
| 4 | 检查 ButlerPanel (专业模式) | 洞察/记忆部分有内容 |
| 5 | 检查 PainStorage 持久性 | SQLite pain_storage 表有条目 |

---

#### 场景 1.7: 预约 — NL Schedule Parser

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 输入"帮我提醒明天下午3点准备质量月报" | NlScheduleParser 转换为 cron |
| 2 | 验证识别 | 系统确认时间和任务 |
| 3 | 检查定时任务 | Settings → 定时任务 tab 可见 |

**边界探测**: "下周 sometime"(模糊), "昨天下午3点"(过去时间), "每周一三五早上9点"(复杂)

---

#### 场景 1.8: 离线韧性

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 发消息时断网 | OfflineIndicator 出现，消息入 offlineStore 队列 |
| 2 | 重连 | health-check 检测到连接，队列消息刷新 |
| 3 | 验证无消息丢失 | 所有消息在历史中完整 |

**边界探测**: 队列5+条消息后重连, 重连期间 SaaS unreachable → 降级到本地 Kernel

---

### 故事线 2: 教师"王老师" — 教学内容创作

**画像**: 35岁小学教师，三年级班主任。创建测验/幻灯片/语音内容。

---

#### 场景 2.1: 首次启动 — 教育欢迎

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 使用教育模板 Agent 启动 | 冷启动问候面向教师 |
| 2 | 回复"我是三年级2班的班主任，班里38个学生" | AI 记住班级信息 |
| 3 | 验证 Agent 身份 | 名称/角色匹配教育模板 |

---

#### 场景 2.2: 测验生成（Quiz Hand）

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | "帮我出一套三年级语文第三单元的测验题，5道选择题" | Quiz Hand 触发(自动执行) |
| 2 | 等待输出 | 生成5道选择题+答案+解析 |
| 3 | 验证测验内容 | 5道选择题格式正确、有答案+解析+难度 |
| 4 | (如有交互式测验 UI) 测试答题功能 | 如渲染了 quiz UI 可交互答题；否则验证内容在聊天中正确显示 |
| 5 | "根据答题情况调整难度" | AI 响应难度调整请求 |

**边界探测**: 模糊主题"出测验题"(应询问), 超高数量"出100道题"(应限制/警告)

---

#### 场景 2.3: 课件幻灯片（Slideshow Hand）

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | "帮我做一节关于《桂林山水》的公开课课件，10页" | Slideshow Hand 触发 |
| 2 | 等待生成 | 结构化幻灯片(标题/内容/备注) |
| 3 | 预览幻灯片 | 专用查看器渲染 |
| 4 | "第三页加一个课堂讨论环节" | AI 更新幻灯片 |

---

#### 场景 2.4: 语音合成（Speech Hand）

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | "朗读一下这段课文：桂林山水甲天下..." | Speech Hand 触发 |
| 2 | 验证音频播放 | Browser TTS 生成音频，播放控件出现 |
| 3 | 测试暂停/恢复 | 控件正常工作 |

**体验检查**: 音频清晰, 中文语音, 控件响应迅速

**边界探测**: 超长文本(1000+字)→应分块, 空文本超时处理

---

#### 场景 2.5: 学生分析 + 跨会话记忆

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | "帮我分析一下张小明，注意力不集中但动手能力强" | AI 个性化分析 |
| 2 | "刘小花呢？上课认真但考试紧张" | AI 记住两个学生 |
| 3 | 新对话问"上次讨论的学生还记得吗？" | Memory pipeline 召回 |

---

#### 场景 2.6: 教育 Pipeline（课程计划）

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 专业模式 → Pipelines → education/lesson-plan.yaml |
| 2 | 填写：主题=桂林山水, 年级=三年级, 时长=40分钟 |
| 3 | 执行管道 | DAG 步骤完成，输出结构化课程计划 |

---

#### 场景 2.7: 技能发现

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | "我想创建一个互动课堂活动" | SemanticSkillRouter 匹配 classroom-generator |
| 2 | 技能执行 | 正确 Tauri 命令 + 参数 |

---

### 故事线 3: 技术用户"极客张" — 复杂工作流

**画像**: 30岁软件工程师，测试边缘和系统边界。专业 UI 模式默认。

---

#### 场景 3.1: 多模型配置

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | Settings → 模型与 API | 添加自定义模型页面 |
| 2 | 添加 DeepSeek: apiKey + baseUrl | OS keyring 存储(非 localStorage) |
| 3 | 切换到自定义模型 | 下拉选择 DeepSeek |
| 4 | 发送消息 | 通过 DeepSeek API 路由，流式响应 |
| 5 | 检查用量 | UsageStats 显示使用量 |

**边界探测**: 无效 API key → 清晰错误, 空 key → 阻止保存

---

#### 场景 3.2: Agent 创建与模板

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 侧边栏 → 分身 → 创建 | 创建页面打开 |
| 2 | 选择 SaaS 模板 | fetchAvailableTemplates() 加载列表 |
| 3 | 自定义并保存 | Tauri invoke('agent_create') → SOUL.md 写入磁盘 |
| 4 | 切换 Agent | UI 更新为新身份 |
| 5 | 验证 SOUL.md | 磁盘文件包含正确人格/场景/模型配置(通过 Rust 日志或 `cat ~/.zclaw/agents/<id>/SOUL.md` 确认) |

**边界探测**: 超长 system prompt(10000+字), 1MB JSON 导入, 删除当前活跃 Agent

---

#### 场景 3.3: Pipeline 编辑与执行

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | WorkflowEditor → 加载 research/literature-review.yaml |
| 2 | 修改: 添加步骤, 更改参数 |
| 3 | 保存并执行 | DAG 按依赖顺序运行 |
| 4 | 检查结果 | PipelineResultPreview 显示输出 |
| 5 | 检查历史 | WorkflowHistory 记录运行 |

**边界探测**: 循环依赖 → 验证错误, 步骤失败 → ActionError 传播, 取消执行

---

#### 场景 3.4: SaaS Relay 模式（关键缺口）

> 这是最大的测试缺口 — SaaSRelay 无自动化测试。

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 切换连接模式为 'saas' | connectionStore.getClient() 返回 SaaSRelayGatewayClient |
| 2 | 发送消息 | HTTP POST → SaaS relay → SSE 流式返回 |
| 3 | 验证 SSE 解析 | delta 正确, onDelta 接收内容, onComplete 在 [DONE] 触发 |
| 4 | 测试流式取消 | AbortController 中止 SSE 流 |
| 5 | SaaS unreachable 降级 | health-check 检测失败 → 降级到本地 Kernel |
| 6 | SaaS 恢复 | 重连 → 恢复 SaaS 模式 |

**三级验证**:
- Desktop: saas-relay-client.ts SSE 事件处理, streamStore 状态机
- SaaS: relay/handlers.rs 请求处理, key_pool.rs key 选择
- Admin: Relay 页面显示任务和使用量

**体验检查**: SSE 首 token < 2s, 降级对用户透明, 无内存泄漏

**边界探测**: 格式错误 SSE 数据, stream_timeout 事件, Token 过期, 429 rate limit

---

#### 场景 3.5: Browser Hand

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | "帮我打开百度搜索 ZCLAW AI" | Browser Hand 触发, 批准模态框 |
| 2 | 批准 | pending_execution 返回 |
| 3 | 测试18种操作类型 | 全部返回 pending_execution 而非崩溃 |

---

#### 场景 3.6: 中间件链验证

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 发含 PHI 消息: "患者张三，身份证号1234567890123456" | DataMasking(优先级90) 剥离 → [REDACTED] |
| 2 | 检查 LLM 接收内容 | 提示中无身份证号 |
| 3 | 医疗关键词: "帮我查住院部床位占用率" | ButlerRouter 分类为 healthcare 域 |
| 4 | 数据报告关键词: "生成本月门诊量统计报告" | ButlerRouter 分类为 data_report 域 |
| 5 | 触发轨迹记录 | TrajectoryRecorder(优先级650) 记录 → SQLite |

**边界探测**: 混合域查询, 空消息, 50000字超长消息

---

#### 场景 3.7: 记忆管道深度测试

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 5轮关于机器学习的深度对话 |
| 2 | 等30s(提取防抖) |
| 3 | 搜索"机器学习" | FTS5 返回相关提取 |
| 4 | 新对话提"ML" | Memory pipeline 注入相关上下文 |
| 5 | 验证排序质量 | 最相关的提取排在前面(通过 Rust 日志确认 TF-IDF 评分) |

---

#### 场景 3.8: 多 Agent 身份切换

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 创建3个不同角色 Agent |
| 2 | 快速切换(每个<5s) |
| 3 | 每次切换后发消息 | 各 Agent 以自己身份响应 |
| 4 | 验证会话隔离 | 各 Agent 对话独立 |
| 5 | 测试身份变更提案 | IdentityChangeProposal 组件 → 用户批准/拒绝 |

---

### 故事线 4: 零基础"妈妈" — 零培训采用

**画像**: 45岁母亲，从未用过 AI 工具。只用过微信和购物。期待简单。

---

#### 场景 4.1: 安装和首次启动

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 下载安装 ZCLAW | 安装无误，桌面快捷方式创建 |
| 2 | 首次启动 | 无需登录/配置，默认 Agent 已加载 |
| 3 | 观察界面 | 仅有: 侧边栏(对话) + 聊天区 + 输入栏 |
| 4 | 找到输入区 | 输入栏醒目，占位符给出明确提示 |

**体验检查**: 安装 < 2min, 首次启动 < 5s, 零配置可用, 无技术术语

---

#### 场景 4.2: 第一条消息

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 输入"你好" | 流式指示器 → 中文友好问候 |
| 2 | "你能做什么？" | AI 用通俗语言解释功能 |
| 3 | 验证模型选择器隐藏 | (Tauri 模式下模型选择器应隐藏) |

**体验检查**: 无英文错误消息, 无原始 JSON 可见, 加载指示器清晰

---

#### 场景 4.3: 使用快速操作 Chip

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 观察 FirstConversationPrompt chips | 5个 chip 可见: 小惊喜/写作/研究/收集/学习 |
| 2 | 点击"小惊喜" | 预填文本, 发送后 AI 创意响应 |
| 3 | 尝试"写作" chip | 预填文本, 可修改后发送 |

---

#### 场景 4.4: 对话历史导航

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 进行3次独立对话 |
| 2 | 侧边栏切换 | 每次切换加载正确对话 |
| 3 | 搜索关键词 | 匹配对话显示 |
| 4 | 删除对话 | 确认对话框 → 删除 |

**体验检查**: 切换 < 500ms, 搜索实时(防抖), 删除有确认

---

#### 场景 4.5: 错误韧性

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 断网发消息 | 中文错误提示"网络连接失败，请检查网络设置"，无堆栈 |
| 2 | 重连重试 | 消息成功发送 |
| 3 | 输入乱码 | AI 礼貌请求澄清 |
| 4 | 快速发5条消息 | 按序处理，无重复/UI冻结 |

**体验检查**: 所有错误中文, 无原始异常, 有重试按钮(验证 P3 bug: 错误按钮不堆叠)

---

#### 场景 4.6: 设置探索

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 点击设置 | 设置页面打开 |
| 2 | 浏览各 tab | 无死胡同/损坏链接 |
| 3 | 切换深色模式 | 主题立即切换，所有 UI 元素正确渲染 |
| 4 | 不保存退出 | 无意外数据丢失 |

---

#### 场景 4.7: 简洁↔专业模式切换

| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 简洁模式点"更多功能" | UI 平滑动画到专业模式 |
| 2 | 检查专业布局 | 完整侧边栏: 对话/分身/Hands/技能/Pipeline/... |
| 3 | 切回简洁模式 | UI 简化回简洁侧边栏 |
| 4 | 验证状态保留 | 当前对话保持不变 |

**体验检查**: AnimatePresence 动画流畅, 无布局偏移, z-index 正确

---

## Part 2: 功能模块矩阵

### 模块 1: 聊天系统

| # | 测试点 | 子测试 | 优先级 | 已知缺口 |
|---|--------|--------|--------|----------|
| 1.1 | GatewayClient(WS) | 连接/发送/接收/重连/断开 | P1 | E2E 已覆盖 |
| 1.2 | KernelClient(Tauri) | invoke/流式/5min超时守护 | P0 | 已测试 |
| 1.3 | SaaSRelay(SSE) | 连接/SSE解析/delta/complete/error/取消 | P0 | **零测试 — 关键缺口** |
| 1.4 | 流式生命周期 | streamStore 状态机/取消/超时 | P0 | 部分测试 |
| 1.5 | 模型切换 | 模型选择器隐藏(Tauri)/自定义配置 | P1 | P0 bug 已修复 |
| 1.6 | 上下文管理 | sessionKey/agentId/>100消息虚拟化 | P1 | |
| 1.7 | 错误处理 | 空 AI 响应/429/网络错误/重试按钮 | P1 | 已知 P1/P2/P3 bugs |
| 1.8 | 离线队列 | 消息排队/刷新/去重 | P2 | offlineStore 已测试 |
| 1.9 | Thinking/推理 | onThinkingDelta/reasoning_effort | P2 | |

### 模块 2: 认证系统

| # | 测试点 | 子测试 | 优先级 |
|---|--------|--------|--------|
| 2.1 | SaaS 登录 | 邮箱密码/JWT/cookie 设置 | P0 |
| 2.2 | SaaS 注册 | 验证(用户名3-32字符,邮箱RFC 5322) | P0 |
| 2.3 | TOTP 2FA | 设置/验证/恢复码 | P1 |
| 2.4 | Token 池 RPM/TPM | Key 轮换/429标记/缓存失效 | P0 |
| 2.5 | 自动降级 | SaaS unreachable → 本地 Kernel 回退 | P0 |
| 2.6 | 密码安全 | Argon2id/password_version 失效 | P1 |
| 2.7 | Admin 认证 | HttpOnly cookie/JS 不读 token | P1 |
| 2.8 | OS Keyring | JWT 存 keyring 非 localStorage | P0 |
| 2.9 | 账户锁定 | 5次失败 → 锁定15分钟 | P1 |

### 模块 3: Hands 系统

| # | Hand | 测试点 | 优先级 | 已知缺口 |
|---|------|--------|--------|----------|
| 3.1 | Browser | 触发/批准/18种操作类型/stub 行为 | P1 | 架构 stub |
| 3.2 | Collector | 触发/数据收集/格式化 | P1 | |
| 3.3 | Researcher | 触发/报告生成/深度研究 | P1 | |
| 3.4 | Twitter | 触发/12个 API v2/OAuth 1.0a | P2 | |
| 3.5 | Whiteboard | 触发/内容生成/渲染 | P2 | 导出开发中 |
| 3.6 | Slideshow | 触发/幻灯片生成/预览 | P1 | |
| 3.7 | Speech | 触发/Browser TTS/暂停恢复 | P2 | 无真实 Rust 音频 |
| 3.8 | Quiz | 触发/生成/评分/自适应 | P1 | **零测试 — 关键缺口** |
| 3.9 | Clip | 触发/视频处理 | P3 | 需 FFmpeg |
| 3.10 | 批准流程 | 批准模态框/批准拒绝/approvalStore | P0 | |
| 3.11 | 审计日志 | 执行日志/输入输出记录 | P2 | |

### 模块 4: 技能系统

| # | 测试点 | 子测试 | 优先级 |
|---|--------|--------|--------|
| 4.1 | 语义路由 | KeywordClassifier/LLM intent 匹配 | P1 |
| 4.2 | 技能执行 | skill_execute 正确参数传递 | P0 |
| 4.3 | 技能发现 | skill-discovery.ts 搜索推荐 | P2 |
| 4.4 | 错误处理 | 失败优雅降级 | P1 |
| 4.5 | 75技能覆盖 | 抽样10个技能执行验证 | P2 |

### 模块 5: Pipeline 系统

| # | 测试点 | 子测试 | 优先级 |
|---|--------|--------|--------|
| 5.1 | YAML 解析 | v1/v2 格式验证 | P1 |
| 5.2 | DAG 执行器 | 顺序+并行步骤/4 worker | P1 |
| 5.3 | 模板执行 | 抽样3个(医疗/教育/研究) | P1 |
| 5.4 | 错误处理 | 步骤失败/ActionError 传播 | P2 |
| 5.5 | 取消 | pipeline_cancel 有效 | P2 |
| 5.6 | 前端集成 | WorkflowEditor/ResultPreview | P2 |

### 模块 6: 管家模式

| # | 测试点 | 子测试 | 优先级 |
|---|--------|--------|--------|
| 6.1 | ButlerRouter | 4域分类: healthcare/data_report/policy/meeting | P0 |
| 6.2 | 冷启动 | 4阶段: idle→greeting→waiting→completed | P0 |
| 6.3 | 痛点持久化 | 内存Vec+SQLite 双写/频率跟踪 | P1 |
| 6.4 | 简洁 UI | SimpleSidebar/SimpleTopBar | P0 |
| 6.5 | 专业 UI | 完整侧边栏/所有面板 | P0 |
| 6.6 | 模式切换 | 切换动画/状态保留 | P1 |
| 6.7 | 问候定制 | Agent 名称/emoji 插值 | P2 |

### 模块 7: 记忆系统

| # | 测试点 | 子测试 | 优先级 |
|---|--------|--------|--------|
| 7.1 | 提取管道 | 对话→LLM 提取→30s防抖 | P1 |
| 7.2 | FTS5 索引 | unicode61 tokenizer/索引创建更新 | P1 |
| 7.3 | TF-IDF 评分 | 0.7*cosine + 0.3*keyword 排序 | P2 |
| 7.4 | 记忆召回 | 查询→FTS5→相关性排序 | P1 |
| 7.5 | 系统提示注入 | 召回记忆注入 LLM 上下文 | P1 |
| 7.6 | 内容去重 | 内容哈希去重 | P2 |
| 7.7 | Viking 存储 | addWithMetadata/storeWithSummaries | P2 |
| 7.8 | 静默降级 | FTS 索引失败优雅处理 | P2 |

### 模块 8: Admin 后台(15页)

| # | 页面 | 测试点 | 优先级 |
|---|------|--------|--------|
| 8.1 | Dashboard | 概览统计/图表渲染 | P1 |
| 8.2 | Accounts | 用户列表/角色分配/锁定解锁 | P0 |
| 8.3 | Agent Templates | CRUD/发布 | P1 |
| 8.4 | Billing | 计划/订阅/支付流程 | P1 |
| 8.5 | Knowledge | CRUD/批量创建(最多50)/搜索 | P1 |
| 8.6 | Login | Admin 认证/session 过期 | P0 |
| 8.7 | Logs | 审计日志/过滤/分页 | P2 |
| 8.8 | Model Services | Provider CRUD/API key 加密/RPM TPM | P0 |
| 8.9 | Prompts | 模板/版本控制 | P1 |
| 8.10 | Relay | 任务/重试/模型列表 | P1 |
| 8.11 | Roles | 权限 CRUD/6+权限键 | P1 |
| 8.12 | Scheduled Tasks | CRUD/调度器 | P2 |
| 8.13 | Usage | Token 使用图表/导出 | P1 |
| 8.14 | Config | 系统配置/CORS/限流 | P1 |
| 8.15 | ConfigSync | 跨设备配置同步 | P2 |

### 模块 9: Settings(19 tab)

| # | Tab | 测试点 | 优先级 |
|---|-----|--------|--------|
| 9.1 | General | 主题切换/语言/通知 | P1 |
| 9.2 | Usage Stats | Token 消耗显示 | P2 |
| 9.3 | Credits | 积分余额/历史 | P2 |
| 9.4 | Models & API | 自定义模型 CRUD/API key 安全存储 | P0 |
| 9.5 | MCP Services | MCP 服务器配置 | P2 |
| 9.6 | Skills | 技能浏览安装 | P2 |
| 9.7 | IM Channels | 频道配置 | P3 |
| 9.8 | Workspace | 工作空间设置 | P2 |
| 9.9 | Data & Privacy | 数据导出/隐私控制 | P1 |
| 9.10 | Secure Storage | Keyring 管理/条目查看 | P1 |
| 9.11 | SaaS Platform | SaaS URL/连接模式/登录登出 | P0 |
| 9.12 | Subscription | 计划/支付历史 | P2 |
| 9.13 | Semantic Memory | 记忆浏览/搜索/删除 | P1 |
| 9.14 | Security Status | 安全审计状态 | P2 |
| 9.15 | Audit Log | 本地审计日志 | P2 |
| 9.16 | Scheduled Tasks | NL schedule/任务列表 | P2 |
| 9.17 | Heartbeat | 反射间隔/心跳设置 | P3 |
| 9.18 | Feedback | 反馈提交 | P3 |
| 9.19 | About | 版本信息/更新检查 | P3 |

### 模块 10: SaaS 后端(12 路由模块)

| # | 模块 | 测试点 | 优先级 |
|---|------|--------|--------|
| 10.1 | auth | 登录/注册/密码重置/TOTP/刷新 token | P0 |
| 10.2 | account | 用户 CRUD/角色分配/锁定解锁 | P0 |
| 10.3 | billing | 计划管理/订阅/支付回调/配额检查 | P1 |
| 10.4 | knowledge | 知识条目 CRUD/批量导入/FTS5 搜索 | P1 |
| 10.5 | relay | 聊天中转/Key 池轮换/RPM-TPM 限流 | P0 |
| 10.6 | model_config | Provider CRUD/API key AES-256-GCM 加密 | P0 |
| 10.7 | prompt | 模板 CRUD/版本管理 | P1 |
| 10.8 | role | 角色 CRUD/6+权限键管理 | P1 |
| 10.9 | agent_template | 模板 CRUD/发布/列表 | P1 |
| 10.10 | scheduled_task | 定时任务 CRUD(当前为占位符) | P2 |
| 10.11 | telemetry | Token 用量/Hand 执行/导出 | P2 |
| 10.12 | migration | 数据库迁移/up+down | P1 |

### 模块 11: Hermes 智能管线

| # | 组件 | 测试点 | 优先级 |
|---|------|--------|--------|
| 11.1 | ExperienceStore | FTS5 经验存储/检索/去重 | P1 |
| 11.2 | Extractor | 对话→LLM 提取→结构化经验 | P1 |
| 11.3 | UserProfileStore | 用户画像结构化存储 | P2 |
| 11.4 | Profiler | 行为分析→画像更新 | P2 |
| 11.5 | NlScheduleParser | 中文自然语言→cron 转换 | P1 |
| 11.6 | TrajectoryRecorder | 交互轨迹记录/SQLite 持久化 | P2 |
| 11.7 | Compressor | 轨迹压缩/摘要 | P2 |

---

## Part 3: 测试执行框架

### Bug 严重度分类

#### P0 — 阻断(上线阻断)
必须修复才能发布。影响所有/大多数用户。无替代方案。

- 应用无法启动或崩溃
- 核心聊天功能完全不可用
- 数据丢失(对话/记忆/配置)
- 安全漏洞允许未授权访问
- 任何层级无限加载/挂起需强制关闭

#### P1 — 严重(功能损坏)
重要功能损坏但有替代方案或影响有限。发布后48h内修复。

- Hand 触发但无输出
- 记忆搜索无结果
- Pipeline 执行静默失败
- SaaS 降级不工作
- 错误消息显示原始 JSON/堆栈
- Admin 页面完全不可用

#### P2 — 中等(体验降级)
令人烦但可用。发布后1周内修复。

- UI 故障不影响功能
- 性能退化(慢但不挂)
- 错误恢复不够优雅
- 非核心功能 UX 问题
- 文字/标签不正确

#### P3 — 低(外观/未来)
已知限制或外观问题。可积压。

- 样式不一致
- "开发中"功能
- 文档不完整
- 边缘场景未优化

### 测试结果记录模板

```
场景 ID: [如 1.1]
测试人: [姓名]
日期: [YYYY-MM-DD]
环境: [Desktop/SaaS/Admin 全栈]
连接模式: [tauri/gateway/saas]
Agent 模板: [如 medical-admin]
模型: [如 GLM-4-Flash]

--- 结果 ---

步骤 1: PASS / FAIL / BLOCK
  备注: [观察]

步骤 2: PASS / FAIL / BLOCK
  备注: [观察]

[...]

--- 发现的问题 ---

[Bug ID] 严重度: P0/P1/P2/P3
标题: [简述]
复现: [具体步骤]
预期: [应发生什么]
实际: [发生了什么]
影响层: Desktop / SaaS / Admin
影响文件: [文件路径]
```

### 修复后回归标准

修复 P0/P1 bug 后，修复者必须验证:

1. **原始场景通过** — 复现 bug 的精确场景现在通过
2. **周围场景未损** — 直接前后场景仍通过
3. **自动化套件通过**:
   ```bash
   cargo test --workspace --exclude zclaw-saas  # Rust (684+)
   cargo test -p zclaw-saas -- --test-threads=1 # SaaS (138+)
   cd desktop && pnpm vitest run                # Frontend (330+)
   ```
4. **类型检查通过** — `npx tsc --noEmit` 零错误
5. **构建通过** — `cargo check --workspace` 成功
6. **回归窗口** — 涉及 streamStore/connectionStore/chatStore 的修复需重跑模块1全部场景。涉及中间件的修复需重跑 684 个 Hermes Rust 测试

### 上线签署清单

#### 构建与测试
- [ ] `cargo check --workspace` 通过, warnings ≤ 8
- [ ] `npx tsc --noEmit` 通过, 零错误
- [ ] 684 Rust workspace tests 全通过
- [ ] 138 SaaS integration tests 全通过
- [ ] 330 Frontend tests 全通过
- [ ] 61 Admin V2 tests 全通过
- [ ] E2E Playwright tests 全通过(18 spec 文件, 参考 TRUTH.md)

#### P0 Bug
- [ ] 零未解决 P0 bug
- [ ] 近期修复已回归验证

#### P1 Bug
- [ ] 所有 P1 已解决或有文档记录(含替代方案)
- [ ] 空 AI 响应处理已验证
- [ ] SaaS relay SSE 错误处理已验证

#### 关键缺口区域(手动 E2E)
- [ ] SaaSRelay(SSE) 通过场景 3.4 验证
- [ ] streamStore 通过流式生命周期场景验证
- [ ] Quiz Hand 通过场景 2.2 验证
- [ ] Slideshow Hand 通过场景 2.3 验证
- [ ] Speech Hand 通过场景 2.4 验证
- [ ] DataMasking 中间件通过场景 3.6 验证
- [ ] ButlerRouter 4域分类通过场景 1.2-1.5 验证
- [ ] 冷启动流程通过场景 1.1 和 4.1 验证
- [ ] 双 UI 模式切换通过场景 1.3/2.6/4.7 验证
- [ ] 记忆管道闭环通过场景 1.6 和 3.7 验证
- [ ] NL Schedule Parser 通过场景 1.7 验证

#### 用户体验(来自全部4条故事线)
- [ ] "妈妈"画像可在10分钟内无帮助完成一项任务
- [ ] "小李"画像可端到端完成会议纪要工作流
- [ ] "王老师"画像可生成并交付测验
- [ ] "极客张"画像可配置自定义模型并执行 Pipeline
- [ ] 所有用户可见文本均为中文(无原始英文错误)
- [ ] 深色模式完全正常
- [ ] 模式切换动画流畅无卡顿

#### 安全与合规
- [ ] API key 不存储在 localStorage(仅 OS keyring)
- [ ] DataMasking 从提示中移除 PHI
- [ ] SaaS CORS 白名单正确配置
- [ ] 生产环境检查清单全部完成
- [ ] Cookie 设置正确: HttpOnly + Secure + SameSite=Strict

#### Admin 后台
- [ ] 15个页面全部加载无错误
- [ ] 关键页面 CRUD 正常(Accounts/AgentTemplates/ModelServices/Knowledge)
- [ ] Admin 认证使用 HttpOnly cookie

#### 性能与资源
- [ ] SSE 流式后无内存泄漏(场景 3.4 长时间流式后检查内存)
- [ ] 100+消息对话无 UI 卡顿
- [ ] 100+记忆条目后搜索仍 < 2s

---

## 关键文件参考

| 文件 | 重要性 |
|------|--------|
| `desktop/src/store/chat/streamStore.ts` | 核心流式编排，零直接测试覆盖 |
| `desktop/src/lib/saas-relay-client.ts` | SaaSRelay SSE 实现，零自动化测试 |
| `desktop/src/store/connectionStore.ts` | 客户端路由4路分支决策树 |
| `crates/zclaw-runtime/src/middleware/butler_router.rs` | ButlerRouter 4域分类 |
| `docs/TRUTH.md` | 唯一真相源 |