# 收集健康度数据

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

收集项目健康度报告所需的四类数据：Issue、PR、贡献者和项目活动。

## 命令

### 步骤 1：收集 Issue 数据

```bash
# 获取未关闭 Issue（用于统计积压）
gitlink-cli issue +list --state open --format json

# 获取已关闭 Issue（用于计算响应时间）
gitlink-cli issue +list --state closed --format json
```

Issue 返回的关键字段：

| 字段 | 用途 |
|------|------|
| `project_issues_index` | Issue 编号 |
| `subject` | Issue 标题 |
| `status_id` | 状态：1=新增, 2=正在解决, 3=已解决, 5=关闭 |
| `priority_id` | 优先级：1=低, 2=正常, 3=高, 4=紧急 |
| `created_at` | 创建时间 (ISO 8601) |
| `closed_at` | 关闭时间（仅已关闭 Issue 有此字段） |
| `author.login` | 创建者 |
| `assigners[]` | 负责人列表 |

### 步骤 2：收集 PR 数据

```bash
# 获取未合并 PR（用于统计积压）
gitlink-cli pr +list --state open --format json

# 获取已合并 PR（用于计算合并效率）
gitlink-cli pr +list --state merged --format json
```

PR 返回的关键字段：

| 字段 | 用途 |
|------|------|
| `pull_request_number` | PR 编号 |
| `name` (title) | PR 标题 |
| `pull_request_status` | 状态：0=open, 1=merged, 2=closed |
| `author_login` | 作者 |
| `pr_full_time` | 创建时间 (ISO 8601) |
| `pr_merged_at` | 合并时间 |
| `pr_created_unix` | 创建时间 (Unix timestamp) |

> ⚠️ `--state` 参数仅影响 `merged_count`/`open_count`/`closed_count` 汇总计数，API 返回的 issues 列表可能包含所有状态的 PR。需按 `pull_request_status` 客户端过滤。

### 步骤 3：收集贡献者统计

```bash
# 获取贡献者统计（Raw API，无 Shortcut）
gitlink-cli api GET /:owner/:repo/contributors --format json
```

返回关键字段：

| 字段 | 用途 |
|------|------|
| `author_count` | 总贡献者数 |
| `commit_count` | 总 commit 数 |
| `commit_count_in_all_branches` | 全部分支的 commit 总数 |
| `additions` / `deletions` | 总增删行数 |
| `authors[]` | 每位贡献者的明细 |

每位贡献者（`authors[]`）字段：

| 字段 | 用途 |
|------|------|
| `login` / `name` | 贡献者 ID 和昵称 |
| `commits` | commit 数量 |
| `additions` / `deletions` | 增删行数 |

### 步骤 4：收集项目活动（可选）

```bash
# 获取项目活动 feed
gitlink-cli api GET /:owner/:repo/activity --format json
```

用于补充近期事件（issue 创建/关闭、PR 创建/合并的时间线）。

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--format` | 否 | 始终建议 `json`，便于 AI 解析 |
| `--state` | 否 | Issue: `open`/`closed`；PR: `open`/`merged`/`closed` |
| `--page` | 否 | 大量数据时分页获取 |
| `--limit` | 否 | 每页条数 |

## 数据覆盖范围

数据收集覆盖以下时间范围：

- **Issue**: 所有未关闭 + 近期已关闭（默认取最近 100 条）
- **PR**: 所有未合并 + 近期已合并（默认取最近 100 条）
- **Contributors**: 项目全量历史数据
- **Activity**: 最近 30 天

对于大型项目，可通过 `--page` 分页获取更多数据。

## 注意事项

- 计算响应时间需要 Issue 有 `closed_at` 字段，仅已关闭 Issue 才会返回此字段
- PR 合并时间需通过 `pr_full_time` 与当前时间对比估算，或结合 PM `/weekly_issues` API
- `contributors` 端点统计基于默认分支（通常为 `master`），不含其他分支
- `--owner` / `--repo` 在仓库目录下可自动解析
- 时间计算使用 Unix 时间戳（`pr_created_unix`）比解析字符串格式（`pr_full_time`）更可靠

## References

- [health-metrics](health-metrics.md) — 收集完成后进行指标计算
- [generate-report](generate-report.md) — 生成报告并输出
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
