# gitlink-faq 数据采集与 Q&A 提取

> 本文档详细说明如何采集 Issue 数据，以及如何从 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` | 含标题、描述、comment_journals_count（评论数） |

> **关键认知**：GitLink 平台很多已解决的 Issue 不会被及时设为"关闭"状态。因此必须**同时采集 open 和 closed 两份列表**，合并去重后才能得到完整的 Issue 集合。

## 筛选策略

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

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

| 类型 | 是否纳入 | 原因 |
|------|----------|------|
| 有 description 的 Issue | ✅ 纳入 | description 可能包含详细的复现步骤和解决方案 |
| 仅有标题无 description | ✅ 纳入 | 标题本身承载了问题信息 |
| 功能请求 | ✅ 纳入 | 可转为"能否支持 xx？"格式的 FAQ |
| 标题含 `[test]`/`测试` | ❌ 排除 | 纯测试数据 |
| 标题为空或纯占位符 | ❌ 排除 | 无有效信息 |

> **宽松吸纳**：宁可多留一条低质量的，也别漏掉一条有答案的。

## 分批采集

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

### 参与度筛选

优先采集"高参与度"的 Issue（更有可能提取到完整答案）：
- `comment_journals_count ≥ 2`（有人讨论过，答案可能来自讨论）
- journals 中包含维护者回复（优先作为答案来源）
- description 中包含"解决""修复""方案""workaround"等关键词

## Q&A 提取方法

这是整个流程的核心：从每条 Issue 的 `subject` + `description` 中提取"问题（Q）→ 答案（A）"。

### 提取 Prompt

```
你正在从项目 Issue 中提取 FAQ 知识库条目。请对每条 Issue 提取 Q&A 对。

## Issue 数据
编号: {number}
标题: {subject}
描述: {description}
评论数: {comment_journals_count}

## 提取规则
1. Q（问题）：用一句话概括这个 Issue 要解决的核心问题。用中文表述，以问号结尾。
2. A（答案）：从 description 中提取解决方案、操作步骤、配置方法、workaround 或官方回复。
   - 如果 description 明确描述了解决方法 → 直接提取
   - 如果 description 仅有问题描述无解决方案 → A 写"暂未找到解决方案，详见 Issue 讨论"
   - 如果 Issue 是功能请求 → A 写当前状态（已支持/开发中/不支持）和替代方案
   - 如果 description 为 null 或只有图片 → A 写"Description 无文本内容，无法提取答案"

返回 JSON：
{
  "issue_number": N,
  "Q": "一句话问题？",
  "A": "答案内容",
  "confidence": "high|medium|low"
}
```

### 不同类型 Issue 的提取策略

| Issue 实际类型 | Q 模板 | A 提取来源 | 示例 |
|---------------|--------|------------|------|
| Bug 报告 | "为什么出现 xxx 错误/异常？" | description 中的修复步骤、workaround | "为什么执行 gitlink-cli issue +view 返回数据与网页端不一致？" |
| Bug 报告（无修复） | "遇到 xxx 问题怎么办？" | "暂未找到解决方案，详见 Issue 讨论" | |
| 功能请求 | "能否支持 xxx？" | description/journals 中的状态说明 | "能否支持按 Issue 序号查询？" |
| 使用问题 | "如何配置/使用 xxx？" | description 中的步骤说明 | "如何在 CI 环境中配置 gitlink-cli？" |
| 使用问题（无回复） | "xxx 怎么处理？" | "暂未找到解决方案，详见 Issue 讨论" | |

### 答案质量标注

| 标注 | 条件 |
|------|------|
| `high` | description 明确描述了解决方案、修复方法或有维护者回复 |
| `medium` | 有部分相关信息但不够完整，或需要结合其他 Issue |
| `low` | description 只有问题描述，无解决方案；或 description 为空 |

## 输出数据格式

采集提取后整理为以下结构供合并归类使用：

```json
[
  {
    "issue_number": 142,
    "Q": "安装 gitlink-cli 后运行报 command not found 怎么办？",
    "A": "将 ~/.local/bin 加入 PATH 环境变量。Linux/Mac 执行: export PATH=$PATH:~/.local/bin。Windows 将 %USERPROFILE%\\.local\\bin 加入系统 PATH。",
    "confidence": "high",
    "journal_count": 5,
    "labels": ["安装配置"]
  },
  {
    "issue_number": 158,
    "Q": "issue +view 命令返回的 JSON 缺少部分字段？",
    "A": "暂未找到解决方案，详见 Issue 讨论",
    "confidence": "low",
    "journal_count": 2,
    "labels": ["CLI 命令", "数据显示"]
  }
]
```

## API 注意事项

- `issue +list` 的 `--limit` 最大 200，超出需分页（`--page` 参数）
- **`--state` 参数不可靠**：与 PR 列表类似，必须同时拉取 open 和 closed 两份列表并合并去重
- **`issue +view` 不返回 journals 内容**：只有 `comment_journals_count`（评论数量），无法通过 API 读取实际评论。`GET /v1/.../issues/{N}/journals` 返回 HTML 而非 JSON。分析只能依靠 `subject` + `description`。
- 大量请求时建议用 `--debug` 查看实际请求 URL，确认分页参数正确
