Plate 的评审模式挖掘（Review Pattern Mining）：把一条 PR 评审意见变成全 diff 范围的修复-开发者社区

Plate 的评审模式挖掘（Review Pattern Mining）：把一条 PR 评审意见变成全 diff 范围的修复

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

本篇基于 Plate 仓库中的 review-sweep 技能文档，系统讲解"评审模式挖掘"这一 AI Agent 协作方法论：如何从单条 PR 评审意见中提取普适规则，并在当前 diff 内识别同类模式、批量修复，同时用明确的适用性分级与"爆炸半径"约束防止过度扩散。读完本文，你将掌握这套方法的完整规则集、正负目标清单、八步工作流，以及它与 Plate 仓库中 resolve-pr-feedback 技能的衔接关系和一个真实落地的应用案例。

一、背景：Plate 的 Agent 技能体系与 review-sweep 的定位

Plate 是一个面向富文本编辑器生态的 TypeScript monorepo（核心编辑器框架 + 数十个插件包，见 packages/ 目录与 README）。仓库在.agents/目录下维护了一套给 AI Agent（Claude Code、Codex 等）使用的技能与规则体系，review-sweep 就是其中之一。

从源码结构看，这套体系有一个明确的"单一事实源"约束。.agents/AGENTS.md 第一行规定：

.agents/AGENTS.mdand.agents/rules/*.mdcare source of truth. After editing them, runpnpm installto sync. Never editSKILL.mddirectly.

也就是说，真正可编辑的源头是 .agents/rules/review-sweep.mdc，而本文主角 .agents/skills/review-sweep/SKILL.md 是由 skiller 工具从.mdc同步生成的。SKILL.md 的 frontmatter 也印证了这一点：

--- description: Mine review comments for broader diff-wide fixes instead of handling each line in isolation name: review-sweep metadata: skiller: source: .agents/rules/review-sweep.mdc ---

.agents/skiller.toml 中default_agents = ["claude-code", "codex"]、[skills] enabled = true，表明该技能会在这些 Agent 环境中被激活。文档开头的适用场景说明也点明了触发时机：

Use this when handling PR review feedback and you want to reduce repeated follow-up review on the same branch.

目标（Goal）一句话概括：把每条评审意见当作推断一条更宽规则的机会，再把该规则应用到当前 diff 中所有明确匹配的位置。

二、核心哲学：提取"规则"，而不是照搬"这一行的改法"

文档的 Core Rules 共 7 条，是整套方法论的行为约束，完整继承如下：

提取底层规则，而不是字面上的那一行修改（Extract the underlying rule, not just the literal line edit）。
当规则是客观的、低歧义的，就在当前 diff 的所有地方修复同一模式（Fix the same pattern everywhere in the current diff when the rule is objective and low-ambiguity）。
不要"cargo-cult"（教条式搬运）评审者的建议到不相关的代码上。
如果反馈属于架构性或个人品味范畴，只做一次决策，二选一：
- 在有意义的接缝（seam）上做一次刻意的重构；或
- 准备一份带理由的简短反驳（pushback）草案。
优先做一次连贯的后续重构，而不是许多零碎的复制粘贴式修补。
让爆炸半径（blast radius）与你的置信度成比例——置信度越高，扩散范围可以越大。
如果一次建议的扫描依赖于另一个 PR 或上游的待合并变更，必须显式指出，而不是靠猜。

这 7 条规则构成一个完整的"扩散决策框架"：规则 1–2 定义"何时扩"，规则 3 定义"何时不扩"，规则 4–5 处理"扩不动/该不该扩"的主观性反馈，规则 6 是强度约束，规则 7 处理跨 PR 依赖。值得注意的设计取舍是第 4 条：面对品味型（taste-heavy）反馈不允许"逐处讨价还价"，而是强制收敛为一次全局决策，避免同一条主观意见在 diff 里被反复拉扯。

三、扫描目标清单：什么值得扫，什么不该扫

文档把扫描目标分成"Good Sweep Targets"和"Bad Sweep Targets"两组白/黑名单，这是该方法论最具可操作性的部分，两组清单完整继承如下。

3.1 好的扫描目标（Good Sweep Targets）

安全规则类（Safety rules）——规则客观、错误可验证：

输入校验（input validation）
索引或 key 的防御性守卫（index or key guards）
危险属性的过滤（dangerous property filtering）
null/undefined 处理（null or undefined handling）

重复出现的文档问题（Repeated docs issues）：

解释不完整（incomplete explanations）
API 文档与概念文档之间的漂移（drift between API docs and concept docs）
缺少权衡（tradeoff）或使用指导（usage guidance）

重复的代码形态问题（Repeated code-shape issues）：

冗余的类型断言（redundant casts）
别扭的条件分支（awkward conditionals）
重复的 helper 模式（repeated helper patterns）
同一接缝上重复的注释、或缺失的注释（duplicated comments or missing comments at the same seam）

重复的测试问题（Repeated test issues）：

脆弱的测试夹具（brittle setup）
过度具体的选择器（over-specific selectors）
相似测试中本应同样存在、却被评审恢复的断言（restored assertions that should exist in similar tests）

这四类有一个共同特征：判定标准是客观的——一个索引守卫该不该加、一条断言该不该补，可以由代码事实本身回答，不依赖评审者的个人偏好。这正是核心规则 2 中"objective and low-ambiguity"的具体化。

3.2 坏的扫描目标（Bad Sweep Targets）

没有明显可读性收益的命名偏好（naming preferences without a strong readability win）
没有仓库证据支撑的大范围架构变更（broad architecture changes without repo evidence）
只能弱泛化的主观风格选择（subjective style choices that only weakly generalize）
仅为满足局部便利而扩大公开 API 的变更（changes that widen public API just to satisfy local convenience）
任何你无法用一句话解释清楚的改动（anything you cannot explain in one sentence）

最后一条是整份文档中最锋利的自检条款：如果一次"diff 范围修复"说不清自己为什么成立，它就属于坏目标，应放弃而非执行。

四、八步工作流：从一条评审意见到一份可审计的交接

文档的 Workflow 部分给出了严格编号的八步流程，完整继承如下：

读取评审意见并分类，归入五类之一：
- safety（安全）
- docs clarity（文档清晰度）
- code-shape cleanup（代码形态清理）
- test robustness（测试健壮性）
- architecture or taste（架构或品味）
用一句话写下你推断出的规则。
在当前 diff 的其余部分搜索同一模式。
把发现分为三档：
- clear applies（明确适用）
- maybe applies（可能适用）
- does not apply（不适用）
只自动应用 clear 档。
对 maybe 档，做出一个显式的、带理由的决策（而非逐处临场发挥）。
直接验证被修改的接缝（Verify the changed seam directly）。
在交接（handoff）中把两类工作分开陈述：
- 你实际处理的那条原始评审意见；
- 你从该意见推断出的、diff 范围内的额外修复。

步骤 4 的三档分级是整套流程的安全阀：它把"能自动做的"和"需要人判断的"显式切开，与核心规则 6 的"爆炸半径与置信度成比例"呼应。步骤 7 要求"直接验证"而非泛泛回归，即对修改点本身跑聚焦的测试或类型检查，而不是等待 CI 全量反馈。步骤 8 则把"模式挖掘"的成果变成可审计的交付物——评审者能在 handoff 里看到"一条意见如何变成了 N 处修复"。

Output Rule：证明你没有只做字面回答

文档最后的输出规则（Output Rule）规定：

When summarizing the work, make it obvious that you did not just answer the comment literally. Say what broader rule you inferred and where else in the diff you applied it.

即总结工作时必须明确说明：推断出的更宽规则是什么、它在 diff 的哪些其他位置被应用。这条规则把"模式挖掘"从隐性行为变成可检验的产出标准——如果一份 PR 处理记录里只能看到"按评审意见改了那一行"，那么 review-sweep 并没有真正发生。

五、上下游衔接：review-sweep 在 resolve-pr-feedback 流水线中的位置

review-sweep 不孤立存在。Plate 的 resolve-pr-feedback 技能定义了完整的 PR 反馈处理流水线（拉取反馈 → 分类 → 逐条修复 → 验证 → autoreview 收口 → 回复 → 解决线程 → 复核），其中第 5 步 Fix 明确规定：

usereview-sweepwhen one comment implies a clear diff-wide rule;

同时它要求"keep fixes scoped to the reviewed diff and its direct owners"、"do not implement speculative architecture changes from review comments"。可以看到两个技能形成清晰分工：resolve-pr-feedback 管流程与边界，review-sweep 管"一条意见如何正确地放大"。review-sweep 的"不扩到无关代码"（核心规则 3）与 resolve-pr-feedback 的"不实现投机性架构变更"是同一防扩散原则在两个层级的表述。

六、真实案例：PR #5120 中的一次 review-sweep 落地

仓库中的 PR 5120 反馈台账记录了这套方法的一次真实执行，可以作为工作流的完整印证。该 PR 有 3 条评审线程，其中一条指出 math 包会把来自旧版 HTML 导入的原始（primitive）公式值在规范化时抹掉。按 review-sweep 的处理方式，修复没有停在"被点名的那一处"，台账中的 Decisions 一节写道：

Preserve string/number/boolean equation values as text; nullish and unsupported values remain empty. Sweep package render/input helpers and copied editable/static/DOCX views without widening public exports.

这正是核心规则 2（在 diff 内修复同一模式）与 Bad Sweep Targets 第四条（不扩大公开 API）同时生效的结果：从一条意见推断出"可恢复的原始值不应在规范化中丢失"这一规则，然后把同一规则扫过包内渲染/输入辅助函数与复制出去的 editable/static/DOCX 视图，但明确不新增任何公开导出。

步骤 7"直接验证被修改的接缝"在该案例中对应一组聚焦测试证据（均记录在台账 Verification evidence 一节）：

bun test packages/math/src/lib：56 通过，0 失败；
bun test packages/math/src/react/hooks/useEquationInput.spec.tsx：5 通过；
bun test apps/www/src/registry/ui/equation-node-static.spec.tsx：16 通过；
外加pnpm turbo typecheck --filter=./packages/math与完整 www typecheck。

而步骤 8 的"交接分开陈述"则体现为台账的 Findings 与 GitHub receipts 部分：3 条可操作线程的逐条裁决（2 fixed、1 replied/already fixed）、每处回复对应精确的 discussion 链接、以及"3 条线程全部 resolve、refetch 后 0 条未解决"的最终核对。

七、小结

review-sweep 的本质是一个受控放大机制：用"一句话可陈述的规则"作为放大条件，用"clear / maybe / does not apply"三档作为闸门，用"爆炸半径与置信度成比例"作为强度约束，最终通过"handoff 中显式区分原始意见与推断修复"形成可审计闭环。它的适用前提也很明确——对象是当前 diff，规则必须客观、低歧义，且能用一句话解释；超出这些边界的东西（品味、架构、公开 API）要么收敛为一次显式决策，要么被直接排除在扫描目标之外。这套方法不仅适用于 AI Agent 处理评审，人类开发者在回应 code review 时同样可以直接套用其目标清单与三档分级。