重复 PR/Issue 智能分组与标注技能

一、技能概述

该技能用于当维护者需要决定某个 PR 或 Issue 是否与已有工作重复时使用。它通过组合三个工具完成端到端的重复检测与标注工作流：

• gitcrawl：本地候选发现与历史上下文层，用于标题/正文搜索、邻居线程、聚类和已关闭线程发现

• gh（GitHub CLI）：实时 GitHub 真相源，用于获取目标状态、正文、评论、审查、文件、链接的 Issue 以及当前的 open/closed/merged 状态

• prtags：维护者策展层，用于创建或复用重复分组、保存重复状态/置信度/理由/分组摘要，并作为 GitHub 面向分组评论的真相源

二、核心功能

1. 工具边界与职责

2. 重复判断标准（严格门槛）

技能不会仅因为标题相似或相同文件变更就判定为重复。一个重复聚类应基于：

• 相同的用户侧问题

• 相同的意图

• 实质性重叠的实现或调查上下文

在宣布重复之前，必须从至少两个类别收集证据：

仅有措辞相似性不足以判定重复。

3. 单组规则（One-Group Rule）

重复组是互斥的。一个 PR 或 Issue 在同一时间应属于至多一个重复组：

• 创建新组前，搜索是否存在已代表相同重复故事的现有组

• 如果目标似乎已属于另一个重复组，停止并先解决冲突

• 不要因为措辞略有不同就为同一目标创建第二个组

• 如果两个看似合理的现有组重叠且无法安全合并判断，停止并向维护者询问

此规则比速度更重要——每个问题应保持一个连贯的重复聚类，而非多个近重复聚类。

4. 好的重复组 vs 坏的重复组

好的分组形状：

• 相同的用户侧 Bug 或相同的维护者侧任务

• 相同的子系统或代码表面

• 相同的预期变更方向

• 相同的重复解决路径

坏的分组形状（太宽泛）：

• “所有触及 Slack 的 PR”

• “所有提到 retry 的 Issue”

• “所有认证相关的条目”

组标题应命名真实的问题，组描述应总结意图和代码表面。

5. 标准工作流程（8 步）

Step 1：读取目标

• 使用 gh pr view 或 gh issue view 获取目标的实时状态

• 记录：类型/编号、标题、问题陈述、提议意图、子系统、是否 open/closed/merged、人类是否已提及可能的重复线程

Step 2：使用 Gitcrawl 广泛搜索

gitcrawl threads openclaw/openclaw --numbers <num> --include-closed --json
gitcrawl neighbors openclaw/openclaw --number <num> --limit 20 --json
gitcrawl search openclaw/openclaw --query "<phrase>" --mode hybrid --limit 20 --json
gitcrawl cluster-detail openclaw/openclaw --id <id> --member-limit 20 --body-chars 280 --json

不要在 gitcrawl 缺失数据、过时或失败之前切换到广泛的实时 GitHub 搜索。

Step 3：针对缺口使用 Live GitHub Search
仅在以下情况使用：

• 目标对本地存储来说太新

• 评论或审查很重要但本地存储缺少

• 精确短语未出现在本地结果中但 Issue/PR 足够新

Step 4：决定结果

• not_duplicate —— 不是重复

• duplicate_needs_judgment —— 需要人工判断

• duplicate_confirmed —— 重复已确认（仅当证据足够强，维护者可安全关闭或重新标记重复项时使用）

Step 5：复用或创建一个 prtags 组

• 先搜索现有组：prtags search text、prtags search similar、prtags group list

• 复用现有组：当它代表相同问题且已包含明确相关的成员时

• 创建新组：仅当没有现有组明确匹配时，使用基于问题的标题和基于意图的描述

• 如果目标似乎已属于另一个重复组且无法安全复用该组，停止

Step 6：确保标注字段存在（幂等性）

• 目标级字段：duplicate_status（enum: not_duplicate, candidate, confirmed）、duplicate_confidence（enum: low, medium, high）、duplicate_rationale（text）

• 组级字段：duplicate_confidence、duplicate_rationale、cluster_summary

Step 7：在 prtags 中保存维护者判断

• 使用 prtags annotation pr set 或 prtags annotation issue set 保存每个目标的判断

• 证据不完整时，设置 duplicate_status=candidate 并降低置信度

• 如果写入失败（prtags 无法解析目标），不要强制 fallback 写入路径

Step 8：让 prtags 同步分组评论

• 不要直接创建 GitHub 评论——prtags 拥有 GitHub 评论作为分组状态的派生投影

• 分组写入已自动入队派生评论投影（如果配置了评论同步）

• 仅在修复或重试路径中手动使用：prtags group sync-comments

三、主要用途

1. 维护者日常分类（Triage）
   当维护者需要判断一个 PR 或 Issue 是否与已有工作重复时，提供系统化的证据收集和决策流程。

2. 重复 Issue/PR 聚类管理
   通过 gitcrawl 的聚类功能和 prtags 的分组能力，将相关的工作项组织成连贯的重复聚类。

3. 维护者判断的持久化与同步
   将维护者的重复判断、置信度和理由保存在 prtags 中，并通过 prtags 自动同步到 GitHub 评论。

4. 冲突检测与升级
   当目标似乎属于两个不同的重复组、分组不清晰、措辞匹配但实现目标不同、或两个 PR 触及相同文件但原因不同时，停止并升级而非强制做出重复决定。

四、前置准备

安装与认证

1. 安装 prtags：

   curl -fsSL https://raw.githubusercontent.com/dutifuldev/prtags/main/scripts/install-prtags.sh | bash -s -- --bin-dir "$HOME/.local/bin"

2. 认证 prtags（使用维护者自己的 GitHub 账号，通过 OAuth 设备流）：

   prtags auth login
   prtags auth status

3. 缺失设置规则：不要在执行工作流之前要求预先检查。按正常步骤进行，直到实际需要工具或账户状态。一旦发现 prtags 缺失或未登录写入步骤，立即停止。

五、与其他技能的协作

六、输出格式

返回简短的维护者报告，包含以下部分：

• Decision：duplicate_confirmed | duplicate_needs_judgment | not_duplicate

• Target：PR # | Issue #

• Confidence：high | medium | low

• Evidence：- ... - ... - ...

• prtags actions：- reused group | created group - added members: ... - annotations written: ... - comment sync: automatic if configured | manual repair triggered for

七、重要原则

1. 不因标题相似就判定重复

2. 不因相同文件变更就判定重复

3. 单组规则：每个目标同一时间属于至多一个重复组

4. 证据门槛：宣布重复前必须从至少两个类别收集证据

5. 仅措辞相似不足够

6. prtags 拥有 GitHub 评论：不直接创建 GitHub 评论

7. 冲突时停止并升级：不强制做出模糊的重复决定

8. 缺失设置时立即停止：不在部分写入模式下继续

八、总结

Tag Duplicate PRs and Issues 是一个面向维护者的重复 PR/Issue 智能分组与标注技能，通过 gitcrawl 的本地候选发现、gh 的实时验证和 prtags 的策展层，系统化地判断一个 PR 或 Issue 是否与已有工作重复，并将维护者的判断持久化并同步到 GitHub。它强调严格的证据门槛（至少两个证据类别）、单组互斥规则和冲突时升级而非强制判断，确保重复聚类的质量和决策的可追溯性。该技能适用于 OpenClaw 项目维护者在日常分类（triage）中高效管理重复 PR/Issue的场景。