# 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 操作
