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

refactor(relay): 将Provider Key管理路由移至model_config模块 fix(saas): 修复demo_keys与provider_keys的匹配逻辑 perf(runtime): 将流式响应超时从60秒延长至180秒以适配思考型模型 docs: 新增模块化审计和上线前功能测试方案文档 chore: 添加tauri-plugin-mcp依赖及相关配置
2026-04-08 13:39:06 +08:00
parent 81d1702484
commit ade534d1ce
18 changed files with 2051 additions and 627 deletions
--- a/docs/superpowers/specs/2026-04-05-pre-launch-functional-audit-design.md
+++ b/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/` |