forked from Gitlink/gitlink-cli
246 lines
8.1 KiB
Markdown
246 lines
8.1 KiB
Markdown
# Workflow: Contributor Growth（贡献者成长体系）
|
||
|
||
> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||
> **AI Agent 工作流**：此工作流专为 AI Agent 设计，用于评估和激励团队贡献者。
|
||
|
||
AI Agent 自动收集贡献者数据，使用 AHP 权重模型计算贡献分数，生成排行榜和可视化报告，并可选择颁发 Badge。
|
||
|
||
## 工作流概述
|
||
|
||
Contributor Growth 工作流通过收集 Issue、PR、代码变更、评论等数据，使用 AHP（层次分析法）权重模型计算每个贡献者的综合分数，生成排行榜、HTML 报告和 Wiki 页面，并可自动颁发 Badge。
|
||
|
||
## 适用场景
|
||
|
||
- **贡献评估**：量化团队成员的贡献程度
|
||
- **排行榜生成**：生成贡献者排行榜
|
||
- **激励机制**：通过 Badge 颁发激励贡献者
|
||
- **团队协调**：了解团队成员的参与度
|
||
|
||
## 触发词
|
||
|
||
- "贡献者" / "contributor"
|
||
- "排行榜" / "leaderboard"
|
||
- "badge" / "徽章"
|
||
- "成长" / "growth"
|
||
- "评分" / "score"
|
||
|
||
## 参数
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--owner` | 否 | 仓库所有者（自动从 git remote 解析） |
|
||
| `--repo` | 否 | 仓库名称（自动从 git remote 解析） |
|
||
| `--sample` | 否 | 采样 PR 数量获取代码统计（默认 10） |
|
||
| `--award` | 否 | 自动创建 Badge 颁发 Issue |
|
||
|
||
## AHP 评分模型
|
||
|
||
| 维度 | 权重 | 数据来源 | 提取字段 |
|
||
|------|------|----------|----------|
|
||
| Issues Created | 15% | `issue +list` (open + closed) | `.data.issues[].author.login` 按作者统计 |
|
||
| PRs Merged | 25% | `pr +list state=merged` | `.data.issues[].author_login` 按作者统计 |
|
||
| Code Changes | 30% | `pr +files`（采样） | `.data.files[].addition` / `.deletion`（单数） |
|
||
| Issue Comments | 15% | `issue +list` 直接提取 | `.data.issues[].comment_journals_count` |
|
||
| Team Member | 15% | `repo +members` | `.data.members[].login` 判断是否成员 |
|
||
|
||
## Badge 等级
|
||
|
||
| Badge | 分数要求 | 说明 |
|
||
|-------|----------|------|
|
||
| Champion | >= 80 | 卓越贡献 |
|
||
| Core Contributor | >= 60 | 核心贡献者 |
|
||
| Active Contributor | >= 40 | 活跃贡献者 |
|
||
| Contributor | >= 20 | 贡献者 |
|
||
| Newcomer | < 20 | 新人 |
|
||
|
||
## 工作流步骤
|
||
|
||
### 步骤 1：收集数据
|
||
|
||
```bash
|
||
# Open Issues
|
||
gitlink-cli issue +list --owner {OWNER} --repo {REPO} --state open --limit 100 --format json
|
||
|
||
# Closed Issues
|
||
gitlink-cli issue +list --owner {OWNER} --repo {REPO} --state closed --limit 100 --format json
|
||
|
||
# Merged PRs
|
||
gitlink-cli pr +list --owner {OWNER} --repo {REPO} --state merged --limit 100 --format json
|
||
|
||
# 仓库成员
|
||
gitlink-cli repo +members --owner {OWNER} --repo {REPO} --limit 100 --format json
|
||
```
|
||
|
||
### 步骤 2：构建贡献者数据
|
||
|
||
遍历数据，为每个贡献者统计：
|
||
- Issues：创建的 Issue 数量
|
||
- Merged：合并的 PR 数量
|
||
- Additions/Deletions：代码变更行数（采样）
|
||
- Comments：评论数量（采样）
|
||
|
||
### 步骤 3：采样代码变更
|
||
|
||
对 merged PR 采样，获取代码变更统计：
|
||
|
||
```bash
|
||
# 获取 PR 变更文件
|
||
gitlink-cli pr +files --owner {OWNER} --repo {REPO} --id {PR_ID} --format json
|
||
```
|
||
|
||
提取字段：`.data.files[].addition`、`.data.files[].deletion`（**注意：是单数形式，不是 additions/deletions**）
|
||
|
||
**已知问题**：
|
||
- `pr +files` 输出的 JSON 在中文 Windows 下可能因编码问题导致解析失败（GBK vs UTF-8）
|
||
- 如果 Python 解析报错 `JSONDecodeError` 或 `UnicodeDecodeError`，需要指定 `encoding='utf-8'`
|
||
- 部分 PR 的 files API 可能返回异常，用 try/except 跳过即可
|
||
- 降级方案：用 PR 数量估算代码变更量（每个 PR 估 100 行）
|
||
|
||
### 步骤 4：采样评论数量
|
||
|
||
有两种方式获取评论数据：
|
||
|
||
**方式 A（推荐）**：直接从 `issue +list` 返回的数据中提取
|
||
- 字段：`.data.issues[].comment_journals_count`
|
||
- 无需额外 API 调用，效率更高
|
||
|
||
**方式 B**：逐个 Issue 采样
|
||
```bash
|
||
gitlink-cli issue +view --owner {OWNER} --repo {REPO} --number {ISSUE_ID} --format json
|
||
```
|
||
- 字段：`.data.comment_journals_count`
|
||
|
||
**补充**：PR 的评论数可从 `pr +list` 返回的 `.data.issues[].journals_count` 获取
|
||
|
||
### 步骤 5：计算 AHP 分数
|
||
|
||
```bash
|
||
# 归一化处理
|
||
NI = Issues / MaxIssues
|
||
NM = Merged / MaxMerged
|
||
NL = Lines / MaxLines
|
||
NC = Comments / MaxComments
|
||
MS = IsMember ? 1 : 0
|
||
|
||
# 加权求和
|
||
Score = NI * 15 + NM * 25 + NL * 30 + NC * 15 + MS * 15
|
||
```
|
||
|
||
### 步骤 6：生成排行榜
|
||
|
||
输出格式：
|
||
|
||
```
|
||
Rank Contributor Issues Merged +/- Lines Comments Score Badge
|
||
---- ------------------ ------ ------ --------- -------- ------ -------------
|
||
1 @contributor1 15 8 +1200/-300 45 82.5 Champion
|
||
2 @contributor2 10 12 +800/-200 30 68.2 Core Contributor
|
||
3 @contributor3 5 6 +400/-100 20 45.1 Active Contributor
|
||
```
|
||
|
||
### 步骤 7：生成 HTML 报告
|
||
|
||
HTML 报告包含：
|
||
- 汇总统计卡片
|
||
- ECharts 饼图（分数分布）
|
||
- 详细排行榜表格
|
||
- AHP 权重说明
|
||
|
||
### 步骤 8：发布到 Wiki
|
||
|
||
```bash
|
||
gitlink-cli wiki +create \
|
||
--owner {OWNER} \
|
||
--repo {REPO} \
|
||
--title "Contributor Leaderboard {DATE}" \
|
||
--content "{WIKI_CONTENT}"
|
||
```
|
||
|
||
Wiki 内容包含：
|
||
- 评分体系说明
|
||
- 排行榜表格
|
||
- 生成时间
|
||
|
||
### 步骤 9：颁发 Badge（可选）
|
||
|
||
如果指定了 `--award` 参数，为获奖者创建 Issue：
|
||
|
||
```bash
|
||
gitlink-cli issue +create \
|
||
--owner {OWNER} \
|
||
--repo {REPO} \
|
||
--title "Badge Award: {BADGE}" \
|
||
--body "{ISSUE_BODY}"
|
||
|
||
gitlink-cli issue +label-add \
|
||
--owner {OWNER} \
|
||
--repo {REPO} \
|
||
--number {ISSUE_ID} \
|
||
--labels badge
|
||
```
|
||
|
||
## 输出示例
|
||
|
||
### 控制台输出
|
||
|
||
```
|
||
====== Contributor Growth System: zzx-coder/gitlink-cli ======
|
||
|
||
[STEP] Collecting data...
|
||
[ OK] Issues(open:15 closed:30) PRs(merged:25) Members:8
|
||
|
||
[STEP] Building contributor profiles...
|
||
[STEP] Analyzing PR code changes (sampling 10)...
|
||
[STEP] Sampling issue comments...
|
||
|
||
[STEP] Calculating scores...
|
||
|
||
====== Contributor Rankings ======
|
||
|
||
Rank Contributor Issues Merged +/- Lines Comments Score Badge
|
||
---- ------------------ ------ ------ --------- -------- ------ -------------
|
||
1 @zzx-coder 12 8 +1500/-400 35 85.2 Champion
|
||
2 @contributor1 8 6 +800/-200 25 62.1 Core Contributor
|
||
3 @contributor2 5 4 +400/-100 15 42.3 Active Contributor
|
||
|
||
====== Generating HTML Report ======
|
||
[ OK] HTML report: contrib-report-zzx-coder-gitlink-cli.html
|
||
|
||
[STEP] Publishing to Wiki...
|
||
[ OK] Published to Wiki: Contributor Leaderboard 2026-07-02
|
||
|
||
====== Awarding Badges ======
|
||
[ OK] Badge issue created: #45 - Badge Award: Champion (1 recipients)
|
||
[ OK] Badge issue created: #46 - Badge Award: Core Contributor (1 recipients)
|
||
|
||
====== Complete ======
|
||
|
||
Contributors: 8
|
||
HTML Report: contrib-report-zzx-coder-gitlink-cli.html
|
||
Wiki: Contributor Leaderboard 2026-07-02
|
||
Badges: Awarded
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- 代码变更统计基于采样，不是全量数据
|
||
- Badge 颁发会创建 issue，需要确认权限
|
||
- HTML 报告使用 ECharts 需要网络连接
|
||
- 建议定期运行（如每月）跟踪贡献趋势
|
||
|
||
## 已知问题与解决方案
|
||
|
||
| 问题 | 原因 | 解决方案 |
|
||
|------|------|----------|
|
||
| Python `UnicodeDecodeError: 'gbk' codec` | 中文 Windows 默认 GBK 编码，gitlink-cli 输出 UTF-8 | `open(file, encoding='utf-8')` |
|
||
| `pr +files` JSON 解析失败 | 输出含特殊字符，GBK 解码破坏 UTF-8 序列 | 用 `encoding='utf-8'` 读取，或用 try/except 跳过 |
|
||
| `pr +files` 字段名为 `addition` 不是 `additions` | GitLink API 使用单数形式 | 用 `f.get('addition', f.get('additions', 0))` 兼容 |
|
||
| Issue 数据中 `comment_journals_count` 为 0 | 某些 Issue 确实没有评论 | 正常现象，不影响评分 |
|
||
|
||
## References
|
||
|
||
- [gitlink-issue](../../gitlink-issue/SKILL.md) — Issue 操作
|
||
- [gitlink-pr](../../gitlink-pr/SKILL.md) — PR 操作
|
||
- [gitlink-repo](../../gitlink-repo/SKILL.md) — 仓库操作
|
||
- [gitlink-wiki](../../gitlink-wiki/SKILL.md) — Wiki 操作
|