iven/zclaw_openfang

Fork 0

Files

iven fa5ab4e161

CI / Lint & TypeCheck (push) Has been cancelled

Details

CI / Unit Tests (push) Has been cancelled

Details

CI / Build Frontend (push) Has been cancelled

Details

CI / Rust Check (push) Has been cancelled

Details

CI / Security Scan (push) Has been cancelled

Details

CI / E2E Tests (push) Has been cancelled

Details

refactor(middleware): 移除数据脱敏中间件及相关代码

移除不再使用的数据脱敏功能，包括：
1. 删除data_masking模块
2. 清理loop_runner中的unmask逻辑
3. 移除前端saas-relay-client.ts中的mask/unmask实现
4. 更新中间件层数从15层降为14层
5. 同步更新相关文档(CLAUDE.md、TRUTH.md、wiki等)

此次变更简化了系统架构，移除了不再需要的敏感数据处理逻辑。所有相关测试证据和截图已归档。

2026-04-22 19:19:07 +08:00

27 KiB

Raw Blame History

ZCLAW 全系统功能测试设计规格书

日期: 2026-04-17 类型: 全系统功能测试 (Full System Functional Test) 执行方式: AI Agent 自动执行 (Chrome DevTools MCP + Tauri MCP + HTTP) 验证深度: 深度验证 (结构完整性 + 数据合理性 + 状态一致性 + 错误合理性 + 跨系统流通)

1. 背景与目标

1.1 为什么需要这次测试

ZCLAW 已完成发布前稳定化阶段的核心功能开发，系统包含：

10 个 Rust Crates (~77K 行)
190 个 Tauri 命令 (104 个有前端 invoke 调用)
137 个 SaaS HTTP 端点 (.route())
14 层 Runtime 中间件 + 10 层 SaaS HTTP 中间件
9 个 Hands + 75 个 Skills + 17 个 Pipeline 模板

之前的 E2E 测试 (04-16, 22 条, 77% 通过率) 覆盖有限，且主要是冒烟级别验证。本测试方案旨在：

全面覆盖 — 10 个子系统逐一验证，不留盲区
深度断言 — 不仅验证"能运行"，还验证"数据真实、逻辑正确、状态一致"
跨系统流通 — 验证数据在系统间的端到端流转，而非孤立功能点

1.2 先决条件

条件	状态
PostgreSQL 运行 + SaaS 后端 (8080 端口)	已就绪
Tauri 桌面端 (1420 端口)	已就绪
Admin V2 开发服务器 (5173 端口)	已就绪
至少一个 LLM Provider + 有余额的 API Key	已就绪

1.3 不覆盖范围

排除项	原因
Model Groups 7 个端点	前端无调用方
Account API Keys (/keys)	与 /tokens 重叠，疑似孤儿
A2A Multi-Agent 5 个命令	feature-gated 禁用
Webhook 系统	已 deprecated
负载/压力测试	非功能测试范畴

2. 测试架构

2.1 三层结构

Layer 0: 基础设施健康 (5 条)
  └─ DB 连接、SaaS 健康、Admin 加载、Tauri 窗口、LLM 可达性

Layer 1: 子系统垂直测试 (10 组 × 7-15 条 = 100 条)
  ├─ V1:  认证与安全       (12 条)
  ├─ V2:  聊天流与流式响应   (10 条)
  ├─ V3:  管家模式与行业路由  (10 条)
  ├─ V4:  记忆管道           (8 条)
  ├─ V5:  Hands 自主能力     (10 条)
  ├─ V6:  SaaS Relay 与 Token 池 (10 条)
  ├─ V7:  Admin 后台全页面    (15 条)
  ├─ V8:  模型配置与计费       (10 条)
  ├─ V9:  Pipeline 与工作流   (8 条)
  └─ V10: 技能系统            (7 条)

Layer 2: 跨系统横向验证 (4 角色 × 6 条 = 24 条)
  ├─ R1: 医院行政 — 日常使用全链路
  ├─ R2: IT 管理员 — 后台配置全链路
  ├─ R3: 开发者 — API + 工作流全链路
  └─ R4: 普通用户 — 注册→首次体验→持续使用

2.2 断言标准（深度验证）

每条链路的断言覆盖以下维度：

维度	验证内容
结构完整性	响应包含所有必填字段、字段类型正确
数据合理性	token 用量 > 0、时间戳在合理范围、ID 格式正确
状态一致性	创建后能查询到、删除后不存在、更新后值已变更
错误合理性	错误响应包含明确 message、HTTP 状态码正确、不泄露内部信息
跨系统流通	聊天后记忆被提取、计费记录增加、审计日志有记录

3. Layer 0: 基础设施健康检查 (5 条)

#	链路	验证方式	预期
L0-01	PostgreSQL 连接	`SELECT 1` via SaaS health	200 + `{"status": "ok"}`
L0-02	SaaS 后端健康	`GET /api/health`	200 + 服务信息
L0-03	Admin V2 加载	浏览器导航到 `localhost:5173`	页面标题含 "ZCLAW" + 无 JS 错误
L0-04	Tauri 桌面端运行	Chrome DevTools 连接 `localhost:1420`	页面可见 + 无白屏
L0-05	LLM Provider 可达	`GET /api/v1/relay/models`	返回至少 1 个可用模型

4. Layer 1: 子系统垂直测试

V1: 认证与安全 (12 条)

#	链路	深度验证点
V1-01	注册新用户	用户名/邮箱/密码校验规则生效；响应含 account_id(非空) + JWT(可解码) + refresh_token；GET /auth/me 返回 status=active + role=user + totp_enabled=false
V1-02	重复注册拒绝	相同用户名→409 + 明确 message；相同邮箱→409；用户名<3字符→400；密码<8字符→400
V1-03	登录获取 Token	响应含 access_token + refresh_token；JWT 解码后 sub=account_id, role 正确, pwv=1；HttpOnly cookie 设置正确
V1-04	错误密码锁定	连续 5 次错误密码→账户锁定 15 分钟；第 6 次尝试→423 + "账户已锁定"；正确密码在锁定期内也不可登录
V1-05	Token 刷新轮换	用 refresh_token 换新 token 对；旧 refresh_token 立即失效(二次使用→401)；新 token 的 jti 不同
V1-06	密码修改使旧 Token 失效	修改密码后 pwv 递增；旧 JWT 访问受保护端点→401；重新登录后正常
V1-07	登出撤销	登出后 refresh_token 失效；access_token 仍在有效期但 refresh 不可用
V1-08	TOTP 设置与验证	setup 返回 secret+QR；verify 成功后 totp_enabled=true；login 需额外 totp_code
V1-09	API Token CRUD	创建→返回明文 token(仅一次)；列表→hash 不含明文；用 token 调 API→成功；撤销→不可用
V1-10	权限中间件	user 角色访问 admin 端点→403；admin 角色→成功；无 token→401
V1-11	限流验证	登录接口 >5次/分钟→429；注册 >3次/小时→429；公共接口 >20次/分钟→429
V1-12	并发会话	同一账户多设备同时登录；各设备 token 独立有效；一处修改密码全部失效

V2: 聊天流与流式响应 (10 条)

#	链路	深度验证点
V2-01	KernelClient 流式聊天	发消息→收到 text_delta 事件流；最终消息完整(非截断)；token 统计 input>0, output>0；消息持久化到 IndexedDB
V2-02	SaaS Relay SSE 流式	走 Relay 路径→SSE 格式正确(data: [DONE])；Admin Usage 页可见新增 token 记录；GET /relay/tasks 返回对应任务记录
V2-03	模型切换后聊天	切换到不同模型→发送消息→验证响应确实来自新模型；模型字段正确
V2-04	流式取消	发消息→中途 cancelStream→收到已生成部分+取消标记；不产生完整 token 计费；session 状态恢复为 idle
V2-05	多轮对话上下文	连续 3 轮对话；第 3 轮能引用第 1 轮内容；上下文窗口不溢出
V2-06	错误恢复	模拟 401→自动 token 刷新→重试成功；模拟网络断开→优雅降级+重连
V2-07	thinking_delta 处理	模型返回 thinking 内容→前端正确展示折叠/展开；thinking 不计入 output token 统计
V2-08	tool_call 事件流	LLM 调用工具→收到 tool_call 事件→工具执行→tool_result 事件→最终回复包含工具结果
V2-09	Hand 触发事件流	触发 Hand→handStart 事件→handEnd 事件+结果；消息列表含 role=hand 消息
V2-10	消息持久化验证	发送 5 条消息→刷新页面→消息恢复完整(含时间戳、角色、内容)；IDB 中数据结构正确

V3: 管家模式与行业路由 (10 条)

#	链路	深度验证点
V3-01	关键词分类命中	发送医疗相关查询→ButlerRouter 分类为 healthcare；响应 system prompt 包含 `<butler-context>` XML 块
V3-02	行业关键词动态加载	Admin 创建自定义行业+关键词→Tauri 加载→查询命中该行业关键词→分类正确
V3-03	未命中默认行为	发送无关查询→无 `<butler-context>` 注入→正常对话流程不受影响
V3-04	多关键词饱和度	连续命中 3+关键词→饱和度达到 1.0→分类置信度最高
V3-05	痛点记录	用户表达痛点→butler_record_pain_point→痛点存入 SQLite→list 可查询
V3-06	方案生成	累积足够痛点→butler_generate_solution→返回结构化方案(标题+描述+步骤)
V3-07	简洁/专业模式切换	切换到简洁模式→UI 隐藏高级选项→对话风格变化(管家更主动)
V3-08	跨会话连续性	新会话→管家引用上次痛点→通过 Tauri 命令 `butler_list_pain_points` 查询痛点数据并验证正确
V3-09	冷启动体验	新用户首次聊天→管家自我介绍+引导→不出现空白或错误
V3-10	4 内置行业覆盖	分别用医疗/数据报告/政策合规/会议协调关键词查询→4 个行业各至少命中一次

V4: 记忆管道 (8 条)

#	链路	深度验证点
V4-01	对话后记忆提取	3 轮对话含明确偏好→对话结束后触发 extraction→SQLite 中有新记忆记录
V4-02	FTS5 全文检索	存入 3 条记忆(A="我喜欢 Python 编程", B="我偏好 Rust 开发", C="今天天气很好")→搜索"编程语言"→viking_find 返回 [A, B]；A/B 排在 C 之前
V4-03	TF-IDF 语义评分	存入多条不同主题记忆→查询特定主题→viking_find 返回按 TF-IDF 相似度排序；语义最相关的排在首位
V4-04	记忆注入系统提示	用户有偏好记忆→新对话→system prompt 中包含 `## 用户偏好` 段+记忆内容
V4-05	Token 预算约束	大量记忆→注入后不超过 500 token 预算；低分记忆被截断
V4-06	记忆去重	重复表达相同偏好→不产生重复记录；或旧记录更新而非新增
V4-07	Agent 级记忆隔离	Agent A 的记忆不出现在 Agent B 的上下文中；切换 Agent 后记忆正确加载
V4-08	记忆统计	memory_stats 返回正确的记忆总数/各类型计数/存储大小

V5: Hands 自主能力 (10 条)

#	链路	深度验证点
V5-01	Browser Hand 执行	触发 browser_hand→创建浏览器实例→导航到 URL→返回页面内容；hand_run_status 正确流转
V5-02	Researcher Hand	触发 researcher→返回研究报告结构(摘要+来源+建议)；执行时间合理
V5-03	Speech Hand + TTS	触发 speech→文本生成→浏览器 TTS 播放(检查 speechSynthesis.speak 调用)
V5-04	Quiz Hand	触发 quiz→返回题目结构(题干+选项+答案)；格式可解析
V5-05	Slideshow Hand	触发 slideshow→返回幻灯片数据(标题+内容+布局)
V5-06	Hand 审批流程	needs_approval 的 Hand→审批前状态=pending→approve 后执行→状态=completed
V5-07	Hand 并发限制	同一 Hand 并发触发超过 semaphore 限制→排队等待；不崩溃
V5-08	Hand 依赖检查	Clip Hand 无 FFmpeg→check_dependencies 返回缺失依赖→graceful 错误消息
V5-09	Hand 列表与注册	hand_list 返回 9 个启用的 Hand；每个含 name+description+tool_count
V5-10	Hand 审计日志	Hand 执行后→Admin 日志审计页可见对应记录(action=hand_execute, target=hand_name)

V6: SaaS Relay 与 Token 池 (10 条)

#	链路	深度验证点
V6-01	Relay 聊天完成	POST /relay/chat/completions→SSE 流返回；GET /relay/tasks 返回该任务且状态为 completed
V6-02	Token 池轮换	provider_keys 有多个 key→连续请求→RPM/TPM 跟踪正确→key 自动轮换
V6-03	Key 限流生效	单个 key 达到 RPM 限制→自动切换到下一个 key；所有 key 耗尽→返回 429
V6-04	Relay 任务列表	完成多次 relay→list_tasks 返回历史；分页正确；状态字段准确
V6-05	Relay 失败重试	使用 intentionally invalid API key 创建 provider→通过 relay 发送聊天→期望失败→使用有效 key 调用 retry 端点→验证成功
V6-06	可用模型列表	list_available_models 返回当前 key 池支持的模型；不含已禁用模型
V6-07	配额检查	用户配额已满→relay 请求→被 quota middleware 拦截→返回 429 + quota exceeded
V6-08	Key 创建/切换/删除	Admin CRUD provider_key→创建后可见→toggle 禁用→删除后不可用
V6-09	Usage 记录完整性	relay 请求→GET /usage 返回新增记录→account_id, model, input_tokens, output_tokens 全部正确
V6-10	Relay 超时处理	长时间请求→15s 超时→返回 timeout 错误(非 hang)

V7: Admin 后台全页面 (15 条)

#	链路	深度验证点
V7-01	Dashboard 统计数据	加载 Dashboard→stats 数值与 DB 一致(用户数/请求数/收入)；图表渲染完整
V7-02	账户管理 CRUD	列表→分页+搜索→创建账户→编辑角色/状态→状态切换(冻结/解冻)→DB 同步
V7-03	模型服务配置	列表 providers→添加 provider→配置 key→关联模型→切换回桌面端→模型可选
V7-04	计费套餐管理	查看 plans→切换用户订阅→GET /billing/subscriptions/:userId 返回更新后的订阅→用户下次登录新配额生效
V7-05	知识库管理	创建分类→添加知识条目→编辑→版本历史→搜索功能→返回匹配结果
V7-06	知识库分析	knowledge/analytics 返回 overview+trends+top_items+quality+gaps 各端点数据合理
V7-07	结构化数据源	上传 Excel→解析为 structured_rows→SQL 查询返回结果→删除后不可查
V7-08	Prompt 模板管理	创建 prompt→编辑→查看版本→回滚到旧版本→版本号正确
V7-09	角色权限矩阵	创建角色→配置权限→分配给用户→用户权限生效(可访问/不可访问的端点)
V7-10	行业配置管理	创建行业+关键词→配置 pain_seeds→关联到用户→用户查询命中该行业
V7-11	Agent 模板管理	创建模板→配置 soul/scenarios→分配给用户→用户端创建 Agent 基于→Agent 配置正确
V7-12	定时任务管理	创建 cron 任务→列表显示→下次执行时间计算正确→手动触发→结果记录
V7-13	Relay 监控	查看任务列表→按状态筛选→查看任务详情→包含完整的 input/output/error
V7-14	日志审计	操作日志列表→按时间/用户/操作类型筛选→日志详情含 IP+UA+变更详情
V7-15	Config 同步	修改配置→同步到桌面端→桌面端 configStore 更新→sync_logs 有记录

V8: 模型配置与计费 (10 条)

#	链路	深度验证点
V8-01	Provider CRUD	创建 provider→设置 base_url + api_key + rate_limits→列表可见→更新→删除
V8-02	模型 CRUD	创建模型→关联 provider→设置 max_tokens/temperature→列表可见→参数正确
V8-03	Key 池管理	Provider 下添加多个 key→各 key 独立 RPM/TPM 跟踪→禁用某 key→请求不再使用
V8-04	计费套餐定义	plans 列表含 Free/Pro/Team；每个 plan 含 features+limits JSON 结构完整
V8-05	订阅切换	用户从 Free→Pro→配额限制更新；Pro→Free→超出 Free 配额的请求被拒绝
V8-06	用量实时递增	每次聊天→GET /billing/usage 返回递增后的 used_tokens；数值与 GET /usage 统计一致
V8-07	支付流程	创建支付→返回支付链接→mock-pay 确认→支付状态变为 paid→订阅生效
V8-08	发票生成	支付完成后→GET /billing/invoices/:id/pdf 返回有效 PDF (Content-Type: application/pdf)
V8-09	模型白名单	Free plan 只能用指定模型→请求不在白名单的模型→被拒绝
V8-10	Token 配额耗尽	配额用完→后续请求→429 + 明确的 quota exceeded 信息→不扣除额外费用

V9: Pipeline 与工作流 (8 条)

#	链路	深度验证点
V9-01	Pipeline 模板列表	pipeline_templates 返回 17 个模板；每个含 name+description+steps；YAML 格式有效
V9-02	Pipeline 创建与执行	从模板创建 pipeline→执行→progress 事件流→result 包含各步骤输出
V9-03	Pipeline DAG 验证	创建含依赖的 pipeline→验证 DAG 无环→执行顺序正确(依赖先完成)
V9-04	Pipeline 取消	执行中 pipeline→cancel→已完成的步骤保留结果+未开始的不执行
V9-05	Pipeline 错误处理	某步骤失败→pipeline 状态=failed→错误信息含失败步骤名+原因
V9-06	工作流 CRUD	创建 workflow→编辑步骤→保存→列表可见→删除后不可见
V9-07	工作流执行	执行 workflow→各节点按序执行→最终输出正确→运行历史可查
V9-08	意图路由	发送自然语言描述→route_intent→匹配到正确的 pipeline 模板

V10: 技能系统 (7 条)

#	链路	深度验证点
V10-01	技能列表	skill_list 返回已加载技能；每个含 name+description+triggers；非空
V10-02	语义路由	发送匹配某技能 trigger 的查询→SkillIndex 中间件匹配→执行对应技能
V10-03	技能执行	skill_execute→返回结构化结果；执行时间合理；无 panic
V10-04	技能 CRUD	skill_create→列表可见→skill_update→字段更新→skill_delete→不可见
V10-05	技能刷新	添加新 SKILL.md→skill_refresh→列表增加；移除 SKILL.md→刷新后减少
V10-06	技能与聊天集成	聊天中触发技能→tool_call 事件→技能执行→结果注入对话
V10-07	技能按需加载	无技能配置时→SkillIndex 中间件不注册；有技能时→正常注册

5. Layer 2: 跨系统横向验证 (24 条)

设计原则：每个角色走完一条完整的端到端旅程，每一步的输出是下一步的输入。

R1: 医院行政 (日常使用全链路)

#	链路	跨系统验证点
R1-01	新用户注册→管家冷启动	注册→登录→首次打开桌面端→管家自我介绍+引导→无报错；saasStore 写入账户信息→connectionStore 选择连接模式→KernelClient 初始化
R1-02	医疗排班对话→管家路由→记忆	发"这周排班太乱了"→ButlerRouter 分类 healthcare→`<butler-context>` 注入→管家主动追问→痛点记录到 VikingStorage→SQLite 可查
R1-03	第二次对话→记忆注入+痛点回访	新会话→系统提示含 `## 用户偏好` 段(上次偏好)→管家主动问"排班问题解决了吗"→记忆提取闭环完成
R1-04	请求研究报告→Hand 触发→计费	发"帮我调研一下智能排班系统"→触发 Researcher Hand→Hand 执行返回结果→GET /usage 返回新增 token 记录→GET /billing/usage 返回递增配额
R1-05	管家生成方案→痛点闭环	累积痛点足够→butler_generate_solution→返回结构化方案→用户查看→butler_update_proposal_status(accepted)→痛点状态变为 addressed
R1-06	审计验证全旅程	Admin 审计日志页可见全旅程日志→上述所有操作均有记录(注册/登录/聊天/Hand 触发/方案生成)；日志含正确的时间戳+操作类型+目标

R2: IT 管理员 (后台配置全链路)

#	链路	跨系统验证点
R2-01	Admin 登录→Provider+Key 配置	Admin 登录→添加 Provider(DeepSeek)+API Key→GET /providers/:id/keys 返回新 key→key 的 RPM/TPM 初始值为 0
R2-02	配置模型→桌面端同步	创建模型(deepseek-v3)→关联 Provider→Admin 可见→切换到桌面端→模型列表含新模型→发起聊天→模型字段正确
R2-03	配额+计费联动	创建计费套餐→给用户分配→desktop 端 saasStore 更新订阅信息→用户发消息→quota 检查通过→聊天后 usage 递增→Admin 端 Usage 页数据同步
R2-04	知识库→行业→管家路由	Admin 创建行业"教育"+关键词+pain_seeds→关联到用户→触发 Tauri 命令 `viking_load_industry_keywords` 加载→用户发教育相关查询→ButlerRouter 命中自定义行业
R2-05	Agent 模板→用户端创建	Admin 创建 Agent 模板(含 soul+scenarios)→分配给用户→用户端 AgentTemplates 可见→创建 Agent→配置从模板加载→聊天使用新 Agent 人格
R2-06	定时任务→执行→审计	创建 cron 定时任务→等待触发(或手动触发)→GET /scheduler/tasks/:id 返回结果记录→操作日志有执行记录→状态流转 pending→running→completed

R3: 开发者 (API + 工作流全链路)

#	链路	跨系统验证点
R3-01	API Token 认证→Relay 调用	创建 API Token→用 token 调 POST /relay/chat/completions→SSE 响应正确→GET /relay/tasks 有记录→GET /usage 有 token 统计
R3-02	多模型切换→Token 池→用量	连续用 3 个不同模型调 Relay→key 池自动选择对应 Provider→usage 按模型分别记录→Admin Usage 页可按 model 分组查看
R3-03	Pipeline 创建→执行→结果	从模板创建 pipeline→执行→progress 实时推送→result 包含完整输出→pipeline_runs 历史可查
R3-04	技能触发→工具调用→结果	通过 API 触发技能→tool_call 执行→tool_result 返回→对话中包含工具输出
R3-05	浏览器 Hand→自动化流程	通过 API 触发 Browser Hand→执行导航+点击+提取→结果返回→审计日志记录
R3-06	API 限流+权限→错误处理	超出 RPM→429 + Retry-After header；用 user 角色 token 调 admin 端点→403；过期 token→401 + 明确 message

R4: 普通用户 (注册→首次体验→持续使用)

#	链路	跨系统验证点
R4-01	注册→邮箱验证→首次登录	注册→邮箱格式被验证→密码强度校验→注册成功→自动登录→JWT + refresh_token 存储→saasStore 初始化
R4-02	首次聊天→模型选择→流式体验	无历史对话→选择模型→发消息→流式响应→消息持久化到 IDB→关闭重开→消息恢复
R4-03	多轮对话→记忆积累→个性化	在 3 个独立对话会话中分别表达偏好(不模拟时间流逝)→每轮对话后记忆提取→第 4 个会话聊天→记忆检索返回至少 1 个先前偏好→系统提示含偏好段
R4-04	触发 Hand→审批→结果查看	需要审批的操作→Hand 状态 pending→用户审批→执行→结果展示→操作日志记录
R4-05	配额用尽→升级提示	Free 配额耗尽→聊天返回 429→UI 显示升级提示→引导到计费页→支付后继续使用
R4-06	安全设置→密码修改→TOTP	修改密码→旧 session 失效→重新登录→设置 TOTP→下次登录需要验证码→设备信任管理

6. 执行策略

6.1 执行顺序与依赖

Phase 0: 基础设施健康检查 (5 条)
  ↓ 全部 PASS 才继续
Phase 1: 垂直测试 — 无依赖组 (并行)
  ├─ V1 认证与安全
  ├─ V2 聊天流 (依赖 V1-03 登录)
  └─ V8 模型配置与计费 (依赖 V1-03 登录)
  ↓ 认证+聊天+模型 PASS 后
Phase 2: 垂直测试 — 依赖组 (并行)
  ├─ V3 管家模式 (依赖 V2 聊天)
  ├─ V4 记忆管道 (依赖 V2 聊天)
  ├─ V5 Hands (依赖 V2 聊天)
  ├─ V6 Relay+Token 池 (依赖 V2 + V8)
  ├─ V9 Pipeline (依赖 V2 聊天)
  └─ V10 技能系统 (依赖 V2 聊天)
  ↓ 所有垂直组完成 (允许 PARTIAL)
Phase 3: 横向验证 (顺序执行)
  ├─ R1 医院行政旅程
  ├─ R2 IT 管理员旅程
  ├─ R3 开发者旅程
  └─ R4 普通用户旅程

6.2 测试数据策略

策略	说明
隔离前缀	所有测试创建的数据加前缀 `e2e_test_`
测试账户	V1 阶段创建：`e2e_admin`, `e2e_user`, `e2e_dev`
幂等性	每条链路可独立重跑；检查"已存在则跳过"
清理策略	不自动删除数据（保留用于分析），标注为测试数据
时间锚点	记录测试开始时间戳，断言基于 `> 开始时间` 过滤

6.3 断言失败分级

级别	含义	处理
CRITICAL	系统核心功能不可用	立即停止当前 Phase，报告根因
HIGH	功能可用但数据不正确	标记失败，继续执行，汇总报告
MEDIUM	非关键字段缺失或格式不完美	记录警告，不阻断
LOW	UI 细节问题、性能轻微波动	记录观察，不影响判定

6.4 链路超时与重试

参数	值
单条链路超时	120 秒
LLM 响应等待超时	60 秒
页面加载超时	15 秒
截图等待	2 秒
失败重试	不重试（记录原始失败，保留现场）

7. 结果报告

7.1 单条链路结果格式

{
  "id": "V2-01",
  "name": "KernelClient 流式聊天",
  "phase": 1,
  "group": "V2",
  "status": "PASS | FAIL | SKIP | PARTIAL",
  "severity": "CRITICAL | HIGH | MEDIUM | LOW",
  "assertions": [
    {
      "point": "收到 text_delta 事件",
      "expected": ">0 events",
      "actual": "47 events",
      "result": "PASS"
    }
  ],
  "duration_ms": 4230,
  "evidence": {
    "screenshot": "path/to/screenshot.png",
    "api_response": "response snippet"
  },
  "error": null
}

7.2 汇总报告结构

指标	说明
总链路数	129 (5 + 100 + 24)
通过率	PASS / 总数 × 100%
各 Phase 通过率	Phase 0/1/2/3 分别统计
CRITICAL 失败数	需立即修复
Bug 清单	按 CRITICAL/HIGH/MEDIUM/LOW 分级
覆盖热力图	10 子系统 × 4 角色矩阵
SaaS API 覆盖率	已测试端点 / 总端点
Admin 页面覆盖率	已测试页面 / 总页面
Tauri 命令覆盖率	已测试命令 / 有前端调用的命令

8. 规模汇总

维度	数量
Layer 0 基础设施	5 条
Layer 1 垂直测试	100 条
Layer 2 横向验证	24 条
总计	129 条
子系统覆盖	10/10
跨系统角色覆盖	4/4
SaaS API 端点覆盖	~90/137
Admin 页面覆盖	14/17 (Login 由 V1 隐式覆盖, ApiKeys/Usage 待后续补充)
Tauri 命令覆盖	~60/104 (有前端调用的)
预估执行时间	~60 分钟

9. 前次 Bug 回归验证

以下为 04-16 E2E 报告中发现的 Bug，在本测试方案中的对应覆盖：

Bug ID	描述	对应测试链路	回归验证点
BUG-01	Agent 创建返回 HTTP 502	V7-11 (Agent 模板管理) + R2-05 (Agent 模板→用户端创建)	验证 Agent 创建返回 201 (非 502)；Agent 配置从模板正确加载
BUG-02	8 条历史消息显示"重试"按钮	V2-10 (消息持久化验证)	验证历史消息不包含"重试"伪影；刷新后消息状态正确恢复
BUG-03	Key Pool exhaustion — "所有 Key 均在冷却中"	V6-03 (Key 限流生效) + V6-02 (Token 池轮换)	验证所有 key 耗尽场景返回 429 + 明确 message；key 冷却后自动恢复

27 KiB Raw Blame History Unescape Escape

ZCLAW 全系统功能测试设计规格书

1. 背景与目标

1.1 为什么需要这次测试

1.2 先决条件

1.3 不覆盖范围

2. 测试架构

2.1 三层结构

2.2 断言标准（深度验证）

3. Layer 0: 基础设施健康检查 (5 条)

4. Layer 1: 子系统垂直测试

V1: 认证与安全 (12 条)

V2: 聊天流与流式响应 (10 条)

V3: 管家模式与行业路由 (10 条)

V4: 记忆管道 (8 条)

V5: Hands 自主能力 (10 条)

V6: SaaS Relay 与 Token 池 (10 条)

V7: Admin 后台全页面 (15 条)

V8: 模型配置与计费 (10 条)

V9: Pipeline 与工作流 (8 条)

V10: 技能系统 (7 条)

5. Layer 2: 跨系统横向验证 (24 条)

R1: 医院行政 (日常使用全链路)

R2: IT 管理员 (后台配置全链路)

R3: 开发者 (API + 工作流全链路)

R4: 普通用户 (注册→首次体验→持续使用)

6. 执行策略

6.1 执行顺序与依赖

6.2 测试数据策略

6.3 断言失败分级

6.4 链路超时与重试

7. 结果报告

7.1 单条链路结果格式

7.2 汇总报告结构

8. 规模汇总

9. 前次 Bug 回归验证

27 KiB

Raw Blame History