# gitlink-faq 文档生成

> 如何将分类+聚类结果组织为结构化知识库 Markdown。

## 生成原则

- **按类型分章节**：Bug → 功能请求 → 使用问题，每章独立
- **按热度排序**：同类内 Issue 数量多的排在前面
- **数据不足时省略**：某类型 < 2 条时标注"暂无足够数据"，不强行展开
- **来源可追溯**：每条结论后附来源 Issue 编号

## 文档结构

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

```markdown
# 📊 Issue 知识库

> 自动生成 | 数据来源：已关闭 Issue（{N} 条有效）
> 更新时间：{DATE}
> 项目：{OWNER}/{REPO}

## 📂 概览

| 类型 | 数量 | 聚类数 |
|------|------|--------|
| 🐛 Bug 报告 | {N} | {M} 个模块 |
| 💡 功能请求 | {N} | {M} 个领域 |
| 📖 使用问题 | {N} | {M} 个主题 |

---

## 🐛 Bug 高频模块

### {模块名}（{N} 个 Bug）

**典型症状**: {描述}
**涉及 Issue**: [#{编号}]({链接}), [#{编号}]({链接})
**已知修复**: {如有则写，无则写"暂未统一修复"}

### {模块名}（{N} 个 Bug）

...

> 如该类 < 2 条，标注"暂无高频 Bug 模式"。

---

## 💡 功能请求热度

### {功能领域}（{N} 个请求）🔥

**用户期望**: {一句话总结}
**涉及 Issue**: [#{编号}]({链接}), [#{编号}]({链接})

### {功能领域}（{N} 个请求）

...

> 如该类 < 2 条，标注"暂无热门功能请求"。

---

## 📖 常见使用问题

### Q{N}: {问题}？

**A:** {答案}

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

...

> 如该类 < 2 条，标注"暂无常见使用问题"。

---

> 💡 本文档由 gitlink-faq 自动生成，建议每 1-2 周更新一次。
```

## 热度标注

| Issue 数 | 热度 |
|----------|------|
| ≥ 5 | 🔥🔥🔥 高频 |
| 3-4 | 🔥🔥 常见 |
| 2 | 🔥 偶发 |
| 1 | 不纳入（标注为单次事件） |

## 答案/解决状态标注

对于 Bug 和功能请求，标注其当前状态：

| 状态 | 标注 | 条件 |
|------|------|------|
| ✅ 已修复/已实现 | 绿色标记 | Issue 关闭且 journals 中有修复记录 |
| 🔧 部分修复 | 黄色标记 | 有修复但不完整 |
| ❓ 状态不明 | 无标记 | journals 为空或无明确解决记录 |
