# 项目健康度报告 — 完整生成示例

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **适用场景：** AI Agent 端到端生成项目健康度报告，以 `zzx-coder/gitlink-cli` 为例。

## 完整流程

### 第一步：收集 Issue 数据

```bash
# 获取未关闭 Issue
gitlink-cli issue +list --state open --format json

# 获取已关闭 Issue
gitlink-cli issue +list --state closed --format json

# AI 从返回中提取：
# - open count: 28
# - closed count: 1 (我们之前创建的 #29，已关闭)
# - priority 分布: 大部分为 normal (priority_id=2)
# - 平均关闭时间: #29 创建后约 1 分钟关闭（测试 issue）
```

### 第二步：收集 PR 数据

```bash
# 获取未合并 PR
gitlink-cli pr +list --state open --format json

# 获取已合并 PR
gitlink-cli pr +list --state merged --format json

# AI 从返回中提取：
# - merged count: 10
# - open count: 0
# - 合并率: 10/11 = 91%
# - 最新合并 PR: #11 (2026-06-04)
# - PR 平均合并时间需逐条计算
```

### 第三步：收集贡献者统计

```bash
# Raw API 获取贡献者数据
gitlink-cli api GET /:owner/:repo/contributors --format json

# AI 从返回中提取：
# - author_count: 4+
# - 各贡献者 commit 数和增删行数
# - 集中度计算
```

### 第四步：AI 计算指标

AI 根据 [指标计算规则](../references/health-metrics.md) 处理数据：

```
Issue 响应时间:
  平均 0.1 天（仅 1 个已关闭 Issue，样本量不足）
  积压 28 个 → 触发扣分

PR 合并效率:
  平均合并时间 ≈ 3.5 天（估算，需 merge_at 字段）
  积压 0 个 ✓
  合并率 91%

贡献者活跃度:
  mengcheng (camelliamc) — 🔥 高频
  zzx-coder — 🔥 高频
  wbtiger — 🟢 正常
  wangyue789 — 🟡 低频

综合评分:
  起始 100
  核心指标: 0 扣分（响应时间样本不足/PR合并正常/贡献者活跃）
  辅助指标: -10 Issue 积压 (28 open), -5 无近期发布 (已解决)
  最终: 85/100（良好 🔵）
```

### 第五步：生成报告草稿

AI 套用模板生成并展示给用户：

```markdown
# 🏥 项目健康度报告

**项目**: zzx-coder/gitlink-cli
**报告时间**: 2026-06-14
**统计周期**: 最近 30 天

---

## 📊 综合评分

| 评分 | 等级 |
|------|------|
| 85/100 | 🔵 良好 |

| 扣分明细 | 扣分 | 状态 |
|----------|------|------|
| **核心指标** | | |
| Issue 响应时间（样本不足） | 0 | ✅ 跳过 |
| PR 合并时间（平均 ~3.5 天） | 0 | ✅ 正常 |
| 贡献者活跃度（2 位高频活跃） | 0 | ✅ 正常 |
| **辅助指标** | | |
| Issue 积压（当前 28 个） | -10 | ⚠️ 需关注 |
| PR 积压（当前 0 个） | 0 | ✅ 正常 |
| 近期发布（v0.1.18, 今天） | 0 | ✅ 正常 |

---

## 🐛 Issue 分析

| 指标 | 数值 |
|------|------|
| 全部 Issue | 29 |
| 已关闭 | 1 |
| 待处理 | 28 |
| 平均关闭时长 | 样本不足 |

### 按优先级分布

| 优先级 | 数量 | 占比 |
|--------|------|------|
| 🔴 紧急 | 0 | 0% |
| 🟠 高 | 0 | 0% |
| 🟡 正常 | 28 | 100% |
| 🟢 低 | 0 | 0% |

---

## 🔀 PR 分析

| 指标 | 数值 |
|------|------|
| 全部 PR | 11 |
| 已合并 | 10 |
| 待合并 | 0 |
| 合并率 | 91% |
| 平均合并时长 | ~3.5 天 |

---

## 👥 贡献者活跃度

| 贡献者 | Commits | PRs | 增/删 | 活跃度 |
|---------|---------|-----|-------|--------|
| mengcheng | 120 | 5 | +8500/-3200 | 🔥 高频 |
| zzx-coder | 65 | 4 | +3200/-1800 | 🔥 高频 |
| wbtiger | 40 | 1 | +2100/-900 | 🟢 正常 |
| wangyue789 | 5 | 0 | +300/-150 | 🟡 低频 |

**总贡献者**: 4 | **总 commits**: 230+ | **代码变更**: +14100/-6050

---

## 💡 改进建议

- **Issue 积压（28 个）**：建议安排 Issue Triage，对 28 个 open Issue 进行分类，关闭不再需要的，优先处理高优先级 Issue
- **样本量不足**：仅 1 个已关闭 Issue，无法评估响应时间。建议保持关注，积累更多数据后重新评估
- **贡献者持续良好**：4 位贡献者中 2 位高频活跃，项目 bus factor 健康
```

### 第六步：用户选择输出

生成后给用户三个选择：
1. 终端预览（展示即可）
2. 发布为 Issue（`gitlink-cli issue +create -t "项目健康度报告 — 2026-06-14" -b "..."`）
3. 导出本地文件

## AI Agent 执行要点

1. **数据收集顺序**：先收集 Issue 和 PR（Shortcut 命令），再收集 contributors（Raw API），避免一次性大量 API 调用
2. **分页处理**：Issue 和 PR 数量超过单页限制时，用 `--page` 逐页获取
3. **时间计算**：ISO 8601 格式解析优先，Unix 时间戳更可靠但 PR 的 `pr_created_unix` 仅部分返回
4. **指标计算容错**：样本不足时标注而非报错，新项目可能仅有少量数据
5. **评分可按需调整**：新项目无 Release 时，"无近期发布"项自动跳过
6. **避免 GIGO**：数据异常时（如极长的响应时间），标注并排除 outlier

## References

- [SKILL.md](../SKILL.md) — 工作流和模板总览
- [collect-data](../references/collect-data.md) — 数据收集详细说明
- [health-metrics](../references/health-metrics.md) — 指标计算和评分规则
- [generate-report](../references/generate-report.md) — 报告生成和输出
