interface-review

界面审查

此技能审查的是变更，而不是屏幕。它会确定范围，将变更文件扩展到其影响的界面，查看差异的两侧，并对每条发现进行分类。

它负责范围、分类和变更范围内的报告。领域规则属于 better-* 技能。严重程度、合并归类、覆盖范围、上限和结论属于 better-interface，此技能会将审查交由它处理。

正确性、测试、安全性和性能属于项目的一般代码审查。只提及此类问题一次，指向该审查，然后略过。

审查变更，而非代码库

作者想知道的是“我是否让情况变糟了？”。报告变更造成的问题，对于仅仅触及的内容，大多保持沉默。指出三个预先存在的问题算是客气；指出三十个就变成了另一种审查，而且没人要求做那种审查。

在形成意见之前，先阅读完整差异。只粗略浏览差异，会导致你指出的问题已在下一个代码块中修复。

1. 先确定变更范围

整个调用都是审查目标，因此 /interface-review pr 482 审查的是拉取请求 482。范围确定列出了接受的目标及其确定方式。

未提供目标时，按以下顺序确定，并在首次匹配时停止：

1. HEAD 超前于 git merge-base origin/<default-branch> HEAD。审查该范围以及所有未提交的变更，并分别说明提交数量和未提交文件数量。
2. 工作树有未提交变更。审查这些未提交的变更。
3. 两者都不是。没有变更可供审查，因此遵循没有变更时，询问而非凭空编造。

将已确定范围的基准提交记录为 $BASE，并在范围区块中注明。此技能及其引用内容中的所有命令都使用它。

根据排除路径，排除锁文件、快照、生成的输出、供应代码和二进制文件，并说明排除了哪些内容。如果排除后没有剩余内容，则按没有变更处理。

2. 没有变更时，询问而非凭空编造

如果工作树干净，且没有任何提交超前于合并基准，则没有变更可供审查。绝不要自行退回到 HEAD~1..HEAD。最后一次提交只是恰好进入分支的内容，通常是合并提交或他人的工作。

收集没有可审查内容中列出的信息，说明这些信息，然后提供以下选项并等待用户回复：

• 当前分支上的未合并拉取请求；如果存在，优先提供。提交已合并的分支会被判定为没有变更，但其拉取请求仍可能正是用户想审查的内容。
• 最后一次提交，即 HEAD~1..HEAD，说明其短 SHA 和主题，以便用户了解审查内容。
• 用户指定的目标，例如 pr <n>、分支、引用或范围。
• 整个代码库的界面审计，这不是变更审查。将其交给 better-interface，作为代码库范围的审查，不使用此技能的范围区块、状态或预先存在的问题部分。

如果排除操作清空了范围，在提供选项时注明被排除的文件。绝不要将对空范围的审查报告为 Approve。

3. 差异不等于界面

变更文件是证据，而不是审查对象。其影响范围是它会呈现于其中的界面集合；审查这些界面。

默认向外扩展一层，检查直接导入者和调用者。只有在设计令牌、主题值和共享原语的情况下才扩展第二层，因为一行代码就可能影响整个产品。

两层扩展合计最多审查五个使用方，并按照范围确定中的规则排序。说明有多少使用方未扩展，否则未说明的截断会让人以为审查已经完整。

4. 阅读已删除的行

回归在变更后的状态中不可见。请对照已删除信号阅读每个代码块中 - 一侧的内容。

信号只是线索，不是发现。只有当某项删除没有被变更中的任何内容替代时，它才构成回归；这一判断由对应领域技能负责。将每项未匹配的删除交给其负责人，只报告该技能确认的问题，并将状态标为 Regression。

5. 为每项发现分类

为每项发现指定一种状态：

• Introduced：由本次变更引入。
• Regression：本次变更削弱了此前正确的内容。
• Pre-existing：变更前就已存在，且未因本次变更而恶化。

状态取决于原因，而非位置。由变更行导致的发现，无论出现在哪里，包括出现在未修改的变更词元使用方中，都属于 Introduced 或 Regression。变更既未引入也未加重的发现属于 Pre-existing，即使它距离代码块只有三行。

若要检查某行是否早于本次变更，请对审查范围执行 blame。^ 前缀表示该行自基准版本以来未更改：

git blame -L <line>,<line> "$BASE"..<head-ref> -- path/to/file

对于未提交的工作，省略范围。标记为 Not Committed Yet 或归因于 $BASE..HEAD 范围内某个提交的行，都属于本次变更。

6. 按变更声明的意图进行审查

阅读拉取请求的标题和正文、关联的问题以及提交消息，然后审查界面是否实现了它们所声称的内容。

这能帮助你发现不完整的变更；表面审查只检查现有状态，因此会漏掉这类问题。请查找缺失的状态：

• 新增的变体、尺寸或主题只应用于部分状态，未覆盖悬停、焦点、激活、禁用、加载和选中状态。
• 新增的面向用户的字符串未录入项目维护的翻译目录。
• 新组件缺少空内容、加载、错误、禁用或窄屏状态。
• 控件只添加到一个界面，而同类控件已存在于其他并列界面。

不要报告范围蔓延。变更做得太多与否是流程问题，不是界面问题。

7. 将审查交给 better-interface

将范围块、受影响的界面以及每项发现的状态交给 better-interface，并按以下格式报告。

如果 better-interface 不可用，请报告已确认的范围和文件清单，指出缺失的技能，然后停止。不要自行编造严重程度等级、上限或结论。

绝不修改工作树

变更审查必须只读，包括检出状态。git fetch 只会写入 .git，因此允许使用。gh pr checkout、git checkout、git switch 和 git stash 会重写作者正在编辑的文件，因此绝不允许使用。请获取拉取请求引用并就地读取。

此处的渲染验证为可选，代替 better-interface 的验证可验证的内容。除非项目提供了便捷预览，或用户要求进行渲染审查，否则将视觉和运行时相关结论标记为 Not verified。对于 working 和 branch，当前检出内容就是头版本，因此请就地渲染。对于任何其他目标，请渲染隔离的工作树，例如 git worktree add /tmp/review-<n> refs/remotes/pr/<n>，完成后将其移除。

完成前

错误	修正
当 HEAD 超前于合并基点时，范围块只统计未提交文件	同时审查分支范围和未提交的更改，并列出两者的数量
用户从未选择过的 HEAD~1..HEAD 报告	陈述事实，并提供 没有更改时，应询问而不是臆造 中的选项
在 Surfaces expanded 下有已更改的共享组件，却没有列出其使用方	扩展到其使用方，并注明跳过了哪些使用方
删除了 aria-label、outline 或 prefers-reduced-motion，却没有发现项或备注	通过 已移除的信号 将其转交给负责人
某个 Regression 的已删除属性在差异的其他位置重新出现	先检查等效替代项
某个使用方未更改，但因令牌变更而产生的问题被标记为 Pre-existing	问题由此次更改导致，因此应标记为 Introduced 或 Regression
某行不在任何差异块中，却被标记为 Introduced，且没有指出导致问题的更改	针对所审查的范围执行 blame
命令日志中出现 gh pr checkout 或 git switch	获取 ref 并使用 git show 读取文件
引用的行与 git show <head-ref>:path 不符	根据范围块中注明的 head ref 引用

审查输出格式

以范围块开头：

字段	值
目标	branch、working、staged、pr 482 或输入的范围
基准 ref	origin/main，位于 a1b2c3d
Head ref	refs/remotes/pr/482，位于 e4f5g6h
提交	7 个已提交，2 个文件未提交
范围内文件	排除后共 12 个
已排除	pnpm-lock.yaml、src/__snapshots__/、锁文件和快照
已扩展的界面	CheckoutPage、SettingsPanel；还有 3 个 Button 使用方未扩展

其后是 better-interface 中的覆盖表。对于更改范围内没有证据的领域，应标记为 Not reviewed: no evidence in the change scope；这是覆盖情况的说明，而不是遗漏。

接着列出发现项，并在每项中添加 对每项发现进行分类 所要求的 Status 列：

严重性	领域	状态	位置	更改前	更改后	原因
HIGH	无障碍	Regression	src/Dialog.tsx:42	此次更改移除了 aria-label="Close"	在仅含图标的控件上恢复 aria-label="Close"	此次更改前，关闭控件有可访问名称；更改后则没有

如果没有 Introduced 或 Regression 发现项，则省略此表，并写明“此次更改中没有可操作的界面问题。”

然后列出 Pre-existing 发现项，最多 3 项，按严重程度从高到低排列，并明确说明这些问题不属于此次更改的责任范围。没有此类问题时，省略该部分。

严重性	领域	位置	问题
MEDIUM	排版	src/Toolbar.tsx:7	数字徽标使用比例数字；该问题早于此次更改

最后按照 better-interface 的格式给出验证结果和结论。