# 生成并输出健康度报告

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

将计算的指标和评分套用模板，生成 Markdown 格式的健康度报告，通过终端、Issue 或文件三种方式输出。

## 输出方式

### 方式 1：终端预览（默认）

直接在对话中展示 Markdown 报告，用户确认后决定是否持久化。

### 方式 2：创建报告 Issue（需认证）

将报告发布为项目的 Review Issue，便于团队讨论和跟踪：

```bash
gitlink-cli issue +create \
  -t "项目健康度报告 — {DATE}" \
  -b "<Markdown 格式的完整报告>" \
  --label 文档
```

> ⚠️ 此为 Write Operation，创建前必须确认用户意图。

### 方式 3：导出 Markdown 文件（本地）

AI Agent 将报告内容写入本地文件：

```
health_reports/health_report_{DATE}.md
```

## 模板

### 标准模板

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

**项目**: {OWNER}/{REPO}
**报告时间**: {DATE}
**统计周期**: 最近 {PERIOD_DAYS} 天

---

## 📊 综合评分

| 评分 | 等级 |
|------|------|
| {SCORE}/100 | {GRADE_ICON} {GRADE} |

| 扣分明细 | 扣分 | 状态 |
|----------|------|------|
| Issue 积压（当前 {OPEN_ISSUES} 个） | -{DEDUCTION} | {ISSUE_BACKLOG_STATUS} |
| PR 积压（当前 {OPEN_PRS} 个） | -{DEDUCTION} | {PR_BACKLOG_STATUS} |
| Issue 响应时间（平均 {RESPONSE_TIME}） | -{DEDUCTION} | {RESPONSE_STATUS} |
| PR 合并时间（平均 {MERGE_TIME}） | -{DEDUCTION} | {MERGE_STATUS} |
| 贡献者集中度（最高占比 {TOP_SHARE}） | -{DEDUCTION} | {CONCENTRATION_STATUS} |
| 近期发布（最新 {LAST_RELEASE}） | -{DEDUCTION} | {RELEASE_STATUS} |

---

## 🐛 Issue 分析

| 指标 | 数值 |
|------|------|
| 全部 Issue | {TOTAL_ISSUES} |
| 已关闭 | {CLOSED_ISSUES} |
| 待处理 | {OPEN_ISSUES} |
| 平均关闭时长 | {AVG_RESPONSE_TIME} |
| 中位数关闭时长 | {MEDIAN_RESPONSE_TIME} |

### 按优先级分布

| 优先级 | 数量 | 占比 |
|--------|------|------|
| 🔴 紧急 | {URGENT_COUNT} | {URGENT_PCT}% |
| 🟠 高 | {HIGH_COUNT} | {HIGH_PCT}% |
| 🟡 正常 | {NORMAL_COUNT} | {NORMAL_PCT}% |
| 🟢 低 | {LOW_COUNT} | {LOW_PCT}% |

---

## 🔀 PR 分析

| 指标 | 数值 |
|------|------|
| 全部 PR | {TOTAL_PRS} |
| 已合并 | {MERGED_PRS} |
| 待合并 | {OPEN_PRS} |
| 合并率 | {MERGE_RATE}% |
| 平均合并时长 | {AVG_MERGE_TIME} |
| 中位数合并时长 | {MEDIAN_MERGE_TIME} |

---

## 👥 贡献者活跃度

| 贡献者 | Commits | PRs | Issues | 增/删 | 活跃度 |
|---------|---------|-----|--------|-------|--------|
| {NAME} | {COMMITS} | {PRS} | {ISSUES} | +{ADD}/-{DEL} | {ACTIVITY_ICON} {LEVEL} |

**总贡献者**: {TOTAL_CONTRIBUTORS} | **总 commits**: {TOTAL_COMMITS} | **代码变更**: +{TOTAL_ADD}/-{TOTAL_DEL}

---

## 💡 改进建议

{SUGGESTIONS}

---
*报告由 [gitlink-health skill](...) 自动生成*
```

## 占位符说明

| 占位符 | 来源 |
|--------|------|
| `{OWNER}` / `{REPO}` | git remote 解析 |
| `{DATE}` | 当前日期 |
| `{PERIOD_DAYS}` | 数据覆盖天数（默认 30） |
| `{SCORE}` | 综合评分（0-100） |
| `{GRADE}` / `{GRADE_ICON}` | 评分等级 + 图标 |
| `{OPEN_ISSUES}` | 未关闭 Issue 数量 |
| `{CLOSED_ISSUES}` | 已关闭 Issue 数量 |
| `{AVG_RESPONSE_TIME}` / `{MEDIAN_RESPONSE_TIME}` | Issue 响应时间 |
| `{OPEN_PRS}` | 未合并 PR 数量 |
| `{MERGED_PRS}` | 已合并 PR 数量 |
| `{AVG_MERGE_TIME}` / `{MEDIAN_MERGE_TIME}` | PR 合并时间 |
| `{MERGE_RATE}` | PR 合并率（%） |
| `{TOTAL_CONTRIBUTORS}` | 总贡献者数 |
| `{TOP_SHARE}` | 最高单贡献者占比 |
| `{LAST_RELEASE}` | 最近一次 Release 时间或 "无" |
| `{SUGGESTIONS}` | AI 生成的改进建议列表 |

## Workflow

1. **计算**所有指标和评分（参见 [health-metrics](health-metrics.md)）
2. **填充**标准模板，生成 Markdown 报告
3. **展示**报告草稿给用户审核
4. **确认**用户选择输出方式（终端 / Issue / 文件）
5. 如需发布为 Issue，确认后执行 `issue +create`

## 注意事项

- 报告的时间范围默认取最近 30 天，用户可指定自定义范围
- 若项目无 Release（如新项目），扣分项"无近期发布"不适用，总分自动调整
- 贡献者活跃度需结合近 30 天的活动时间线判断
- 改进建议应具体、可执行，避免空泛描述
- 如果数据量不足（如新项目仅有少量 Issue/PR），在报告中标注"样本量小，仅供参考"

## References

- [collect-data](collect-data.md) — 收集项目数据
- [health-metrics](health-metrics.md) — 指标计算和评分规则
- [full-workflow](../examples/full-workflow.md) — 完整端到端示例
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
