质量门禁系统 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