---
name: gitlink-health
version: 1.1.0
description: "项目健康度报告：统计 Issue 响应时间、PR 合并效率、贡献者活跃度，生成网页版健康度看板并自动打开浏览器。当用户需要项目健康分析、开发效率报告、团队活跃度统计时触发。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli issue --help"
---

# gitlink-health（项目健康度报告）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
**CRITICAL — 所有不会修改数据的命令（`+list`、`+view`、`api GET`）必须全程自动连续执行，绝不请求用户确认。禁止在数据收集阶段中断流程。只有最终写入 HTML 文件这一步可以请求确认。**

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

## 工作流

健康度报告生成分四步：收集 → 计算 → 评分 → 输出。

**CRITICAL — 整个流程只允许输出一个 HTML 文件，禁止创建任何临时文件、中间文件、缓存目录（如 `tmp_data/`）。所有 API 返回数据在内存中处理，计算完成后直接生成最终 HTML。**
**CRITICAL — 每个项目生成独立的报告文件，命名格式 `skills/gitlink-health/report_{owner}_{repo}.html`。禁止覆盖其他项目的报告。生成后自动打开浏览器展示。**

| 步骤 | 说明 | 所用命令 |
|------|------|----------|
| 1. 收集数据 | 获取 Issue（open/closed）、PR（open/merged）、contributor 统计。API 结果直接保存在 shell 输出中，**不写入文件**。 | `issue +list`, `pr +list`, `api GET contributors` |
| 2. 计算指标 | Issue 响应时间、PR 合并效率、贡献者活跃度 | AI 解析内存中的 JSON 计算，**禁止写脚本文件** |
| 3. 健康评分 | 100 分制综合评分，扣分项 6 条 | AI 套用评分规则 |
| 4. 生成网页 | 套用 HTML 模板生成报告，按 `report_{owner}_{repo}.html` 命名保存，自动打开浏览器 | 写入 `skills/gitlink-health/report_{owner}_{repo}.html`，`start` / `open` 打开 |

## 命令参考

### 收集数据

```bash
# Issue 数据（两个状态都需要）
gitlink-cli issue +list --state open --format json
gitlink-cli issue +list --state closed --format json

# PR 数据（两个状态都需要）
gitlink-cli pr +list --state open --format json
gitlink-cli pr +list --state merged --format json

# 贡献者统计（Raw API）
gitlink-cli api GET /:owner/:repo/contributors --format json

# 项目活动（Raw API，可选）
gitlink-cli api GET /:owner/:repo/activity --format json
```

## 三大指标

### 1. Issue 响应时间

支持两种口径，**推荐优先使用响应时间**（新增→已解决）：

| 口径 | 计算方式 | 说明 |
|------|----------|------|
| **响应时间（推荐）** | `avg(resolved_at - created_at)` | 从创建到解决，反映实际处理效率 |
| 全周期时间 | `avg(closed_at - created_at)` | 从创建到正式关闭，反映完整生命周期 |

| 指标 | 计算方式 | 说明 |
|------|----------|------|
| 平均响应时间 | `avg(resolved_at - created_at)` 或 `avg(closed_at - created_at)` | 无 `resolved_at` 时用历史 `updated_at` 推断 |
| 中位数响应时间 | `median(...)` | 排除极端值影响 |
| Issue 积压数 | `count(open Issues)` | 当前待处理的 Issue 数量 |
| 按优先级分布 | 按 `priority_id` 分组：低(1)/正常(2)/高(3)/紧急(4) | 高优先级积压更值得关注 |

> **注意**：GitLink API 不返回 `closed_at`/`resolved_at` 字段。若项目有"先解决后批量关闭"的工作流，`updated_at` 可能被关闭操作覆盖而虚高，应优先从会话历史推断解决时间。

### 2. PR 合并效率

PR 合并效率由**三类 PR** 共同决定，需计算**三段时间**：

| 时间 | 名称 | 公式 | 适用对象 |
|------|------|------|----------|
| ① | 已合并 PR 平均合并时长 | `avg(merged_at - created_at)` | status=1（已合并） |
| ② | 开放 PR 平均等待时长 | `avg(now - created_at)` | status=0（开放中） |
| ③ | 加权总平均处理时长 | `(merged/total) * ① + (open/total) * ②` | 已合并 ∪ 开放 |

**总样本数 = 已合并数 + 开放数**（已关闭未合并的 PR 不参与时间计算，仅参与合并率分母）。

| 指标 | 计算方式 | 说明 |
|------|----------|------|
| ① 已合并平均合并时长 | `avg(merged_at - created_at)` | **仅对已合并 PR**（`status=1`）计算，从创建到合并成功的时长 |
| ② 开放平均等待时长 | `avg(now - created_at)` | 开放 PR 从创建到当前的等待时长，反映积压压力 |
| ③ 加权总平均 | `(merged/total) * ① + (open/total) * ②` | 综合 PR 处理节奏的总体指标 |
| PR 积压数 | `count(open PRs)` | 当前待合并的 PR 数量 |
| 合并率 | `merged / (merged + closed)` | 已合并占所有已关闭 PR（合并+关闭）的比例 |

**统计对象规则**：

| PR 状态 | 计入时间计算 | 计入合并率分母 | 计入积压 |
|---------|------------|---------------|---------|
| 已合并（status=1） | ① | ✅ | ❌ |
| 已关闭未合并（status=2） | ❌ | ✅ | ❌ |
| 开放中（status=0） | ② | ❌ | ✅ |

> **数据获取**：`merged_at` 仅在 `pr +view --id <pull_request_number>` 单个 PR 详情中返回（路径 `data.pull_request.merged_at`），列表接口不暴露。
> **绝对禁止**：用「当前时间 - 创建时间」估算已合并 PR 的合并时间。开放 PR 用此公式是允许的（且必要），因为它们没有合并时间点，等待时长反映积压。

### 3. 贡献者活跃度

| 指标 | 数据源 | 说明 |
|------|--------|------|
| 贡献者总数 | `contributors.author_count` | 项目总贡献者数 |
| 每人 commits | `contributors.authors[].commits` | 按 commit 数排名 |
| 每人增删行数 | `contributors.authors[].additions / deletions` | 代码贡献量 |
| 每人 PR 数 / Issue 数 | PR 和 Issue 列表统计 | 在 podium 和 contributor-row 中显示 |
| 活跃度分级 | 综合 commits + PRs + Issues | 高频 / 正常 / 低频 |

**CRITICAL — 每个贡献者必须同时显示 PR 数量和 Issue 数量**，格式为 `N PRs · M Issues`。
- **Podium 前三名**（冠亚季军）：`N PRs · M Issues · 🔥 高频` — 带活跃度标签。
- **其他贡献者**（contributor-row）：`N PRs · M Issues` — 不带活跃度标签。

活跃度分级标准：

| 级别 | 条件 |
|------|------|
| 🔥 高频 | 近 30 天 commits ≥ 5 或 PRs ≥ 2 |
| 🟢 正常 | 近 30 天 commits ≥ 1 或 PRs ≥ 1 |
| 🟡 低频 | 近 30 天无 commit 和 PR，但有近期 Issue 活动 |
| ⚪ 不活跃 | 近 60 天无任何活动记录 |

## 健康度综合评分（100 分制）

### 核心指标（75 分）

| 扣分项 | 扣分 | 条件 |
|--------|------|------|
| Issue 响应慢 | -25 | Issue 平均响应时间（新增→已解决）> 3 天 |
| PR 合并慢 | -25 | PR 加权总平均处理时长 > 2 天（③） |
| 贡献者活跃度低 | -25 | 近 30 天有活跃行为的贡献者 < 2 人，或单一贡献者占总 commit 数 > 70% |

### 辅助指标（25 分）

| 扣分项 | 扣分 | 条件 |
|--------|------|------|
| Issue 积压严重 | -10 | open 状态 Issue 数量 > 20 |
| PR 积压严重 | -10 | open 状态 PR 数量 > 10 |
| 近期无发布 | -5 | 最近 30 天无新 Release |

评分等级：

| 分数 | 等级 | 图标 |
|------|------|------|
| 90-100 | 优秀 | 🟢 |
| 70-89 | 良好 | 🔵 |
| 50-69 | 一般 | 🟡 |
| 30-49 | 需关注 | 🟠 |
| 0-29 | 严重 | 🔴 |

## 报告输出（HTML 网页）

### 模板文件

报告使用 `skills/gitlink-health/template.html` 作为模板。AI 将计算后的指标填入模板中的 `{{PLACEHOLDER}}` 占位符，按 `report_{owner}_{repo}.html` 格式命名（如 `report_chroe_gitlink-cli.html`），生成到 `skills/gitlink-health/` 目录下。每个项目独立文件，不覆盖其他项目报告。

### 占位符说明

| 占位符 | 来源 | 说明 |
|--------|------|------|
| `{{OWNER}}` / `{{REPO}}` | git remote 解析 | 项目路径 |
| `{{DATE}}` | 当前日期 | 报告生成日期 |
| `{{PERIOD_DAYS}}` | 默认 30 | 统计周期天数 |
| `{{SCORE}}` | 计算得出 | 综合评分 0-100 |
| `{{SCORE_COLOR}}` | 评分映射 | #00b894(优秀) / #0984e3(良好) / #fdcb6e(一般) / #e17055(需关注) / #d63031(严重) |
| `{{SCORE_DASH}}` | 评分计算 | SVG stroke-dasharray：`(SCORE/100*377) 377` |
| `{{GRADE}}` | 评分映射 | 优秀 / 良好 / 一般 / 需关注 / 严重 |
| `{{DEDUCTION_ROWS}}` | 扣分明细 | 6 行 `<tr>`，每行含指标名、实际值、扣分、状态 |
| `{{TOTAL_ISSUES}}` 等 | 统计数据 | Issue/PR 各项数值 |
| `{{PRIORITY_BAR}}` | 优先级分布 | 4 个 `<span>` 表示紧急/高/正常/低占比 |
| `{{PRIORITY_LEGEND}}` | 优先级分布 | 图例说明 |
| `{{CONTRIBUTOR_ROWS}}` | 贡献者统计 | 每人一行的表格数据 |
| `{{SUGGESTIONS}}` | AI 生成 | 改进建议列表 |

### 生成并打开

1. 将计算后的数据填入模板所有占位符
2. 写入 `skills/gitlink-health/report_{owner}_{repo}.html`（每个项目独立文件，不覆盖）
3. 写入成功后立即根据操作系统自动打开浏览器：
   - Windows: `start skills/gitlink-health/report_{owner}_{repo}.html`
   - macOS: `open skills/gitlink-health/report_{owner}_{repo}.html`
   - Linux: `xdg-open skills/gitlink-health/report_{owner}_{repo}.html`

## API 注意事项

- `GET /:owner/:repo/contributors` 无 Shortcut，通过 `gitlink-cli api GET` 调用
- PR list 的 `--state` 仅影响统计计数，返回列表需客户端按 `pull_request_status` 过滤
- Issue 字段名：网页编号为 `project_issues_index`，数据库 ID 为 `id`
- Issue 时间字段：API **不返回**独立的 `closed_at` 或 `resolved_at`，仅有 `created_at` 和 `updated_at`。`updated_at` 是最后更新时间（可能反映解决时间或关闭时间，需根据上下文判断）
- 贡献者统计基于默认分支，不含其他分支的 commit
- `contributors` 返回 `author_count`（总数）和 `authors[]`（每人明细）

## References

- [collect-data](references/collect-data.md) — 数据收集详细说明
- [health-metrics](references/health-metrics.md) — 指标计算和评分规则
- [generate-report](references/generate-report.md) — 报告生成和输出
- [full-workflow](examples/full-workflow.md) — 完整端到端示例
- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证和全局参数
