forked from Gitlink/gitlink-cli
117 lines
3.2 KiB
Markdown
117 lines
3.2 KiB
Markdown
# 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。
|