3.8 KiB

Raw Blame History

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 来保证覆盖度。

输出数据格式

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

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

3.8 KiB Raw Blame History Unescape Escape