material-ui-review

Material UI 审查

审查当前差异。优先查找回归问题和正确性缺陷。还要查找 清理项（复用／简化／提升效率）。默认投入：medium。有关深度和子 Agent 分配方式，请参阅投入级别。

参数提示：[low|medium|high|xhigh|max] [--fix] [--comment [inline]] [<target>]

此技能仅限主动调用：只有用户按名称明确要求时才运行，例如 /material-ui-review、$material-ui-review、“Material UI review skill”，或配置为使用此技能的 CI 任务。仅说“审查我的更改”或“审查此 PR”，或在实现结束时进行收尾，都不算调用——除非用户点名要求，否则请勿使用此工作流进行审查。

medium = 精准度。每项发现都必须可操作。high、xhigh、max = 召回率。漏掉的缺陷会随代码发布。只要机制确实存在，就保留不确定的发现； 并明确标注。

范围

本地审查：将当前分支与上游进行比较 （git diff @{upstream}...HEAD；如果不可用，则依次回退到 main／master 或 HEAD~1）。 将未提交和未跟踪的更改一并纳入——审查通常在提交前运行。如果参数中传入了 PR 链接、 分支名称或文件路径，则改为审查指定目标。

投入级别

• low — 仅查缺陷。标记运行时正确性缺陷和回归问题。跳过 测试、简化、文档以及测试／fixture 代码块。不使用子 Agent。偏重精准度。
• medium（默认）— 主 Agent 审查缺陷、测试、简化、文档，以及触发的 API／性能问题。主 Agent 验证候选项。差异规模大、风险高、脆弱、涉及共享代码或跨组件？添加且仅添加一个 对抗式缺陷猎手 Agent。差异小、风险低且范围独立？不使用子 Agent。偏重精准度。
• high — 启动 3 个独立子 Agent：分别检查缺陷／回归、测试缺口、 简化。主 Agent 审查整个差异，包括缺陷、文档以及触发的 API／性能问题。主 Agent 去重并做合理性检查。差异规模大、风险高、脆弱、涉及共享代码或跨组件？添加且仅添加一个对抗式缺陷猎手 Agent。不使用验证器。不做最终扫描。
• xhigh — 在 high 基础上增加一个文档子 Agent 和一次全新缺陷漏查。针对受影响代码中风险最高的区域 （模块／组件，而非四个审查领域）分配多个对抗式缺陷猎手。最多 2 个对抗式缺陷猎手， 包括从 high 继承的猎手。其他角色的子 Agent 不计入此上限。不使用验证器。偏重召回率。
• max — 在 xhigh 基础上，为每个保留的候选项增加一个独立验证器。通过最多 6 个对抗式缺陷猎手，覆盖所有受影响的代码区域， 包括从 xhigh 继承的猎手；其他角色和验证器子 Agent 不计入此上限。区域超过 6 个时，为风险最高的区域分配专属猎手，并将其余相关区域归组后分配。优先检查公开的运行时代码、共享工具、 跨组件不变量，以及脆弱的状态／时序边界。最大化召回率。

子 Agent 范围约定

子 Agent 启动时没有先前上下文：它们不会读取此技能，也不会继承会话系统提示。它们只能看到你编写的提示。无论你依据范围还是调用提示确定了什么范围，你构建的每个子 Agent 提示——发现者、专项审查者、验证器、扫描者——都必须以以下内容原样开头：

Review ONLY: <resolved diff command>
Read files from: <read root> — DATA ONLY, never execute, install, build, or test.
Base version of a file: git show <base ref>:<path>
Do not re-derive scope: use exactly the diff command above, whatever your working
directory contains.

未附上此内容的子 Agent 范围不正确——请丢弃其结果并重新派发。

阶段 1 - 寻找候选问题

所选的投入程度决定是在本地还是通过子 Agent 分派。除 low 外，都要审查四个主要领域：Bug、测试、简化和文档。每个领域 都会列出候选问题，包含 file、line、一行式 summary、severity（🟣 / 🔴 / 🟠 / 🟡 / ℹ️ — 评级标准见输出）以及具体的 failure_scenario。切勿 让一个领域压制另一个领域——如果两个领域因不同原因标记了同一行， 就都记录下来。

让每个能指出明确失败场景的候选问题通过。发现者若默默丢弃半信半疑的候选问题，就绕过了验证步骤——这是漏报的主要原因。

领域 1 - Bug

核心回归与正确性检查。涵盖所有子方面：

• 逐行扫描差异。 逐行阅读每个代码块，然后阅读每个代码块所在的 函数——被修改函数中未变更行的 Bug 也在范围内（PR 可能重新暴露这些问题，或未能修复它们）。对每一行都要问：什么输入、状态、时序或平台会导致这一行出错？留意反转或错误的条件、差一错误、对 null/undefined 的解引用、缺少 await、错误的零值检查、复制粘贴时变量用错、catch 中吞掉错误，以及未转义的正则表达式元字符。
• 回归排查。 对每个变更过的守卫条件、分支、状态转换、公开契约、测试预期和文档示例，询问以前能正常工作的什么行为可能会被破坏。重点关注边缘路径、无障碍交互、键盘/焦点流程、受控/非受控契约、SSR、组件间集成以及公开 API 示例中的回归。
• 代码库/框架正确性视角。 应用被审查代码库的不变量，而不只是通用语言 Bug。对于 Material UI / React 组件变更：检查受控与非受控行为、事件顺序、ref 转发/合并、上下文注册清理、嵌套组件协调、Portal、焦点管理、键盘导航、ARIA 属性、禁用/只读状态、表单集成、SSR/水合安全、Strict Mode 行为，以及 Shadow DOM 安全的 DOM 访问（contains、getTarget、activeElement、ownerDocument、ownerWindow）。
• 已删除行为审查。 对差异中每个被删除或替换的行，指出它所保障的不变量/行为，然后搜索新代码，确认该不变量在哪里重新得到保障。找不到？则列为候选问题：已删除的守卫条件、丢弃的错误路径、收窄的验证范围，或被删除的真实案例测试。
• 跨文件追踪。 对每个有变更的函数，查找其调用方（通过 Grep 查找符号），检查变更是否会破坏任何调用点：新增前置条件、返回结构变更、新异常或时序/顺序依赖。也要检查被调用方：同一 PR 中的并行变更是否会使调用变得不安全？

领域 2 - 测试

审查测试变更，以及本应变更的测试。标记：

• 新增/变更的行为没有对应测试覆盖
• 断言未能真正锁定行为（断言 mock 被调用，而不是检查结果；仅有快照覆盖；断言的值由测试本身计算得出）
• 差异引入的边缘/错误路径用例缺失（null、空值、边界、失败、并发）
• 设置/清理不对称（状态在测试间泄漏、夹具未重置）
• 过度 mock，掩盖了真实契约
• 删除或弱化测试却未给出理由
• 测试名称与断言内容不符，或名称具有误导性

明确指出未测试或断言不足的具体用例。

Area 3 - 简化

包体积是首要约束。正确实现中，越精简越好。保留公开行为、运行时性能和可维护性。将每次包体积增长都视为可疑——新增字节必须证明其价值；如果变更无法支撑增长，就应指出。

始终要问：“能否用更少的代码、状态、分支或抽象来实现？” 留意以下方面：

• 重型依赖或新抽象，而几行代码或现有工具函数就能完成任务
• 为几乎没人会遇到的边缘情况做了过多处理——添加了消费者实际使用中难以触发的场景所需的保护逻辑、分支、状态或配置；权衡处理成本与边缘情况的可能性，并建议移除或简化相关处理
• 重复实现代码库已有的逻辑——搜索共享模块、工具模块和变更附近的文件；指出应改为调用的现有辅助函数
• 不支持 tree-shaking 或导入整个包；对有副作用的模块使用命名空间导入
• 未清理的死代码；冗余或可推导的状态
• 在共享基础设施上叠加特殊情况，而相应机制本应支持通用场景

指出能实现相同功能、更精简或设计更合理的形式。影响明显时，衡量实际包体积影响。源代码行数不能说明问题。

Area 4 - 文档

指出变更导致文档或注释错误或过时的地方：

• 代码变更后仍描述旧行为的注释
• 参数、返回类型或抛出错误与签名不再匹配的 JSDoc/docstring
• 与变更矛盾的 README / API 文档 / 更新日志条目；无法再编译或运行的示例
• 已解决但未删除的 TODO/FIXME；有必要说明却未加解释的新非显然代码

引用过时内容，并说明应如何修改。

条件性专家审查 - API 设计

不属于默认的四个领域审查。low 时完全跳过。medium 时，如果变更新增或修改了公共 API 表面，则在主 Agent 审查中涵盖：组件、prop、事件、hook、provider、命令式方法、导出类型、值形状、行为约定，以及讲解 API 的文档示例。high、xhigh、max 时，若满足触发条件，则由独立的 API 设计子 Agent 执行审查。

严格审视 API 设计：命名、心智模型、与同一代码库中相邻 API 的一致性、受控/非受控模式的易用性、组合方式、逃生舱口、类型形状、默认行为、未来扩展性、迁移风险，以及用户可能遇到的陷阱。优先报告能在不理想的公共契约发布前避免问题的发现。 如果 API 设计问题可能导致用户可见的陷阱或回归，则在 Bugs 下报告；否则在简化下报告。

条件性专家审查 - 运行时性能

不属于默认的四个领域审查。low 时完全跳过。medium 时，如果变更可能影响运行时性能，则在主 Agent 审查中涵盖：渲染热路径、大量条目集合、虚拟化、定位、布局测量、滚动/调整大小/指针/键盘处理程序、观察器、动画、重复的 DOM 读写、循环中的状态更新、组件注册/查找路径。high、xhigh、max 时，若满足触发条件，则由独立的运行时性能子 Agent 执行审查。

可行时优先进行具体测量：使用现有性能测试、有针对性的基准测试脚本或小型可复现测量。如果无法实际测量，请说明预期的复杂度或浏览器工作量，以及如何验证。若用户可感知到卡顿、掉帧、挂起或过量工作，则在 Bugs 下报告运行时性能问题；否则在简化下报告。

对抗性 Bug 猎手

根据投入级别添加的子 Agent 角色。假设 diff 中存在消费者会遇到的 Bug。不要相信 PR 描述、注释或测试名称——要对照代码核实。直接攻击已更改的不变量：构造能让新代码出错的具体输入、状态、时序或平台。报告每个具有明确失败场景的候选问题；若没有候选问题成立，则报告为空——绝不要为了证明搜寻有价值而凑出牵强的问题。

---

简化、测试、文档类候选问题使用相同的 file/line/summary 格式；在 failure_scenario 中，说明具体代价（重复了什么、浪费了什么、哪些内容未测试或已过时、维护难度如何增加），而不是崩溃。排序时，回归和正确性 Bug 的优先级始终高于简化、测试和文档类问题。

阶段 2 - 核实候选问题（默认在本地核实；max 级别增加子 Agent 投票）

合并指向同一行／机制的候选问题，保留失败场景最具体的一个。默认由主 Agent 在本地核实候选问题。

根据可触发性和影响评估每个候选问题。保留每个有效 Bug。如果行为在真实消费者的使用场景中实际上无法触发、没有实际用户影响，或只是可选改进而非正确性缺陷，则降级为 ℹ️ 提示。降级并不代表驳回——降级的问题仍要输出，只是严重性较低。在 max 级别，如果有可用且经授权的子 Agent，还要为每个剩余候选问题安排一名核实者：提供 diff、相关文件和候选问题，并要求其仅返回以下一项：

• CONFIRMED — 能指出触发问题的输入／状态以及错误输出或崩溃，并引用代码行。
• PLAUSIBLE — 机制确实存在，但触发条件不确定（时序、环境、配置）。说明如何确认。
• REFUTED — 事实错误（代码并非如此）或已由其他位置防护。引用证明这一点的代码行。

保留投票为 CONFIRMED 或 PLAUSIBLE 的候选问题。

在 max 级别，核实应偏向尽量避免漏报——默认判为 PLAUSIBLE：如果状态现实可见（并发竞态、罕见但可触发路径上的 nil/undefined、将假值 0 当成缺失值、边界代码未排除导致的差一错误、重试风暴／部分失败、正则／允许列表丢失锚点），不要仅以“推测性”或“取决于运行时状态”为由驳回候选问题。只有在能从代码中构造性地证明时才判为 REFUTED：事实错误、可证明不可能、已在此 diff 中处理，或纯风格问题且没有可观察影响。

阶段 3 - 扫描遗漏（xhigh / max 投入级别）

在 xhigh 和 max 级别，增加一名查找者，作为新审查者，并提供当前问题列表。重新阅读 diff 和外围函数，仅查找尚未列出的问题。不要重新推导或重新确认已有问题——任务是查漏。重点关注初轮容易漏掉的内容：移动／提取代码时丢失防护或锚点；次级陷阱（dataclass 默认值只求值一次、hash() 非确定性、锁作用域缩小、有副作用的谓词方法）；测试中的设置／清理不对称；配置默认值被翻转。提出额外候选问题，并指出尚未列出的缺陷。如果没有新问题，则返回空的扫描结果——不要凑数。

输出

以 Markdown 回复。不要将主要结果包在 JSON 或代码围栏中。# 标题和所有问题标题都使用句首字母大写格式，不要使用标题式大小写。开头不要写“已对照 branch 审查 owner/repo#123”这类泛泛的目标／基准信息。只有在解释具体问题或限制时，才提及目标或基准分支。

仅输出非空类别章节，并按以下顺序排列：Bugs、Tests、Simplifications、Docs。没有问题的类别不输出任何内容——不写标题、不计数，也不写“No findings.” 占位内容。结尾始终写 Verdict。发送前，确认每个保留的问题恰好输出一次，且每个已输出章节的计数与编号问题数量相符。若所有类别均无问题，则使用无问题格式。

严重性标准

每条发现的标题都必须以一个严重性标记开头：

• 🟣 critical - blocking（严重 - 阻止合并）。 正确性问题导致常见流程崩溃、用户数据丢失、安全/隐私问题、公共组件契约无法使用，或造成跨组件的广泛无障碍、焦点、表单或 SSR 问题。必须阻止合并。
• 🔴 high - blocking（高 - 阻止合并）。 在正常组件使用、无障碍、键盘/焦点行为、受控/非受控行为、表单集成、SSR/水合、公共 API 行为方面，或公共文档示例不再能编译或会教用户错误的 API 用法时，造成现实的用户可见回归。即使受影响路径有变通方法，或并非最常见路径，也应阻止合并。
• 🟠 medium - non-blocking（中 - 不阻止合并）。 值得在条件允许时于合并前修复的实际问题，但通常不阻止合并：范围狭窄或不常见的缺陷、有意义的测试缺失、不影响复制粘贴代码的过时公共文档文本，以及可避免未来可能错误的清理工作。仅当问题不破坏公共契约，且不影响无障碍、焦点、表单、SSR 或正常组件使用时才使用。
• 🟡 low - non-blocking（低 - 不阻止合并）。 轻微的边缘情况缺陷、小的测试/文档缺口，或虽有帮助但维护者可以轻松延后的适度简化。
• ℹ️ note（说明）。 仅供参考——观察、提示或可选建议，维护者可以合理地不予采纳。

Material UI 的质量标准比大多数应用更严格——组件库中的小回归会在许多下游产品中成倍放大。在相邻严重性之间选择时，如果问题会影响现实的使用方场景、无障碍行为、表单行为、焦点管理、SSR、公共 API 契约或有缺陷的公共文档示例，请选择更高的严重性。不要只把 🔴 high 用于导致服务中断级别的问题。

在每个部分内，按 🟣 -> 🔴 -> 🟠 -> 🟡 -> ℹ️ 排序。

结论

以 ## Verdict 行结束评审，依据标记确定结论：

• Request changes（请求修改） — 至少有一条 🟣 或 🔴 发现。
• Approve after nits（修正小问题后批准） — 没有 🟣 或 🔴，但有一条或多条值得处理的 🟠 或 🟡 发现。
• Approve（批准） — 没有 🟣、🔴、🟠 或 🟡 发现（仅有 ℹ️ 说明，或没有发现）。

结论后用一个分句说明决定因素。

发现格式

使用以下结构。计数为零的类别块应省略：

# PR review

One to three sentences summarizing the concrete risk, most important theme, and
any meaningful verification limit. State up front whether anything is merge-blocking.
If there are no actionable findings, say that clearly.

## Bugs ({count})

### 1. {severity marker} {Sentence-case title}

**Location:** `path/to/file.ext:123`

```tsx
// Small relevant code excerpt from the reviewed file.
```

{Description of what is wrong and why it matters.}

**Failure scenario:** {Simple, obvious user-facing or example issue someone would
see.}

**Fix:** {Specific recommended change.}

## Tests ({count})

## Simplifications ({count})

## Docs ({count})

## Verdict

**{Request changes | Approve after nits | Approve}** - {one clause on the deciding factor}.

---

🤖 Review generated with {Claude Code | Codex}

测试、简化、文档部分也使用相同的单条发现格式。对于测试，将失败场景描述为缺失的测试用例或薄弱的断言。对于简化，指出具体重复、冗重或更难维护的代码路径。对于文档，指出过时或缺失的面向公众/开发者的信息。

发现质量

发现数量不限。报告每一项经过验证、可采取行动，且维护者会合理地在合并前修复的问题。不要用薄弱、风格方面、推测性或重要性低的问题充数。如果有多项发现，应在根本原因相同的情况下将相关问题归为一项。

没有发现

如果没有问题通过验证，则省略所有类别标题和计数。返回 # PR review、No findings.、一条简短说明，指出剩余的测试缺口或风险、包含 Approve 的 ## Verdict，以及 🤖 Review generated with ... 页脚。

最终输出预检

将输出格式视为硬性要求。发送前：

• 使用 # PR review；摘要应从具体风险开始，而不是目标/基准填充内容。
• 仅为非空类别打印精确的 ## {Category} ({count}) 标题。
• 每条发现只打印一次，并核对每个类别的计数。
• 使用单独的 ## Verdict 标题和规定的结尾页脚。

如果有任何一项检查未通过，请在发送前重写输出。

评审始终以 --- 水平分隔线结束，空一行后添加 🤖 Review generated with {Claude Code | Codex}。当此技能由 Claude Code harness 执行时使用 Claude Code；由 Codex harness 执行时使用 Codex。

发布到 GitHub（--comment）

仅当目标是 GitHub PR 且参数包含评论模式时，才发布到 GitHub：

• 未指定 --comment — 不发布到 GitHub；如果也未指定 --fix，则在 Markdown 审查报告处停止。
• --comment — 通过 gh pr comment 将 Markdown 审查内容作为一条顶层 PR 评论发布。
• --comment inline — 为能映射到 PR 差异行的发现发布行内评论，并将所有不在差异中的发现放入顶层备用评论。

使用 --comment inline 时，每条行内评论正文都应包含相同的严重性标记。使用最新 PR 头部的 commit_id、path、line 和 side，通过 gh api（repos/{owner}/{repo}/pulls/{pr}/comments）发布，每条发现调用一次。（如果会话中有可用的 GitHub 行内评论 MCP 工具，则使用该工具。）

行内评论只能附加到 PR 差异中存在的行。将 PR 差异之外的发现（已修改函数中的未更改行）放入顶层备用评论，通过 gh pr comment 发布；不要丢弃这些发现，也不要因为某条行内评论无法发布而停止发布其余审查内容。如果目标不是 PR，则将发现打印到终端，并注明已忽略 --comment。

应用修复（--fix）

如果参数中传入了 --fix 标志，则在列出发现后，将发现应用到工作树，而不是停留在报告上：直接修复每一项，包括正确性错误以及复用、简化和效率方面的清理。如果某项修复会改变预期行为、需要大幅修改审查差异之外的内容，或你判断其为误报，则跳过该项，并注明已跳过，无需辩解。最后简要总结已修复和已跳过的内容。

如果既未传入 --comment，也未传入 --fix，则在 Markdown 审查报告处停止。