# 生成并输出健康度报告

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

将计算的指标和评分套用 HTML 模板，生成网页版健康度报告，自动打开浏览器展示。

## 输出方式（HTML 网页）

**CRITICAL — 整个流程只允许输出一个文件 `skills/gitlink-health/report.html`，禁止创建任何临时文件、中间文件、缓存目录、脚本文件或额外的 Markdown 文件。**

### 步骤 1：填充模板

读取 `skills/gitlink-health/template.html`，将计算后的指标替换所有 `{{PLACEHOLDER}}` 占位符。占位符说明见 [SKILL.md](../SKILL.md#占位符说明)。

### 步骤 2：写入文件

将填充后的 HTML 写入 `skills/gitlink-health/report.html`。

### 步骤 3：自动打开浏览器

| 平台 | 命令 |
|------|------|
| Windows | `start skills/gitlink-health/report.html` |
| macOS | `open skills/gitlink-health/report.html` |
| Linux | `xdg-open skills/gitlink-health/report.html` |

## 备选输出方式（仅发布 Issue，不创建额外文件）

### 创建报告 Issue（需认证）

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

> ⚠️ 此为 Write Operation，创建前必须确认用户意图。内容从内存中的计算结果直接生成，不写本地文件。

## 模板关键占位符

| 占位符 | 来源 |
|--------|------|
| `{{OWNER}}` / `{{REPO}}` | git remote 解析 |
| `{{DATE}}` | 当前日期 |
| `{{SCORE}}` | 综合评分（0-100） |
| `{{SCORE_COLOR}}` | #00b894(90+)/#0984e3(70+)/#fdcb6e(50+)/#e17055(30+)/#d63031(<30) |
| `{{SCORE_DASH}}` | `(SCORE/100*377) 377` |
| `{{GRADE}}` | 优秀 / 良好 / 一般 / 需关注 / 严重 |
| `{{DEDUCTION_ROWS}}` | 6 行 `<tr>` 扣分明细 |
| `{{OPEN_ISSUES}}` / `{{CLOSED_ISSUES}}` 等 | 统计数据 |
| `{{CONTRIBUTOR_ROWS}}` | 每人一行 `<tr>` |
| `{{SUGGESTIONS}}` | `<li>` 列表 |

完整占位符列表参见 [SKILL.md](../SKILL.md).

## Workflow

1. **计算**所有指标和评分（参见 [health-metrics](health-metrics.md)），所有数据在内存中处理
2. **填充** HTML 模板所有占位符
3. **写入** `skills/gitlink-health/report.html`（唯一的输出文件）
4. **打开** 浏览器自动展示（`start` / `open` / `xdg-open`）
5. 如需持久化，可选发布为 Issue（内容从内存生成，不写本地文件）

## 注意事项

- 报告的时间范围默认取最近 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) — 认证和全局参数
