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.7cosine + 0.3keyword 排序	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. 自动化套件通过:

   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	唯一真相源