pr-diagram:为拉取请求绘制图表
目标:一张图表,让评审者在 10 秒内了解变更的作用和流程,而不是整个代码库的地图。
安全防护(绝对遵守)
- 绝不修改代码。 不编辑、创建或删除仓库中的文件,不提交、推送或切换分支。
.mmd文件放在临时或暂存目录,绝不放在仓库中。 - 绝不批准、请求变更或合并。 不运行
gh pr review、gh pr merge或gh pr close,不发表 PR 评论。此技能唯一执行的写入操作是gh pr edit --body-file更新描述。 - 一个批准步骤:在同一消息中显示完整的 PR 描述并询问是否发布。 不要先问“要我发布吗?”然后再显示描述——这样会有两轮批准。显示整个描述,而不仅仅是添加的部分,并在消息末尾提出询问。对该消息回复“看起来不错”、“发布”或“是”即视为批准。沉默、提出疑问或要求调整则不算。调整后,再次同时显示完整描述和问题。
- 为你添加的所有内容签名, 在添加块的最后一行加上以下确切内容:
- 由 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 同一条消息)
在回复前执行此操作,以便图表、完整的新描述和问题同时发出:
-
将当前描述提取到临时文件:
gh pr view <N> --json body -q .body > <tmp>/body-old.md -
在
<tmp>/body-new.md中构建新描述。将新增块放在标记之间,以便重新运行时替换而非堆叠:<!-- pr-diagram:start --> ## 变更图 <摘要句子> ```mermaid ...图例: 绿色 = 新增 · 黄色 = 已修改 · 灰色(或无色调)= 未更改 (使用文字而非彩色表情符号。表情符号在不同操作系统上显示为不同颜色,例如 ⬜ 在 Windows 上显示为薰衣草色。)
- 由 Claude Code 生成
如果标记已存在,则仅替换它们之间的文本。否则,在空白行后附加该块。原始描述的其他字节保持原样。 -
检查新描述是否以完整的原始描述开头。原始描述必须逐字节保留。
-
以完整的新描述的围栏块、PR URL 和问题结束消息:“发布到 ?” 然后停止并等待(安全防护第 3 条)。
步骤 8:发布(仅在收到步骤 7 消息的“是”之后)
gh pr edit <N> --body-file <tmp>/body-new.md。绝不使用--body和内联文本,因为 shell 引号会破坏反引号和$。- 使用
gh pr view <N> --json body -q .body验证其是否与body-new.md匹配,然后提供 PR URL。比较时忽略尾部空白,因为-q会添加换行符。例如,在 Python 中比较两者的.rstrip()。
尚无 PR(只有本地分支)?提供块,以便用户在打开 PR 时粘贴。不要创建 PR。
禁止事项
- 不要为每个文件绘制图表。显示所有内容的图表等于什么都没显示。
- 不要在标签中包含机密信息、内部主机名、带有令牌或查询字符串的完整 URL 以及客户数据。