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

gitlink-faq 重复检测

本文档说明如何处理新 Issue 的重复检测——对比已有 FAQ 和历史 Issue。

检测流程

┌────────────────────────────────────────────┐
│ Step 1: 确定搜索目标                        │
│   编号 → issue +view 获取目标               │
│   关键词 → 进入全量搜索模式                  │
└────────────────┬───────────────────────────┘
                 ▼
┌────────────────────────────────────────────┐
│ Step 2: 拉取全量列表                        │
│   issue +list --state open                 │
│   issue +list --state closed               │
│   标题匹配筛选候选 Issue                     │
└────────────────┬───────────────────────────┘
                 ▼
┌────────────────────────────────────────────┐
│ Step 3: 自动读详情（不需等用户确认）          │
│   对每条候选 → issue +view --number N       │
│   提取: subject + description + journals   │
└────────────────┬───────────────────────────┘
                 ▼
┌────────────────────────────────────────────┐
│ Step 4: 分析 & 输出结论                      │
│   综合标题+描述+journals 给出：              │
│   - 核心讨论内容摘要                         │
│   - 维护者是否有回复/方案                     │
│   - 相关度判定                              │
└────────────────┬───────────────────────────┘
                 ▼
┌────────────────────────────────────────────┐
│ Step 5: 用户确认后执行写操作（可选）          │
│   > 0.85 → comment + label                 │
│   0.6-0.85 → comment only                  │
│   < 0.6 → 无需操作                         │
└────────────────────────────────────────────┘

相似度匹配 Prompt

你正在判断一个新提交的 Issue 是否与已有问题重复。

## 新 Issue
标题: {subject}
描述: {description}

## 候选匹配列表
{候选列表，每条含: 来源、标题、摘要}

请对每个候选给出 0-1 的相似度评分：
- > 0.85: 问的是同一个问题（只是表述不同）
- 0.6-0.85: 有关联但不是同一个问题（如"登录报 401"
  和"Token 配置"）
- < 0.6: 无关

返回 JSON 数组，按相似度降序排列。

输出 JSON

{
  "target_issue": {
    "number": 245,
    "title": "登录页面打不开",
    "description": "点击登录按钮后页面白屏..."
  },
  "matches": [
    {
      "source": "FAQ",
      "entry": "Q3: 登录失败或提示 401 错误怎么处理？",
      "similarity": 0.92,
      "level": "high_duplicate"
    },
    {
      "source": "issue",
      "number": 142,
      "title": "登录页面显示空白",
      "summary": "用户反馈登录页白屏，最终确认是浏览器缓存问题",
      "similarity": 0.88,
      "level": "high_duplicate"
    },
    {
      "source": "issue",
      "number": 178,
      "title": "Token 刷新机制咨询",
      "summary": "询问 Token 有效期和刷新策略",
      "similarity": 0.65,
      "level": "related"
    }
  ],
  "recommendation": "high_duplicate",
  "top_match_similarity": 0.92
}

评论模板

高度重复（similarity > 0.85）

你好！检测到你的问题与已有内容高度相似：

- 📖 [FAQ - {条目名}]({FAQ 链接})
- 🔗 相关 Issue: #{编号} - {标题}

建议先查看以上内容。如果无法解决你的问题，请补充更多细节（如错误日志、操作步骤），我们会进一步排查。

可能相关（0.6 ~ 0.85）

你好！你的问题可能与以下内容相关，供参考：

- {匹配条目列表}

如果这些不解决你的问题，请提供更多上下文。

注意事项

• 不要误判：问题表述相似但根因不同（如"打不开"可能是网络问题也可能是代码 bug），相似度 < 0.85 时只建议参考不打标签
• 同一用户的多条 Issue：如果同一用户就同一问题连续发 Issue，先合并讨论再判断
• 对事不对人：评论始终友好，引导用户找到答案而非指责