# gitlink-faq 文档生成

> 如何将提取合并后的 Q&A 条目组织为结构化 FAQ 知识库 Markdown。

## 生成原则

- **纯 Q&A 格式**：每个条目是"问题 → 答案 + 来源"，不做统计分析
- **按主题归类**：用主题标签组织章节，不用 Bug/Feature/Question 分类
- **答案有据可查**：每条 FAQ 附来源 Issue 编号
- **数据不足时如实说明**：某主题标签下无条目时省略该章节
- **不编造答案**：无法提取答案的标注"待确认"，不强行写

## 文档结构

参考 [`examples/faq-template.md`](../examples/faq-template.md)。

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

> 自动生成 | 收录 {N} 个问题 | 更新时间：{DATE}
> 项目：{OWNER}/{REPO}
>
> 本知识库从项目 Issue 中自动提取，将用户遇到的实际问题与解决方案整理为 FAQ。

## {主题标签 1}

### Q{序号}: {问题}？

**A:** {答案}

> 📎 来源: [#{编号}]({链接})

### Q{序号}: {问题}？

**A:** {答案}

> 📎 来源: [#{编号}]({链接}), [#{编号}]({链接})

## {主题标签 2}

...
```

## 章节生成规则

- 按主题标签分组，每个标签一个 `##` 二级标题，**标题前必须带对应图标**（如 `## 🔧 安装配置`）
- 标签内有 ≥ 1 条 FAQ 即生成该章节
- 标签内无条目则省略该章节
- 章节排列顺序及图标：🔧 安装配置 → 💻 CLI 命令 → 🔗 API 与集成 → 📊 数据显示 → 🖥️ 平台兼容 → ⚡ 性能 → 💡 功能请求 → 📦 其他

## Q&A 条目格式

### 标准格式

```markdown
### Q{序号}: {问题}？

**A:** {答案}

> 📎 来源: [#{编号}]({链接}), [#{编号}]({链接})
```

### 序号规则

- 全局递增编号（跨所有主题标签），如 Q1, Q2, Q3...
- 方便引用和检索

### 答案质量标注（可选）

当答案 confidence 为 `low` 时，可在答案中标注：

```markdown
**A:** 暂未找到明确解决方案，详见 Issue 讨论。⚠️ 待确认
```

## 答案编写规范

### DO（应该做的）

- ✅ 答案具体可操作：给出明确的命令、配置、步骤
- ✅ 综合多个来源：合并多个 Issue 的讨论得出完整答案
- ✅ 标注适用范围：如果答案只适用于特定平台/版本，明确说明
- ✅ 引用原始讨论：来源链接让用户可以查看完整上下文

### DON'T（不应该做的）

- ❌ 不编造答案：没有就是没有，写"待确认"
- ❌ 不做统计分析：不写"XX 模块有 N 个 Bug"
- ❌ 不写长篇大论：答案简洁直接，一两段即可
- ❌ 不假设用户背景：用通俗语言，避免术语黑话

## 功能请求类 FAQ 的特殊处理

功能请求类 Issue 转为 FAQ 时，答案应说明**当前状态**而非"应该怎么做"：

```markdown
### Q{N}: 能否支持 xxx 功能？

**A:** 该功能目前已在 v2.1 中支持，使用 `gitlink-cli xxx --flag` 即可。

> 📎 来源: [#{编号}]({链接})
```

或：

```markdown
### Q{N}: 能否支持 xxx 功能？

**A:** 该功能目前暂不支持。替代方案：可以先通过 yyy 方式实现类似效果。详见 Issue 讨论。

> 📎 来源: [#{编号}]({链接})
```

## 输出文件

生成的 Markdown 保存为 `./issue-faq.md`，展示给用户预览，确认后发布到 Wiki。
