forked from Gitlink/gitlink-cli
141 lines
5.7 KiB
Markdown
141 lines
5.7 KiB
Markdown
# 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 编号升序
|