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

# gitlink-faq（Issue 知识库 / FAQ）

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

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../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。

```bash
# 同时采集 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`](references/gitlink-faq-collect.md)。

### 第 2 步：筛选 + 读取详情

先按标题粗筛，仅排除：
- 标题含 `[test]` / `测试` 的纯测试 Issue
- 标题为空或仅有占位符的 Issue

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

```bash
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`](references/gitlink-faq-cluster.md)。

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

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

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

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

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

```markdown
# 📖 {项目} FAQ 知识库

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

## 🔧 安装配置

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

## 💻 CLI 命令

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

...
```

完整模板参见 [`examples/faq-template.md`](examples/faq-template.md)。

生成原则参见 [`references/gitlink-faq-generate.md`](references/gitlink-faq-generate.md)。

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

### 第 6 步：发布到 Wiki

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

```bash
# 先检查 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 列表

```bash
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 后，**立即逐个读取详情，不需询问用户**：

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

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

### 第 4 步：给出分析结论

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

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

对每条匹配的 Issue 输出：
- 标题 + 编号
- 一句话摘要（从描述和 journals 提取）
- 维护者有无回复/解决方案
- 相关度判定

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

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

```bash
# 添加评论（使用 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`](../gitlink-issue/SKILL.md)。

---

## 模式 C：Wiki 增量更新

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

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

### 第 1 步：读取现有 Wiki

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

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

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

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

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

```bash
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

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

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

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

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

---

## 命令速查

本 skill 只涉及知识库分析相关的命令。通用 Issue 操作（创建、查看、更新、关闭、批量操作等）统一使用 [`gitlink-issue`](../gitlink-issue/SKILL.md) 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

- [gitlink-faq-collect](references/gitlink-faq-collect.md) — Issue 数据采集与 Q&A 提取
- [gitlink-faq-cluster](references/gitlink-faq-cluster.md) — 同类问题合并逻辑
- [gitlink-faq-generate](references/gitlink-faq-generate.md) — FAQ 知识库文档生成
- [gitlink-faq-detect](references/gitlink-faq-detect.md) — 重复检测逻辑
- [gitlink-faq-publish](references/gitlink-faq-publish.md) — Wiki 发布
- [weekly-faq-refresh-workflow](examples/weekly-faq-refresh-workflow.md) — 定期刷新示例
- [duplicate-detection-demo](examples/duplicate-detection-demo.md) — 重复检测示例
- [faq-template](examples/faq-template.md) — FAQ 文档模板
- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证和全局参数
