Community图像github.com

pr-diagram

为拉取请求绘制 Mermaid (.mmd) 图表,让评审者在阅读差异之前先看到变更流程。

pr-diagram 是什么?

pr-diagram 是一个 AI 专家技能,专为 Claude Code、Cursor、Codex 等 AI 代理设计,用于为拉取请求 (PR) 生成结构化图表。它的核心目标是通过一个直观的 Mermaid 图表,帮助代码评审者在 10 秒内理解 PR 的变更意图和流程,而不是浏览整个代码库的地图。该技能通过读取 PR 差异(只读操作),识别新增、修改和未更改的代码,并自动选择最匹配的图表类型(如流程图、序列图、状态图或 ER 图)来可视化数据流、请求路径或状态变化。图表中的每个节点都用颜色编码(绿色表示新增,黄色表示已修改,灰色表示未更改),并包含简短的英文标签。pr-diagram 还提供一键将图表发布到 PR 描述的功能,并包含严格的安全防护措施,确保它永远不会修改代码或执行 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. 一个批准步骤:在同一消息中显示完整的 PR 描述并询问是否发布。 不要先问“要我发布吗?”然后再显示描述——这样会有两轮批准。显示整个描述,而不仅仅是添加的部分,并在消息末尾提出询问。对该消息回复“看起来不错”、“发布”或“是”即视为批准。沉默、提出疑问或要求调整则不算。调整后,再次同时显示完整描述和问题。
  4. 为你添加的所有内容签名, 在添加块的最后一行加上以下确切内容: - 由 Claude Code 生成

参数

  • /pr-diagram 使用当前分支的 PR,如果不存在 PR,则使用本地分支差异。
  • /pr-diagram 123 或 PR 的 URL 针对该 PR(支持通过 URL 指定其他仓库)。
  • 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 标题和描述作为意图,但如果它们与代码不一致,则以代码为准。每个节点和边都必须追溯到你读取的代码。绝不为了图表整洁而编造步骤。 如果某些内容不确定,则省略并说明。

已删除的代码:如果被删除的步骤对评审者很重要,则显示为带有虚线边的灰色节点,标签为“(已删除)”,否则省略。

步骤 3:选择图表类型

输出始终是 .mmd 文件中的 Mermaid 图表。根据流程匹配以下类型:

变更主要是...图表类型
逐步流程或决策逻辑flowchart TD(自上而下)
组件或服务之间的连接,或流水线flowchart LR(从左到右)
3 个或更多参与者之间随时间传递的请求或消息sequenceDiagram
状态或生命周期变化(待处理 → 已批准 → ...)stateDiagram-v2
表、列或关系(迁移)erDiagram

使用一个图表。只有当 PR 同时明显改变了结构和运行时流程时,才使用两个图表。如果 PR 太小而不需要图表(1-2 个文件,没有新流程),则说明并停止。

步骤 4:构建图表

标签:短小精悍的英文描述。

  • 描述步骤的功能,而非代码标识符:使用 Check card is not expired,而不是 CardValidator.validateExpiry()。当名称有帮助时,使用简短形式:PaymentReconciliationService 变为 Payment reconciler。
  • 缩短 URL 为路径:api.example.com/v2/orders/{id}/refunds 变为 POST /orders/:id/refunds。
  • 矩形节点 A["..."]: 每行最多 35 个字符。
  • 体育场 A(["..."]) 和圆角 A("...") 节点: 每行最多 25 个字符。
  • 菱形节点 A{"..."}: 最多 25 个字符。
  • 圆柱 A[("...")]: 数据存储。
  • 如果节点需要更多细节,使用 <br/> 将其拆分为多行(每行不超过限制),最多 3 行。
  • 形状含义:矩形 = 步骤或组件,体育场 = 开始或结束(触发、响应),圆角 = 外部系统,菱形 = 决策,圆柱 = 数据存储。
  • 最多 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 个)。修复超限的。
  • 确保标签中没有原始代码标识符(camelCase、Foo.bar()、snake_case),如果可以用中文描述代替的话。
  • 检查每个节点的颜色:它在差异中确实是新增、已修改还是未更改?
  • 可选渲染检查: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 URL 和问题结束消息:“发布到 ?” 然后停止并等待(安全防护第 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 URL。比较时忽略尾部空白,因为 -q 会添加换行符。例如,在 Python 中比较两者的 .rstrip()。

尚无 PR(只有本地分支)?提供块,以便用户在打开 PR 时粘贴。不要创建 PR。

禁止事项

  • 不要为每个文件绘制图表。显示所有内容的图表等于什么都没显示。
  • 不要在标签中包含机密信息、内部主机名、带有令牌或查询字符串的完整 URL 以及客户数据。

相关技能