# gitlink-faq 同类问题合并

> 本文档说明如何判断多个 Issue 描述的是同一个问题，以及如何将它们合并为一条 FAQ 条目。

## 合并流程

```
┌─────────────────────────────────────────┐
│ Step 1: Q&A 提取完成                     │
│   每条 Issue → {Q, A, confidence}        │
└──────────────────┬──────────────────────┘
                   ▼
┌─────────────────────────────────────────┐
│ Step 2: 相似度判断                       │
│   比较 Q 的语义相似度                     │
│   比较 A 的答案是否一致                    │
└──────────────────┬──────────────────────┘
                   ▼
┌─────────────────────────────────────────┐
│ Step 3: 合并                             │
│   同一问题 → 综合 Q + 综合 A + 合并来源    │
│   不同问题 → 各自保留                     │
└──────────────────┬──────────────────────┘
                   ▼
┌─────────────────────────────────────────┐
│ Step 4: 按主题标签归类                    │
│   为每条 FAQ 打上主题标签                 │
└─────────────────────────────────────────┘
```

## Step 1: 相似度判断

### 判断 Prompt

```
你正在判断两个 Issue 是否描述的是同一个问题，是否应该合并为一条 FAQ。

## Issue A
Q: {Q_A}
A: {A_A}

## Issue B
Q: {Q_B}
A: {A_B}

请判断它们是否属于同一问题：
- **same**：描述的是同一个问题，只是表述不同（应合并）
- **related**：涉及同一主题但具体问题不同（不合并，但可放同一主题下）
- **different**：完全不同的问题

返回 JSON：
{
  "level": "same|related|different",
  "reason": "一句话判断依据"
}
```

### 合并判断标准

| 判断 | 条件 | 处理 |
|------|------|------|
| **same（合并）** | 两个 Issue 的症状/需求一致，答案也一致或互补 | 合并为一条 FAQ |
| **related（相邻）** | 同一主题但具体问题不同 | 不合并，放在同一主题标签下相邻排列 |
| **different（独立）** | 完全无关 | 各自独立 |

### 合并判断示例

```
✅ 合并：
Issue #16: Q="安装后运行报 command not found？" A="加入 PATH"
Issue #20: Q="gitlink-cli 命令找不到？"       A="检查 PATH 配置"
→ 同一问题，表述不同，合并

❌ 不合并：
Issue #16: Q="安装后运行报 command not found？" A="加入 PATH"
Issue #42: Q="如何配置代理？"                   A="设置 HTTP_PROXY"
→ 都是安装配置主题，但是不同的问题
```

## Step 2: 合并规则

### 合并后的 Q（问题）

- 选择表述更清晰、更完整的那个 Q
- 如果各有优劣，综合提炼一个新的 Q

### 合并后的 A（答案）

- 优先采用 confidence 更高的 A
- 如果两个 A 互补（各有信息），合并为更完整的答案
- 标注"综合自 Issue #A 和 #B 的讨论"

### 合并后的来源

- 列出所有相关 Issue 编号
- 按编号排序

### 合并示例

```json
// 合并前：3 条独立条目
[
  { "issue": 16, "Q": "安装后运行报 command not found？", "A": "加入 PATH", "confidence": "high" },
  { "issue": 20, "Q": "gitlink-cli 命令找不到？", "A": "检查 ~/.local/bin 在 PATH 中", "confidence": "high" },
  { "issue": 35, "Q": "终端提示 command not found: gitlink-cli", "A": "暂未找到解决方案", "confidence": "low" }
]

// 合并后：1 条 FAQ
{
  "Q": "安装 gitlink-cli 后运行报 command not found 怎么办？",
  "A": "将 ~/.local/bin 加入 PATH 环境变量。\\nLinux/Mac: export PATH=$PATH:~/.local/bin\\nWindows: 将 %USERPROFILE%\\.local\\bin 加入系统 PATH",
  "confidence": "high",
  "sources": [16, 20, 35],
  "labels": ["安装配置"]
}
```

## Step 3: 按主题标签归类

合并完成后，为每条 FAQ 打上主题标签。每个标签有对应图标，生成文档时章节标题必须带图标。标签体系：

| 图标 | 主题标签 | 适用范围 | 关键词信号 |
|------|----------|----------|------------|
| 🔧 | `安装配置` | 安装、登录、认证、Token、代理、环境变量 | install, auth, login, token, proxy, config, setup |
| 💻 | `CLI 命令` | 命令使用、参数、输出格式、交互 | command, flag, option, output, format |
| 🔗 | `API 与集成` | API 调用、Webhook、CI/CD | api, webhook, ci, cd, integration |
| 📊 | `数据显示` | 数据不一致、字段缺失、展示 | data, field, display, missing, mismatch |
| 🖥️ | `平台兼容` | OS 兼容、环境依赖 | windows, linux, macos, platform, compatibility |
| ⚡ | `性能` | 响应慢、超时、资源 | slow, timeout, performance, memory |
| 💡 | `功能请求` | 用户希望新增/改进 | 希望、能否、建议、支持 |
| 📦 | `其他` | 不属于以上 | — |

> 一条 FAQ 可以打多个标签。例如一个 Bug 既是 CLI 命令问题又是数据显示问题，就打两个标签。

## 排序规则

同一主题标签内的 FAQ 条目按以下顺序排列：
1. 合并来源多的在前（反映问题更常见）
2. 同等数量按 confidence 高的在前
3. 同等 confidence 按 Issue 编号升序
