---
name: gitlink-faq
version: 1.3.0
description: "Issue 知识库：从项目 Issue 自动分类（Bug/功能请求/使用问题），按类型归纳聚类，生成结构化知识库发布到 Wiki；增量更新已有知识库；检测新 Issue 是否与已有问题重复。当用户需要整理 Issue、归纳 Issue、总结常见问题/Bug、建立知识库、更新知识库、检查重复 Issue、查重时触发。通用 Issue 操作（创建/查看/更新/关闭/评论等）请使用 gitlink-issue skill。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli issue --help"
---

# gitlink-faq（Issue 知识库）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 写入/删除操作前，务必先确认用户意图。默认 dry-run 预览，用户确认后再执行。**
**CRITICAL — 只读操作（`issue +list`、`issue +view`、`wiki +view`）自动连续执行，不要逐个请求用户确认。数据采集和分析阶段一气呵成，仅在最终写入步骤前暂停确认。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)

## 运行模式

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

---

## 模式 A：Issue 归纳（6 步）

当用户说 **"整理 Issue"、"归纳已关闭 Issue"、"总结项目问题"、"建立知识库"** 等时，执行以下流程。

### 第 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 步：筛选 + 读取详情（依靠 description）

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

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

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

提取字段：`subject`（标题）、`description`（描述）。

**description 是核心分析源**：
- 部分 Issue 的 description 非常详细（含复现步骤、环境信息、修复建议）
- description 的质量直接决定分析深度
- `comment_journals_count` 数值可参考（表示讨论热度），但实际评论内容无法通过 API 获取（见下方 API 限制）

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

### 第 3 步：Issue 类型分类

对每条 Issue，AI 根据 (subject + description) 判断类型。**不要因为"缺少 journals"或"状态未关闭"而排除 Issue**——是否有分析价值取决于内容本身，不是状态。

| 类型 | 判断依据 | 纳入条件 | 分析价值 |
|------|----------|----------|----------|
| **Bug 报告** | 描述异常行为、报错、与预期不符 | description 非空 或 subject 明确描述症状 | 高频 Bug = 模块质量信号 |
| **功能请求** | 建议新增能力、改进体验 | 保留。高频请求反映用户需求 | 用户需求优先级 |
| **使用问题** | 不知道怎么用、配置不清楚 | 保留。即使未回复也是需求信号 | 文档/体验改进方向 |
| **其他** | 不属于以上三类 | 标题无实质内容则忽略 | 低 |

**输出**：每条 Issue 带上类型标签。

**宽松原则**：宁可多留一条低价值的，也别漏掉一条有洞察的。不确定类型的归入"其他"而非丢弃。

### 第 4 步：按类型分别聚类

将同类型的 Issue 按语义相似度聚类。不同类型聚类维度不同：

| 类型 | 聚类维度 | 聚类目标 |
|------|----------|----------|
| Bug 报告 | 按**出问题的模块/功能**归类 | 找出"哪个模块 Bug 最多"、"同类 Bug 的共同根因" |
| 功能请求 | 按**请求的功能领域**归类 | 找出"用户最想要什么能力"、"哪些增强呼声最高" |
| 使用问题 | 按**操作场景**归类 | 传统 Q&A：提炼"问题 → 答案" |

**Bug 聚类输出**：

```json
{
  "module": "Issue 数据显示",
  "bug_count": 4,
  "pattern": "CLI 返回数据与网页端不一致、字段缺失",
  "affected_issues": [5, 7, 15, 18],
  "typical_symptom": "issue +view / pr +view 返回结果缺少关键字段或与网页端不一致"
}
```

**功能请求聚类输出**：

```json
{
  "feature_area": "API 能力增强",
  "request_count": 3,
  "pattern": "希望 API 支持更多查询/操作能力",
  "affected_issues": [9, 14, 21],
  "common_ask": "支持按序号查询 Issue、读取仓库文件、返回完整时间字段"
}
```

**使用问题聚类输出**（仅当同类 ≥2 条时生成 Q&A）：

```json
{
  "topic": "安装配置",
  "question": "gitlink-cli 安装后无法运行怎么办？",
  "answer": "检查 PATH、确认平台支持，详见安装文档",
  "source_issues": [16, 20]
}
```

### 第 5 步：生成知识库文档

按以下结构组织 Markdown：

```markdown
# 📊 Issue 知识库

> 自动生成 | 数据来源：已关闭 Issue（{N} 条）
> 更新时间：{DATE}

## 🐛 Bug 高频模块

### {模块名}（{N} 个 Bug）
- **典型症状**: ...
- **涉及 Issue**: #A, #B, #C
- **已知修复**: ...（如有）

## 💡 功能请求热度

### {功能领域}（{N} 个请求）
- **用户期望**: ...
- **涉及 Issue**: #D, #E, #F

## 📖 常见使用问题

### Q: {问题}？
**A:** {答案}
> 来源: #G, #H
```

根据实际数据量，若某类型 Issue 过少（<2 条），该章节可省略或合并到"其他"。

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

完成后保存为 `./issue-knowledge-base.md`，展示给用户预览。

### 第 6 步：发布到 Wiki

用户确认后：

```bash
# 首次创建
gitlink-cli wiki +create --title "Issue-知识库" --file ./issue-knowledge-base.md

# 后续更新
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-knowledge-base.md
```

---

## 模式 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 加到知识库里"、"更新 Wiki 页面"、"补充到知识库"、"同步最新 Issue 到 Wiki"** 等时执行。

**核心思路**：不是重新生成整个知识库，而是读取现有 Wiki 内容 → 拉取新 Issue → 分类合并 → 更新 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

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

将新 Issue 按类型归入现有章节：

- **Bug**：归入"Bug 高频模块"，若属于已有模块则追加，否则新建模块条目
- **功能请求**：归入"功能请求热度"，若属于已有领域则合并，否则新建领域条目
- **使用问题**：归入"常见使用问题"，新建 Q&A 条目

合并时更新：
- Issue 计数（总数、各类型数量）
- 更新时间
- 受影响的 `-- 涉及 Issue` 列表

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

将合并后的完整 Markdown 展示给用户预览，标注新增/变更的部分（可用 `[NEW]` 标记）。

### 第 6 步：更新 Wiki

用户确认后：

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

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

---

## 命令速查

本 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 类型不能混在一起聚类（Bug 和功能请求本质不同）
- **所有结论必须有来源**：Bug 模式、功能热度、Q&A 答案都必须来自实际 Issue，不编造
- **数据不足时如实说明**：某类型 < 2 条时不强行归纳，标注"暂无足够数据"
- **评论语气友好**：重复检测是帮助用户，不是指责
- **用户确认优先**：所有写入操作前先预览

## References

- [gitlink-faq-collect](references/gitlink-faq-collect.md) — Issue 数据采集
- [gitlink-faq-cluster](references/gitlink-faq-cluster.md) — 分类+聚类算法
- [gitlink-faq-generate](references/gitlink-faq-generate.md) — 知识库文档生成
- [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) — 文档模板
- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证和全局参数
