mirror of
https://github.com/xinnan-tech/xiaozhi-esp32-server.git
synced 2026-07-22 07:03:53 +08:00
118 lines
5.2 KiB
Markdown
118 lines
5.2 KiB
Markdown
# 质量门禁
|
||
|
||
## 1. 原则
|
||
|
||
自动测试负责证明“实现符合可观察的现有行为”；真实测试负责证明“设备、供应商和生产网络确实
|
||
按预期工作”。两类证据不得互相替代。
|
||
|
||
## 2. 测试层次
|
||
|
||
| 层次 | 目标 | 典型内容 | 运行时机 |
|
||
| --- | --- | --- | --- |
|
||
| 静态 | 快速发现格式、类型、依赖问题 | Ruff、Mypy、前端 lint/type、配置校验 | 每次提交 |
|
||
| 单元 | 验证纯逻辑与状态转换 | Token、协议解析、队列、配置版本、Provider DTO | 每次提交 |
|
||
| 特征/契约 | 冻结现有可观察行为 | 旧服务黄金报文、API envelope、设备帧、Provider 请求 | 每个 PR |
|
||
| 隔离集成 | 验证真实本地依赖 | MySQL、Redis、文件、jobs、Pub/Sub、事务 | 每个相关 PR |
|
||
| 模拟 E2E | 验证用户和设备流程 | manager-web、虚拟设备、Fake Provider、统一 gateway | 每个里程碑 |
|
||
| 差分 | 比较旧/新实现 | REST、OTA、WS 会话和副作用 | M1 起持续运行 |
|
||
| 非功能 | 容量和恢复 | 多连接、背压、断线、摘流、资源泄漏、安全 | M6/M7 |
|
||
| 真实环境 | 外部事实 | ESP32、云 Provider、MQTT/RAGFlow、目标部署 | M8 |
|
||
|
||
## 3. CI 分层
|
||
|
||
### Tier A：快速门禁
|
||
|
||
目标是在常规 PR 中快速反馈，建议控制在 10 分钟内：
|
||
|
||
- FastAPI Ruff、Mypy、unit/contract pytest。
|
||
- manager-web i18n、unit、snapshot。
|
||
- xiaozhi-server/迁移代码语法与导入检查。
|
||
- 路由、消费者和生成文档一致性。
|
||
- Secret 扫描和部署配置静态检查。
|
||
|
||
从 P01 建立覆盖率基线后，变更行覆盖率不得低于 85%，协议解析和会话状态机的分支覆盖率
|
||
不得低于 90%，全局覆盖率不得下降。覆盖率用于发现遗漏，不允许为了数字制造无行为价值的测试。
|
||
|
||
### Tier B：PR 集成门禁
|
||
|
||
- 隔离 MySQL/Redis。
|
||
- manager-web 生产构建及浏览器关键路径。
|
||
- 虚拟设备完整对话流程。
|
||
- Fake Provider 覆盖成功、超时、断流、取消和错误映射。
|
||
- API/realtime/jobs 镜像构建与 Compose readiness。
|
||
- 修改范围对应的旧/新差分。
|
||
|
||
### Tier C：里程碑门禁
|
||
|
||
- 全量旧/新差分。
|
||
- 多 realtime worker 配置广播。
|
||
- 并发连接和 60 分钟模拟 soak。
|
||
- 优雅摘流、进程终止、Redis/MySQL 短暂故障恢复。
|
||
- 依赖漏洞、鉴权边界和恶意输入测试。
|
||
- 支持架构的镜像构建或至少可重复的构建证明。
|
||
|
||
Tier C 不在每个小 PR 重复运行，以节约资源；相关核心代码变化或阶段收口时必须运行。
|
||
|
||
性能采用相同 runner 上的新旧实现相对比较。初始自动门槛为：
|
||
|
||
- Fake Provider 下业务错误率为 0。
|
||
- WebSocket 握手和控制消息 p95 回退不超过 15%。
|
||
- 可完成会话吞吐回退不超过 10%。
|
||
- 每个 realtime PR 运行 20 个虚拟连接、5 分钟；RC 运行 100 个虚拟连接、60 分钟。
|
||
- 测试结束后 RSS、线程、async task、文件描述符和临时文件不得持续线性增长。
|
||
|
||
这些指标只约束模拟回归，不代表真机容量结论；如固定测试机不足，PR 必须记录实际档位，不能
|
||
静默降低门槛。
|
||
|
||
## 4. 必须建立的协议场景
|
||
|
||
虚拟设备测试至少覆盖：
|
||
|
||
1. OTA 获取 WebSocket/MQTT 信息和未绑定激活码。
|
||
2. WebSocket header 与 query 参数两种握手。
|
||
3. hello、listen、abort、ping、iot、mcp、server 控制消息。
|
||
4. Opus 音频输入、ASR 文本、LLM 流、TTS 文本及音频输出。
|
||
5. 唤醒、连续对话、主动中断、无语音超时。
|
||
6. 设备绑定前后的行为。
|
||
7. Provider 超时、断流、无内容、限流和取消。
|
||
8. 客户端断线、服务摘流和重连。
|
||
9. MQTT gateway 16 字节桥接帧的编码与解码。
|
||
10. 配置更新只影响约定的当前或后续会话。
|
||
|
||
黄金数据必须脱敏、可提交且带版本说明。不能从一次偶然运行直接认定为规范；旧代码、文档和至少
|
||
一个调用方必须交叉确认。
|
||
|
||
## 5. PR 合并门禁
|
||
|
||
所有 PR：
|
||
|
||
- 计划工作包和文件所有权明确。
|
||
- 新行为有测试，重构行为有特征/差分证据。
|
||
- 相关 Tier A 全绿。
|
||
- 无未解释 skip、xfail、warning 激增或生成文件漂移。
|
||
- 文档和配置随行为同步。
|
||
- 回滚方法明确。
|
||
|
||
高风险 PR 额外要求：
|
||
|
||
- 设备协议：协议 Reviewer + 虚拟设备差分。
|
||
- 鉴权/密钥：Security Reviewer + 失败路径和密钥泄露检查。
|
||
- 数据迁移：全新库、已有库、重复执行和回滚测试。
|
||
- 并发/任务：取消、超时、资源关闭和故障注入。
|
||
- Provider 公共接口：所有能力族契约测试通过。
|
||
|
||
## 6. RC 自动化退出条件
|
||
|
||
只有满足以下全部条件，才能转入真实测试：
|
||
|
||
- 所有计划 PR P00-P12 已合并或明确取消并记录理由。
|
||
- 公开兼容边界全部关联到自动测试。
|
||
- 虚拟设备和 manager-web E2E 全绿。
|
||
- 所有 Provider 适配器通过 Fake/契约矩阵。
|
||
- 没有 P0/P1 内部缺陷；P2 风险有接受或后续方案。
|
||
- 统一发行物在干净环境完成安装、升级和回滚。
|
||
- 模拟负载下没有无界内存、线程、任务或文件增长。
|
||
- 未验证项逐条映射到真实环境交接用例。
|
||
|
||
满足这些条件代表“纯 Agent 阶段完成”，不代表真实 Provider 或硬件已经通过。
|