Community影像github.com

pr-diagram

繪製合併請求(Pull Request)的流程圖(Mermaid .mmd 格式),讓審查者在閱讀差異前先看到變更的流動。當使用者說「pr diagram」、「diagram this PR」、「visualize the PR」、「draw the changes」、「add a diagram to the PR」或使用 /pr-diagram 指令時使用。需要 PR 編號/網址,或使用目前分支。根據變更類型選擇圖表樣式,以顏色標示新增/變更/未經修改的部分,並在顯示完整新版說明以取得核准後,提供將圖表張貼至 PR 描述的選項。

pr-diagram 是什麼?

pr-diagram 是一個專為開發者與 AI 代理設計的技能,用於自動根據合併請求(Pull Request)的差異產生 Mermaid 流程圖。其主要目標是以一張圖表在十秒內向審查者傳達「變更的內容與流程」,而非整個程式碼庫的地圖。該技能支援 GitHub CLI(gh)、Claude Code、Cursor、Codex 等平台,並提供嚴格的護欄,例如絕不修改程式碼、絕不核准或合併 PR、僅透過一次核准步驟張貼至 PR 描述。它會先以唯讀方式收集差異,分析變更的檔案來識別流程,並根據變更本質選擇圖表類型(流程圖 TD/LR、序列圖、狀態圖、ER 圖)。生成的節點會依據程式碼的新增、變更或未經修改狀態以顏色區分,並自動簽署每項新增內容。最終,它會顯示完整的新版 PR 描述,並在單一訊息中詢問使用者是否張貼,以確保完整的核准流程。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/amihali1/claude-skills/tree/HEAD/plugins/pr-diagram/skills/pr-diagram

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

pr-diagram:針對合併請求繪製圖表

目標:一張圖表,讓審查者在 10 秒內了解變更的內容與流程。 它不是整個程式碼庫的地圖。

護欄(不可違反)

  1. 絕不修改程式碼。 請勿編輯、建立或刪除儲存庫中的檔案,也請勿提交、推送或切換分支。.mmd 檔案應放在暫存或暫存目錄中,絕不能放在儲存庫中。
  2. 絕不核准、要求變更或合併。 請勿執行 gh pr review、gh pr merge 或 gh pr close,也請勿張貼 PR 評論。此技能唯一會進行的寫入操作是 gh pr edit --body-file 在描述上。
  3. 一個核准步驟:在相同訊息中顯示完整的新版描述並詢問是否張貼。 請勿先問「要不要我張貼?」,然後再顯示描述。這樣會形成兩個核准回合。顯示完整的內容主體,而不只是新增的區段,並在訊息結尾提問。對該訊息回覆「看起來不錯」、「張貼」或「是」視為核准。沉默、提問或要求調整則不屬核准。調整後,再次一併顯示完整主體和提問。
  4. 為您新增的所有內容簽名,在新增區塊的最後一行加上以下這行文字: - 由 Claude Code 產生

引數

  • /pr-diagram 使用目前分支的 PR,如果沒有 PR 則使用本機分支差異。
  • /pr-diagram 123 或 PR 網址則指定該 PR(也可以透過網址用於其他儲存庫)。
  • type=td|lr|sequence|state|er 強制指定圖表類型。

步驟 1:收集差異

使用 PR(皆為唯獨):

gh pr view <N> --json number,title,body,url,baseRefName,headRefName,files,additions,deletions
gh pr diff <N> --name-only
gh pr diff <N>

沒有 PR:找出基礎分支(gh repo view --json defaultBranchRef -q .defaultBranchRef.name),然後執行 git diff --stat $(git merge-base origin/<base> HEAD) 和 git diff $(git merge-base origin/<base> HEAD)。

大型差異(超過 1500 行變更或超過 30 個檔案):先讀取 --stat 和 PR 主體,然後只讀取包含邏輯的檔案。跳過鎖定檔案、產生的程式碼、快照和純粹重新命名的檔案。

步驟 2:識別流程

差異顯示的是行數,而非關係。讀取(唯獨)每個受影響檔案的最新版本,並整理出:

  • 流程: 觸發條件(請求、任務、事件、使用者操作)、執行順序,以及結束位置(回應、資料庫寫入、訊息、外部呼叫)。
  • 每個步驟的狀態: 新增(由此 PR 新增)、變更(已存在但經修改)或未經修改(審查者理解變更所需的上下文)。
  • 一句話摘要供審查者參考(例如「在付款呼叫之前新增一個重試步驟」)。

以 PR 標題和主體作為意圖的參考,但如果程式碼與其不符,請相信程式碼。每個節點和邊緣都必須可以追溯至您讀過的程式碼。絕不為了讓圖表更整齊而憑空發明步驟。 如果不確定,就省略並說明原因。

移除的程式碼:如果移除的步驟對審查者很重要,請用灰色節點、標籤為「(removed)」並使用虛線邊緣來顯示。否則就省略。

步驟 3:選擇圖表類型

輸出始終是 Mermaid 格式的 .mmd 檔案。根據流程特性選擇類型:

變更主要涉及…圖表
逐步流程或決策邏輯flowchart TD(由上而下)
元件或服務的接線方式,或管線flowchart LR(由左至右)
3 個以上參與者之間隨時間傳遞的請求或訊息sequenceDiagram
狀態或生命週期變更(待處理 → 核准 → …)stateDiagram-v2
資料表、欄位或關係(遷移)erDiagram

使用一個圖表。僅當 PR 同時變更結構和執行時期流程時,才使用兩個。如果 PR 太小不需要圖表(1-2 個檔案,沒有新流程),請直接說明並停止。

步驟 4:建立圖表

標籤:使用簡潔的英文文字。

  • 寫下步驟的作用,而非程式碼識別碼:例如 檢查卡片是否未過期,而不是 CardValidator.validateExpiry()。如果名稱有幫助,可以使用簡短形式:PaymentReconciliationService 變成 付款協調器。
  • 將網址縮短為路徑:api.example.com/v2/orders/{id}/refunds 變成 POST /orders/:id/refunds。
  • 矩形節點 A["..."]:每行最多 35 個字元。
  • 圓角矩形 A(["..."]) 和圓角 A("...") 節點:每行最多 25 個字元。
  • 如果節點需要更多細節,請使用 <br/> 將其拆分成多行(每行都在其限制內)。最多使用 3 行。
  • 形狀含義:矩形 = 步驟或元件,圓角矩形 = 起點或終點(觸發條件、回應),圓角 = 外部系統,菱形 A{"..."} = 決策點(最多 25 個字元),圓柱體 A[("...")] = 資料儲存。
  • 最多 15 個節點。當節點數量大約超過 8 個時,使用 subgraph 按服務或區域進行分組。
  • 簡短地為邊緣加上標籤,使用簡潔的英文文字(例如 發送、失敗時、儲存),最多 20 個字元。
  • 序列圖: 參與者和演員名稱最多 25 個字元。訊息、loop、alt 和 opt 的標籤,以及 Note 文字每行最多 35 個字元(使用 <br/> 分行,最多 3 行)。請勿在訊息文字中使用 ; 或 #,因為它們會破壞解析。

顏色(在 GitHub 淺色和深色模式下均可閱讀)。 使用淺色填滿搭配深色文字和明顯的邊框:

classDef new fill:#d3f9d8,stroke:#2b8a3e,stroke-width:2px,color:#0b3d17
classDef changed fill:#fff3bf,stroke:#e67700,stroke-width:2px,color:#4a2b00
classDef unchanged fill:#e9ecef,stroke:#868e96,stroke-width:1px,color:#343a40
class StepA,StepB new
class StepC changed
class StepD unchanged

每個節點只有一個類別。在 stateDiagram-v2 中,使用 classDef 加上 class StateName new。

序列圖: 類別不適用。rect 只設定背景,文字顏色來自 GitHub 的主題(深色模式下為淺灰色)。不透明的淺色填滿在深色模式下會使文字無法閱讀,因此務必使用半透明色調:

  • 新增:rect rgba(46,160,67,0.18)
  • 變更:rect rgba(210,153,34,0.22)
  • 未經修改:不使用 rect

絕對不要使用不透明的 rect rgb(...)。為關鍵變更加上 Note over。

全部是新增的 PR(沒有變更或未經修改的項目): 保留綠色色調,並在摘要中說明「此圖表中的所有內容皆為新程式碼」,因為沒有其他可對比的項目。

語法陷阱(它們會破壞 GitHub 的渲染)。請逐一檢查:

  • 節點 ID 必須是純英數字元(例如 ChkCard)。標籤必須始終使用引號:ChkCard["Check card"]。
  • 在標籤中使用 #quot; 來表示字面意義的 "。<br/> 是標籤中唯一允許的 HTML。
  • 絕對不要使用 end(小寫)作為 ID。在箭頭周圍務必加上空格(A --> B),因為 A---oB 會被解析為圓形邊緣。
  • subgraph Id["Label"] … end。每個子圖都需要自己的 end。
  • 序列參與者:participant API as Orders API(ID 沒有空格)。
  • erDiagram 的屬性類型必須是單字(例如 varchar,而不是 varchar(255))。
  • 不要使用 %%{init}%% 主題區塊。classDef 顏色會處理兩種模式。

儲存圖表為 pr-<N>-diagram.mmd(或 branch-<name>-diagram.mmd),放在暫存或暫存目錄中。提供完整路徑。

步驟 5:呈現前自我檢查

  • 計算每個標籤行上的字元數量,並對照其限制(矩形 35 個字元,圓角矩形、圓角和菱形節點 25 個字元,邊緣標籤 20 個字元;在序列圖中,參與者 25 個字元,訊息、區塊和註解 35 個字元)。修正任何超出的部分。
  • 確保沒有標籤包含原始程式碼識別碼(駝峰式命名、Foo.bar()、底線命名),而可以使用簡潔的英文文字取代。
  • 檢查每個節點的顏色:它在差異中真的是新增、變更或未經修改嗎?
  • 可選的渲染檢查:npx -y @mermaid-js/mermaid-cli -i <file>.mmd -o <file>.svg。第一次執行會下載 Chromium(約 150 MB),因此請先詢問再執行。

步驟 6:呈現

在聊天中使用以下格式:

**<PR 功能的一句摘要>**

<2-3 句話:以文字描述的流程、變更在流程中的位置、任何省略或不確定的部分>

```mermaid
...
```
**圖例:** 綠色 = 新程式碼 · 黃色 = 變更的程式碼 · 灰色(或無色調)= 未經修改的上下文

儲存位置:<.mmd 檔案的完整路徑>

步驟 7:顯示完整描述並詢問是否張貼(與步驟 6 在同一個訊息中)

在回覆前執行此操作,以便圖表、完整的新版描述和問題一併送出:

  1. 將目前主體擷取到暫存檔案:gh pr view <N> --json body -q .body > <tmp>/body-old.md

  2. 在 <tmp>/body-new.md 中建立新版主體。將區塊放在標記之間,以便重新執行時取代而非累加:

    <!-- pr-diagram:start -->
    ## 變更圖表
    <摘要句子>
    
    ```mermaid
    ...
    

    圖例: 綠色 = 新 · 黃色 = 變更 · 灰色(或無色調)= 未經修改 (使用文字,而非彩色表情符號。表情符號在不同作業系統上會呈現不同的顏色,例如 ⬜ 在 Windows 上顯示為薰衣草色。)

    • 由 Claude Code 產生
    如果標記已存在,只取代它們之間的內容。否則在空白行後附加該區塊。保留原始主體的其他每個位元組不變。
    
  3. 檢查新版主體是否以完整的原始主體開頭。必須逐位元組保留。

  4. 以圍欄程式碼區塊顯示完整的新版描述、PR 網址和問題作為訊息結尾:「張貼到此 <PR 網址>?」 然後停止並等待(護欄 3)。

步驟 8:張貼(僅在步驟 7 的訊息得到「是」之後)

  1. gh pr edit <N> --body-file <tmp>/body-new.md。絕對不要使用 --body 搭配內嵌文字,因為 Shell 的引號處理會弄亂反引號和 $。
  2. 使用 gh pr view <N> --json body -q .body 驗證它是否與 body-new.md 相符,然後提供 PR 網址。比較時忽略尾隨空格,因為 -q 會加入換行。例如,在 Python 中比較兩者的 .rstrip()。

還沒有 PR(僅本機分支)?提供區塊讓使用者開啟 PR 時貼上。請勿建立 PR。

禁止事項

  • 不要為每個檔案繪製圖表。為所有內容繪製圖表等於什麼都沒有顯示。
  • 不要在標籤中放入機密、內部主機名稱、包含 Token 或查詢字串的完整網址,或客戶資料。

相關技能