---
name: gitlink-contributor-insight
version: 1.1.0
description: "贡献者活跃度分析：分析仓库贡献者的活跃度、贡献趋势和工作节奏，生成贡献者洞察报告。当用户需要分析贡献者活跃度、查看团队贡献趋势、评估成员参与度时触发。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli user --help"
---

# gitlink-contributor-insight（贡献者活跃度分析）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 本 Skill 为只读操作，不会修改任何仓库。无需用户额外确认即可执行。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。

---

## ⚠️ 命令可用性声明

gitlink-cli 的命令集在持续演进中。以下命令**当前版本可能不可用**，执行前先验证：

| 命令 | 状态 | 替代方案 |
|------|------|----------|
| `repo +contributors` | ❌ 不可用 | 从 `pr +list` 提取 `author_login` + `repo +info` 获取 `contributor_users_count` |
| `user +heatmap` | ❌ 不可用 | 从 PR 时间戳手动推算活跃天数 |
| `user +stats` | ❌ 不可用 | 从 `pr +list` 统计 PR 数；Issue 数通过 `issue +list` 获取 |
| `user +trends` | ❌ 不可用 | 从 PR 时间分布手动判断趋势（上升/平稳/下降） |
| `repo +info` | ✅ 可用 | — |
| `pr +list` | ✅ 可用 | — |
| `user +info` | ✅ 可用 | — |
| `issue +list` | ✅ 可用 | — |

> **核心原则**：优先使用可用的 Shortcut 命令。当所需命令不可用时，从 `pr +list` 和 `user +info` 中提取等效数据，并在报告中标注"数据来源：PR 列表（命令 X 不可用）"。

---

## 功能概述

面向开源社区管理者和维护者的贡献者分析工具：

1. **项目概览** — 获取仓库贡献者规模和基本信息
2. **贡献数据分析** — 通过 `pr +list` 提取每位贡献者的 PR 数量和时间分布
3. **用户画像** — 通过 `user +info` 了解贡献者背景
4. **趋势判断** — 从 PR 时间序列推断贡献趋势
5. **洞察报告** — 生成贡献者活跃度排名和团队健康度评估

---

## 工作流：贡献者分析全流程

### Step 1：获取仓库基本信息

```bash
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
```

提取：`contributor_users_count`、`full_name`、`description`、`default_branch`、`fork_info`（如为 Fork 项目）。

### Step 2：获取贡献者列表（通过 PR 数据）

由于 `repo +contributors` 不可用，改用两步获取贡献者：

```bash
# 2a. 获取所有 PR（含已合并和已关闭）
gitlink-cli pr +list --owner <owner> --repo <repo> --format json

# 2b. 如果 Issue 数据也需要
gitlink-cli issue +list --owner <owner> --repo <repo> --format json
```

从 `pr +list` 返回数据中：
- 提取所有唯一的 `author_login` 作为实际代码贡献者
- 统计每位作者的 PR 数（`pull_request_status`: 0=open, 1=merged, 2=closed）
- 记录每个 PR 的 `pr_full_time` 用于时间分析
- 记录每个 PR 的 `journals_count`（评论/审核活动数）

从 `issue +list` 返回数据中：
- 提取所有唯一的 `author_login` 作为 Issue 参与者
- 统计每位作者的 Issue 数

> 如果 PR 数量较多（>50），按 `author_login` 聚合后取 PR 数前 10 的贡献者分析，报告中注明"基于 Top 10 分析"。

### Step 3：逐位贡献者深度分析

对每位贡献者执行：

```bash
# 用户基本信息
gitlink-cli user +info --login <username> --format json
```

从 `user +info` 提取：`login`、`name`、`created_time`（注册时间）、`user_projects_count`、`user_org_count`、`user_identity`。

**如果 `user +heatmap/+stats/+trends` 可用**（未来版本），补充执行。当前版本用以下替代方案：

| 维度 | 替代数据源 | 分析要点 |
|------|----------|----------|
| 贡献频率 | PR 时间戳列表 | 统计活跃天数、相邻 PR 间隔、判断"持续贡献者"还是"间歇参与者" |
| 贡献产出 | `pr +list` 聚合 | PR 数、Issue 数，区分"代码贡献者"和"问题反馈者" |
| 活跃趋势 | PR 按日/周聚合 | 贡献量上升/稳定/下降，识别"上升期贡献者"和"逐渐淡出者" |

> ⚠️ **控制 API 调用**：贡献者 >15 人时，仅分析 PR 数最高的前 10 位。每人 1 次 `user +info` 调用（共 ≤10 次），PR 数据已在 Step 2 全量获取。

### Step 4：贡献者分级与分类

#### 4.1 活跃度分级

| 级别 | 判定标准 |
|------|----------|
| 🔥 **核心贡献者** | 最近 30 天有贡献 + 总贡献 PR ≥ 5（或总贡献 PR > 10） |
| 🌟 **活跃贡献者** | 最近 60 天有贡献 + 总贡献 ≥ 3 |
| 🌱 **新兴贡献者** | 最近 90 天首次出现 + 贡献频率上升 |
| 💤 **休眠贡献者** | 最近 90 天无贡献 + 历史有贡献 |

> **年轻项目特殊处理**：项目历史 < 30 天时，放宽标准——所有活跃贡献者均可标记为核心贡献者，报告中注明"项目处于早期阶段，分级标准已放宽"。

#### 4.2 贡献类型分类

| 类型 | 判定 |
|------|------|
| **代码贡献者** | PR 数量 > Issue 数量 |
| **问题反馈者** | Issue 数量 > PR 数量 |
| **全能贡献者** | PR 和 Issue 数量均衡（差异 ≤ 1） |

### Step 5：生成贡献者洞察报告

按下方输出模板生成报告，并根据数据可用性灵活调整章节。

---

## 输出模板

```markdown
# 👥 贡献者洞察报告：{{仓库名}}

> 分析时间：{{当前时间}}
> 仓库：{{full_name}}
> 总贡献者：{{contributor_users_count}} 人，本次分析：{{analyzed_count}} 人

---

## 一、团队概览

| 指标 | 数值 |
|------|------|
| 总贡献者 | {{contributor_users_count}} |
| 核心贡献者 | {{core_count}} |
| 活跃贡献者 | {{active_count}} |
| 新兴贡献者 | {{new_count}} |
| 休眠贡献者 | {{dormant_count}} |
| 近 30 天活跃率 | {{active_30d_rate}}% |

---

## 二、贡献者活跃度排行榜

| 排名 | 贡献者 | 级别 | 类型 | 活跃天数 | 总PR | 总Issue | 趋势 |
|------|--------|------|------|---------|------|---------|------|
| 1 | {{login}} | 🔥 | 代码 | {{d}} 天 | {{pr_count}} | {{issue_count}} | ↑ |
| ... | ... | ... | ... | ... | ... | ... | ... |

---

## 三、重点贡献者分析

> 仅展示核心/活跃贡献者。

### 🔥 {{login}}（核心贡献者）

| 维度 | 数据 | 说明 |
|------|------|------|
| 活跃天数 | {{d}} 天 | {{评价}} |
| 总 PR 数 | {{pr_count}} | |
| 总 Issue 数 | {{issue_count}} | |
| 贡献趋势 | {{trend_direction}} | {{trend_comment}} |

**PR 贡献明细**：（可选，数据充足时展示）

| PR# | 标题 | 日期 | 类型 |
|-----|------|------|------|
| ... | ... | ... | feat/fix/refactor |

---

## 四、团队健康度评估

### 健康度指标

| 指标 | 状态 | 说明 |
|------|------|------|
| 核心贡献者占比 | {{core_ratio}}% | {{core_comment}} |
| 新老比例 | {{new_old_ratio}} | {{new_old_comment}} |
| 贡献频率稳定性 | {{stability}} | {{stability_comment}} |
| 知识分散度 | {{bus_factor}} | {{bus_factor_comment}} |

### 风险提示

- ⚠️ **核心贡献者不足**（当 core_count < 3 时）：仅 {{core_count}} 位核心贡献者，存在单点依赖风险（Bus Factor = {{core_count}}）。
- ⚠️ **贡献者流失**（当 dormant_rate > 50% 时）：超过一半的贡献者已不活跃，需要关注社区留存。
- ⚠️ **缺少新鲜血液**（当 new_count == 0 时）：近期无新兴贡献者，建议通过 Good First Issue 等方式吸引新人。
- ℹ️ **项目处于早期阶段**（当项目历史 < 30 天时）：贡献者分级标准已放宽，以上风险置信度有限。
- ✅ **团队健康**（当以上情况均不满足时）：贡献者结构合理，团队运转良好。

---

## 五、社区建设建议

1. **激励核心贡献者**：{{核心贡献者维护建议}}
2. **激活休眠贡献者**：{{休眠贡献者召回建议}}
3. **吸引新贡献者**：{{新贡献者吸引建议}}
4. **平衡贡献类型**：{{贡献类型平衡建议}}

---

## 📋 数据来源与局限性

| 数据维度 | 来源 | 可靠性 |
|----------|------|--------|
| 贡献者数量 | `repo +info` | ✅ 可靠 |
| PR 贡献数据 | `pr +list` 全量 | ✅ 可靠 |
| Issue 数据 | `issue +list` | ✅ 可靠 |
| 用户信息 | `user +info` | ✅ 可靠 |
| 贡献热力图 | 不可用（命令未实现） | ❌ 缺失 |
| 统计信息 | 不可用（命令未实现） | ❌ 缺失 |
| 趋势数据 | 不可用（命令未实现） | ❌ 缺失 |

> **局限性**：本报告仅反映 GitLink 平台活动，不包括其他平台（GitHub、GitLab 等）的数据。
```

---

## 异常场景处理

| 场景 | 处理方式 |
|------|----------|
| `repo +contributors` 不可用（当前版本常态） | 从 `pr +list` 的 `author_login` 提取贡献者列表 |
| `user +heatmap` / `+stats` / `+trends` 不可用 | 从 PR 时间戳推算活跃天数，PR 聚合得产出量，时间分布得趋势 |
| `pr +list` 返回空 | 标注"仓库暂无 PR 数据"，仅展示 `repo +info` 基本信息 |
| `user +info` 返回空 | 标注"用户信息不可用"，仅展示 PR 统计 |
| 贡献者 > 15 人 | 仅分析 PR 数最高的前 10 位，报告中注明"基于 Top 10 分析" |
| 项目历史 < 30 天 | 放宽分级标准，报告中注明"项目处于早期阶段" |
| `issue +list` 返回空 | Issue 数列为 0，贡献类型统一标注"代码贡献者" |

---

## 注意事项

- ✅ **所有命令使用 `--format json`**，确保可解析
- ✅ **本 Skill 为纯只读分析**，不会修改任何仓库
- ✅ **Owner/repo 优先从 `git remote` 自动解析**，无 git 上下文时询问用户
- ⚠️ **核心数据来源为 `pr +list`**：当前版本 gitlink-cli 中 `user +heatmap/+stats/+trends` 不可用，分析主要依赖 PR 列表数据
- ⚠️ **`repo +contributors` 不可用**：贡献者列表从 PR 作者提取，可能与实际 `contributor_users_count` 有差异（后者包含未提 PR 的参与者）
- ⚠️ **数据仅反映 GitLink 平台活动**：不包括 GitHub 或其他平台的数据
- ℹ️ **参照样例**：[`EXAMPLES.md`](EXAMPLES.md) 包含手动执行和 Agent 调用两种场景的完整样例，[`examples/jiangtx-gitlink-cli.md`](examples/jiangtx-gitlink-cli.md) 包含原始命令输出数据