Quality Gateways 技术评估
核心定位
openClaw Quality Gateways 是一套语言无关的六维质量门禁框架，专为包含后端 API、Web 前端及 CI/CD 流水线的典型应用项目设计。通过标准化的 .defs/quality-gateway-definition.json 配置文件，项目团队可定义并自动化执行跨技术栈的质量评估。
六大质量维度
1. 构建与依赖健康 (Build & Dependency Health)
- 核心指标：CI 管道状态、可复现构建、依赖新鲜度、许可证合规、SBOM 存在性
- 评分逻辑：布尔检查（PASS/FAIL）+ 过时依赖比例线性评分
- 阻断机制：许可证策略违规可配置为阻断项
2. 自动化测试与覆盖率 (Automated Testing & Coverage)
- 覆盖层级：单元测试 → 集成/API 测试 → E2E/冒烟测试
- 评分模型：测试通过率 + 代码覆盖率（目标值 100 分、警告区间 70-99、低于警告 0-69）
- 高级特性：关键路径覆盖率加权、 flaky 测试率监控
3. 安全与供应链 (Security & Supply-Chain)
- 零容忍项：密钥泄露检测（任何发现即 FAIL 阻断）
- 漏洞分级管控：Critical=0 强制阻断、High 配额制、Medium 预算制
- 扩展检查：SAST、容器镜像扫描、安全配置基线
4. 性能与效率 (Performance & Efficiency)
- API 指标：p95 延迟、错误率、吞吐量
- Web 指标：Core Web Vitals (LCP/CLS/INP)、资源包体积
- 评分曲线：目标区间内线性插值，超阈值硬失败
5. 可维护性与代码健康 (Maintainability & Code Health)
- 技术债务量化：静态分析问题密度、圈复杂度超标率、代码重复率
- 风险热点识别：高频变更 + 高复杂度文件的交叉分析
- 文档覆盖：公共 API 文档完整性检查
6. 发布就绪与可运维性 (Release Readiness & Operability)
- 可观测性三支柱：健康端点、结构化日志、指标看板
- 运维资产：告警配置、故障模式 runbook、版本变更日志
- 成熟度模型：0（缺失）/ 50（部分）/ 100（完整）阶梯评分
标准执行流程
| 步骤 | 动作 | 输出 |
|:---|:---|:---|
| 1 | 加载并校验 JSON 配置 | 有效配置对象 |
| 2 | 按检查项采集指标（CI 产物优先，本地回退） | 原始指标值 + 证据引用 |
| 3 | 单检查评分（0-100） | 标准化分数 |
| 4 | 网关加权汇总 + 状态判定 (PASS/WARN/FAIL) | 网关级结果 |
| 5 | 生成 Markdown + JSON 双格式报告 | 可阅读 + 可消费 |
显著优势
标准化与灵活性平衡
- 预置 6 大领域 30+ 典型检查项，降低启动门槛
- JSON 配置驱动所有阈值、权重、阻断策略，适配不同风险等级项目
工程友好设计
- 明确的证据收集规范（文件路径、CI 链接、工具输出）
- 未知指标处理策略：默认 WARN（70 分），安全类强制 FAIL
可扩展架构
- 检查项抽象为
metricType+scoringMethod组合，便于新增自定义检查 - 报告模板可覆盖，输出路径可配置
局限性与注意事项
工具链依赖
- 框架本身不提供扫描能力，需前置集成各类 SAST/DAST/SCA 工具
- 指标采集依赖 CI 产物或本地命令执行权限
配置复杂度
- 首次配置需理解 6 大网关 × 多检查项的权重博弈
- 建议从模板起步，渐进调优而非一次性完备配置
LLM 执行边界
- 文档强调"若指标无法测量，不得虚构数据"，实际落地时需确保数据管道可靠
- 大规模仓库的指标采集可能存在性能与存储开销
适用场景
| 场景 | 适配度 | 说明 |
|:---|:---|:---|
| 多技术栈统一质量度量 | ⭐⭐⭐⭐⭐ | 语言无关设计核心优势 |
| 发布门禁自动化 | ⭐⭐⭐⭐⭐ | 阻断机制 + 机器可读报告直接对接 CI/CD |
| 技术债务可视化 | ⭐⭐⭐⭐☆ | 历史趋势需额外数据存储 |
| 安全合规审计 | ⭐⭐⭐⭐☆ | 需配套工具链，框架本身不扫描 |
| 初创团队快速启动 | ⭐⭐⭐☆☆ | 配置 overhead 较高，建议成熟团队采用 |
潜在风险
- 配置漂移：JSON 配置与工具版本不同步可能导致评分失真
- 误报阻断：过于激进的阈值设置可能阻碍正常迭代
- 证据管理：
docs/quality/evidence/目录可能累积大量历史文件，需配套清理策略