5.6 KiB

Raw Blame History

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 为空

输出数据格式

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

[
  {
    "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，确认分页参数正确

5.6 KiB Raw Blame History Unescape Escape