gitpodium — 交互式贡献审计
你(AI 代理)将完整端到端地运行此流程。用户无需输入任何命令。
将设置过程设计为简短问答,确认计划,运行管道,交付报告,并且始终陈述免责声明。问题应分批提出(在 Claude Code 中使用 AskUserQuestion),不要逐行盘问。
GP 下文指代此技能所在的目录路径。每个步骤都会将产物写入用户指定的输出目录(GITPODIUM_OUT,默认为当前目录)。
步骤 0 — 前置条件(在提问之前完成)
gh auth status— 如果未认证,告诉用户运行gh auth login(在 Claude Code 中可输入! gh auth login)。所需的令牌权限:repo(私有仓库)和read:org(列出组织仓库)。继续前重新检查。- 确认
git、python3、bash、awk存在(macOS/Linux 上标准支持)。如果缺少gh或python3,则停止并报告。
仅当 gh auth status 显示绿色时才继续。
步骤 1 — 审计范围
询问用户:
- 哪些 GitHub 所有者? 一个或多个组织和/或用户(例如
acme-inc acme-labs)。用户自己的仓库也适用。可提供运行gh org list/gh repo list <owner> --limit 5来帮助确认正确名称。 - 扫描整个所有者还是只选一部分? 如果只想审计特定仓库,则收集一个
owner/repo列表,使用仓库文件代替扫描整个组织。 - 提醒:私有仓库仅当
gh令牌有权访问时才被包含。
映射为 clone 的参数,或使用 -f repos.txt 文件。
步骤 2 — 排名指标
询问:按哪个指标排名?(HTML 报告始终允许查看者实时切换;此处设定默认视图和口头报告的标题)
| 选项 | 含义 |
|---|---|
churn (默认) | 新增+删除的行数 — 最常见,表示“代码变动量” |
commits | 提交次数 — 活动/节奏,不易被大型重构操纵 |
added / deleted | 增长 vs. 清理 |
net | 新增 − 删除 |
repos | 涉及仓库数量(广度) |
映射为 GITPODIUM_METRIC=<选择>(传递给报告构建)。这将为 git churn 视图排序。报告还会附带一个协作标签页(下一段),其中包含自己的 GitHub 指标 — 无需二选一,两者都会构建。
同时收集:GitHub 协作数据(PR、审查、Issue)
除了 git 历史之外,gitpodium 还会通过 GitHub API(gitpodium github)拉取拉取请求、代码审查、审查评论和 Issue,放入第二个协作标签页,并按 GitHub 登录名作为键。这弥补了代码变动审计缺失的部分 — 一个审查很多但写代码很少的审查者现在终于能上榜了。在介绍报告时提及这一点。需要传达的注意事项:
- 需要
ghAPI,并且只覆盖令牌可见的 GitHub 托管仓库;受 GraphQL 速率限制。设置GITPODIUM_SKIP_GITHUB=1可跳过此步骤(适用于非 GitHub 仓库,或节省速率配额)。 - Issue 可能近乎为空,如果团队使用 Jira/Linear — 这正常,不是缺陷。
- 机器人(GraphQL
Bot类型的参与者、*[bot]、extra_bots)也会从审查者中排除。
步骤 3 — 时间窗口
询问:全量历史,还是指定日期范围? 对于控制台摘要,按月/季度/年分桶?HTML 报告始终包含所有历史,并带有实时时间筛选器;窗口主要影响控制台排行榜的呈现。
映射为 rank [FROM TO [month|quarter|year]]。
步骤 4 — 噪音过滤
解释默认值,让用户调整:
- 机器人(dependabot、CI、AI 代理)— 默认排除(
DROP_BOTS=1)。 - 批量/外部导入(框架导入、生成代码)— 任何单次提交超过
MAXCHURN=10000行或MAXFILES=400个文件将被丢弃,以防造成虚假领先者。如果需要,可提供“原始无过滤”模式(MAXCHURN=0 MAXFILES=0 DROP_BOTS=0)。
映射为环境变量 DROP_BOTS、MAXCHURN、MAXFILES。
步骤 5 — 输出
询问:报告放在哪里? 默认:当前目录 → ./report.html(一个自包含文件,无需服务器,可安全地通过邮件/Slack 发送)。设置 GITPODIUM_OUT。
步骤 6 — 确认计划,然后运行
回显一段摘要计划:所有者、指标、窗口、过滤条件、输出。确认后,导出所选环境变量并运行 — 对于大量仓库,可在后台运行克隆:
export GITPODIUM_OUT="<输出目录>" GITPODIUM_METRIC="<指标>" \
MAXCHURN=<n> MAXFILES=<n> DROP_BOTS=<0|1>
"$GP/bin/clone-all.sh" <所有者...> # 或: -f repos.txt (幂等;重新运行会更新)
"$GP/bin/build-mailmap.py" "$GITPODIUM_OUT/clones"
"$GP/bin/collect.sh" "$GITPODIUM_OUT/clones"
"$GP/bin/rollup.sh"
"$GP/bin/collect-github.py" <所有者...> # PRs/reviews/issues -> github.json (gh API; 跳过使用 GITPODIUM_SKIP_GITHUB=1)
"$GP/bin/build-report.py" # -> $GITPODIUM_OUT/report.html (嵌入两个数据集)
(等效一步:导出环境变量后运行 "$GP/gitpodium" run <所有者...> — run 包含 GitHub 步骤的尽力而为模式,因此即使 API 失败,git 报告仍会构建。)
步骤 7 — 审查身份合并(提供选项,不强制)
在 build-mailmap.py 运行后,它会打印合并了多少个身份,并写入 mailmap-review.md — 低置信度的猜测(一个名称是另一个的前缀)保持未合并状态。提供选项让用户查看。如果用户确认任何合并,将它们写入 gitpodium.identity.json(包含 force_merge / canonical_override / extra_bots — 参考 examples/gitpodium.identity.json),设置 GITPODIUM_IDENTITY 指向它,然后重新运行 build-mailmap.py → collect.sh → rollup.sh → build-report.py。
步骤 8 — 交付
- 告知用户
report.html的位置(他们可以在任意浏览器中打开)。 - 使用
"$GP/bin/report.sh"口头汇报前几名贡献者(遵循相同的窗口/过滤环境变量)。透明度行会显示有多少提交/代码变动因批量或机器人被丢弃 — 提及这一点,以免看起来有隐藏信息。 - 指出协作标签页(如果
github.json已构建):展示主要审查者和“churn-blind 审查者”数量 — 那些审查很多但提交 PR 很少的人,完全被 git 排行榜遗漏。这是有必要超越代码变动来看待的主要理由。 - 始终以免责声明结尾(不可协商):
代码动荡不等于贡献。代码审查、指导、设计和调试对 git 不可见;squash 合并/删除的分支无法恢复。协作标签页恢复了其中的一部分(审查、PR、Issue),但并非全部。这是一个对话的起点,而非排名或绩效指标。
快速参考(问答 ↔ 配置)
| 问答中的答案 | 配置方式 |
|---|---|
| 所有者 / 仓库 | clone-all.sh <所有者...> 或 -f repos.txt |
| 指标(git churn 视图) | `GITPODIUM_METRIC=churn |
| 协作(PR/审查/Issue) | collect-github.py <所有者...> → github.json · 跳过:GITPODIUM_SKIP_GITHUB=1 |
| 窗口 / 分桶 | `report.sh FROM TO [month |
| 机器人 / 批量过滤器 | DROP_BOTS MAXCHURN MAXFILES |
| 身份合并 | GITPODIUM_IDENTITY=gitpodium.identity.json |
| 输出目录 | GITPODIUM_OUT(克隆目录:GITPODIUM_CLONES) |