zzx-coder
/
gitlink-cli
forked from Gitlink/gitlink-cli
0
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases 8 Wiki Activity
gitlink-cli/skills/gitlink-faq/SKILL.md

16 KiB
Raw Blame History

name version description metadata
gitlink-faq 2.0.0 Issue 知识库（即 FAQ、常见问题）：从项目 Issue 提取问题与答案，合并同类 Issue，生成结构化 FAQ 发布到 Wiki。注意——用户说的「知识库」「FAQ」「常见问题」都是指这个 skill，这三个词是同义词。触发场景：整理 Issue、归纳 Issue、生成/建立/更新/刷新知识库、生成 FAQ、总结常见问题、检查重复 Issue、查重。通用 Issue 操作（创建/查看/更新/关闭/评论等）请使用 gitlink-issue skill。
requires cliHelp
bins
gitlink-cli
gitlink-cli issue --help

gitlink-faq（Issue 知识库 / FAQ）

CRITICAL — 开始前必须先阅读 ../gitlink-shared/SKILL.md，其中包含认证、权限处理和 API 注意事项。 CRITICAL — 全流程自动执行，不要中途停下来问用户。从采集数据到发布 Wiki 一气呵成，最后告诉用户结果即可。 CRITICAL — GitLink 操作只能用 gitlink-cli。禁止用 gh（GitHub CLI）操作 GitLink 资源。

前置条件： 先阅读 ../gitlink-shared/SKILL.md

核心概念

「知识库」=「FAQ」=「常见问题」——这三个词是同一个东西。 用户不管说哪个，都指的是这个 skill。

FAQ 知识库是一个 "问题 → 答案" 的集合，从项目 Issue 中提取真实用户遇到的问题和对应的解决方案。与统计分析报告不同，知识库的重点在于：

  • 收集 Issue 内容：从 subject（标题）+ description（描述）+ journals（评论讨论）中提取问题和答案
  • 合并同类问题：多个 Issue 描述的是同一个问题 → 合并为一条 FAQ，综合各方讨论给出完整答案
  • 按主题归类：用主题标签（安装配置、CLI 命令、API 等）组织，方便检索
  • 可追溯来源：每条 FAQ 附来源 Issue 编号，方便查看原始讨论

运行模式

模式 说明 典型触发语 需要认证
模式 A：生成/刷新 FAQ 采集全部 Issue → 提取 Q&A → 合并同类问题 → 按主题归类 → 发布 Wiki "整理 Issue""归纳 Issue""总结常见问题""生成 FAQ""建立知识库""刷新知识库""更新知识库""生成知识库" 是（发布 Wiki 需写入）
模式 B：查找与查重 对指定 Issue/关键词，在知识库和历史 Issue 中查找相似项，判断是否重复 "查重""有没有类似的 Issue""这个是不是有人报过""知识库里有没有" 否（仅读取；评论需认证）
模式 C：增量更新 读取已有 Wiki 页面 → 拉取新 Issue → 提取 Q&A 合并到现有知识库 → 更新 Wiki "把这个 Issue 加到知识库""补充到知识库""同步到知识库""更新 FAQ""更新知识库" 是（读取+写入 Wiki）

模式 A：生成/刷新 FAQ 知识库（6 步）

当用户说 "整理 Issue"、"归纳 Issue"、"总结常见问题"、"生成 FAQ"、"建立知识库"、"刷新知识库"、"更新知识库" 等时，执行以下流程。记住：「知识库」=「FAQ」，用户说知识库就是在让你执行这个 skill。

第 1 步：采集全部 Issue

CRITICAL：不要仅采集 --state closed。GitLink 平台很多已解决的 Issue 不会被及时设置为"关闭"状态，只看 closed 会漏掉大量有分析价值的 Issue。

# 同时采集 open 和 closed，覆盖所有 Issue
gitlink-cli issue +list --state open --limit 100 --format json
gitlink-cli issue +list --state closed --limit 100 --format json

将两份列表合并去重，得到完整 Issue 集合。

采集量策略参见 references/gitlink-faq-collect.md。

第 2 步：筛选 + 读取详情

先按标题粗筛，仅排除：

  • 标题含 [test] / 测试 的纯测试 Issue
  • 标题为空或仅有占位符的 Issue

其余 Issue 一律保留，逐个读详情：

gitlink-cli issue +view --number N --format json

提取字段：subject（标题）、description（描述）、comment_journals_count（评论数）。

description 是核心分析源：

  • 部分 Issue 的 description 非常详细（含复现步骤、环境信息、修复建议）
  • description 的质量直接决定能提取出什么质量的 Q&A
  • comment_journals_count 数值可参考（表示讨论热度），但实际评论内容无法通过 API 获取（见下方 API 限制）

每批 20-30 个，尽量覆盖所有非测试 Issue。

第 3 步：从每个 Issue 提取 Q&A 对

对每条 Issue，AI 根据 (subject + description) 提取"问题 → 答案"对。

提取规则：

字段 提取来源 提取方法
Q（问题） subject + description 开头部分 提炼 Issue 要解决的核心问题，用一句话表达
A（答案） description 后半部分 + journals（如有） 提取解决方案、workaround、配置方法、官方回复等

不同 Issue 类型的 Q&A 转换：

Issue 原始类型 Q 示例 A 提取策略
Bug 报告 "为什么执行 xxx 命令后出现 yyy 错误？" 从 description 提取修复方法/workaround；如无则写"暂未找到解决方案"
功能请求 "能否支持 xxx 功能？" 从 description/journals 提取当前状态（已支持/规划中/不支持+替代方案）
使用问题 "如何配置/使用 xxx？" 从 description 提取操作步骤；从 journals 提取维护者回复

宽松原则：宁可多留一条不完美的 Q&A，也别漏掉一条有价值的。不确定答案质量的标注"待确认"而非丢弃。

第 4 步：合并同类问题

多个 Issue 描述的是同一个问题 → 合并为一条 FAQ 条目。

合并判断标准：

  • 两个 Issue 的 subject 高度相似（同义表述）
  • 两个 Issue 描述的症状/需求一致
  • 两个 Issue 的根因/答案相同

合并后的 FAQ 条目：

  • Q：综合多个 Issue 提炼一个清晰的问题
  • A：综合各方描述和讨论给出最完整的答案
  • 来源：列出所有相关 Issue 编号

详细合并逻辑参见 references/gitlink-faq-cluster.md。

第 5 步：按主题归类 + 生成 FAQ 文档

将 Q&A 条目按主题标签归类。每个标签有对应图标，生成文档时章节标题必须带图标。标签体系：

图标 主题标签 适用范围
🔧 安装配置 安装、登录、认证、Token 配置、代理设置
💻 CLI 命令 命令使用、参数、输出格式、交互行为
🔗 API 与集成 API 调用、Webhook、CI/CD 集成
📊 数据显示 数据不一致、字段缺失、展示错误
🖥️ 平台兼容 操作系统兼容、环境依赖
⚡ 性能 响应慢、超时、资源占用
💡 功能请求 用户希望新增或改进的功能
📦 其他 不属于以上类别

一个 Q&A 条目可以打多个标签。

按以下结构组织 Markdown（注意章节标题前必须带图标）：

# 📖 {项目} FAQ 知识库

> 自动生成 | 收录 {N} 个问题 | 更新时间：{DATE}
> 项目：{OWNER}/{REPO}

## 🔧 安装配置

### Q1: {问题}？
**A:** {答案}
> 📎 来源: [#N]({链接}), [#M]({链接})

## 💻 CLI 命令

### Q2: {问题}？
**A:** {答案}
> 📎 来源: [#N]({链接})

...

完整模板参见 examples/faq-template.md。

生成原则参见 references/gitlink-faq-generate.md。

完成后保存为 ./issue-faq.md，然后直接进入第 6 步发布，不需要等用户确认。

第 6 步：发布到 Wiki

直接发布，不要询问用户：

# 先检查 Wiki 页面是否已存在
gitlink-cli wiki +view --title "Issue-知识库" --format json

# 如果存在（返回内容）→ 用 update；如果 404 → 用 create
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-faq.md
# 或
gitlink-cli wiki +create --title "Issue-知识库" --file ./issue-faq.md

发布完成后给用户反馈：发布了多少条 FAQ、Wiki 页面标题。

模式 B：Issue 查找与查重

当用户说 "查重"、"检查重复"、"有没有类似的 Issue"、"找一下关于 xx 的 Issue"、"这个是不是有人报过"、"有没有和 xx 相关的" 时执行。

CRITICAL：本模式下，匹配到候选 Issue 后必须自动读取其详情和 journals，不要问用户"需要我读详情吗"。一次性完成搜索→读详情→给出分析结论。

第 1 步：确定搜索目标

  • 用户指定了 Issue 编号 → issue +view --number N 获取目标内容
  • 用户描述了主题/关键词（如"与创建 Issue 有关的"）→ 进入关键词搜索模式

第 2 步：拉取 Issue 列表

gitlink-cli issue +list --state open --limit 100 --format json
gitlink-cli issue +list --state closed --limit 100 --format json

提取全部 Issue 的 subject（标题），按用户主题进行标题匹配。

第 3 步：自动读取候选 Issue 详情（关键步骤）

筛选出候选 Issue 后，立即逐个读取详情，不需询问用户：

gitlink-cli issue +view --number N --format json

提取：标题、描述、journals（评论讨论历史）。

第 4 步：给出分析结论

综合标题+描述+journals，给用户完整分析：

  • 直接匹配：Issue 的核心讨论内容、维护者回复中有无解决方案
  • 间接相关：Issue 涉及同一模块/功能但由于不同原因
  • 不相关：标题含关键词但内容无关

对每条匹配的 Issue 输出：

  • 标题 + 编号
  • 一句话摘要（从描述和 journals 提取）
  • 维护者有无回复/解决方案
  • 相关度判定

第 5 步：执行操作（自动）

如果判定高度重复，直接添加评论引导用户，不要询问：

# 添加评论（使用 Issue ID，参见 gitlink-issue skill）
gitlink-cli issue +comment --number N --body "此 Issue 与 #M 内容重复，建议..."

# 打重复标签（使用项目内编号，批量操作）
gitlink-cli issue +batch-label --label duplicate --numbers N,M

通用 Issue 操作（创建、查看、更新、关闭、评论等）参见 ../gitlink-issue/SKILL.md。

模式 C：Wiki 增量更新

当用户说 "把这个 Issue 加到知识库里"、"更新 FAQ"、"更新知识库"、"补充到知识库"、"同步到知识库" 等时执行。

核心思路：不是重新生成整个知识库，而是读取现有 Wiki 内容 → 拉取新 Issue → 提取 Q&A → 合并到现有结构 → 更新 Wiki。

第 1 步：读取现有 Wiki

gitlink-cli wiki +view --title "Issue-知识库" --format json

从返回的 JSON 中提取内容（CLI 自动处理 base64 解码）。

如果 Wiki 不存在（404），回退到模式 A——首次创建知识库。

第 2 步：拉取用户指定的 Issue

根据用户指示直接读 Issue 详情，用户说哪个就拉哪个，不要自己去拉全量列表做差集对比。

gitlink-cli issue +view --number N --format json
用户意图 操作
"把 Issue #N 加到知识库" 只读 #N：issue +view --number N
"把这几个 Issue 加进去：#A, #B, #C" 逐个读 #A, #B, #C
"把关于 XX 的 Issue 补充进去" 先按关键词搜索（同模式 B 第 2-3 步），找到匹配 Issue 后逐个读详情
"把最近新增的 Issue 同步到 Wiki" 用户未指定具体编号时，才拉全量列表，对比 Wiki 中已有的编号做差集

第 3 步：从新 Issue 提取 Q&A

同模式 A 第 3 步，从每个新 Issue 提取"问题 → 答案"对。

第 4 步：合并到现有知识库

将新 Q&A 条目归入现有主题分类：

  • 已存在同类问题：合并到已有 Q&A 条目，更新答案和来源列表
  • 全新问题：在对应主题章节下新建 Q&A 条目

合并时更新：

  • 收录问题计数
  • 更新时间
  • 来源 Issue 列表

第 5 步：生成合并后的文档

将合并后的完整 Markdown 保存为 ./issue-faq.md，标注新增/变更的部分（可用 [NEW] 标记）。

第 6 步：更新 Wiki

直接更新，不要询问用户：

gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-faq.md

CRITICAL：必须用 wiki +update（不是 +create），因为页面已存在。

发布完成后给用户反馈：新增了多少条 FAQ、更新了多少条已有条目。

命令速查

本 skill 只涉及知识库分析相关的命令。通用 Issue 操作（创建、查看、更新、关闭、批量操作等）统一使用 gitlink-issue skill。

命令 用途 模式
issue +list --state open --limit 100 --format json 获取 open Issue 列表 A / C
issue +list --state closed --limit 100 --format json 获取 closed Issue 列表 A / C
issue +view --number N --format json 读取单个 Issue 详情 A / B / C
issue +comment --number N --body "..." 查重时添加评论引导用户 B
issue +batch-label --label duplicate --numbers N,M 查重时批量标记重复 B
wiki +view --title "Issue-知识库" --format json 查看已有知识库内容 C
wiki +create --title "Issue-知识库" --file ./xxx.md 首次创建知识库 Wiki 页面 A
wiki +update --title "Issue-知识库" --file ./xxx.md 增量更新知识库 Wiki 页面 A / C

API 注意事项

  • issue +list 的 --state 参数不可靠（与 PR 列表同款问题），返回列表可能包含所有状态。因此必须同时拉 open + closed 两份列表合并去重。
  • issue +view 不返回 journals 内容：只有 comment_journals_count（评论数量），无法通过 API 读取实际评论。GET /v1/.../issues/{N}/journals 返回 HTML 而非 JSON。分析只能依靠 subject + description。
  • issue +label-add API 返回 404：GitLink 平台 POST /v1/.../issues/{N}/labels 端点不可用。打标签请改用 issue +batch-label（走 updateIssueField 而非 labels API）。
  • wiki +view Gateway API 可能返回 404（已知问题），但 wiki +create / wiki +update 写入正常。

注意事项

  • 从 Issue 提取，不编造：Q&A 的 Q 和 A 都必须来自实际 Issue 的 subject/description/journals，不凭空编造
  • 合并优于罗列：多个 Issue 问同一个问题 → 合并为一条 FAQ，而不是罗列多条相似条目
  • 答案有据可查：每条 FAQ 必须附来源 Issue 编号
  • 数据不足时如实说明：无法提取答案的 Issue 标注"待确认"，不强行写答案
  • 评论语气友好：重复检测是帮助用户，不是指责
  • 全自动执行：触发后从头到尾自动完成，不中途询问用户，最后告知结果即可

References