標記重複的 PR 與 Issue

標記重複的 PR 與 Issue 是做什麼的？

當維護者需要判斷一個 Pull Request 或 Issue 是否與現有工作重複時，使用此技能。

此技能用於維護者分類與分組。 它不適用於審查 PR 的實作品質。

必要設定

在完成此設定之前，不要撰寫重複群組或註解。 唯讀的探索仍可使用 gitcrawl 和即時 gh 來進行。

附屬技能

首先使用 $gitcrawl 進行本地候選項探索。 當 prtags 倉庫中的 skills/prtags/SKILL.md 可用時，使用其中的 prtags 技能。

安裝 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。 將其視為相關問題、重複嘗試和已關閉討論串的本地歷史記錄與聚類層。

在做出可操作的判斷之前，請使用即時 gh 或 gh api 來查詢目標討論串和任何候選項。 當 gitcrawl 因具體原因遺失或過時時，使用即時 GitHub，例如：

• 目標或候選項尚未出現
• 針對您需要的決策，本地資料明顯過時或不完整
• gitcrawl 錯誤、超時或缺少所需的鄰居/搜尋資料

當您改用即時 GitHub 搜尋時，請註明您這樣做了以及原因。

如果稍後的 prtags 目標層級寫入因其自身的鏡像尚未跟上而失敗，請停止並回報管理後端缺少目標物件，而不是強制使用備用寫入路徑。

目標

對於每個目標 PR 或 Issue：

1. 收集重複證據
2. 判斷是否為真正的重複
3. 為該重複集群建立或重用一個 prtags 群組
4. 將維護者的判斷儲存在 prtags 中
5. 當配置了 GitHub 評論同步時，依賴正常的 prtags 群組寫入來驅動它

工具角色

請按照以下界限使用這些工具：

• gitcrawl 用於候選項產生與歷史脈絡
  • 首先使用它進行本地標題/內文搜尋、鄰居、叢集和已關閉討論串的探索
  • 在即時 GitHub 確認之前，將每個候選項視為線索
• gh 用於即時 GitHub 資料
  • 用於目標狀態、內文、評論、審查、檔案、連結的 Issue 和目前的開啟/關閉/合併狀態
  • 僅當 gitcrawl 過時、缺失資料或無法表達所需查詢時，才使用 gh search
• prtags 是維護者的管理層
  • 用於建立或重用一個重複群組
  • 用於儲存重複狀態、信心水準、理由和群組摘要
  • 作為面向 GitHub 的群組評論的真實來源

工作規則

• 不要僅因為標題相似就稱某個東西為重複。
• 不要僅因為相同的檔案變更就稱某個東西為重複。
• 一個重複集群應基於相同的使用者面對問題、相同的意圖，以及大幅重疊的實作或調查脈絡。

一個群組規則

將重複群組視為互斥的。 一個 PR 或 Issue 一次最多只能屬於一個重複群組。

這表示：

• 在建立新群組之前，先搜尋一個已存在且代表相同重複故事的群組
• 如果目標似乎已經屬於另一個不同的重複群組，請先停止並解決該衝突
• 不要僅因為措辭略有不同就為同一個目標建立第二個群組
• 如果兩個看似合理的現有群組重疊，且您無法安全地合併判斷，請停止並詢問維護者

此規則比速度更重要。 此技能應為每個問題維護一個連貫的重複集群，而不是多個近似重複的集群。

一個好的重複群組應代表什麼

一個重複群組應描述根本問題和預期的修復方向。 不要僅因為它們共享一個關鍵字就將項目分組。

良好的群組形狀：

• 相同的使用者面對錯誤或相同的維護者面對任務
• 相同的子系統或程式碼表面
• 相同的預期變更方向
• 相同的可能重複解決路徑

不良的群組形狀：

• "所有觸及 Slack 的 PR"
• "所有提到重試的 Issue"
• "所有與驗證相關的項目"

群組標題應命名真正的問題。 群組描述應總結意圖和程式碼表面。

範例：

• gateway: 從通道狀態啟動的迴歸問題
• whatsapp: QR 預檢逾時處理
• release: 跨作業系統驗證交接缺口

證據檢查清單

在宣告重複之前，從至少兩個類別收集證據。 gitcrawl 的鄰居、搜尋結果和集群成員資格僅算作候選項產生，不足以作為證明。

對於 PR：

• 相同或幾乎相同的問題陳述
• 相同的變更檔案或重疊的檔案範圍
• 相同的修復方向
• 相同的子系統和失敗模式
• 相同的連結 Issue 或相同的使用者可見症狀

對於 Issue：

• 相同的使用者可見問題
• 相同的重現故事或相同的失敗模式
• 相同的可能修復區域
• 已連結或討論的相同 PR
• 已引導朝向相同重複分組的相同維護者

如果您僅有措辭相似性，那是不夠的。

步驟 1：讀取目標

首先讀取目標本身。 使用即時 GitHub 獲取目標的當前狀態。

對於 PR：

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

對於 Issue：

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

記錄：

• 目標類型和編號
• 標題
• 問題陳述
• 提議的意圖
• 子系統
• 它是開啟、關閉還是已合併
• 是否已有人類提及的可能重複討論串

步驟 2：使用 Gitcrawl 廣泛搜尋

首先使用 gitcrawl，因為它是 OpenClaw 的本地歷史記錄與聚類來源。 除非 gitcrawl 缺失資料、過時或失敗，否則不要切換到廣泛的即時 GitHub 搜尋。

從目標和附近的討論串開始：

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

然後搜尋關鍵片語和子系統詞彙：

gitcrawl search openclaw/openclaw --query "<key phrase from title or body>" --mode hybrid --limit 20 --json
gitcrawl search openclaw/openclaw --query "<subsystem or error phrase>" --mode hybrid --limit 20 --json

檢查可能的叢集：

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

對於 PR，使用即時檔案資料驗證可能的程式碼重疊：

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

對於 Issue，即時驗證可能重複的 Issue 狀態和評論：

gh issue view <candidate-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 -- "<key phrase>"
gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "<key phrase>"
gh search issues --repo openclaw/openclaw --match comments --limit 50 -- "<error or maintainer phrase>"

步驟 4：決定結果

選擇以下結果之一：

• not_duplicate
• duplicate_needs_judgment
• duplicate_confirmed

僅在證據足夠強，維護者可以安全地關閉或重新標記重複項目時，才使用 duplicate_confirmed。

當以下情況時使用 duplicate_needs_judgment：

• 問題看起來相同但實作目標不同
• 程式碼重疊性弱
• Issue 措辭含糊不清
• 可能存在兩種有效的重複群組解釋
• 目標似乎與兩個現有的重複群組相交

步驟 5：重用或建立一個 prtags 群組

在建立群組之前，先搜尋 prtags 中現有的群組。

從群組的文本搜尋開始：

prtags search text -R openclaw/openclaw "<problem phrase>" --types group --limit 10
prtags search similar -R openclaw/openclaw "<problem summary>" --types group --limit 10
prtags group list -R openclaw/openclaw

檢查可能的群組：

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

當以下情況時重用現有群組：

• 它代表相同的問題
• 它已包含明確相關的成員
• 加入目標會保持群組的連貫性

不要僅僅因為 gitcrawl 將幾個 PR 或 Issue 放在附近，就擴大現有群組。 在加入新成員之前，確認實際的實作路徑和維護者意圖仍然匹配。

僅在沒有現有群組明確符合時才建立新群組。

使用基於問題的標題和基於意圖的描述來建立群組：

prtags group create -R openclaw/openclaw \
  --kind mixed \
  --title "<problem-centered title>" \
  --description "<same intent, subsystem, and duplicate-resolution path>" \
  --status open

然後附加目標和任何已知的重複成員：

prtags group add-pr <group-id> <pr-number>
prtags group add-issue <group-id> <issue-number>

如果目標似乎已屬於另一個重複群組，且您無法安全地重用該群組，請停止。 不要建立第二個群組。

步驟 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-number> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<same problem, same fix direction, overlapping files and comments>"

對於 Issue：

prtags annotation issue set -R openclaw/openclaw <issue-number> \
  duplicate_status=confirmed \
  duplicate_confidence=high \
  duplicate_rationale="<same user-visible problem and same intended fix path>"

對於群組：

prtags annotation group set <group-id> \
  duplicate_confidence=high \
  cluster_summary="<one-sentence problem summary>" \
  duplicate_rationale="<why these items belong in one duplicate cluster>"

當證據不完整時，設定 duplicate_status=candidate 並降低信心水準。

如果因為 prtags 無法解析目標而導致每個 PR 或 Issue 的註釋寫入失敗，請勿強制使用備用寫入路徑。 保留您能寫入的群組狀態，回報管理後端仍然缺少目標物件，並將最終判斷推遲，直到該問題解決。