gitlink-cli/skills/gitlink-faq/references/gitlink-faq-generate.md

gitlink-faq 文档生成

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

生成原则

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

文档结构

参考 examples/faq-template.md。

# 📖 {项目名} FAQ 知识库

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

## {主题标签 1}

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

**A:** {答案}

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

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

**A:** {答案}

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

## {主题标签 2}

...

章节生成规则

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

Q&A 条目格式

标准格式

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

**A:** {答案}

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

序号规则

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

答案质量标注（可选）

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

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

答案编写规范

DO（应该做的）

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

DON'T（不应该做的）

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

功能请求类 FAQ 的特殊处理

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

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

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

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

或：

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

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

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

输出文件

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