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

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 编号
• 按编号排序

合并示例

// 合并前：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 编号升序