---
name: gitlink-contributor-growth
version: 1.0.0
description: "贡献者成长体系：贡献活动追踪 → 成长排行与段位 → 自动颁发徽章。串联 contributors-stat / commit / pr / issue 数据，多维加权计算成长分并自动颁奖。"
metadata:
  requires:
    bins: ["gitlink-cli", "jq"]
  cliHelp: "gitlink-cli repo +contributors --help / gitlink-cli issue +create --help / gitlink-cli label +create --help"
---

# gitlink-contributor-growth（贡献者成长体系）

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证、全局参数和 API 注意事项。
>
> **CRITICAL — 所有 GitLink 操作必须使用 `gitlink-cli`，禁止使用 `gh`（GitHub CLI）操作 GitLink 资源。**

## 说明

本 Skill 构建一套完整的贡献者成长激励体系，将分散的 PR / Issue / Commit 数据聚合为可量化的"成长分"，并按段位自动颁发徽章，形成"持续贡献 → 即时反馈"的闭环。

**三个阶段串联：**

1. **贡献活动追踪** — 采集仓库贡献者代码统计、贡献者列表、近期提交、已合并 PR、已关闭 Issue
2. **贡献排行 + 成长等级** — 多维加权计算成长分、排名、划分段位（🌱新芽 / 🌿新星 / 🌳中坚 / 🏆核心）
3. **自动颁发徽章** — 对达到段位的贡献者创建致谢 Issue 或在已有 Issue 下颁发徽章评论，给新人发 good-first-issue 引导

---

## 三阶段工作流总览

```mermaid
flowchart LR
    A[周期触发 / 手动] --> B[Phase 1: 贡献追踪]
    B --> C[Phase 2: 排行与段位]
    C --> D[Phase 3: 颁发徽章]

    subgraph B[Phase 1: 贡献追踪]
        B1[contributors-stat 代码统计] --> B2[commit 近期提交]
        B2 --> B3[merged PR 列表]
        B3 --> B4[closed Issue 列表]
        B4 --> B5[按 login 聚合指标]
    end

    subgraph C[Phase 2: 排行与段位]
        C1[计算成长分] --> C2[排名排序]
        C2 --> C3[划分成长段位]
        C3 --> C4[输出排行报告]
    end

    subgraph D[Phase 3: 颁发徽章]
        D1[识别首次贡献者] --> D2[达段位者颁奖]
        D2 --> D3[good-first-issue 引导]
        D3 --> D4[创建致谢 Issue / 评论]
    end
```

---

## 成长分与段位模型

### 成长分计算公式

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

| 维度 | 权重 | 数据来源 | 说明 |
|------|------|----------|------|
| 提交数 (commits) | ×1 | `commit +list --limit 100` | 近期代码贡献基础分 |
| 合并 PR 数 | ×5 | `pr +list --state merged` | 协作产出，权重最高 |
| 关闭 Issue 数 | ×3 | `issue +list --state closed` | 协助社区/参与讨论 |
| 首次贡献奖励 | +10 | 对比 contributors 历史列表 | 鼓励新成员加入 |

### 成长段位

| 成长分区间 | 段位 | 徽章 | 含义 |
|-----------|------|------|------|
| 0 – 9 | 🌱 新芽 | — | 刚起步的新贡献者 |
| 10 – 29 | 🌿 新星 | 🌿 | 持续活跃的潜力成员 |
| 30 – 79 | 🌳 中坚 | 🌳 | 团队核心生产力 |
| ≥ 80 | 🏆 核心 | 🏆 | 不可或缺的项目骨干 |

### 段位进度条

报告中用 ASCII 进度条展示当前段位距下一段位还差多少分，例如：

```
🌿 新星 (23/29)  ████████░░░  距 🌳 中坚 还差 6 分
```

---

## Phase 1：贡献活动追踪

### 步骤

```bash
# 1. 贡献者代码统计（contributions / additions / deletions）
gitlink-cli repo +contributors-stat --owner <owner> --repo <repo> --format json

# 2. 贡献者列表（用于识别"首次贡献者"——历史列表中是否包含当前 login）
gitlink-cli repo +contributors --owner <owner> --repo <repo> --format json

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

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

# 5. 已关闭 Issue（按 assignee 或参与者 login 聚合 closedIssue 数）
gitlink-cli issue +list --owner <owner> --repo <repo> --state closed --limit 100 --format json
```

聚合规则（按 `login`）：
- **commits** = commit list 中 author.login 出现次数
- **mergedPR** = merged PR 列表中 user.login 出现次数
- **closedIssue** = closed Issue 中 assignee.login（或参与者）出现次数
- **isFirstTime** = 当前贡献者不在 contributors 历史列表中

---

## Phase 2：贡献排行与成长等级

### 计算流程

```
输入：每个贡献者的 { commits, mergedPR, closedIssue, isFirstTime }

计算：
  score = commits × 1 + mergedPR × 5 + closedIssue × 3 + (isFirstTime ? 10 : 0)

排名：按 score 降序

段位映射：
  score >= 80 → 🏆 核心
  score >= 30 → 🌳 中坚
  score >= 10 → 🌿 新星
  else        → 🌱 新芽
```

### 输出

- `contribution-ranking.md` — 排行榜表格（排名|贡献者|提交|合并PR|关闭Issue|成长分|段位|进度条）
- `contributor-growth-report.md` — 成长报告（含社区活跃度综合评分 /10、段位分布、新人识别、颁奖建议）

---

## Phase 3：自动颁发徽章

### 颁奖规则

| 触发条件 | 动作 | 命令 |
|---------|------|------|
| 新人首次贡献 | good-first-issue 引导评论 | `issue +comment` |
| 达到 🌿 新星 | 致谢 Issue + 🌿 徽章标签 | `issue +create` / `label +create` |
| 达到 🌳 中坚 | 致谢 Issue + 🌳 徽章标签 | `issue +create` |
| 达到 🏆 核心 | 致谢 Issue + 🏆 徽章标签 | `issue +create` |

### 步骤

```bash
# 1. 预先创建徽章标签（dry-run 优先）
gitlink-cli label +create --owner <owner> --repo <repo> --name "🏆 核心贡献者" --color ff6b35

# 2. 为达段位者创建致谢 Issue
gitlink-cli issue +create -t "🏅 致谢 @<user> 达成 <段位> 段位" \
  -b "感谢 @<user> 在本周期内的贡献：提交 X / 合并 PR Y / 关闭 Issue Z，成长分 W，晋升 <段位>。" \
  --label <label_id>

# 3. 在已有 Issue 下颁发徽章评论（针对解决 Issue 的贡献者）
gitlink-cli issue +comment --owner <owner> --repo <repo> --number <id> \
  --body "🏅 感谢 @<user> 关闭本 Issue，达成 <段位> 段位！"

# 4. 给 good-first-issue 新人发引导评论
gitlink-cli issue +comment --owner <owner> --repo <repo> --number <id> \
  --body "👋 欢迎新贡献者 @<user>！这是你的首次提交，可参考 good-first-issue 列表继续参与。"
```

**所有写操作默认 dry-run**，确认后通过 `DRY_RUN=false` 切换。

---

## 可复现脚本

本 Skill 提供可直接执行的 Bash 脚本，位于 `scripts/` 目录：

| 脚本 | 功能 | 使用方式 |
|------|------|----------|
| `01-track-activity.sh` | Phase 1 贡献活动追踪 | `bash 01-track-activity.sh <owner> <repo>` |
| `02-rank-and-tier.sh` | Phase 2 排行与段位 | `bash 02-rank-and-tier.sh <owner> <repo>` |
| `03-award-badges.sh` | Phase 3 颁发徽章 | `bash 03-award-badges.sh <owner> <repo>` |
| `growth-analyze.js` | 核心引擎（成长分 / 段位 / 报告） | `node growth-analyze.js <output_dir>` |
| `contributor-growth-full.sh` | 全流程串联 | `bash contributor-growth-full.sh <owner> <repo>` |

**所有脚本默认 dry-run 模式**（不会实际修改数据），确认无误后通过环境变量切换：

```bash
# Dry-run（默认，安全）
DRY_RUN=true bash scripts/contributor-growth-full.sh z2_cc gitlink-cli

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

---

## 注意事项

1. **dry-run 优先**：所有写操作（`issue +create`、`issue +comment`、`label +create`）默认不实际执行
2. **Token 有效**：运行前确认 `gitlink-cli auth status` 返回正常
3. **优雅降级**：API 未登录或无网络时，脚本必须用 `2>&1 || echo "[WARN]"` 兜底，保证离线也能产出报告（用空数据填充）
4. **首次贡献者识别**：依赖 contributors 历史列表与近期贡献者对比，列表为空时所有近期贡献者均视为首次
5. **避免重复颁奖**：颁奖前可检查是否已存在同名致谢 Issue（标题包含 `@<user>`）
6. **输出文件**：所有 JSON / MD / HTML 报告保存到 `scripts/_output/` 目录供审计
