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

> **前置条件：** 先阅读 [`../../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（良好 🔵）
```

### 第五步：填充 HTML 模板

AI 读取 `skills/gitlink-health/template.html`，将计算后的指标替换所有 `{{PLACEHOLDER}}` 占位符，生成完整的 HTML 文件。

### 第六步：输出报告

1. 写入 `skills/gitlink-health/report.html`（唯一的输出文件）
2. 自动打开浏览器展示报告
3. 如需持久化，可选发布为 Issue（内容从内存生成，不写本地文件）

## 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
7. **HTML 生成**：读取 `template.html` → 替换所有 `{{PLACEHOLDER}}` → 写入 `report.html` → 自动 `start`/`open` 打开浏览器
8. **禁止创建临时文件**：所有 API 数据在内存中处理，禁止创建 `tmp_data/`、脚本文件、中间 JSON 等任何多余文件。整个流程只输出一个 `report.html`。

## References

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