miro-code-review

可视化代码审查

在 Miro 白板上，根据拉取请求／合并请求、本地更改或分支比较生成全面的可视化代码审查。内容包括架构分析、安全审查，并可选择结合企业文档进行丰富。创建好相关内容后，将链接添加到 PR／MR 描述中，让审查者无需离开代码托管平台即可找到这些内容。

用户会提供 Miro 白板 URL，以及以下来源之一：PR／MR 编号、owner/repo#number（或 group/project!number）、完整的 PR／MR URL、关键词“local changes”，或用于与默认分支比较的分支名称。此技能不依赖特定平台：它会根据 URL 或已配置的 git 远程仓库识别代码托管平台，并使用本地可用的 CLI。

工作流程

1. 根据用户请求识别来源

确定来源类型，并根据 URL 或已配置的 git 远程仓库推断平台：

• 纯数字 → 当前仓库中的 PR／MR（根据已配置的 git 远程仓库推断平台：git remote get-url origin）
• owner/repo#number（或 GitLab 风格的 group/project!number）→ 与当前远程仓库位于同一平台的外部仓库中的 PR／MR，除非指定了主机
• 完整 URL → 从 URL 中提取主机、所有者／群组、仓库／项目和 PR／MR 编号；主机决定平台
• “local changes”／未提交的工作 → 仅本地差异，没有 PR
• 分支名称 → 与默认分支（main 或远程仓库显示的默认分支）比较的本地差异

工具选择

根据已安装的 CLI 和来源所指向的平台选择 CLI。不要假设一定有 gh。调用前运行 command -v <cli> 检查是否可用：

• GitHub URL／github.com 远程仓库 → 如果可用，使用 gh CLI
• GitLab URL／gitlab.com 或自托管的 GitLab → 如果可用，使用 glab CLI
• 如果检测到的平台没有对应的官方 CLI，则使用 curl 发起已认证的 REST 请求，并使用用户已配置的凭据（例如 ~/.netrc、环境变量令牌，如 $GITHUB_TOKEN、$GITLAB_TOKEN）
• 对于本地更改／分支比较来源，使用纯 git 即可，无需平台 CLI

继续之前，先在聊天输出中说明检测到的平台和所用工具。

2. 提取更改内容

无论平台是什么，都要获取以下两项：

1. 元数据：标题、描述／正文、作者、已更改文件列表，以及每个文件的新增／删除行数
2. 统一差异

使用与 §1 中检测到的平台相匹配的 CLI；不同代码托管平台返回的 JSON／文本格式会有所不同，请在后续步骤中统一字段。

GitHub 示例（gh）：

# Current repo
gh pr view $PR_NUMBER --json title,body,author,files,additions,deletions
gh pr diff $PR_NUMBER

# External repo
gh pr view $PR_NUMBER --repo $OWNER/$REPO --json title,body,author,files,additions,deletions
gh pr diff $PR_NUMBER --repo $OWNER/$REPO

GitLab 示例（glab）：

# Current project
glab mr view $MR_NUMBER -F json
glab mr diff $MR_NUMBER

# External project
glab mr view $MR_NUMBER -R $GROUP/$PROJECT -F json
glab mr diff $MR_NUMBER -R $GROUP/$PROJECT

REST 回退方案（适用于任何平台）： 向该平台用于 PR／MR 及其差异的 REST 端点发起经过身份验证的 curl 请求。使用用户配置的令牌（$GITHUB_TOKEN、$GITLAB_TOKEN 等），并为差异传递 Accept: application/vnd.github.v3.diff（或平台对应的值）。

对于本地更改：

git status --porcelain
git diff HEAD

对于分支比较：

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git log $DEFAULT_BRANCH..HEAD --oneline
git diff $DEFAULT_BRANCH...HEAD

确定源链接基础 URL

一次性记录并在 §5 的所有文件引用中重复使用（表格单元格、文档项目、图示标签）。将链接固定到头部 SHA，使其在强制推送后仍然有效。记录：

• LINK_HOST、LINK_OWNER/LINK_REPO（或 LINK_GROUP/LINK_PROJECT）——来自 §1
• LINK_SHA——PR/MR 头部提交 SHA（本地/分支源回退到 git rev-parse HEAD）
• LINK_BASE_SHA——基准提交 SHA（PR/MR 目标分支最新提交，或分支比较时的 git merge-base）；§5“显示变更”必需。如果无法访问，则跳过“之前”图示，并在聊天中说明一次。
• LINK_TEMPLATE——符合托管平台格式的 blob URL，带有 {path} 占位符和可选的 #L<start>-L<end>锚点。对于无远程源（local changes，或没有远程仓库/PR 的分支），将其设为 "" 并渲染为纯路径——绝不要虚构 URL。

创建产物前，在聊天中说明所选模板。有关各平台获取 SHA 的命令、各代码托管平台的 URL 模板，以及无远程/无法访问基准版本时的处理方式，请参阅 references/source-links.md。

3. 分析变更

针对每个变更文件，确定：

基本分析：

• 状态：新增、已修改或已删除
• 变更摘要：简要说明变更内容和审查要点
• 风险级别：参见下方的风险评估

架构分析：

• 引入的新组件或模块
• 依赖项变更（新增导入、软件包更新）
• 接口/API 修改
• 模式变更（引入或违反的设计模式）
• 需要使用方更新的破坏性变更

安全分析：

• 输入验证与清理
• 身份验证/授权变更
• 敏感数据处理（日志记录、存储）
• 注入漏洞（SQL、XSS、命令）
• 密码学用法
• 配置安全

4. 风险评估

风险级别	标准
高	安全敏感、身份验证/授权、数据库迁移、核心业务逻辑、破坏性 API 变更、密码学
中	API 变更、配置、共享实用工具、新依赖项、数据模型变更
低	测试、文档、样式、本地化、内部重构

4.5 分诊：决定要创建哪些内容（如果需要）

每项内容都必须证明其存在价值。在开展任何创建工作之前，先决定 PR 是否值得进行可视化，以及哪些内容类型确实能帮助审阅者。

退出规则。 如果以下条件全部满足，则不创建任何 Miro 内容，仅在聊天中报告：

• 更改的文件数 ≤ 2，且
• 更改的行数（新增和删除合计）< 20，且
• §4 中没有标记为高风险的文件，且
• 未涉及安全敏感路径（身份验证、加密、配置、迁移）。

在这种情况下，整个技能的输出仅为一条如下格式的聊天消息：

PR 很简单（N 个文件，±M 行，无高风险区域）。跳过 Miro 可视化——看板无法提升审阅价值。未修改 PR/MR 描述。

完全跳过 §5 和 §6。

价值门槛（逐项内容）。 如果不适用退出规则，也仅在内容能向审阅者说明差异本身无法一目了然的信息时才创建：

• 表格——更改文件数 ≥ 3 或存在混合风险等级时创建。对于未触发退出规则的 1–2 个文件的 PR，跳过表格。
• 摘要文档——当 PR 包含尚未在标题或正文中说明的非平凡意图，或至少有 2 个高风险项需要特别说明时创建。如果只是复述 PR 描述，则跳过。
• 架构文档——仅在检测到结构性更改时创建（新增模块、修改公共接口、依赖项更改、破坏性更改）。否则跳过。
• 安全文档——仅在涉及安全敏感路径时创建（参见 §3“安全分析”）。切勿创建仅包含检查清单的内容。
• 图表——仅当更改涉及多组件流程、控制流／数据流路径更改，或难以从差异中理解的结构关系时创建。默认以并排的前后对比图呈现（参见 §5“展示更改”）；仅当更改纯粹为增量式且涉及 ≤ 3 个元素时，才使用单张带注释的“更改后”图。如果图表只有一个节点、两个节点之间一条箭头，或只是照搬差异内容，则明确跳过。

在创建任何内容之前，先在聊天中公布计划，例如：

计划：1 个表格、1 份摘要文档，不创建图表（更改仅涉及单个函数）。

这样可以让用户看到分诊结果，并能在创建任何看板内容之前提出调整。

5. 创建 Miro 看板内容

**原则：**每项内容都必须证明其存在价值。如果某项内容无法帮助审阅者比单看差异更快地理解 PR，就不要创建。分诊规则参见 §4.5。

根据 PR 规模，在以下上限范围内调整内容规模，并应用 §4.5 的价值门槛——内容更少也可以。

链接约定

§5 中生成的每个文件引用，在有基础 URL 时都必须是指向源代码平台的可点击超链接。使用 §2 中记录的 LINK_TEMPLATE 和 LINK_SHA。

• 设置了 LINK_TEMPLATE 时（PR/MR 或已知远程仓库的分支）：替换文件 {path}，以此构建 URL。在指出特定代码块时（高风险文件、安全问题、架构说明），添加行锚点 #L<start>-L<end>。根据 §2 中记录的差异代码块（@@ -a,b +c,d @@，使用新文件范围）确定 start/end。如果引用跨越多个不连续代码块，则跳过锚点。
• LINK_TEMPLATE 为空时（local changes 或没有远程仓库）：将每个文件引用显示为纯路径。不要编造 URL。

各类产物规则：

• 表格 → File 列：将完整 URL 作为单元格内容。Miro 会将文本单元格中的 URL 渲染为可点击链接。没有远程仓库时，填入纯路径。
• 文档：使用 Markdown 链接——整文件引用用 [path/to/file.ts](url)，代码块引用用 [path/to/file.ts:42-58](url#L42-L58)。在每处文件提及中都应用此规则（Overview、Key Changes、High-Risk Areas、Architecture > New Components / Modified Interfaces、Security > Security-Sensitive Changes 等）。
• 图表：节点标签保留为纯路径——Miro 图表工具没有说明节点可点击。节点对应单个源文件时，在节点标签的第二行附上 URL，方便读者复制。

布局：

尽量将产物排成一行，方便审阅者从左到右浏览。按照 Miro MCP 工具的 schema 传入布局参数。

缩放指南

PR 规模	文件数	LOC（±）	文档	图表
微小	1–2	< 20	无（按 §4.5 提前退出）	无
小型	1–5	< 100	0–1 篇摘要	0–1 个流程图
中型	6–15	< 500	1–2 篇（摘要 + 必要时深入分析）	1–3 个
大型	16–30	< 1500	2–3 篇（摘要 + 架构 + 适用时的安全分析）	2–4 个
超大型	30+	≥ 1500	3+ 篇（按子系统划分）	3+ 个

上述预算中，并排的变更前／变更后对照算作一个图表——列数限制的是概念性产物，而不是画布上的原始组件数。

---

文件变更表

首先创建（显示在画布中央）。使用 Miro MCP 表格工具创建包含以下四列的表格，顺序如下：

1. 状态——固定选项列，取值为 Added、Modified、Deleted，分别以绿色／橙色／红色标记。
2. 文件——文本列，内容为按照 §5「链接约定」构建的完整源代码 URL（Miro 会将 URL 渲染为可点击链接）。没有可用的远程 URL 时，使用纯路径。
3. 变更——文本列，简要概述变更内容和需要重点审阅的事项。
4. 风险——固定选项列，取值为 Low、Medium、High，分别以绿色／橙色／红色标记。

根据表格工具的实时 schema 选择列类型和选项格式。

对于超大型 PR（30+ 个文件），创建单独的表格：

• 高风险变更表
• 常规变更表

---

文档

文档 1：主要摘要 — 仅在摘要文档通过 §4.5 的价值门槛时创建。如果 PR 描述已涵盖相同内容，则跳过。

文档 2：架构分析 — 仅在架构文档通过 §4.5 的价值门槛时创建（差异引入了新模块、修改了公共接口、更改了依赖项，或增加了破坏性变更）。否则跳过，即使是中型/大型 PR 也一样。

文档 3：安全分析 — 仅在涉及安全敏感路径（身份验证、加密、配置、迁移、输入处理）时创建。对于没有安全相关差异的 PR，绝不要仅创建清单式文档。

其他文档 — 对于超大型 PR，按子系统创建文档，并放在同一行（“API 变更分析”、“数据库迁移审查”、“UI/前端变更”等）。

每份文档的完整 Markdown 模板请参阅 references/document-templates.md。

---

图表

根据变更类型创建图表。放在最后一份文档之后（x 坐标继续以 800 为增量递增）。

展示变更：前后对比还是带注释的图表

每张图表都必须让差异一目了然，而不能只展示变更后的状态。

• 默认：并排展示前后对比图。 构建两张类型相同、使用相同 DSL 约定的图表，并将它们相邻放在同一 y 行。从 LINK_BASE_SHA 版本构建“变更前”图表（如果统一差异中缺少足够的上下文结构，则使用 git show $LINK_BASE_SHA:path），从 LINK_SHA 构建“变更后”图表。
• 仅当以下条件全部满足时，才改为单张带注释的“变更后”图表：
  • 变更纯粹是新增内容（相关子系统中没有删除的文件、移除的类/组件或移除的边），并且
  • 新增内容不会重新调整现有关系（没有重新连接调用方，也没有转移职责），并且
  • 要标记的新节点/边不超过 3 个。
• 如果无法访问 LINK_BASE_SHA（浅克隆、历史记录已清理），则将每组对比图都改为单张带注释的“变更后”图表，并复用 §2 中的聊天公告。

标注约定

主要标记为标签前缀（Miro Mermaid 渲染器不保证逐元素样式）：[ADDED]（仅出现在变更后图中）、[REMOVED]（仅出现在变更前图中）、[UPDATED]（出现在两张图中，且仅在变更后图中添加前缀）；未标注的元素为未变更的上下文。前缀本身必须足以表达含义。此外，尽力输出 Mermaid classDef 指令，作为颜色标记层。

完整的前缀语义以及要输出的 classDef 代码块，请参见 references/diagram-conventions.md。

图表选择指南：

变更类型	图表类型	模式	用途
功能新增（纯新增）	流程图	单张标注后的图	展示新增组件及其接入方式
重构	类图	前后并排	结构调整是核心内容
API/集成变更	时序图	前后并排	流程形态发生变化
数据库迁移/架构变更	ER 图	前后并排	重点展示架构差异
Bug 修复	流程图	单张标注后的图	在流程中标出修复点
数据管道重构	流程图	前后并排	数据流形态发生变化
混合/大型重构	按子系统划分	各子系统前后并排	每个受影响的边界各配一组图

图表位置：

将前后并排的图放在一起，以便一眼看出差异。其他情况下遵循 §5“定位”中的行布局——根据 Miro MCP 图表工具的架构，将位置传递给该工具。

图表（或图组）	创建时机
主流程/架构图组	始终创建
组件关系图组	中型及以上且有结构变更的 PR
时序/交互图组	API/集成变更
ER 图组	数据管道/架构变更
单张标注图（仅新增）	纯新增变更，新增元素不超过 3 个

每张图都应展示：

• 受影响的组件/模块（高亮显示）
• 变更代码中的数据流/控制流
• 变更文件之间的依赖关系
• 信任边界（与安全相关的变更）
• 如果某个节点对应单个源文件，请在标签的第二行附上该文件的 URL，方便读者复制（仅路径——图表节点不可点击）。没有远程仓库时，不要附加 URL。变更前图中的 URL 使用 LINK_BASE_SHA；变更后图中的 URL 使用 LINK_SHA。
• 将 §5“标注约定”中的变更标记应用于每个已修改/新增/删除的元素——图表或图组必须能让人一眼看出差异。

6. 在 PR/MR 中添加回链

创建好各项内容后，在 PR/MR 本身中展示链接，方便审阅者无需离开代码托管平台即可查看。

以下情况请完全跳过此步骤：

• 来源为“本地变更”
• 来源为没有关联开放 PR/MR 的分支

在这些情况下，仅在聊天输出中报告链接（见下文 §输出）。

将一个带分隔符的代码块（每次运行都复用相同的 … 标记）追加到现有描述中；如果该代码块已存在，则在原位置替换，且绝不覆盖用户撰写的内容。使用 §1 中选择的相同 CLI 读取、替换并写回正文；如果因权限不足导致编辑失败，则改为在 PR/MR 中发表评论，并在聊天中说明。

准确的代码块格式、链接规则、幂等规则以及各平台（gh/glab/REST）的命令，请参见 references/pr-linking.md。

输出

如果适用 §4.5 中的退出条件，全部输出仅为一条表示简单 PR 的聊天消息——没有看板链接、没有描述更新，也没有其他内容。

否则，完成后提供：

1. Miro 看板链接（如果提供了 moveToWidget，则提供框架链接）
2. 确认 PR/MR 描述已更新，或已作为备用方案发表评论，或因源代码是本地的／没有分支而跳过了发布步骤
3. 创建元素的摘要（X 份文档、Y 张图表，其中包含 N 对和 M 张单独注释的图表、Z 行表格）。仅在此聊天摘要中注明基础修订版本 <short LINK_BASE_SHA> 和头部修订版本 <short LINK_SHA>——不要将这些 SHA 放到 Miro 看板上。还需注明根据 §4.5 有意跳过了哪些制品类型，并用一行说明原因。
4. 需要仔细审查的高风险文件
5. 安全问题（如有严重或高危问题）
6. 架构方面的顾虑（如有破坏性变更）

参考资料

• references/risk-assessment.md — 详细的评分标准
• references/review-patterns.md — 审查模式
• references/source-links.md — §2 中各平台的 SHA 获取命令和 blob URL 模板
• references/diagram-conventions.md — 图表变更标记前缀和 Mermaid classDef 代码块（§5）
• references/document-templates.md — 摘要、架构和安全文档的完整 Markdown 模板（§5）
• references/pr-linking.md — 将链接回贴至 PR/MR 的区块格式、链接／幂等规则和各平台命令（§6）
• references/background.md — 审查理念、可视化审查的优势、制品选择表和看板布局参考