标记重复的PR和Issues

标记重复的 PR 和 Issues

当维护者需要判断一个拉取请求 (PR) 或问题 (Issue) 是否与现有工作重复时，使用此技能。

此技能专为维护者的分类和分组工作而设计。 不用于审查 PR 的实现质量。

必需的先决设置

在完成此设置之前，请不要写入重复分组或注解。 只读的发现工作仍可使用 gitcrawl 和实时的 gh 进行。

配套技能

• 首先使用 $gitcrawl 进行本地候选发现。
• 当 prtags 技能可用时，使用 prtags 仓库中 skills/prtags/SKILL.md 定义的技能。

安装 CLI

从下方固定的发布版本安装 prtags。 不要依赖旧的本地构建，除非维护者明确要求测试未发布的行为。

prtags CLI 安装路径：

GOBIN="$HOME/.local/bin" go install github.com/dutifuldev/prtags/cmd/[email protected]

prtags 位于 OpenClaw 组织之外，因此此安装会固定到一个经过审核的版本，该版本由 Go 模块代理解析并由公共校验和数据库验证。GOBIN 将安装的可执行文件保存在与之前安装程序相同的用户本地目录中，因此现有的 $HOME/.local/bin 在 PATH 中会继续解析新安装的版本。 不要通过将远程脚本管道传输到 shell 中来安装，也不要将安装指向某个分支：这两种方式都会执行第三方在运行时提供的任意内容，并拥有维护者自身的权限。升级到更新的 prtags 版本是对本文件的审核变更，而不是任务中间步骤。

认证 prtags

prtags 应通过 OAuth 设备流使用维护者自己的 GitHub 帐户登录。 不要在交互式分类中使用共享的维护者令牌。

prtags auth login
prtags auth status

预期结果是 prtags 将登录的维护者身份存储在本地，并使用该帐户进行经过身份验证的写入操作。

缺失设置时的规则

在开始工作流程之前，不要要求进行预先检查。 按照正常步骤进行，直到你实际需要某个工具或帐户状态。

一旦你在写入步骤中发现 prtags 缺失或未登录，请立即停止。 之后不要以部分写入模式继续执行。

如果 prtags 缺失，请要求用户运行 安装 CLI 中的固定安装命令。 将该部分作为已安装版本的唯一来源；不要临时创建其他安装路径。

如果 prtags auth status 显示用户未登录，请要求用户运行：

prtags auth login

只有在缺失的工具或登录状态被修复后才能恢复。

读取路径默认行为

在此工作流程中，进行候选发现时，首先使用 gitcrawl。 将其视为相关 Issues、重复尝试和已关闭线程的本地历史记录和聚类源。

在做出可操作的判断之前，对目标线程和任何候选对象使用实时的 gh 或 gh api。 当 gitcrawl 因具体原因（例如：目标或候选对象尚不存在；本地数据明显过时或不完整；gitcrawl 报错、超时或缺少所需的邻居/搜索数据）而缺失或过时时，使用实时 GitHub。

当你回退到实时 GitHub 搜索时，请说明你进行了回退及其原因。

如果后续的 prtags 目标级写入因其自身镜像尚未同步而失败，请停止并报告管理后端缺少目标对象，而不是强制使用回退写入路径。

目标

对于每个目标 PR 或 Issue：

1. 收集重复证据
2. 判断是否为真正的重复
3. 为该重复集群创建或复用一个 prtags 分组
4. 将维护者的判断保存到 prtags 中
5. 当该集成配置后，依赖正常的 prtags 分组写入来驱动 GitHub 评论同步

工具职责

按以下边界使用工具：

• gitcrawl：用于候选生成和历史上下文
  • 首先用于本地标题/正文搜索、邻居查找、聚类和已关闭线程发现
  • 将每个候选对象视为线索，直到实时 GitHub 确认
• gh：用于实时 GitHub 真相
  • 用于目标状态、正文、评论、审查、文件、关联 Issues 以及当前打开/关闭/合并状态
  • 仅在 gitcrawl 过时、数据缺失或无法表达所需查询时使用 gh search
• prtags：维护者的管理层
  • 用于创建或复用一个重复分组
  • 用于保存重复状态、置信度、理由和分组摘要
  • 作为面向 GitHub 的分组评论的真实来源

工作规则

• 不要仅仅因为标题相似就将其判定为重复。
• 不要仅仅因为相同文件被修改就将其判定为重复。
• 一个重复集群应基于相同的面向用户的问题、相同的意图以及实质性重叠的实现或调查上下文。

一个分组规则

将重复分组视为互斥的。 一个 PR 或 Issue 一次最多只能属于一个重复分组。

这意味着：

• 在创建新分组之前，搜索现有分组是否已经代表了相同的重复故事
• 如果目标似乎已属于另一个不同的重复分组，请停止并首先解决该冲突
• 不要仅仅因为措辞略有不同就为同一目标创建第二个分组
• 如果两个可能存在的现有分组重叠，并且你无法安全地合并判断，请停止并向维护者询问

此规则比速度更重要。 该技能应保持每个问题一个连贯的重复集群，而不是多个近似的重复集群。

一个好的重复分组应该代表什么

一个重复分组应描述根本问题和预期的修复方向。 不要仅因为它们共享一个关键词就将项目分组。

良好的分组形态：

• 相同的面向用户的错误或相同的面向维护者的任务
• 相同的子系统或代码表面
• 相同的预期变更方向
• 相同的可能重复解决路径

不良的分组形态：

• “所有涉及 Slack 的 PR”
• “所有提到重试的 Issues”
• “所有与认证相关的项目”

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

示例：

• gateway: 通道状态启动时的回归问题
• whatsapp: QR 预检超时处理
• release: 跨操作系统验证交接的间隙

证据清单

在声明重复之前，至少从两个类别收集证据。 gitcrawl 邻居、搜索结果和聚类成员资格仅作为候选生成，其本身不足以作为证据。

对于 PR：

• 相同或几乎相同的问题陈述
• 相同或重叠的文件变更范围
• 相同的修复方向
• 相同的子系统和故障模式
• 相同的已链接 Issue 或相同的用户可见症状

对于 Issues：

• 相同的用户可见问题
• 相同的重现步骤或相同的故障模式
• 相同的可能修复区域
• 已链接或讨论过的相同 PR
• 相同的维护者已引导向相同的重复分组

如果你仅有措辞相似性，则不足以作为证据。

步骤 1：读取目标

从读取目标本身开始。 使用实时 GitHub 获取当前目标状态。

对于 PR：

gh pr view <编号> --json number,title,state,mergedAt,body,closingIssuesReferences,files,comments,reviews,statusCheckRollup

对于 Issue：

gh issue view <编号> --json number,title,state,body,comments,closedAt

记录：

• 目标类型和编号
• 标题
• 问题陈述
• 提出的意图
• 子系统
• 其状态（打开、关闭或合并）
• 是否已经有人为提及可能的重复线程

步骤 2：使用 Gitcrawl 广泛搜索

首先使用 gitcrawl，因为它是本地 OpenClaw 历史和聚类源。 除非 gitcrawl 数据缺失、过时或失败，否则不要切换到广泛的实时 GitHub 搜索。

从目标和附近线程开始：

gitcrawl threads openclaw/openclaw --numbers <issue-或-pr-编号> --include-closed --json
gitcrawl neighbors openclaw/openclaw --number <issue-或-pr-编号> --limit 20 --json

然后搜索关键短语和子系统术语：

gitcrawl search openclaw/openclaw --query "<标题或正文中的关键短语>" --mode hybrid --limit 20 --json
gitcrawl search openclaw/openclaw --query "<子系统或错误短语>" --mode hybrid --limit 20 --json

检查可能的聚类：

gitcrawl cluster-detail openclaw/openclaw --id <聚类-id> --member-limit 20 --body-chars 280 --json

对于 PR，使用实时文件数据验证可能的代码重叠：

gh pr view <候选-pr> --json number,title,state,mergedAt,files,body,comments,reviews

对于 Issues，实时验证可能的重复 Issue 状态和评论：

gh issue view <候选-issue> --json number,title,state,body,comments,closedAt

步骤 3：使用实时 GitHub 搜索填补空白

在以下情况时，在 gitcrawl 之后使用有针对性的实时 GitHub 搜索：

• 目标太新，本地存储中尚无记录
• 评论或审查很重要，但本地存储中缺少
• 确切短语未出现在本地结果中，但 Issue/PR 足够新，GitHub 应该知道它

gh search prs --repo openclaw/openclaw --match title,body --limit 50 -- "<关键短语>"
gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "<关键短语>"
gh search issues --repo openclaw/openclaw --match comments --limit 50 -- "<错误或维护者短语>"

步骤 4：决定结果

从以下结果中选择一个：

• not_duplicate (非重复)
• duplicate_needs_judgment (需要判断重复)
• duplicate_confirmed (确认重复)

仅在证据足够强，维护者可以安全地关闭或重新标记重复项时，才使用 duplicate_confirmed。

在以下情况使用 duplicate_needs_judgment：

• 问题看起来很相似，但实现目标不同
• 代码重叠较弱
• Issue 措辞模糊
• 可能存在两种有效的重复分组解释
• 目标似乎与两个现有的重复分组相交

步骤 5：复用或创建一个 prtags 分组

在创建分组之前，搜索 prtags 中的现有分组。

从对分组的文本搜索开始：

prtags search text -R openclaw/openclaw "<问题短语>" --types group --limit 10
prtags search similar -R openclaw/openclaw "<问题摘要>" --types group --limit 10
prtags group list -R openclaw/openclaw

检查可能的分组：

prtags group get <分组-id>
prtags group get <分组-id> --include-metadata

在以下情况复用现有分组：

• 它代表了相同的问题
• 它已经包含了明显相关的成员
• 添加目标对象后，分组仍保持连贯性

不要仅仅因为 gitcrawl 将几个 PR 或 Issues 放在彼此附近，就扩大现有分组。 在添加新成员之前，确认实际的实现路径和维护者意图仍然匹配。

仅在没有现有分组明确匹配时才创建新分组。

使用基于问题的标题和基于意图的描述创建分组：

prtags group create -R openclaw/openclaw \
  --kind mixed \
  --title "<以问题为中心的标题>" \
  --description "<相同的意图、子系统和重复解决路径>" \
  --status open

然后添加目标对象和任何已知的重复成员：

prtags group add-pr <分组-id> <pr-编号>
prtags group add-issue <分组-id> <issue-编号>

如果目标似乎已经属于另一个重复分组，并且你无法安全地复用该分组，请停止。 不要创建第二个分组。

步骤 6：确保注解字段存在

使用 field ensure，使此技能幂等。

推荐的目标级字段：

prtags field ensure -R openclaw/openclaw --name duplicate_status --scope pull_request --type enum --enum-values not_duplicate,candidate,confirmed --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_status --scope issue --type enum --enum-values not_duplicate,candidate,confirmed --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope pull_request --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope issue --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope pull_request --type text --searchable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope issue --type text --searchable

推荐的分组级字段：

prtags field ensure -R openclaw/openclaw --name duplicate_confidence --scope group --type enum --enum-values low,medium,high --filterable
prtags field ensure -R openclaw/openclaw --name duplicate_rationale --scope group --type text --searchable
prtags field ensure -R openclaw/openclaw --name cluster_summary --scope group --type text --searchable

步骤 7：在 prtags 中保存维护者的判断

对于 PR：

prtags annotation pr set -R openclaw/openclaw <pr-编号> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<相同的问题、相同的修复方向、重叠的文件和评论>"

对于 Issue：

prtags annotation issue set -R openclaw/openclaw <issue-编号> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<相同的用户可见问题和相同的预期修复路径>"

对于分组：

prtags annotation group set <分组-id> \
  duplicate_confidence=high \
  cluster_summary="<一句话问题摘要>" \
  duplicate_rationale="<为什么这些项目属于一个重复集群>"

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

如果某个 PR 或 Issue 的注解写入因 prtags 无法解析目标而失败，不要强制使用回退写入路径。 保留你能够写入的分组状态，报告管理后端仍然缺少目标对象，并将最终注解推迟到稍后的步骤。

……

[为翻译截断]