# 贡献者成长体系工作流 — 端到端示例

**场景**：项目维护者希望量化每位贡献者的产出，按成长分划分段位，并对达到段位的成员自动颁发徽章致谢，形成"贡献 → 反馈 → 持续激励"的闭环。

## 前置条件

- `gitlink-cli` 已安装并登录（`gitlink-cli auth status`）
- 目标仓库已确认（示例使用 `z2_cc/gitlink-cli`）
- `jq` 已安装（用于 JSON 解析）

## 工作流步骤

### Step 1：贡献活动追踪（Phase 1）

```bash
# 1.1 贡献者代码统计（基线，含历史贡献者列表）
gitlink-cli repo +contributors-stat --owner z2_cc --repo gitlink-cli --format json

# 1.2 贡献者列表（识别首次贡献者的历史基线）
gitlink-cli repo +contributors --owner z2_cc --repo gitlink-cli --format json

# 1.3 近期提交（按 author.login 聚合 commits）
gitlink-cli commit +list --owner z2_cc --repo gitlink-cli --limit 100 --format json

# 1.4 已合并 PR（按 user.login 聚合 mergedPR）
gitlink-cli pr +list --owner z2_cc --repo gitlink-cli --state merged --limit 100 --format json

# 1.5 已关闭 Issue（按 assignee.login 聚合 closedIssue）
gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state closed --limit 100 --format json
```

**输出示例（聚合后的多维指标）：**
```json
{
  "contributors": [
    {"login": "alice", "commits": 25, "mergedPR": 8, "closedIssue": 4, "isFirstTime": false},
    {"login": "bob",   "commits": 6,  "mergedPR": 2, "closedIssue": 1, "isFirstTime": false},
    {"login": "carol", "commits": 3,  "mergedPR": 1, "closedIssue": 0, "isFirstTime": true}
  ]
}
```

### Step 2：成长分计算与段位划分（Phase 2）

**成长分公式：** `commits × 1 + mergedPR × 5 + closedIssue × 3 + (首次贡献者 ? +10 : 0)`

**计算演示：**
```
alice: 25×1 + 8×5 + 4×3 + 0  = 25 + 40 + 12 + 0  = 77  → 🌳 中坚
bob:    6×1 + 2×5 + 1×3 + 0  = 6  + 10 + 3  + 0  = 19  → 🌿 新星
carol:  3×1 + 1×5 + 0×3 + 10 = 3  + 5  + 0  + 10 = 18  → 🌿 新星（含新人加成）
```

**段位划分：**

| 成长分区间 | 段位 |
|-----------|------|
| 0 – 9 | 🌱 新芽 |
| 10 – 29 | 🌿 新星 |
| 30 – 79 | 🌳 中坚 |
| ≥ 80 | 🏆 核心 |

**Expected 断言：**
- alice（77）→ 🌳 中坚 ✅
- bob（19）→ 🌿 新星 ✅
- carol（18）→ 🌿 新星 ✅（首次贡献 +10 起关键作用）

### Step 3：自动颁发徽章（Phase 3，dry-run）

```bash
# 3.1 预先创建徽章标签（dry-run 模式）
DRY_RUN=true
echo "[DRY-RUN] 将创建标签: 🏆 核心贡献者 (#ff6b35)"
echo "[DRY-RUN] 将创建标签: 🌳 中坚贡献者 (#16a34a)"
echo "[DRY-RUN] 将创建标签: 🌿 新星贡献者 (#3b82f6)"
```

```bash
# 3.2 为 alice 颁发 🌳 中坚 徽章（dry-run）
echo "[DRY-RUN] 将为 @alice 颁发 🌳 中坚 徽章"
echo "[DRY-RUN] 将创建致谢 Issue: 🏅 致谢 @alice 达成 🌳 中坚 段位"
```

```bash
# 3.3 给首次贡献者 carol 发引导评论（dry-run）
echo "[DRY-RUN] 将为首次贡献者 @carol 发送 good-first-issue 引导评论"
```

**Expected：** alice、bob、carol 均进入颁奖清单；carol 进入新人引导清单；alice 是榜首。

### Step 4：实际执行（确认后切换）

```bash
# 切换到实际执行
DRY_RUN=false bash skills/gitlink-contributor-growth/scripts/contributor-growth-full.sh z2_cc gitlink-cli
```

实际执行将：
1. 通过 `label +create` 创建 🏆核心 / 🌳中坚 / 🌿新星 三类徽章标签
2. 通过 `issue +create` 为 alice 创建"🏅 致谢 @alice 达成 🌳 中坚 段位"致谢 Issue
3. 在合适 Issue 下通过 `issue +comment` 为 carol 发新人引导评论

## 完整命令速览

```bash
# Phase 1: 追踪
gitlink-cli repo +contributors-stat --owner z2_cc --repo gitlink-cli --format json
gitlink-cli repo +contributors      --owner z2_cc --repo gitlink-cli --format json
gitlink-cli commit +list --owner z2_cc --repo gitlink-cli --limit 100 --format json
gitlink-cli pr +list --owner z2_cc --repo gitlink-cli --state merged --limit 100 --format json
gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state closed --limit 100 --format json

# Phase 2: 排行（自动调 growth-analyze.js）
bash scripts/02-rank-and-tier.sh z2_cc gitlink-cli

# Phase 3: 颁奖
gitlink-cli label +create --owner z2_cc --repo gitlink-cli --name "🏆 核心贡献者" --color ff6b35
gitlink-cli issue +create -t "🏅 致谢 @alice 达成 🌳 中坚 段位" -b "<贡献统计正文>"
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number <id> --body "<引导评论>"
```

## 注意事项

- 所有写操作（`label +create` / `issue +create` / `issue +comment`）默认 dry-run
- API 未登录或无网络时，脚本优雅降级，用空数据填充，仍能产出报告
- 首次贡献者识别依赖 contributors 历史列表与近期贡献者对比
- 颁奖前可检查是否已存在同名致谢 Issue，避免重复颁奖
- 输出文件位于 `scripts/_output/`：`contribution-ranking.md` / `.json` / `contributor-growth-report.md` 及对应 HTML
