interface-review

审查变更，而不只是审查变更留下的代码

差异不只是表面内容。变更删除的行和新增的行同样重要，而且变更涉及的文件很少仅限于它直接修改的文件。

此技能只负责变更范围：确定目标，将变更文件扩展到受影响的范围，阅读差异两侧，并对每项发现进行分类。领域规则由 better-* 技能负责。模式、严重程度、合并、覆盖范围、上限、输出格式和结论由 better-interface 负责，本技能会将审查交给它。切勿在此重复或覆盖这些规则。

正确性、测试、安全性和性能由项目的常规代码审查负责。指出一次相关问题即可，然后继续。

快速参考

类别	使用时机
范围解析	目标和命令、默认分支、合并基点、PR 和分叉引用、仓库状态、无变更可审、重命名、排除项、使用方扩展
已删除信号	查看差异块中 - 一侧的内容，以及每项删除由哪个技能负责

核心原则

1. 首先确定变更范围

better-interface 负责解析模式；模式之后的所有内容都是目标，因此 /interface-review quick pr 482 表示对第 482 个拉取请求进行 quick 审查。范围解析列出了可接受的目标及对应命令。

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

1. HEAD 超前于 git merge-base origin/<default-branch> HEAD：审查该范围以及所有未提交的变更，并分别说明提交数和未提交文件数。
2. 工作树有改动：审查未提交的变更。
3. 两者均不满足：没有可审查的变更。根据原则 2 停止并询问用户。

顺序很重要：先检查工作树，会让一处零散的格式修改掩盖一个包含 12 个提交的分支，而报告却仍声称已完整覆盖。

排除锁文件、快照、生成的输出、供应代码和二进制文件，并说明排除了哪些内容。如果排除后范围为空，这只是通过另一种方式触及原则 2：列出排除的文件并询问用户。

2. 没有变更时，应先询问，而不是自行臆造

如果工作树干净，并且没有提交超前于合并基点，就表示用户要求审查一个并不存在的变更。切勿擅自退回到 HEAD~1..HEAD。最后一个提交只是碰巧进入仓库的内容——往往是一次合并，也往往是其他人的工作——针对它的报告无法与针对用户本意的报告区分开来。

说明你查到的仓库事实，然后给出可选方案并等待回复。无变更可审列出了相关命令：

• 最后一个提交：HEAD~1..HEAD，列出短 SHA 和主题，让用户在选择前知道会审查什么。
• 用户指定的目标：pr <n>、分支、引用或范围，按原则 1 解析。
• 整个仓库的界面审计：这不是变更审查。将其作为仓库范围审查交给 better-interface，并去掉本技能的范围区块、状态和预先存在的问题区块：没有变更时，所有发现都属于既存问题，这种分类不提供任何信息。

询问前，先检查当前分支是否有未关闭的拉取请求；如果有，优先提供该选项。分支上的提交即使已合并到基准分支，当前分支仍会解析为无变更，但其拉取请求仍可能正是用户所指的目标。

排除后范围为空时，情况相同，只是成因不同。说明排除了哪些文件，并按同样方式询问；不要将对空范围的审查报告为 Approve。

3. 差异不等于界面

变更的文件只是证据，不是评审对象。它渲染出的各个界面才是其影响范围，应评审这些界面。

默认将影响范围扩展一跳：直接导入者和调用者。只有设计令牌、主题值和共享基础组件才扩展第二跳，因为一行代码就可能影响整个产品。

最多评审五个使用方，按范围解析中的规则排序，并说明还有多少个未扩展。无边界地全面检查，会得出无法佐证的覆盖声明；不说明检查范围上限，则会让报告看似完整，实则不然。

4. 阅读被删除的行

回归在变更后的状态中不可见。请根据已删除信号阅读每个差异块中 - 一侧的内容。

信号只是线索，不是发现。只有变更中没有任何内容替代某项删除时，该删除才构成回归；这项判断由相应领域技能负责。将每项未匹配的删除交给其负责人，只报告该技能确认的内容。然后将其标记为 Regression，以此告知作者：他们破坏了原本正常工作的内容，而不是犯了一个新错误。

5. 为每项发现分类

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

• Introduced：由此变更引入。
• Regression：此变更削弱了之前正确的内容。
• Pre-existing：存在于触及的代码中，但并非由此变更导致。

根据差异触及的内容判断状态，而不是看它位于哪个文件：变更从未触及的行，即使距差异块只有三行，也属于 Pre-existing。必要时根据基准引用确认：

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

将每项发现连同其状态一起交给 better-interface，由它应用数量上限和判定规则。

6. 根据变更声明的意图进行评审

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

这会揭示不完整的变更；界面评审无法通过检查已存在的状态发现这一点，因为问题恰恰在于这些状态缺失：

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

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

7. 将评审交给 better-interface

明确评审范围、受影响的界面以及差异的两侧后，将评审连同范围区块和每项发现的状态交给 better-interface。它会转交给领域技能、应用严重程度、合并发现、执行数量上限并给出判定，包括其 Change-Scoped Reviews 章节中的变更范围规则。

如果 better-interface 不可用，请报告解析后的范围和文件清单，指出缺失的技能，然后停止。不要擅自设定严重程度等级、数量上限或判定。

8. 绝不修改工作树

变更评审是只读操作，包括检出操作。请获取拉取请求引用；绝不要检出它们。git fetch 只会写入 .git，因此允许使用。gh pr checkout、git checkout、git switch 和 git stash 会重写作者当前打开的文件，可能因本地编辑而失败，也可能丢弃这些编辑，因此在任何模式下都绝不允许使用。

渲染验证需由用户选择启用：除非项目提供低成本预览，或用户要求进行渲染评审，否则应将视觉和运行时声明标记为 Not verified。若启用，请使用隔离的工作树（git worktree add /tmp/review-<n> refs/remotes/pr/<n>），完成后将其移除。这样不会触碰作者的工作树，而检出操作会，因此检出并非此处的替代方案。

常见错误

错误	修正方法
只检查了一处意外改动，而不是整个分支	先检查 merge-base，再检查工作树，并报告两者的计数
因为没有改动就检查了最后一次提交	说明仓库的实际情况，并提供最后一次提交、指定目标或仓库审计等选项
检查了代码块，却没有检查使用它们的代码	向外扩展一层；对于令牌和基础组件，扩展两层，并说明跳过了哪些内容
只读了差异的 + 一侧	搜索 - 一侧，查找被移除的无障碍、焦点、动效和文本信号
将等效替换报告为回归	将移除项交由负责的技能处理，并且只报告其确认的内容
将移除项报告为新错误	将状态标为 Regression，让作者知道它以前可以正常工作
将代码块附近的一行标为 Introduced	根据差异实际触及的内容确定状态，并通过对照基础引用的 git blame 加以确认
为了审查而检出拉取请求	获取引用并就地审查
引用了审查所用引用中不存在的行号	根据范围块中指定的头部引用给出引用位置
在此重复说明模式、严重程度、上限、输出格式或结论	遵循 better-interface 的规定
在报告中提出正确性、测试或安全方面的问题	只提一次该问题，指向项目的代码审查，并将其删除

审查输出格式

输出格式由 better-interface 负责，包括其 Change-Scoped Reviews 一节中的四项变更范围补充。请按原样遵循，不要在此添加任何内容。

此技能提供以下范围块：

字段	值
目标	branch、working、staged、pr 482 或按原样输入的范围
基础引用	origin/main，位于 a1b2c3d
头部引用	refs/remotes/pr/482，位于 e4f5g6h
提交	已提交 7 个，未提交文件 2 个
范围内的文件	排除后 12 个
已排除	pnpm-lock.yaml、src/__snapshots__/：锁文件和快照
已扩展的界面	CheckoutPage、SettingsPanel；未扩展另外 3 个 Button 的使用处

此外，根据原则 5，为每项发现标注状态。

在 better-interface 的 Verification 一节中，列出确切的 git 和 gh 命令及其结果，包括对 .git 的每次写入（如 fetch、deepen、set-head、worktree），以便审计只读声明是否符合原则 8。