MR / PR 复杂度评分器

一个与平台无关的合并请求（GitLab MR）和拉取请求（GitHub PR）复杂度评分引擎。基于四维框架构建，精准刻画代码评审中“复杂”的真实含义——而不仅限于变更行数。

复杂度维度

输出等级： trivial / simple / moderate / complex / highly_complex

适用场景

• 在评审会议前，按复杂度对积压的开放 PR 进行优先级排序
• 标记高复杂度 MR，强制要求二次评审
• 为团队生成周度复杂度趋势报告
• 理解某 PR 耗时较长的**根本原因**（各维度分解）
• 构建工程总监看板（参见 score_mr.py）

快速开始

# 评分一个 GitHub PR（基础模式 —— 仅传入 PR 对象）
curl -s "https://api.github.com/repos/OWNER/REPO/pulls/NUMBER" 
     -H "Authorization: Bearer $GITHUB_TOKEN" 
     | python score_mr.py --provider github

# 评分一个 GitLab MR（含 diff 统计信息）
curl -s "https://gitlab.com/api/v4/projects/PROJECT_ID/merge_requests/IID?include_diff_stats=true" 
     -H "PRIVATE-TOKEN: $GITLAB_TOKEN" 
     | python score_mr.py --provider gitlab

# 更丰富的评分 —— 同时获取文件列表 + 评审记录
curl -s ".../pulls/NUMBER" > pr.json
curl -s ".../pulls/NUMBER/files" > files.json
curl -s ".../pulls/NUMBER/reviews" > reviews.json
python score_mr.py --provider github --pr pr.json --files files.json --reviews reviews.json

示例输出

{
  "provider": "github",
  "id": 412,
  "title": "Migrate auth service to OAuth2",
  "score": {
    "total": 74.2,
    "tier": "complex",
    "size": 68.0,
    "cognitive": 81.5,
    "review_effort": 72.0,
    "risk_impact": 60.0
  },
  "summary": "High mental load: 14 files across 6 directories, 3 reviewers involved",
  "tier_insight": "Needs careful review — high cognitive load and cross-module impact.",
  "stats": {
    "additions": 412,
    "deletions": 87,
    "files_changed": 14,
    "reviewers": 3,
    "discussions": 9,
    "net_lines": 325
  }
}

文件结构

mr-complexity-scorer/
  SKILL.md                      # 本文件
  mr_complexity_service.py      # 核心四维评分引擎（纯 Python 实现）
  score_mr.py                   # CLI 工具：接收 API 返回的 JSON 输入，输出复杂度 JSON
  requirements.txt              # 无外部依赖 —— 仅使用标准库，支持 Python 3.9+
  adapters/
    gitlab_adapter.py           # 将 GitLab MR API 字典映射为 MRData
    github_adapter.py           # 将 GitHub PR API 字典映射为 MRData

在自有代码中使用

from mr_complexity_service import MRComplexityCalculator, MRData
from adapters.github_adapter import github_pr_to_mrdata

# 从 GitHub PR 字典（来自 API 或 webhook payload）构建 MRData
mr_data = github_pr_to_mrdata(
    pr=pr_dict,
    files=files_list,       # 可选：/pulls/:number/files
    commits=commits_list,   # 可选：/pulls/:number/commits
    reviews=reviews_list,   # 可选：/pulls/:number/reviews
)

calculator = MRComplexityCalculator()
result = calculator.calculate(mr_data)

print(result.complexity_tier)   # "complex"
print(result.total_score)       # 74.2
print(result.human_summary)     # "High mental load: ..."

增强数据 —— 哪些 API 调用值得获取

即使不进行数据增强，评分器仍可正常工作——它会使用基础 PR 对象中的 changed_files、review_comments 和 requested_reviewers 字段。增强数据可显著提升评分准确性。

扩展至其他平台

只需实现一个轻量适配器，将目标平台的 MR/PR 字典映射为 MRData 类型即可：

from mr_complexity_service import MRData

def linear_issue_to_mrdata(issue: dict) -> MRData:
    return MRData(
        iid=issue["number"],
        title=issue["title"],
        # ... 映射其余字段
    )

已验证兼容：GitLab、GitHub、Gitea、Bitbucket、Azure DevOps —— 任何提供 MR/PR 元数据的平台均可支持。

调整权重配置

from mr_complexity_service import MRComplexityCalculator, ComplexityConfig

config = ComplexityConfig(
    weight_size=0.15,
    weight_cognitive=0.35,
    weight_review=0.30,
    weight_risk=0.20,
)
calculator = MRComplexityCalculator(config=config)