apply-ui-review

apply-ui-review · 落实 UI 验收评审

把独立评审给出的差距清单变成真实的界面改进，让下一轮评审的分数明显提高。评审看过目标和截图，所以可修复的差距默认全部处理；但每条仍要对照截图、目标包和规范核实一遍，评审看错的、与目标包矛盾的，不照着改。用户调用本技能，即授权核实、修复、运行必要的检查、按计划约定提交并回写记录。

核实和自检都以运行中的真实界面为准。 无论是判断评审看错、判断差距已不存在，还是确认修复生效，依据只能是本轮实拍的截图、页面里实测的样式和尺寸，以及实际操作的结果。不能读了代码就下结论。

本技能不给自己打分。 修复是否到位，由下一轮 review-ui 的独立评审判定，所以记录里的处置最多写到「已修改待评审」。不改评审报告、评审截图和 judge.md；只有用户明确确认后，才把用户的决定写进目标包。推送、部署等按已有授权处理。

references/ 相对本文件解析。启动方式、组件库、设计规范和检查命令从目标仓发现。语言跟随用户。

循环模式与能力探测

先核对报告前缀对应的 <前缀>.ui-review.json 与安装回执。已有纯 Markdown 历史而无 managed 索引时按本文人工流程执行，必须显式 import 才接管；缺少 Phoenix CLI 不妨碍读取报告、目标和原文材料，也不把人工处置宣称为 managed 状态。

已有 Phoenix managed 索引时，修复前核对固定版本 engine 身份与实际 review 协议；缺失、不匹配、未来 schema 或状态损坏时只读历史，可收集未登记素材，不改产品代码、目标、处置、计数、报告生成区或计划记录。说明恢复匹配 engine 的方法，恢复后续接原循环；不以人工降级、新前缀或重置基线绕过它。

安装包包含 review-ui 时，按其 Phoenix 评审协议 发现能力与续接状态；单独使用本技能时仍遵守上述边界，机器输入只依实际 review --help 与 review schema --json 返回的 typed examples，不猜字段；样例不是证据，身份、hash 和 revision 取真实操作与材料。managed 处置用 review apply record 登记当前轮，带当前 applied revision；旧 Markdown 的接入必须显式 review import，历史不明的尝试、重构次数不视为零。

1. 锚定输入

1. 定位用户给的 UI 验收报告，从报告头的「评审对象」找到计划、目标包、截图目录和上轮报告，并核实它们确实对应。用户没给报告时，人工循环从上下文或计划同目录取轮次最大的 .ui-review 报告；managed 循环从索引读取本循环当前报告，不按文件修改时间或猜轮次。有多份无法判断时询问。
2. 按报告的验收判定处理：
   • 需要修改：处理可修复的差距。带「停滞预警」时，按下文做重构轮。带「待裁定」时，那些事项先不改，记「待决定」，除非用户本次已就它给出方向。
   • 需补证：所缺的证据由 review-ui 补齐。报告里已评单元的可修复差距，用户要求时可以先修。
   • 需用户裁定：用户本次没给方向时，转述报告里的选项，请用户决定，不动停滞和待裁定的部分；给了方向就照做，并把用户原话记下来。
   • 通过验收 / 用户豁免通过：只有用户要继续打磨时，才处理剩余差距。
3. 用户接受某处偏差或修改期望时，经用户明确确认后，写进目标包对应单元的比较口径或规范要点，注明日期和用户原话，并追加变更记录；下一轮评审会据此重建基线。用户接受整体界面时，提示由 review-ui 记为豁免通过，本技能不改报告。
4. 读目标包、报告中的差距清单、待裁定事项和上轮复核表，以及以往各轮的修复记录（见记录合同）。记下当前 HEAD 和未提交改动，分清哪些是用户已有的修改、哪些是本次修复。用户限定了差距编号或单元时，只处理这些。

2. 核实与排序

• 核实：逐条打开报告引用的截图和目标图，在运行中的界面里按同一单元、状态、视口和主题复现；再对照目标包的规范要点、比较口径和 DESIGN.md。
• 成立的：进入修复。
• 不采纳：以下情况记「不采纳」并写明依据，不改代码：评审看错（运行中的界面与评审描述不符，附截图或实测值）；与目标包或规范矛盾；属于比较口径排除的差异。报告附了核对说明的差距，同样自己核实，确实不成立就记不采纳。
• 待决定或阻塞：需要素材、文案、数据、接口或产品决定才能修的，记「待决定」或「阻塞」，然后继续处理其他条目。
• 待核实：先在运行中的界面上确认现状；已经没问题就附截图如实记录，不为它改代码。
• 建议：不扣分。与规范一致且代价小时可以顺手做，但不能因此降低对目标的还原度。
• 顺序：P0/P1 先修；同一严重度内按可挽回分从高到低。能一次消掉多条差距的共同根因优先，例如字体没加载、token 用错、布局原语选错、容器约束。

3. 修复

• 在正确的层级修根因，层级从高到低依次是：主题与 token、共享组件、页面布局、单处样式。用 DESIGN.md 的 token 和现有组件，不为贴合截图写魔法数字，也不为单个页面复制一份共享组件。目标确实要求偏离规范时，记下依据。
• 只改界面范围内必要的代码、样式、素材和测试。修复需要改接口、数据契约或计划范围时，记「待决定」，不擅自扩大。
• 保留用户已有的修改，不 reset、stash 或回退。
• 回归：报告判为回归的差距，先用上一轮以来的 diff 找出是哪个改动引入的，修正它；不要用另一处回归来换。
• 重构轮：报告带停滞预警时做，只针对预警的范围（全局，或某条差距所在的单元）。停止微调：
  1. 写清以往的尝试为什么没奏效。
  2. 列出可能的结构性原因：布局模型或组件选错；素材质量不够；token 或主题不符；字体或图片没正确加载；容器与断点约束；数据形态；采集环境与目标不一致。
  3. 选证据最强的一条，做一次大的结构性改变，目标是明显提分，而不是小修小补。
  4. 把范围、假设、改动和预期写进记录。每个范围在同一基线内只有一次重构机会；下一轮评审靠这份记录判断有没有走出停滞。
• 只记真正改过的：一轮做不完的差距，如实标「未处理」，不算尝试过。只有真正改过的才记「已修改待评审」，下一轮的顽固差距判定以此为准。

4. 自检

1. 启动当前代码，按目标包的条件采集受影响的单元，自己与目标对照；再把其他单元快速过一遍，确认没引入回归。自检截图默认放临时目录；需要作为记录证据时，存到 <前缀>.ui-captures/r<n>-apply/，不覆盖评审截图。
2. 运行计划和仓库要求的相关检查：组件测试、单元测试、类型检查、lint、构建。项目有视觉回归测试时，只在改动符合目标的情况下更新快照，并说明更新了哪些。检查失败时，分清是新引入的回归、原本就有的失败，还是环境问题；新引入的回归要继续修。
3. 应用起不来或无法截图时，自检记「未运行」并写明原因，不能凭代码判断已经修好；处置仍是已修改待评审，由下一轮评审在真实界面上判定。
4. 自检不算验收：不估分，不宣称已经达标。

5. 提交、记录与交付

1. 按 记录合同 保存本轮处置。人工循环更新这一轮已有的小节，不重复追加；managed 循环用 review apply record 和当前 applied revision 更新，只让 engine 投影原记录位置里属于本循环、本轮的区块。冲突或生成区被手改时保留原文并停止覆盖，用显式 import 按权威事实恢复生成区，再以当前 applied revision 重新登记要保留的处置，不自动强写。

2. 计划有提交约定，或用户授权提交时：

   • 只暂存本次修复和记录，遵守仓库的提交规范，不跳过提交钩子；
   • 提交后，在完成记录对应里程碑行的「提交」列追加 UI修复 加短 SHA，再单独提交这次登记。

   两者都没有时不提交，修复留在工作树，下一轮评审以工作树为被测版本。提交失败就如实记录，不伪造 SHA。

3. 回读记录和计划的改动；查看最终 diff，确认没有无关修改，评审报告、截图和 judge.md 都没被改动，目标包只多了经用户确认的决定，用户的修改没被覆盖。

4. 回复内容：

   • 各类处置的数量和关键改动；
   • 重构假设（如有）；
   • 自检和检查结果；
   • 提交 SHA，或未提交的原因；
   • 记录链接；
   • 待用户决定的事项。

   结尾给下一步：用 review-ui <计划路径> 复审，按当前客户端写法给出（如 Codex $review-ui、Claude Code /review-ui）。不自行启动评审。

调用示例：

使用 $apply-ui-review goal/LOGIN.ui-review.r2.md
使用 $apply-ui-review goal/LOGIN.ui-review.r3.md，只处理 UI-04 和 UI-07。
使用 $apply-ui-review goal/LOGIN.ui-review.r5.md，U3 按设计稿改成两栏卡片。

项目状态回写

若仓库已登记状态台账，或存在仓根 .xgent-ai/sdlc/protocol.md（兼容已有 docs/project-status/protocol.md；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存及 managed 能力异常时的只读边界优先，登记失败须说明，不影响如实交付已完成的原产物。

接着原评审对象登记处置：差距编号、处置、修复版本、自检结果和未完项，并链接实现记录。「已修改待评审」不登记为已解决，修复也不能登记成独立复审通过。