# gitlink-faq 数据采集

> 本文档详细说明 FAQ 生成时 Issue 数据的采集策略和参数。

## 数据源

| 数据 | 命令 | 说明 |
|------|------|------|
| Issue 列表（open） | `issue +list --state open --limit 100 --format json` | 仍开放的 Issue |
| Issue 列表（closed） | `issue +list --state closed --limit 100 --format json` | 已关闭的 Issue |
| Issue 详情 | `issue +view --number N --format json` | 含标题、描述、journals（评论历史） |

> **关键认知**：GitLink 平台很多已解决的 Issue 不会被及时设为"关闭"状态，存在延迟甚至从未更改状态。因此必须**同时采集 open 和 closed 两份列表**，合并去重后才能得到完整的可分析 Issue 集合。用 `issue +view` 读取的 `journals`（评论讨论历史）比 `status` 字段更能判断一个 Issue 是否"已解决"。

## 筛选策略

### 有价值 vs 无价值 Issue

采集后需筛选。注意：GitLink API **不支持读取 Issue 评论（journals）**，筛选只能基于 subject + description。

**宽松筛选原则**（只排除明确无价值的）：

| 类型 | 是否纳入 | 原因 |
|------|----------|------|
| 有 description 的 Issue | ✅ 纳入 | description 可能非常详细 |
| 仅有标题无 description | ✅ 纳入 | 标题本身有价值信息 |
| 功能请求 | ✅ 纳入 | 反映用户需求优先级 |
| 标题含 `[test]`/`测试` | ❌ 排除 | 纯测试数据 |
| 标题为空或纯占位符 | ❌ 排除 | 无有效信息 |

> 不再排除"功能请求"和"仅有标题"的 Issue。没有评论数据的情况下，最大化保留所有可分析的 Issue。

### 分批采集

```
Issue 总量        采集策略
─────────        ─────────
< 20             全部采集，逐个读详情（含 journals）
20-50           全部采集，按标题粗筛后读重点 Issue 详情
50-100        分批采集（每批50），先按标题粗筛
> 100            取最近活跃的 100 个，优先高参与度的
```

### 参与度筛选

优先采集"高参与度"的 Issue（更有分析价值）：
- **journals 非空**（有人讨论过）——这是最重要的筛选信号，空 journals 的 Issue 分析价值极低
- journals 中包含维护者回复（优先提取作为答案/修复方案）
- 评论数量 ≥ 2

### API 限制：无法读取评论

`issue +view` 只返回 `comment_journals_count`（评论数），不返回评论内容。`GET /v1/.../issues/{N}/journals` 端点返回 HTML 而非 JSON，无法通过 API 获取评论正文。

因此分析只能基于 `subject` + `description` 两个字段。这也是筛选规则放宽的原因——没有评论作为补充信息，凭标题和描述能分析到的内容更有限，需要尽可能保留更多 Issue 来保证覆盖度。

## 输出数据格式

采集后整理为以下结构供聚类使用：

```json
[
  {
    "number": 142,
    "subject": "安装后运行报 command not found",
    "description": "按照 README 安装后，终端输入 gitlink-cli 提示...",
    "labels": ["bug", "installation"],
    "journal_count": 5,
    "last_comment_author": "maintainer",
    "resolution": "需要将 ~/.local/bin 加入 PATH"
  }
]
```

## API 注意事项

- `issue +list` 的 `--limit` 最大 200，超出需分页（`--page` 参数）
- **`--state` 参数不可靠**：与 PR 列表类似，`--state` 参数可能不严格过滤列表（返回数据中 `closed_count` 才是真实统计）。必须同时拉取 open 和 closed 两份列表并合并去重。
- `issue +view` 的 `journals` 字段包含完整评论历史，是判断解决过程的关键
- `journals` 中的 `body` 字段是评论的纯文本内容，`author.login` 是评论者
- 大量请求时建议用 `--debug` 查看实际请求 URL，确认分页参数正确
