review-pr

Review PR 技能

審查目前的 pull request，並將輸出寫入 review.json。

情境

• 工作目錄為 PR 分支的檢出目錄。
• 工作流程通常會在 pr_diff.txt 中提供帶註解的 diff。
• 工作流程通常會在 pr_description.txt 中提供 PR 描述。
• 如果 spec_context.md 存在，則包含用於實作與規格驗證的規格上下文。
• 當提示提及 .agents/skills/review-pr/scripts/resolve_spec_context.py 時，使用該腳本按需產生 spec_context.md，而非預期提示中已嵌入規格內容。
• 專注於此 PR 變更的檔案與行數。
• 不要直接發布評論或審查到 GitHub。

審查範圍

• 優先關注正確性、安全性、錯誤處理以及有意義的效能問題。
• 如果使用此技能的儲存庫提供了本機的 security-review-pr 輔助技能，或提示要求進行安全檢查，則將其作為程式碼 PR 的補充指引，並將所有安全發現合併到同一個 review.json 中，而非產生單獨的輸出。
• 當 spec_context.md 存在時，如果儲存庫有本機的 check-impl-against-spec 技能，則使用該技能，並將實質的規格偏差視為審查關注點。
• 僅當你能提供具體的建議區塊時，才包含風格或 nit 評論。
• 如果關注點涉及未修改的程式碼，則在頂層的 body 中提及，而非行內評論。
• 當現有測試已涵蓋有意義的行為時，不要建議僅改變建構子輸入或結構體欄位的測試案例。僅在測試涵蓋不同的程式碼路徑或邊界情況時，才建議新增測試。
• 當 PR 明顯是 V0 或初始實作時，將穩健性建議（如逾時、重試、生命週期管理）視為可選的未來工作，而非阻擋性問題，除非它們影響正確性、安全性或資料遺失。

儲存庫特定指引

使用此技能的儲存庫可能附帶一個 review-pr-local 輔助技能。當提示中包含一個引用該輔助技能的「儲存庫特定指引」區塊時，請閱讀並將其指引作為審查的一部分。輔助技能中的指引不得變更此技能中描述的輸出 JSON 結構、嚴重性標籤、安全規則、證據規則、建議區塊限制或 diff 行註解合約。

如果提示中未引用輔助檔案，則僅依賴核心合約。

Diff 行註解

diff 檔案使用以下前綴：

• [OLD:n] 表示舊端的刪除行。使用 "LEFT"。
• [NEW:n] 表示新端的新增行。使用 "RIGHT"。
• [OLD:n,NEW:m] 表示未變更的上下文。使用 "RIGHT" 並指定行號 m。

將這些註解視為行內評論位置的唯一真實來源。對於你發出的每一條行內評論，首先在 pr_diff.txt（或內嵌的 PR diff）中找到確切的註解行，並將其路徑、端點和行號複製到 review.json 中。不要從文字描述、渲染的 GitHub 檢視、檔案長度、周圍的規格文字或未註解的片段推斷行號。如果你無法指向註解 diff 中的特定 [NEW:n]、[OLD:n] 或 [OLD:n,NEW:m] 行，則將回饋放在頂層的 body 中，而非 comments。

評論要求

每條評論內容必須以以下標籤之一開頭：

• 🚨 [CRITICAL] 用於錯誤、安全性問題、崩潰或資料遺失。
• ⚠️ [IMPORTANT] 用於邏輯問題、邊界情況或缺少錯誤處理。
• 💡 [SUGGESTION] 用於有價值的改進或更好的模式。
• 🧹 [NIT] 僅在評論包含建議區塊時用於清理。

撰寫評論時需遵守以下限制：

• 簡潔、直接且可操作。
• 不要添加讚美或模糊用語。
• 偏好單行評論。
• 範圍最多 10 行。
• 行內評論僅限於明確出現在註解 PR diff 中的行。
• 僅為此 PR diff 中存在的檔案建立檔案級別或行內評論。
• 如果相關檔案或行不屬於 diff，則將回饋放在頂層的 body 中，而非 comments。
• 在添加每條評論物件之前，確認其 path、side、line 以及可選的 start_line/start_side 對應於同一檔案 diff 區段中的真實註解。

建議區塊

當提出程式碼變更時，使用：

<替換的程式碼>

規則：

• 與原始檔案的縮排完全一致。
• 僅包含替換的程式碼。
• 區塊內容完全替換 start_line 到 line（含）之間的行。區塊內的每一行都成為該範圍的新檔案內容，GitHub 保持所有其他行不變。
• 不要包含該範圍外的行。start_line 以上和 line 以下的行保留在檔案中；如果在區塊內重複它們，則在提交建議後這些行會出現兩次。
• 切勿以已出現在 start_line 正上方的行作為區塊開頭，也切勿以已出現在 line 正下方的行作為區塊結尾。如果需要這些行作為錨點，請擴大 start_line 或 line，使它們實際屬於被替換的範圍。
• 計算原始替換行中大括號、中括號、小括號和區塊分隔符號（{、[、(、end 等）的深度，並確保替換內容在相同深度結束。不要發出虛假的閉合符號，也不要遺漏必要的符號。
• 如果不確定周圍上下文，請擴大 start_line/line 以包含 diff 中足夠的真實行，而不是猜測周圍的符號。
• 對於多行建議，將 start_line 和 start_side 設為第一行，將 line 和 side 設為最後一行。

輸出格式

建立 review.json，格式如下：

{
  "verdict": "REJECT",
  "body": "## 概述\n...\n\n## 關注點\n- ...\n\n## 判定\n發現：1 個 critical，2 個 important，3 個 suggestions\n\n**要求變更**",
  "comments": [
    {
      "path": "path/to/file",
      "line": 42,
      "side": "RIGHT",
      "start_line": 40,
      "start_side": "RIGHT",
      "body": "⚠️ [IMPORTANT] 簡短說明\n\n```suggestion\nreplacement\n```"
    }
  ]
}

欄位規則：

• verdict 為必填，且必須是字串 "APPROVE" 或 "REJECT"（大寫）。將最終建議映射為：Approve 或 Approve with nits → "APPROVE"；Request changes → "REJECT"。verdict 與頂層 body 中的人類可讀建議必須一致。
• 頂層 body 是 GitHub 審查內容，為必填。使用 body，而非 summary，作為審查概述和最終建議。
• comments 為必填，且必須是陣列。當沒有行內評論時，使用空陣列。
• path 必須相對於儲存庫根目錄。
• line 為必填，且必須指向正確的端點。
• start_line 為可選，僅用於多行範圍。當 start_line 存在時，start_side 為必填，且必須是 "LEFT" 或 "RIGHT"。
• side 必須是 "LEFT" 或 "RIGHT"。

內容要求

頂層 body 必須包含：

• PR 的高層級概述。
• 重要的關注點以及任何無法行內評論的未修改程式碼關注點。
• 問題計數，格式為 Found: X critical, Y important, Z suggestions。
• 最終建議：Approve、Approve with nits 或 Request changes。此建議必須與頂層 verdict 欄位一致（Approve / Approve with nits → "APPROVE"；Request changes → "REJECT"）。

最終檢查

在返回或上傳 review.json 之前：

• 如果驗證失敗，修正無效的 JSON。
• 確認行號與註解 diff 相符。
• 針對你審查的確切註解 diff 執行內建的驗證器：

  python3 .agents/skills/review-pr/scripts/validate_review_json.py --review-json review.json --diff pr_diff.txt
  

  如果腳本報告任何無效的評論，修正 review.json 並重新執行。在驗證器通過之前，不要返回或上傳 review.json。如果腳本路徑不在該確切位置，請在載入的 review-pr 技能目錄下找到 validate_review_json.py，並使用相同的參數執行該副本。
• 不要執行 gh pr review、gh pr comment、gh api 或任何其他發布到 GitHub 的命令。

你唯一的輸出是最終的 review.json。