quality-gate-system

name	quality-gate-system
version	5.0.0
description	质量门禁系统 Skill V5 - 完整的CI/CD质量门禁检查系统 覆盖：代码/文档/配置的质量检查，支持自动化门禁判定
author	Satisficing Institute
tags	["quality","ci-cd","gate","automation","testing"]
requires	[{"model":"kimi-coding/k2p5"},{"local_tools":["python3","bash","git"]}]

质量门禁系统 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": "[e-mail]"
  },
  "gate_config": {
    "level": "standard",
    "min_score": 75,
    "block_on_fail": true
  },
  "dimensions": {
    "prerequisites": {
      "score": 
       
       
       
               
               
      
    
     
       
       
       
       ...
    
     
       
       
       
       ...
    
     
       
       
       
       ...
    
  
   
     
     
     
     
  
   ...
   ...

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未更新"
       
       
       

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')
    
        
          
         

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"
       
       
       
    
    
       
       
       
       
       
    
  

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)
        
        
         result.grade.value == template[], \
            

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:
       
       
       
       
      
  
     
    
       
       
       
       
      
  
     
    
       
       
       
       



  
     
     [, ]
  
     []
     []

---

附录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