feat: 添加MCP调试插件并优化流式超时处理

refactor(relay): 将Provider Key管理路由移至model_config模块
fix(saas): 修复demo_keys与provider_keys的匹配逻辑
perf(runtime): 将流式响应超时从60秒延长至180秒以适配思考型模型
docs: 新增模块化审计和上线前功能测试方案文档
chore: 添加tauri-plugin-mcp依赖及相关配置

docs/superpowers/specs/2026-04-04-module-audit-design.md

@@ -0,0 +1,279 @@
+ # ZCLAW 模块化端到端深度功能验证审计方案
+
+> **版本**: v1.1 (review fix)
+> **日期**: 2026-04-04
+> **状态**: 设计完成，待执行
+> **审计目标**: 端到端功能验证——系统性找出每个模块从 UI 到后端的断链
+
+---
+
+## 1. 背景与动机
+
+ZCLAW 项目已有 14 次审计历史（V1-V11 共 11 轮版本化审计 + 3 轮专项审计），前几轮以"技术层横向扫描"为主：检查 Tauri 命令调用率、SaaS API 前端消费、死代码清理等。这些审计修复了大量问题，但存在三个结构性盲区：
+
+1. **缺乏功能视角** — 已知 24 个 Tauri 命令无前端调用，但不知属于哪些用户故事
+2. **缺乏边界验证** — 只查"调了没有"，没查"调错了怎么表现"、"空数据怎么表现"
+3. **缺乏累积性** — 每轮从头扫，无模块级基线
+
+本方案以**功能领域为主轴**组织审计，以标准化的**五维检查清单**确保不遗漏，以**三波并行策略**高效执行。
+
+---
+
+## 2. 审计模块划分
+
+### 模块清单
+
+| 模块 | 功能领域 | 核心链路 | 涉及关键文件 |
+|------|---------|---------|-------------|
+| **M1** | 智能对话 | 用户输入 → ChatArea → chatStore → Kernel → LLM Driver → 流式回传 | `components/ai/*`, `store/chat/*`, `lib/kernel-chat.ts`, `kernel_commands/chat.rs`, `zclaw-runtime/src/driver/*` |
+| **M2** | Agent 分身 | 创建/切换/配置 Agent → agentStore → Kernel → SQLite | `agentStore.ts`, `lib/kernel-agent.ts`, `kernel_commands/agent.rs`, `zclaw-memory/src/agent_store.rs` |
+| **M3** | Hands 自主能力 | 触发 Hand → handStore → Kernel → Hand 执行 → 事件回调 | `handStore.ts`, `lib/kernel-hands.ts`, `crates/zclaw-hands/src/hands/*`, `hands/*.HAND.toml` |
+| **M4** | 智能层 | 记忆/身份/反思/心跳/自主授权/压缩 各链路 | `intelligence-client/*`, `store/memoryGraphStore.ts`, `intelligence/*.rs` |
+| **M5** | 技能生态 | 技能浏览/搜索/执行 → Skills 语义路由 → SKILL.md | `lib/kernel-skills.ts`, `crates/zclaw-skills/src/*`, `skills/*.md` |
+| **M6** | Pipeline 工作流 | 创建/编辑/执行 Pipeline → workflowStore → DSL Engine | `components/pipeline/*`, `workflowStore.ts`, `crates/zclaw-pipeline/src/*` |
+| **M7** | SaaS 平台(Desktop) | 登录/配置/支付 → saasStore → saas-client → SaaS API | `components/SaaS/*`, `saasStore.ts`, `lib/saas-client.ts`, `crates/zclaw-saas/src/*` |
+| **M8** | Admin V2 | 14 页面 CRUD → 18 services → SaaS API → PostgreSQL | `admin-v2/src/pages/*`, `admin-v2/src/services/*` |
+| **M9** | 通信与安全 | 连接管理/认证/TOTP/加密/限流/MCP 协议 | `connectionStore.ts`, `securityStore.ts`, `gateway-client.ts`, `lib/mcp-client.ts`, `crates/zclaw-saas/src/auth/*`, `crates/zclaw-protocols/src/mcp/*` |
+| **M10** | 横切关注点 | 错误一致性、类型一致性、并发安全（汇总分析） | 全局横切 |
+| **M11** | Classroom 课堂 | 课堂场景播放/聊天/笔记/白板/TTS | `store/classroomStore.ts`, `components/classroom_player/*`, `lib/classroom-adapter.ts` |
+
+---
+
+## 3. 五维检查模板
+
+每个模块必须完成以下五个维度的检查：
+
+### 维度 1: 链路完整性
+
+- 画出该模块的完整调用链（UI → Store → Client → IPC/API → Rust → DB/网络）
+- 标注每个节点的文件路径
+- 检查每条边的连通性（"写了没接"检查）
+
+### 维度 2: 参数/类型一致性
+
+| 检查点 | 方法 |
+|--------|------|
+| 前端调用参数 vs Rust 命令签名 | 逐字段比对名称、类型、Optionality |
+| 返回值类型链路 | Rust struct → Tauri IPC → TS type → Store state |
+| 枚举值/常量两端同步 | 比对 Rust enum 与 TS union type |
+| 数据库字段与 API 字段对齐 | SQL 列 vs handler struct field |
+
+### 维度 3: 边界与错误处理
+
+| 场景 | 检查内容 |
+|------|---------|
+| 空状态 | 数据库无数据时 UI 表现；空字符串/空数组/null 参数传递 |
+| 错误状态 | 网络 5xx / 4xx / 超时 / 序列化失败 → 是否有用户可见反馈 |
+| 并发 | 快速双击；多操作并行；Token 刷新并发 |
+| 性能降级 | 大数据量（1000+ 消息）；FTS 全表扫描；连接池满 |
+| 输入边界 | 超长文本、特殊字符、非 UTF-8、负数、零值 |
+
+### 维度 4: 状态管理
+
+- Store 状态机完整性（loading / success / error / reset）
+- 组件是否正确订阅 Store 变化
+- 持久化/恢复路径是否完整
+- 竞态条件风险（stale closure、过期 setState）
+
+### 维度 5: 安全与资源
+
+- 敏感数据加密/脱敏
+- 资源泄漏（事件监听器未清理、定时器未清除、连接未释放）
+- 权限检查完整性
+- 日志是否包含敏感信息
+
+---
+
+## 4. 断链检测方法
+
+### 步骤 1: Tauri 命令调用矩阵
+
+```
+对模块涉及的所有 Tauri 命令:
+  1. 从 kernel_commands/mod.rs 提取 #[tauri::command] 注册名
+  2. grep desktop/src/ 找 invoke('commandName') 调用
+  3. 对比 → 标注 connected / reserved / broken
+```
+
+### 步骤 2: 参数签名级比对
+
+```
+对每个 connected 命令:
+  1. 提取 Rust 端参数类型定义 (struct/derive)
+  2. 提取 TS 端调用参数
+  3. 逐字段比对名称/类型/Optionality
+  4. 不匹配 → 记为 P1 断链
+```
+
+### 步骤 3: 事件链路追踪
+
+```
+  1. grep desktop/src-tauri/src/ 找 .emit("event-name") 发射点
+  2. grep desktop/src/ 找 .listen("event-name") 监听点
+  3. 交叉比对 → 找出 emit 但无 listen 的断裂
+```
+
+### 步骤 4: 数据库-API-UI 三端对齐
+
+```
+  1. grep crates/zclaw-saas/src/ 找 SELECT/INSERT 语句
+  2. 对比 API handler 暴露的端点
+  3. 对比前端 service 层调用
+  4. 找出"有表无 API" 或 "有 API 前端未调"
+```
+
+---
+
+## 5. 边界验证方法
+
+采用三层验证策略：
+
+### 第一层: 静态分析（工具辅助，60% 工作量）
+
+| 检查 | 命令 |
+|------|------|
+| TypeScript 类型安全 | `tsc --noEmit` |
+| Rust 编译检查 | `cargo check` |
+| 潜在 panic | `grep -rn "unwrap()" crates/` |
+| 静默忽略 | `grep -rn "let _ =" crates/` |
+| 类型逃逸 | `grep -rn "as any" desktop/src/` |
+| 技术债标记 | `grep -rn "TODO\|FIXME\|HACK"` |
+
+### 第二层: 代码推理（人工审查，30% 工作量）
+
+对每条链路的每个"edge"，推理：
+- 上游返回 null/undefined/Err 时，下游如何处理？
+- 上游超时 30s 无响应，UI 如何表现？
+- 用户在 loading 期间切换页面，状态如何恢复？
+
+### 第三层: 实机验证（P0/P1 必须，高频模块加强）
+
+**标准模块（M2/M4-M11）**: 10% 工作量，仅 P0/P1 级发现做实机验证。
+
+**高频模块（M1/M3）**: 20-30% 工作量，除 P0/P1 外还需验证：
+- 并发场景：快速连续发送消息、快速连续触发 Hand
+- 流式中断：中途断网、切换模型、切换 Agent
+- 大数据场景：1000+ 消息加载、长时间会话压缩
+
+实机验证启动命令：`pnpm start:dev`
+- 空数据场景：清空相关表，验证 UI 不崩溃
+- 错误场景：关闭后端服务，验证前端降级提示
+- 并发场景：快速连续触发同一操作
+
+---
+
+## 6. 优先级分级标准
+
+| 级别 | 定义 | 示例 | 修复时限 |
+|------|------|------|---------|
+| **P0** | 必然崩溃或数据丢失，用户无法绕过 | skill_execute 空参数导致 serde panic | 立即 |
+| **P1** | 功能失效但不崩溃；核心功能断链 | API 路径 404、参数不匹配静默失败 | 24h |
+| **P2** | 功能部分可用但不完整；可能演变为 P1 | 静默忽略错误、fire-and-forget spawn | 1 周 |
+| **P3** | 不影响功能但影响可维护性 | 类型命名不一致、文档数字偏差 | 下个迭代 |
+| **P4** | 信息级建议改进 | 配置参数预留未消费、feature-gated 未启用 | backlog |
+
+### 判断流程
+
+```
+用户是否看到异常？ → 是 → P0/P1
+数据是否丢失/损坏？ → 是 → P0
+核心路径是否受阻？ → 是 → P1
+是否可能引发 P1？ → 是 → P2
+是否仅影响开发者体验？ → 是 → P3/P4
+```
+
+---
+
+## 7. 执行策略
+
+### 执行假设与节奏
+
+- **执行者假设**: 单人执行（AI Agent 辅助 + 人工决策）
+- **模块粒度**: 每模块约 1 个工作日（含五维检查 + 报告编写）
+- **总工期**: 11 个工作日（11 模块 x 1 天/模块），跨约 2.5 周
+
+### 波次安排
+
+| 波次 | 模块 | 耗时 | 说明 |
+|------|------|------|------|
+| **第一波** | M1(对话) + M2(Agent) + M3(Hands) | 3 天 | 核心路径，历史断链最密集区 |
+| **第二波** | M4(智能层) + M5(技能) + M6(Pipeline) | 3 天 | 智能与编排 |
+| **第三波** | M7(SaaS) + M8(Admin) + M11(Classroom) | 3 天 | 平台层 |
+| **第四波** | M9(通信安全) + M10(横切汇总) | 2 天 | 基础设施+全量汇总 |
+
+每波内模块顺序执行（单 Agent 每日 1 模块），避免 context 窗口溢出。
+
+### 模块内部执行顺序
+
+五维检查串行执行：链路图 → 参数比对 → 边界验证 → 状态管理 → 安全检查
+
+---
+
+## 8. 报告格式
+
+每个模块独立输出一份审计报告，格式如下：
+
+```markdown
+# 模块 [Mx] [模块名] 审计报告
+
+## 1. 模块概况
+- 功能描述
+- 涉及文件清单（按层分类）
+- 调用链路图
+- 前次审计已知问题继承
+
+## 2. 五维检查结果
+
+### 2.1 链路完整性
+| 链路 | 起点 | 终点 | 状态 | 断裂点 |
+
+### 2.2 参数/类型一致性
+| 接口 | 前端类型 | 后端类型 | 一致性 | 不匹配字段 |
+
+### 2.3 边界与错误处理
+| 场景 | 输入 | 预期行为 | 实际行为 | 级别 |
+
+### 2.4 状态管理
+| Store | 状态机完整性 | 持久化 | 竞态风险 |
+
+### 2.5 安全与资源
+| 检查项 | 状态 | 说明 |
+
+## 3. 问题清单
+| ID | 描述 | 文件:行号 | 级别 | 修复建议 | 验证方法 |
+
+## 4. 改进建议
+- 短期修复项（按优先级排序）
+- 长期架构建议
+```
+
+最终汇总为 `docs/features/MODULE_AUDIT_SUMMARY.md`，包含：
+- 各模块问题统计表
+- P0/P1 问题优先修复清单
+- 整体健康度评分
+- 对 TRUTH.md 数字更新的建议
+
+---
+
+## 9. 与已有审计的衔接
+
+- **继承 AUDIT_TRACKER.md**：每个模块开头从已有追踪表继承已知问题
+- **更新 TRUTH.md**：审计中发现的数字偏差回写真相源
+- **延续版本线**：本审计为 V12（第 15 次），报告编号继续递增
+- **新 P0 处理流程**：审计中发现的 P0 级问题立即中断当前模块审计，优先修复并验证，再继续审计
+- **避免重复**：已标记为"已修复"的问题仅做验证性检查，不重新审计
+
+---
+
+## 10. 前几轮审计盲区（本次重点关注）
+
+| 盲区 | 说明 | 本次覆盖维度 |
+|------|------|-------------|
+| Store 状态机完整性 | 前几轮几乎未检查 loading/error/reset | 维度 4 |
+| 错误传播链路 | 后端 Err 是否能传到 UI | 维度 3 |
+| 事件监听对称性 | emit 但无 listen 的断裂 | 维度 1 |
+| 并发安全 | 约 15 处 fire-and-forget spawn 未审计 | 维度 5 |
+| 空数据降级 | Desktop 端空数据表现未验证 | 维度 3 |
+| Desktop 前端零测试 | 边界验证只能靠代码推理+实机 | 维度 3，M1/M3 加强实机验证 |
+| Classroom 课堂 | 27 个 Tauri 命令中 7 个无前端调用，未审计 | 新增 M11 |
+| MCP 协议链路 | MCP 服务发现→工具列举→执行 链路未验证 | M9 增加检查项 |

docs/superpowers/specs/2026-04-05-pre-launch-functional-audit-design.md

@@ -0,0 +1,363 @@
+# ZCLAW 上线前功能审计方案
+
+> **目标**: 对 ZCLAW 全部功能模块进行系统性的端到端验证，确保每个功能按设计文档正常工作，发现并修复所有 P0/P1 缺陷。
+> **方法**: 基于 V12 模块化审计框架，12 模块逐个测试 + 端到端用户场景集成验证。
+> **状态**: 设计完成，待执行。
+
+---
+
+## 1. 背景
+
+### 1.1 当前状态
+
+ZCLAW 已完成稳定化阶段（2026-04-03），V12 模块化审计给出了 76/100 的整体健康度。各模块健康度差异显著（58-91/100），低分模块存在未发现的功能缺陷风险。上线前需要一次系统性的全量功能验证。
+
+### 1.2 已有基础设施
+
+- **V12 审计**: V12 审计覆盖了 11 个功能模块（M1-M9, M11；M10 编号跳过无对应报告），含健康度评分和已知问题清单。本测试方案重组为 12 个测试模块（T1-T12），其中 T11（SaaS 后端 API）无独立 V12 审计报告，T12 为跨模块集成测试。
+- **自动化测试**: Vitest (desktop + admin) + Playwright E2E (~278 tests) + cargo test (~595 tests, 含 386 同步 + 209 异步)
+- **测试工具**: tauri-mcp（Tauri 端）、Playwright（Web E2E）、cargo test（Rust）、HTTP 脚本（SaaS API）
+- **环境**: Tauri 桌面端 + SaaS 后端 + Admin V2 + LLM API Key 全部可用
+
+### 1.3 设计决策
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| 测试方案 | 模块化系统测试 + 端到端用户场景 | 与 V12 审计对齐，效率最高 |
+| Tauri 端测试工具 | tauri-mcp | 用户指定 |
+| SaaS API 测试工具 | cargo test + HTTP | 已有 86+ 单元测试基础 |
+| Admin V2 测试工具 | Playwright + vitest | 已有 ~71 单元测试 + Playwright 配置 |
+| 测试范围 | 全量覆盖（12 模块） | 上线前无死角验证 |
+
+---
+
+## 2. 测试模块矩阵
+
+### 2.1 模块清单（按风险排序）
+
+| 序号 | 模块 | V12 健康度 | 风险等级 | 主要测试工具 | 关键验证点 |
+|------|------|-----------|---------|------------|-----------|
+| T1 | Hands 自主能力 | 58/100 | HIGH | tauri-mcp + cargo test | 9 Hands 触发/执行/审批闭环 |
+| T2 | 智能层（记忆/反思/心跳/自主） | 61/100 | HIGH | tauri-mcp + cargo test | 记忆提取/注入、反思触发、心跳周期 |
+| T3 | Agent 分身 | 67/100 | HIGH | tauri-mcp | Agent CRUD、身份切换、SOUL.md |
+| T4 | 课堂系统 | 70/100 | HIGH | tauri-mcp | 场景播放、TTS、白板、笔记（含 3 个 P1 问题） |
+| T5 | Pipeline 工作流 | 72/100 | MEDIUM | tauri-mcp + cargo test | DSL 解析、7 种 Action 执行、导出 |
+| T6 | SaaS 桌面集成 | 85/100 | MEDIUM | tauri-mcp + HTTP | 登录/订阅/Relay/配置同步 |
+| T7 | 技能生态 | 85/100 | LOW | tauri-mcp + cargo test | 75 Skills 加载/路由/执行（采样策略：5 个/执行模式 + 全量解析验证；重点验证 M5-01 tags-triggers 映射问题） |
+| T8 | 智能对话 | 91/100 | LOW | tauri-mcp | 8 Provider 流式响应/Markdown/多模型切换 |
+| T9 | Admin V2 后台 | 82/100 | MEDIUM | Playwright + vitest | 15 页面 CRUD、认证、数据流（10 页有测试，5 页缺失：Billing/ConfigSync/Knowledge/Roles/ScheduledTasks） |
+| T10 | 通信与安全 | 86/100 | LOW | cargo test + HTTP | JWT/TOTP/Ed25519/CSP/限流 |
+| T11 | SaaS 后端 API | N/A | MEDIUM | cargo test + HTTP | 131 API 端点、34 表、7 Worker |
+| T12 | 端到端用户场景 | N/A | HIGH | tauri-mcp | 跨模块真实用户流程 |
+
+### 2.1.1 T-M 映射表
+
+本测试方案按风险重排了模块顺序。V12 审计编号 M10 跳过（无对应报告），T11 无 V12 审计基线。
+
+| 测试模块 | V12 审计模块 | 说明 |
+|---------|------------|------|
+| T1 Hands 自主能力 | M3 | 健康度最低 (58/100) |
+| T2 智能层 | M4 | 含 2 个 P0 问题 |
+| T3 Agent 分身 | M2 | 14 个已知问题 |
+| T4 课堂系统 | M11 | 3 个 P1 问题 |
+| T5 Pipeline 工作流 | M6 | 2 个 P1 问题 |
+| T6 SaaS 桌面集成 | M7 | SaaS 前端集成 |
+| T7 技能生态 | M5 | 重点验证 M5-01 |
+| T8 智能对话 | M1 | 健康度最高 (91/100) |
+| T9 Admin V2 后台 | M8 | 15 页面，5 页缺测试 |
+| T10 通信与安全 | M9 | 安全基线验证 |
+| T11 SaaS 后端 API | 无 | 无 V12 审计，使用功能文档 + 集成测试作为基线 |
+| T12 端到端用户场景 | 多模块 | 跨模块集成验证 |
+
+### 2.2 测试工具分配
+
+| 端 | 测试工具 | 用途 |
+|----|---------|------|
+| Tauri 桌面端 | tauri-mcp | UI 交互、组件状态、Tauri 命令调用、实时截图 |
+| Rust 后端 | cargo test | 单元测试、集成测试（~595 已有 + 补充） |
+| SaaS API | cargo test + HTTP | API 端点验证、权限检查、并发测试 |
+| Admin V2 | Playwright + vitest | 页面交互、数据流（~71 已有测试，5 页需新增） |
+| E2E 集成 | tauri-mcp | 跨模块端到端用户场景（桌面端真实交互） |
+
+---
+
+## 3. 测试用例设计
+
+### 3.1 用例模板
+
+```
+TC-{模块编号}-{序号} | {用例名称}
+前置条件: ...
+测试步骤: ...
+预期结果: ...
+优先级: P0/P1/P2
+场景类型: 正常(Normal) / 边界(Boundary) / 异常(Exception)
+验证方法: tauri-mcp query_page + screenshot / cargo test / HTTP
+```
+
+### 3.2 三类场景定义
+
+| 场景类型 | 定义 | 示例 |
+|---------|------|------|
+| **正常** | 核心功能的 Happy Path | 发送消息 -> 收到流式响应 -> 消息正确显示 |
+| **边界** | 极限输入和状态转换 | 10000 字消息、同时触发 5 个 Hands、模型列表为空 |
+| **异常** | 错误处理和降级 | API Key 无效错误提示、网络断开离线模式、LLM 超时重试 |
+
+### 3.3 每模块用例数量
+
+风险分级规则：HIGH = 健康度 < 75 或 P1 问题 >= 3；MEDIUM = 健康度 75-89；LOW = 健康度 >= 90 或安全模块。
+
+| 风险等级 | 正常 | 边界 | 异常 | 合计 | 适用模块 |
+|---------|------|------|------|------|---------|
+| HIGH | 8-12 | 4-6 | 4-6 | 16-24 | T1, T2, T3, T4 |
+| MEDIUM | 6-8 | 3-4 | 3-4 | 12-16 | T5, T6, T9, T11 |
+| LOW | 4-6 | 2-3 | 2-3 | 8-12 | T7, T8, T10 |
+| 集成 | 8-10 | 2-3 | 2-3 | 12-16 | T12 |
+
+**预估总用例数: ~170-230 个**
+
+### 3.4 缺陷分级标准
+
+| 级别 | 定义 | 示例 | 修复时限 |
+|------|------|------|---------|
+| **P0 阻塞** | 核心功能完全不可用 | 聊天无法发送、App 崩溃 | 立即修复 |
+| **P1 严重** | 主要功能异常但有 workaround | Hand 触发失败但手动可恢复 | 当天修复 |
+| **P2 一般** | 次要功能异常或体验问题 | 设置页布局错位 | 本周修复 |
+| **P3 轻微** | 视觉/文案/优化建议 | 按钮间距不一致 | 下个迭代 |
+| **P4 建议** | 改进建议 | 交互体验优化 | 记录不修 |
+
+---
+
+## 4. 测试执行流程
+
+### 4.1 四阶段执行计划
+
+```
+阶段 1: 环境准备 (预计 0.5-1 天)
+  1.1 启动所有服务 (Tauri + SaaS + Admin + PostgreSQL)
+  1.2 验证 tauri-mcp 连接
+  1.3 确认至少 1 个 LLM Provider API Key 可用
+  1.4 执行现有自动化测试基线
+      - cargo test --workspace
+      - cd desktop && pnpm vitest run
+      - cd admin-v2 && pnpm vitest run
+  1.5 记录基线结果
+
+阶段 2: 高风险模块 (T1-T4) (预计 3-5 天)
+  T1 Hands 自主能力 (58/100) -- 最优先
+  T2 智能层 (61/100)
+  T3 Agent 分身 (67/100)
+  T4 课堂系统 (70/100)
+  目标: P0/P1 缺陷清零
+  注: 测试与修复并行，每发现 P0/P1 立即修复并回归验证
+
+阶段 3: 中低风险模块 (T5-T11) (预计 3-5 天)
+  T5 Pipeline -> T6 SaaS 集成 -> T7 技能 -> T8 对话
+  T9 Admin V2 -> T10 安全 -> T11 SaaS API
+  每模块完成后立即修复发现的问题
+  注: T11 无 V12 审计报告，以功能文档 (docs/features/08-saas-platform/)
+      和现有集成测试 (crates/zclaw-saas/tests/) 为基线
+
+阶段 4: 端到端集成验证 (T12) (预计 2-3 天)
+  8-10 个跨模块用户场景
+  回归验证阶段 2-3 修复的问题
+  生成最终测试报告
+
+总计预估: 8-14 天
+```
+
+### 4.2 每模块执行流程
+
+```
+Step 1: 读取该模块的 V12 审计报告 (docs/features/audit-v12/M{n}-{name}.md)
+        确认已知问题清单
+        注: T11 (SaaS 后端 API) 无 V12 审计报告，跳过此步，
+            以 docs/features/08-saas-platform/ 和 crates/zclaw-saas/tests/ 为基线
+
+Step 2: 读取功能设计文档 (docs/features/{module-dir}/{doc}.md)
+        理解预期行为和设计规范
+        具体路径参见 Section 8 文件索引
+
+Step 3: 执行该模块的现有自动化测试
+        cargo test / vitest run -- 相关文件
+        记录基线通过率
+
+Step 4: 用 tauri-mcp 执行手动测试用例
+        - query_page(mode='map') 获取页面结构
+        - 执行用户交互 (click, type_text, navigate)
+        - take_screenshot 截图记录
+        - 验证 Store 状态 (execute_js 检查 Zustand)
+
+Step 5: 发现问题 -> 立即修复 -> 回归验证
+        修复后重新执行相关用例
+
+Step 6: 模块完成 -> 生成测试报告
+        更新 docs/features/audit-v12/ 中的模块报告
+```
+
+### 4.3 tauri-mcp 测试工作流
+
+Tauri 端测试的标准化流程：
+
+```
+1. 窗口管理
+   manage_window(action='list') -> 获取窗口列表
+   manage_window(action='focus') -> 聚焦目标窗口
+
+2. 页面状态检查
+   query_page(mode='state') -> URL/title/scroll 状态
+   query_page(mode='map') -> DOM 元素结构
+   query_page(mode='find_element') -> 精确定位交互目标
+
+3. 用户交互
+   click(selector_type='ref', selector_value='{ref}') -> 点击
+   type_text(text='{text}') -> 输入
+   mouse_action(action='scroll', direction='down') -> 滚动
+   navigate(action='goto', url='{url}') -> 导航
+
+4. 状态验证
+   take_screenshot() -> 截图记录
+   wait_for(text=['{expected}']) -> 等待预期结果
+   Store 状态验证优先级:
+     a) DOM 元素内容检查 (query_page mode='map' 验证渲染结果)
+     b) execute_js 检查 React 组件渲染状态 (document.querySelector)
+     c) 如需直接访问 Store，通过 query_page(mode='map') 的 interactive_only=true
+        检查受控组件值间接推断 Store 状态
+
+5. 结果记录
+   截图保存到 docs/test-results/{module}/
+   测试结果记录到测试报告
+```
+
+---
+
+## 5. 端到端用户场景 (T12)
+
+### 5.1 核心用户场景
+
+| # | 场景名称 | 涉及模块 | 关键步骤 |
+|---|---------|---------|---------|
+| E2E-01 | 新用户首次对话 | T8, T3, T7 | 打开应用 -> 首次引导 -> 选择模型 -> 发送消息 -> 收到回复 |
+| E2E-02 | Agent 创建与使用 | T3, T8, T2 | 创建新 Agent -> 配置个性/技能 -> 切换到新 Agent -> 发送消息验证身份 |
+| E2E-03 | Hand 触发与审批 | T1, T2, T8 | 对话中触发 Hand -> 查看执行状态 -> 审批确认 -> 查看结果 |
+| E2E-04 | SaaS 登录与订阅 | T6, T10 | 登录 SaaS -> 查看订阅状态 -> 配置同步 -> 验证本地状态 |
+| E2E-05 | Pipeline 创建与执行 | T5, T1 | 创建 Pipeline -> 配置 Action -> 执行 -> 查看结果 -> 导出 |
+| E2E-06 | 记忆与反思闭环 | T2, T3, T8 | 多轮对话 -> 触发记忆提取 -> 验证记忆存储 -> 反思触发 -> 身份演化 |
+| E2E-07 | Admin 管理全流程 | T9, T11 | 登录 Admin -> 管理账户 -> 配置模型 -> 查看日志 -> 管理 Prompt |
+| E2E-08 | 离线与重连 | T1, T2, T6, T8 | 断开网络（tauri-mcp: 关闭 SaaS 后端模拟服务端不可达）-> 离线模式验证（聊天降级、Hand 事件队列、心跳检测）-> 恢复网络 -> 自动重连 -> 消息同步 |
+| E2E-09 | 课堂场景播放 | T4, T1 | 进入课堂 -> 播放场景 -> TTS 朗读 -> 白板互动 -> 笔记记录 |
+| E2E-10 | 技能发现与执行 | T7, T8 | 浏览技能市场 -> 安装技能 -> 对话中触发技能 -> 验证执行结果 |
+
+---
+
+## 6. 上线达标标准
+
+### 6.1 强制达标项（全部必须通过）
+
+| # | 达标项 | 标准 |
+|---|--------|------|
+| 1 | P0 缺陷 | 0 个 |
+| 2 | P1 缺陷 | <= 2 个（且有明确修复计划） |
+| 3 | 核心流程 | 聊天、Agent CRUD、Hand 触发、SaaS 登录 4 条主路径 100% 通过 |
+| 4 | 自动化测试 | `cargo test --workspace` + `cd desktop && pnpm vitest run` + `cd admin-v2 && pnpm vitest run` + `cargo check --workspace` 全部通过 |
+| 5 | 安全 | 无 HIGH 级别安全缺陷（复用渗透测试 V1 标准） |
+
+### 6.2 建议达标项
+
+| # | 达标项 | 目标 |
+|---|--------|------|
+| 1 | 整体通过率 | >= 95% |
+| 2 | 模块最低健康度 | >= 65/100（所有模块），争取 >= 70/100。健康度重评采用与 V12 相同的 5 维度框架（功能完整性、代码质量、测试覆盖、文档完备、集成连通性），由测试执行者在每模块完成后打分 |
+| 3 | 平均健康度 | >= 85/100 |
+| 4 | E2E 用户场景通过率 | >= 90% |
+
+---
+
+## 7. 测试报告格式
+
+### 7.1 模块测试报告模板
+
+```markdown
+## T{n} {模块名} 测试报告
+
+### 摘要
+- 执行用例数: X/Y
+- 通过率: Z%
+- 发现缺陷: P0: a, P1: b, P2: c, P3: d
+
+### V12 已知问题验证
+| V12 Issue ID | 描述 | V12 严重度 | 验证结果 | 备注 |
+|-------------|------|-----------|---------|------|
+
+### 新发现问题
+| TC-ID | 描述 | 场景类型 | 优先级 | 状态 | 截图 |
+|-------|------|---------|--------|------|------|
+
+### 健康度评估
+- V12 基线: XX/100
+- 本次评估: YY/100
+- 变化: +/-ZZ
+- 关键改善: ...
+- 残留风险: ...
+```
+
+### 7.2 最终交付物
+
+| # | 交付物 | 路径 |
+|---|--------|------|
+| 1 | 测试计划文档 | `docs/test-results/TEST_PLAN.md` |
+| 2 | 模块测试报告 | `docs/test-results/T{n}-{module}/REPORT.md` |
+| 3 | 缺陷清单 | `docs/test-results/DEFECT_LIST.md` |
+| 4 | 截图证据 | `docs/test-results/T{n}-{module}/screenshots/` |
+| 5 | 上线评估 | `docs/test-results/RELEASE_READINESS.md` |
+| 6 | 自动化脚本 | 新增的测试脚本（如有） |
+
+---
+
+## 8. 关键文件索引
+
+### 8.1 功能设计文档
+
+| 模块 | 文档路径 |
+|------|---------|
+| 通信层 | `docs/features/00-architecture/01-communication-layer.md` |
+| 状态管理 | `docs/features/00-architecture/02-state-management.md` |
+| 安全认证 | `docs/features/00-architecture/03-security-auth.md` |
+| 聊天界面 | `docs/features/01-core-features/00-chat-interface.md` |
+| Agent 分身 | `docs/features/01-core-features/01-agent-clones.md` |
+| Hands 系统 | `docs/features/01-core-features/02-hands-system.md` + `docs/features/05-hands-system/` |
+| 智能层 | `docs/features/02-intelligence-layer/` (8 files) |
+| 技能生态 | `docs/features/04-skills-ecosystem/` |
+| Pipeline | `docs/features/07-pipeline-dsl/` |
+| SaaS 平台 | `docs/features/08-saas-platform/` |
+| Tauri 后端 | `docs/features/06-tauri-backend/` |
+
+### 8.2 V12 审计报告
+
+| 模块 | 报告路径 |
+|------|---------|
+| M1 智能对话 | `docs/features/audit-v12/M1-intelligent-chat.md` |
+| M2 Agent 分身 | `docs/features/audit-v12/M2-agent-clones.md` |
+| M3 Hands | `docs/features/audit-v12/M3-hands-system.md` |
+| M4 智能层 | `docs/features/audit-v12/M4-intelligence-layer.md` |
+| M5 技能生态 | `docs/features/audit-v12/M5-skill-ecosystem.md` |
+| M6 Pipeline | `docs/features/audit-v12/M6-pipeline-workflow.md` |
+| M7 SaaS 桌面 | `docs/features/audit-v12/M7-saas-desktop.md` |
+| M8 Admin V2 | `docs/features/audit-v12/M8-admin-v2.md` |
+| M9 安全 | `docs/features/audit-v12/M9-communication-security.md` |
+| M11 课堂 | `docs/features/audit-v12/M11-classroom.md` |
+
+### 8.3 测试基础设施
+
+| 类型 | 路径 |
+|------|------|
+| Desktop Vitest 配置 | `desktop/vitest.config.ts` |
+| Desktop 测试文件 | `desktop/tests/` |
+| E2E Playwright 配置 | `desktop/tests/e2e/playwright.config.ts` |
+| E2E 测试文件 | `desktop/tests/e2e/specs/` |
+| E2E 测试工具 | `desktop/tests/e2e/fixtures/` + `utils/` |
+| Admin Vitest 配置 | `admin-v2/vitest.config.ts` |
+| Admin 测试文件 | `admin-v2/tests/` |
+| Root 测试文件 | `tests/` |
+| Root Mock Server | `tests/fixtures/zclaw-mock-server.ts` |
+| SaaS 集成测试 | `crates/zclaw-saas/tests/` |