forked from Gitlink/gitlink-cli
130 lines
5.6 KiB
Markdown
130 lines
5.6 KiB
Markdown
# 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，确认分页参数正确
|