quality-gate-system

质量门禁系统 Skill V5 - 完整的CI/CD质量门禁检查系统 覆盖:代码/文档/配置的质量检查,支持自动化门禁判定

SKILL.md

GitHub

质量门禁系统 Skill V5.0.0

概述

质量门禁系统是一个完整的CI/CD质量检查框架,提供自动化的质量门禁判定能力。

核心能力:

  • 多维度质量检查(S2)
  • 自动化门禁判定(S1/S3)
  • CI/CD无缝集成(S4)
  • 标准一致性验证(S5)
  • 认知谦逊与局限标注(S6)
  • 对抗测试验证(S7)

S1: 输入标准化

1.1 被测对象定义

对象类型 描述 检查范围 示例
代码文件 源代码、脚本 语法、规范、测试覆盖 .py, .js, .go
配置文件 环境/部署配置 格式、完整性、安全性 .yaml, .json, .env
文档文件 技术/用户文档 完整性、准确性、一致性 .md, .rst
Skill文件 OpenClaw Skill 5标准合规性 SKILL.md, 脚本
提交记录 Git commit 规范、描述完整性 commit message

1.2 质量门禁标准

1.2.1 门禁维度与权重

维度 权重 描述 关键检查点
前置条件 15% 环境/依赖就绪 环境变量、依赖安装、权限检查
过程合规 25% 流程规范执行 代码规范、提交规范、构建流程
结果验收 40% 质量指标达标 测试通过、覆盖率、性能指标
文档完整 20% 配套文档齐全 变更说明、API文档、部署指南

1.2.2 门禁等级定义

gate_levels:
  critical:  # 发布前门禁
    min_score: 90
    block_on_fail: true
    dimensions: [前置条件, 过程合规, 结果验收, 文档完整]
    
  standard:  # 合并前门禁
    min_score: 75
    block_on_fail: true
    dimensions: [前置条件, 过程合规, 结果验收]
    
  basic:  # 提交前门禁
    min_score: 60
    block_on_fail: false
    dimensions: [过程合规]
    
  warning:  # 仅告警
    min_score: 50
    block_on_fail: false
    dimensions: [过程合规, 结果验收]

1.3 通过准则

等级 总分要求 单项最低 处理动作
PASS ≥90分 ≥70分 自动通过,进入下一环节
CONDITIONAL 75-89分 ≥60分 通过,附带改进建议
FAIL 60-74分 ≥50分 阻断,需修复后重试
BLOCK <60分 - 强制阻断,需人工评审

1.4 豁免规则

exemption_rules:
  hotfix:
    description: "紧急修复可降级通过"
    max_score_drop: 10
    requires_approval: [captain, director]
    audit_required: true
    
  docs_only:
    description: "纯文档变更简化检查"
    skip_dimensions: [结果验收]
    min_score: 70
    
  wip:
    description: "Work-in-Progress标记"
    block_on_fail: false
    requires_tag: "[WIP]"

S2: 门禁检查流程

2.1 检查流程图

┌─────────────────────────────────────────────────────────────────┐
│                        质量门禁检查流程                          │
└─────────────────────────────────────────────────────────────────┘

[开始] → [解析输入] → [识别对象类型] → [加载对应标准]
                              ↓
                    ┌─────────────────┐
                    │   四维度检查    │
                    └─────────────────┘
                              ↓
        ┌─────────────────────┼─────────────────────┐
        ↓                     ↓                     ↓
   [前置条件]            [过程合规]            [结果验收]
   - 环境检查            - 代码规范            - 单元测试
   - 依赖验证            - 提交规范            - 集成测试
   - 权限确认            - 安全扫描            - 性能测试
   - 配置验证            - 静态分析            - 覆盖率检查
        ↓                     ↓                     ↓
        └─────────────────────┼─────────────────────┘
                              ↓
                        [文档完整]
                        - 变更日志
                        - API文档
                        - 部署说明
                              ↓
                    [综合评分计算]
                              ↓
                    [通过/拒绝判定]
                              ↓
              ┌───────────────┴───────────────┐
              ↓                               ↓
          [通过]                          [拒绝]
              ↓                               ↓
        [生成通过报告]                  [生成修复清单]
        [允许继续流程]                  [阻断流程]

2.2 前置条件检查 (15%)

检查项 权重 通过标准 失败处理
环境变量 25% 必需变量已设置 报错并列出缺失
依赖安装 25% 所有依赖已安装 尝试自动安装
权限检查 25% 具有执行权限 报错提示
配置文件 25% 配置文件存在且有效 报错并给出模板
# 前置条件检查示例
def check_prerequisites():
    checks = {
        'env_vars': check_required_env(),
        'dependencies': check_dependencies(),
        'permissions': check_permissions(),
        'config': check_config_files()
    }
    return calculate_score(checks, weights={'env_vars': 0.25, ...})

2.3 过程合规检查 (25%)

检查项 权重 通过标准 工具
代码规范 30% 符合项目规范 pylint, eslint, gofmt
提交规范 20% 符合Conventional Commits commitlint
安全扫描 30% 无高危漏洞 bandit, safety, trivy
静态分析 20% 无严重问题 sonarqube, codeql
# 过程合规检查
def check_compliance():
    checks = {
        'code_style': run_linter(),
        'commit_msg': check_commit_message(),
        'security': run_security_scan(),
        'static_analysis': run_static_analysis()
    }
    return calculate_score(checks)

2.4 结果验收检查 (40%)

检查项 权重 通过标准 阈值
单元测试 30% 全部通过 100%通过
测试覆盖率 25% 覆盖率达到要求 ≥80%
集成测试 25% 全部通过 100%通过
性能测试 20% 性能指标达标 无回归>10%
# 结果验收检查
def check_results():
    checks = {
        'unit_tests': run_unit_tests(),
        'coverage': check_coverage(),
        'integration': run_integration_tests(),
        'performance': run_performance_tests()
    }
    return calculate_score(checks)

2.5 文档完整检查 (20%)

检查项 权重 通过标准 检查方式
变更说明 30% CHANGELOG已更新 文件变更检测
API文档 30% 公共API有文档 文档存在性检查
部署说明 20% 部署文档最新 版本匹配检查
README更新 20% README反映最新变更 关键信息检查
# 文档完整检查
def check_documentation():
    checks = {
        'changelog': check_changelog_updated(),
        'api_docs': check_api_documentation(),
        'deploy_docs': check_deployment_docs(),
        'readme': check_readme_updated()
    }
    return calculate_score(checks)

S3: 输出标准化

3.1 门禁报告格式

{
  "report_version": "5.0.0",
  "gate_id": "QG-20260321-001",
  "timestamp": "2026-03-21T19:38:00+08:00",
  "target": {
    "type": "commit",
    "ref": "abc123",
    "branch": "feature/new-api",
    "author": "developer@example.com"
  },
  "gate_config": {
    "level": "standard",
    "min_score": 75,
    "block_on_fail": true
  },
  "dimensions": {
    "prerequisites": {
      "score": 95,
      "weight": 0.15,
      "weighted_score": 14.25,
      "checks": [
        {"name": "env_vars", "passed": true, "score": 100, "details": "All required env vars set"},
        {"name": "dependencies", "passed": true, "score": 90, "details": "All deps installed"}
      ]
    },
    "compliance": {
      "score": 82,
      "weight": 0.25,
      "weighted_score": 20.5,
      "checks": [...]
    },
    "results": {
      "score": 88,
      "weight": 0.40,
      "weighted_score": 35.2,
      "checks": [...]
    },
    "documentation": {
      "score": 75,
      "weight": 0.20,
      "weighted_score": 15.0,
      "checks": [...]
    }
  },
  "summary": {
    "total_score": 84.95,
    "grade": "CONDITIONAL",
    "passed": true,
    "blocked": false
  },
  "findings": [...],
  "remediation": [...]
}

3.2 通过/拒绝判定

class GateDecision:
    """门禁判定逻辑"""
    
    def evaluate(self, report: GateReport) -> Decision:
        # 计算总分
        total_score = sum(
            dim.score * dim.weight 
            for dim in report.dimensions.values()
        )
        
        # 检查单项最低分
        min_dimension_score = min(
            dim.score for dim in report.dimensions.values()
        )
        
        # 判定等级
        if total_score >= 90 and min_dimension_score >= 70:
            grade = Grade.PASS
            blocked = False
        elif total_score >= 75 and min_dimension_score >= 60:
            grade = Grade.CONDITIONAL
            blocked = False
        elif total_score >= 60 and min_dimension_score >= 50:
            grade = Grade.FAIL
            blocked = report.gate_config.block_on_fail
        else:
            grade = Grade.BLOCK
            blocked = True
            
        return Decision(
            total_score=total_score,
            grade=grade,
            blocked=blocked,
            message=self._generate_message(grade)
        )

3.3 修复清单生成

当门禁未通过时,自动生成修复清单:

remediation_plan:
  gate_id: "QG-20260321-001"
  total_issues: 5
  critical: 1
  warning: 4
  
  tasks:
    - id: 1
      severity: critical
      dimension: results
      check: unit_tests
      issue: "3个单元测试失败"
      suggestion: "修复失败的测试用例"
      auto_fixable: false
      command: "pytest tests/ -v"
      
    - id: 2
      severity: warning
      dimension: compliance
      check: code_style
      issue: "代码格式不符合PEP8"
      suggestion: "运行自动格式化"
      auto_fixable: true
      command: "black . && isort ."
      
    - id: 3
      severity: warning
      dimension: documentation
      check: changelog
      issue: "CHANGELOG未更新"
      suggestion: "添加变更说明"
      auto_fixable: false
      template: "- [类型] 简短描述 (#PR号)"

3.4 输出格式支持

格式 用途 命令行选项
JSON 程序化消费 --format json
Markdown 人工阅读 --format md
JUnit XML CI集成 --format junit
HTML 报告展示 --format html
Console 终端输出 --format console

S4: CI/CD集成

4.1 集成模式

# GitHub Actions 集成示例
name: Quality Gate

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  pre-commit-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Pre-commit Gate
        run: |
          python3 -m quality_gate \
            --level basic \
            --target ${{ github.sha }} \
            --format junit \
            --output gate-report.xml
      
  merge-gate:
    runs-on: ubuntu-latest
    needs: pre-commit-gate
    steps:
      - uses: actions/checkout@v4
      - name: Run Merge Gate
        run: |
          python3 -m quality_gate \
            --level standard \
            --target ${{ github.sha }} \
            --block-on-fail \
            --notify slack
      
  release-gate:
    runs-on: ubuntu-latest
    if: startsWith(github.ref, 'refs/tags/v')
    steps:
      - uses: actions/checkout@v4
      - name: Run Release Gate
        run: |
          python3 -m quality_gate \
            --level critical \
            --target ${{ github.ref }} \
            --block-on-fail

4.2 Git Hooks集成

#!/bin/bash
# .git/hooks/pre-commit
# 提交前门禁检查

echo "🔍 Running pre-commit quality gate..."

python3 -m quality_gate \
    --level basic \
    --target staged \
    --quick \
    --format console

if [ $? -ne 0 ]; then
    echo "❌ Quality gate failed. Fix issues before committing."
    exit 1
fi

echo "✅ Quality gate passed!"
exit 0
#!/bin/bash
# .git/hooks/pre-push
# 推送前门禁检查

echo "🔍 Running pre-push quality gate..."

python3 -m quality_gate \
    --level standard \
    --target local \
    --format console

if [ $? -ne 0 ]; then
    echo "❌ Quality gate failed. Fix issues before pushing."
    exit 1
fi

echo "✅ Quality gate passed!"
exit 0

4.3 自动触发配置

{
  "triggers": [
    {
      "name": "pre-commit",
      "event": "git.pre-commit",
      "level": "basic",
      "blocking": false,
      "timeout": 60
    },
    {
      "name": "pre-push",
      "event": "git.pre-push",
      "level": "standard",
      "blocking": true,
      "timeout": 300
    },
    {
      "name": "pr-merge",
      "event": "github.pull_request",
      "level": "standard",
      "blocking": true,
      "timeout": 600
    },
    {
      "name": "release",
      "event": "github.release",
      "level": "critical",
      "blocking": true,
      "timeout": 900
    }
  ]
}

4.4 CI状态上报

# 向CI系统上报状态
class CIReporter:
    def report_github(self, decision: Decision):
        """上报到GitHub Status API"""
        status = "success" if not decision.blocked else "failure"
        data = {
            "state": status,
            "description": f"Quality Gate: {decision.grade.value}",
            "context": "quality-gate-system"
        }
        # POST to GitHub API
        
    def report_gitlab(self, decision: Decision):
        """上报到GitLab Pipeline"""
        # GitLab CI集成
        
    def report_jenkins(self, decision: Decision):
        """上报到Jenkins"""
        # Jenkins插件集成

S5: 标准一致性验证

5.1 标准版本控制

# config/standards.yaml
standards_version: "5.0.0"
last_updated: "2026-03-21"

dimensions:
  prerequisites:
    version: "1.0.0"
    checksum: "sha256:abc123..."
    
  compliance:
    version: "1.0.0"
    checksum: "sha256:def456..."
    
  results:
    version: "1.0.0"
    checksum: "sha256:ghi789..."
    
  documentation:
    version: "1.0.0"
    checksum: "sha256:jkl012..."

5.2 标准漂移检测

class StandardDriftDetector:
    """检测门禁标准是否发生非预期变更"""
    
    def detect_drift(self) -> DriftReport:
        drifts = []
        
        # 检查维度权重变更
        for dim_name, dim_config in self.current_standards.items():
            baseline = self.load_baseline(dim_name)
            if dim_config.weight != baseline.weight:
                drifts.append(Drift(
                    type="weight_change",
                    dimension=dim_name,
                    old=baseline.weight,
                    new=dim_config.weight
                ))
        
        # 检查检查项变更
        for check_name in self.get_all_checks():
            if not self.check_exists_in_baseline(check_name):
                drifts.append(Drift(
                    type="new_check",
                    check=check_name
                ))
        
        return DriftReport(drifts=drifts)

5.3 变更审批流程

[标准变更申请] → [影响评估] → [审批] → [实施] → [验证]
      ↓               ↓          ↓         ↓         ↓
   提交PR         分析影响     Director   更新配置   回归测试
   说明理由       通知干系人   审批        记录版本   验证一致性

5.4 一致性审计

# 定期审计门禁标准的一致性
def run_consistency_audit():
    audit = {
        "timestamp": datetime.now().isoformat(),
        "checks": {
            "standards_version_match": check_version_match(),
            "dimension_weights_valid": check_weights_sum_to_100(),
            "thresholds_consistent": check_threshold_consistency(),
            "configs_synced": check_config_synchronization(),
            "scripts_up_to_date": check_scripts_version()
        }
    }
    
    if not all(audit["checks"].values()):
        alert_audit_failure(audit)
    
    return audit

S6: 局限标注

6.1 系统局限性

局限类型 描述 影响范围 缓解措施
自动化局限 无法完全替代人工代码审查 复杂逻辑、架构设计 保留人工评审环节
上下文理解 无法理解业务逻辑正确性 业务规则验证 领域专家参与
工具依赖 依赖外部检查工具的准确性 工具误报/漏报 多工具交叉验证
性能约束 大规模项目检查耗时较长 大型代码库 增量检查、并行化
安全边界 无法检测所有安全漏洞 安全关键系统 结合专业安全扫描

6.2 置信度标注

class ConfidenceLevel(Enum):
    HIGH = "high"      # 自动化可准确判断
    MEDIUM = "medium"  # 建议人工复核
    LOW = "low"        # 必须人工确认

# 在报告中标注置信度
class CheckResult:
    def __init__(self):
        self.confidence: ConfidenceLevel
        self.automated: bool
        self.requires_human_review: bool

6.3 免责声明

disclaimer: |
  本质量门禁系统的检查结果仅供参考,不构成质量保证。
  
  已知局限:
  1. 无法保证业务逻辑的正确性
  2. 无法检测所有类型的缺陷
  3. 工具可能存在误报和漏报
  4. 不替代人工代码审查和测试
  
  建议:
  - 关键系统应结合人工评审
  - 定期评估门禁检查的有效性
  - 根据项目特点调整检查规则

6.4 不适用场景

场景 原因 建议替代方案
算法正确性验证 需要形式化证明 单元测试+数学证明
UI/UX质量评估 主观性强 用户测试+A/B测试
性能瓶颈定位 需要运行时分析 Profiling工具
架构合理性判断 需要领域知识 架构评审

S7: 对抗测试

7.1 测试策略

class AdversarialTestSuite:
    """对抗测试套件 - 验证门禁系统的有效性"""
    
    def run_all_tests(self) -> TestReport:
        return {
            "detection_rate": self.test_detection_rate(),
            "false_positive": self.test_false_positive(),
            "false_negative": self.test_false_negative(),
            "boundary": self.test_boundary_conditions()
        }

7.2 缺陷植入测试

# tests/adversarial/defect_injection.py

DEFECT_TEMPLATES = {
    "syntax_error": {
        "description": "植入语法错误",
        "injection": lambda code: code.replace("def ", "df "),
        "expected": "FAIL"
    },
    "security_vulnerability": {
        "description": "植入SQL注入漏洞",
        "injection": lambda code: code + '\nquery = f"SELECT * FROM users WHERE id = {user_id}"',
        "expected": "FAIL"
    },
    "missing_test": {
        "description": "删除测试覆盖",
        "injection": lambda files: [f for f in files if not f.endswith("_test.py")],
        "expected": "FAIL"
    },
    "broken_doc": {
        "description": "损坏文档链接",
        "injection": lambda md: md.replace("](http", "](broken_http"),
        "expected": "CONDITIONAL"
    }
}

def test_defect_detection():
    """测试门禁能否发现植入的缺陷"""
    for defect_type, template in DEFECT_TEMPLATES.items():
        # 植入缺陷
        modified = template["injection"](load_target())
        
        # 运行门禁
        result = run_quality_gate(modified)
        
        # 验证结果
        assert result.grade.value == template["expected"], \
            f"{defect_type}: expected {template['expected']}, got {result.grade.value}"

7.3 假阳性/假阴性分析

class FalseRateAnalyzer:
    """分析假阳性和假阴性率"""
    
    def analyze(self, historical_results: List[Result]):
        # 假阳性:实际合格但被拒绝
        false_positives = [
            r for r in historical_results 
            if r.decision.blocked and r.post_hoc_review == "ACCEPTABLE"
        ]
        
        # 假阴性:实际不合格但通过
        false_negatives = [
            r for r in historical_results 
            if not r.decision.blocked and r.post_hoc_review == "DEFECTIVE"
        ]
        
        return {
            "false_positive_rate": len(false_positives) / len(historical_results),
            "false_negative_rate": len(false_negatives) / len(historical_results),
            "false_positives": false_positives,
            "false_negatives": false_negatives,
            "recommendations": self.generate_recommendations(false_positives, false_negatives)
        }

7.4 边界条件测试

BOUNDARY_TESTS = [
    {
        "name": "exact_threshold",
        "description": "测试刚好在阈值边界的情况",
        "setup": lambda: set_score(74.99),  # 刚好低于75
        "expected": "CONDITIONAL"  # 根据配置可能为FAIL
    },
    {
        "name": "empty_content",
        "description": "测试空内容",
        "setup": lambda: "",
        "expected": "BLOCK"
    },
    {
        "name": "huge_content",
        "description": "测试超大内容",
        "setup": lambda: "x" * 100_000_000,
        "expected": "handled_gracefully"
    },
    {
        "name": "special_chars",
        "description": "测试特殊字符",
        "setup": lambda: "<script>alert('xss')</script>",
        "expected": "FAIL"
    }
]

7.5 定期对抗测试

# 对抗测试计划
adversarial_testing:
  schedule:
    frequency: weekly
    day: sunday
    time: "02:00"
  
  test_cases:
    - type: defect_injection
      count: 10
      categories: [syntax, security, logic, docs]
    
    - type: false_positive
      count: 5
      sources: [historical_appeals]
    
    - type: boundary
      count: 8
      scenarios: [threshold, empty, huge, special]
  
  acceptance_criteria:
    detection_rate: ">= 85%"
    false_positive_rate: "<= 10%"
    false_negative_rate: "<= 5%"

附录A: 脚本参考

A.1 门禁检查脚本

# 运行完整门禁检查
python3 scripts/quality-gate-check.py \
    --target ./src \
    --level standard \
    --format json \
    --output report.json

# 快速检查(提交前)
python3 scripts/quality-gate-check.py --quick

# 检查特定维度
python3 scripts/quality-gate-check.py --dimension compliance

A.2 CI钩子

钩子 安装位置 触发时机
pre-commit .git/hooks/ git commit前
pre-push .git/hooks/ git push前
github-action.yml .github/workflows/ PR/推送
gitlab-ci.yml 项目根目录 MR/流水线

A.3 报告生成

# 生成HTML报告
python3 scripts/generate-report.py \
    --input report.json \
    --format html \
    --output report.html

# 生成趋势分析
python3 scripts/generate-report.py --trend --days 30

附录B: 配置参考

B.1 完整配置示例

# config/quality-gate.yaml
version: "5.0.0"

# 门禁等级
gate_levels:
  basic:
    min_score: 60
    block_on_fail: false
    dimensions: [compliance]
    timeout: 60
    
  standard:
    min_score: 75
    block_on_fail: true
    dimensions: [prerequisites, compliance, results]
    timeout: 300
    
  critical:
    min_score: 90
    block_on_fail: true
    dimensions: [prerequisites, compliance, results, documentation]
    timeout: 600

# 维度权重
dimensions:
  prerequisites:
    weight: 0.15
    checks:
      env_vars: 0.25
      dependencies: 0.25
      permissions: 0.25
      config_files: 0.25
      
  compliance:
    weight: 0.25
    checks:
      code_style: 0.30
      commit_message: 0.20
      security_scan: 0.30
      static_analysis: 0.20
      
  results:
    weight: 0.40
    checks:
      unit_tests: 0.30
      coverage: 0.25
      integration_tests: 0.25
      performance: 0.20
      
  documentation:
    weight: 0.20
    checks:
      changelog: 0.30
      api_docs: 0.30
      deploy_docs: 0.20
      readme: 0.20

# 通知配置
notifications:
  slack:
    webhook: "${SLACK_WEBHOOK_URL}"
    on: [fail, block]
  email:
    to: ["team@example.com"]
    on: [block]

附录C: 版本历史

版本 日期 变更内容 作者
5.0.0 2026-03-21 完整7标准实现,CI/CD集成,对抗测试 Satisficing Institute
2.0.0 2026-03-21 5+2标准初版 Satisficing Institute
1.1.0 2026-03-19 增加CI/CD集成 Satisficing Institute
1.0.0 2026-03-20 五维检查初始版 Satisficing Institute

版本: v5.0.0
更新日期: 2026-03-21
作者: Satisficing Institute