review-ui

review-ui · UI/UX 验收评审

判断实现出来的界面是否达到预期，并给出一份清单：另一位 agent 照单修完，下一轮分数应明显提高。本技能与 apply-ui-review 组成验收循环：每次调用评一轮，修复后再评，直到通过、停滞后交用户裁定，或用户明确放过。

每轮由全新上下文的独立评审对照目标打分。主 agent 只负责采集、复核和裁定，不给自己的修复打分。 循环的状态都在落盘文件里：目标包、逐轮截图、评审原始结论、报告和修复记录。手动交替调用和用 goal 自动推进，都按同一规则续接。

只认真实效果。 分数、差距和判定只能来自三种证据：本轮在真实运行的产品上实拍的截图、实际执行过的操作、在页面上实测的结果。代码、diff、计划、设计意图，以及「按代码应该会这样」的推断，只能用来找入口、定位问题，不能用来打分、开差距、关差距或判通过。拿不到真实效果的单元不打分，判需补证：宁可不评，也不能想象。

默认交付：首轮建立目标包；每轮的截图、评审原始结论和完整报告落盘并回读。聊天先给验收判定，再给分数轨迹、关键差距、截图位置和下一步命令。产品代码、计划和历史报告只读，不修复、不提交、不改进度。

references/ 相对本文件解析。目标仓的启动方式、账号、设计规范和截图工具在运行时发现。语言跟随用户。

适用边界

• 适用于有可运行界面的验收：计划实施并通过代码评审后可选的 UI 验收、修复后的复审，以及用户给出页面与目标图或规范的单次验收。
• 不适用于：代码缺陷评审用 review-code；修复差距用 apply-ui-review；找视觉方向用 design-reference；交互方案选型用 ui-pattern-research；维护 DESIGN.md 用 design-md。
• 拿不到真实效果时（没有可用的渲染或截图工具、应用起不来、状态到达不了），按上面的规则判需补证，说明缺什么、怎么补。

循环模式与能力探测

先确定本循环的前缀，检查 <前缀>.ui-review.json、已有报告和安装回执。已有纯 Markdown 历史而无 managed 索引时继续人工流程，必须显式 import 才接管。全新无索引、无旧循环历史且用户已要求 UI 验收时，先按下述协议探测；真实 engine 与 review verbs 匹配后可 review begin 建立 managed 循环，缺 CLI 或能力不匹配时走人工流程。没有 CLI 不妨碍读取原文、采集真实界面和人工落盘；没有机器索引就不能假称已接管。

已有 managed 索引时，先按 Phoenix 评审协议 核对固定版本 engine 的身份与实际支持的 review 协议。缺失、不匹配、未来 schema 或索引损坏时只读历史，可收集未登记素材；不计分、不裁定、不写处置、计数或报告生成区，也不新建循环来绕过原状态。说明恢复匹配 engine 的方法，恢复后续接原轮次与 revision。

匹配时由 review begin 分配轮次并冻结目标与矩阵，后续依次登记采集、读取白名单 packet、登记评审原文、裁定与回读。JSON 输入按实际 review --help 与 review schema --json 返回的 typed examples 构造，不猜字段；样例不是证据，身份、hash 和 revision 必须取真实操作与材料。旧 Markdown 只有经显式 review import 才进入 managed 循环；历史不明的尝试或重构次数不能当作零。

1. 锚定对象与目标包

1. 读取适用的仓库规则。给了开发计划时，读计划的前端与交互、真实环境与 UI 验证、里程碑验收，再沿「需求来源」读 PRD 中的界面需求与 UAT。同时读项目 DESIGN.md 或主题规范，以及计划或 PRD 链接的设计稿。只给 URL 或路由加目标图时，按单次验收处理。
2. 按 报告合同 的命名规则确定前缀和轮次。人工循环取已有最大轮次；managed 循环读索引，未结束轮次续接原 round/revision，不自行加一。已有本循环的报告时，本轮为复审；每个单元的「上一轮」是最近一次覆盖它且有评审结论的轮次；覆盖了却没有任何评审结论（如全部缺证封存）的轮次不算。
3. 按 目标包与采集 定位或建立目标包，并计算目标指纹。指纹与上一轮 capture.md 记录的不同，说明期望或目标图变了，本轮就是重建基线：历史最佳分、停滞判定和重构记录都从本轮重新开始。只改「采集」节不影响指纹。
4. 目标包建立后，本技能不改写其中的期望，只能修改「采集」节并记入变更记录。目标图与规范互相矛盾时，列为待裁定事项；某单元既没有目标图也没有规范时，该单元需补证。其他单元照常评审。

2. 采集本轮截图

1. 按目标包启动或连接被测环境，记录被测版本（HEAD、未提交改动指纹或构建号）和访问地址，并确认运行的是当前代码而不是旧构建。为评审临时启动的服务放在后台运行，记下停止方式，结束前停掉。只用测试账号和种子数据，不对真实业务数据写入或做破坏性操作。
2. 每轮采集目标包的全部格子（单元 × 状态 × 视口 × 主题），这样才能发现回归。用户限定范围时只采该范围，其余标「本轮未复核」。每轮在相同条件下重拍，不挑好看的角度或数据。
3. 每张截图都必须本轮在真实产品上实拍，要求见 目标包与采集 的「真实性」。设计稿、旧截图、为评审写的模拟页面等不合要求的图，一律当作没采到。
4. 交互单元按步骤实际操作，每步动作之后拍关键帧，包括键盘走查时的焦点帧。操作记录只写实际执行的动作和截图里看到的结果，不写「应该会」「预期会」之类的推断。采集期间顺带保存控制台日志和失败请求，留到评审之后再分析。
5. 状态到达不了时，先找项目已有的造数、mock 或路由拦截手段。仍采集不到的格子写明原因，不用相近状态冒充。
6. 按报告合同保存被测版本、目标指纹、采集条件、每张图对应的格子和出处，以及没采到的格子。人工循环写 capture.md；managed 循环用 review capture add 登记并回读生成的清单，补采追加 attempt，不覆盖原图或旧记录。

3. 独立评审

按 独立评审 派发和复核：

• 每轮派一个全新上下文的 subagent 当评审，只读，不再派生。评审只拿到三样东西：目标包；本轮截图、capture.md 与交互记录；每个单元上一轮的截图和 judge.md（只含评审自己给的分和差距）。
• 不给评审的东西：代码、diff、提交说明、修复记录、修复者自述、完整报告、机器检查结果和门槛分。并要求评审只打开所列材料，免得被「已经修了」带偏，也免得朝门槛凑分。
• managed 循环用 review judge-pack 的白名单材料派发；不沿材料内链接打开被排除的文件。packet 的 hash 绑定本批材料，确认评审沿用同一批材料；白名单是信息边界，不冒充宿主的文件权限沙箱。
• 格子多时按单元分组并行派发。新差距先用临时编号，由主 agent 合并后统一编号。评审报告看不出的格子，主 agent 补采后再派一位全新评审重评涉及的单元，取较低分。
• 派不出 subagent，或评审打不开图片时：
  • 当前对话没参与这个界面的实现或修复：主 agent 可以自己评审。评审前只读目标包、本轮和上一轮的截图、capture.md 和 judge.md；先评审并保存 judge.md，再做第 4 节的事；报告注明「单上下文评审」。
  • 当前对话参与过：不在本对话打分，给出在新对话运行本技能的命令。
• 主 agent 不改分、不删差距、不改门槛项，也不因争议换评审重评。认为评审看错时，只在该差距下附核对说明，交给修复方核实，下一轮由评审复核。
• 本轮将判通过、但最低单元分严格低于「门槛 + 0.5」时，用同一批材料再派一位全新评审确认；恰好等于时不强制。每个单元选总分较低的那位评审的一整组四维分与理由，差距取全部评审的并集；不逐维拼成一个不存在的评分。

4. 裁定与落盘

1. 保存各位评审原文及本轮合并的 judge.md；managed 循环还须用 review judge add 登记原文与忠实的结构化结果并回读。此后再做以下几件事：
   • 做机器检查，全部在运行中的页面上执行：分析采集时保存的日志，在页面里实测溢出，注入可访问性扫描，用真实按键做键盘走查。从代码或样式表推断出的问题不算检查结果，只能提示去哪里补拍或实测；
   • 读上轮完整报告和各轮修复记录。修复记录在计划记录目录里含「UI 验收修复」节的那份；没有计划时，是 <前缀>.ui-review.applied.md；
   • 确定门槛：用户本次指定的优先，其次沿用上轮报告记录的，都没有则默认 8/10。
2. 按报告合同完成裁定：
   • 由主 agent 重新检查上轮的机器检查差距和主 agent 核实的差距；
   • 计算本轮分数、门槛项、待裁定事项和停滞状态；
   • 得出验收判定。
3. 人工循环按报告合同写报告；managed 循环用 review finalize 以当前 revision 提交裁定，不手写生成区。返回 confirmation_required 时本轮仍是草稿，先完成确认评审再裁定；操作退出 0 本身不表示验收通过。写完回读状态、报告和链接，核对判定、分数与编号映射。写入失败时如实说明未落盘，并在聊天中交付已核实的内容。

5. 验收判定与下一步

最终回复先给一行验收判定（定义见报告合同），再给分数轨迹、最低分单元及主要差距、最新截图位置，最后给可直接复制的下一步命令。命令按当前客户端的技能调用写法（如 Codex $apply-ui-review、Claude Code /apply-ui-review），路径填实际文件。

首轮刚建立目标包时，列出期望的来源和假设，请用户确认；用户修改期望后，下一轮按重建基线评审。

验收判定	下一步
需要修改	apply-ui-review <本报告路径>，修复后再用本技能复审。带「停滞预警」时，说明是全局重构，还是重构哪个单元。带「待裁定」时，同时列出这些事项请用户决定；修复方先处理其余差距
通过验收 / 用户豁免通过	给出最新截图，问用户是否继续打磨：要打磨就 apply-ui-review <本报告路径> 处理剩余差距，再复审。不打磨时，如果本轮循环的 UI 修复改了代码（登记为「UI修复」的提交或未提交改动），先 review-code <计划路径> 复审这些改动；之后计划来自 PRD 的可选 review-prd-dev-gaps <计划路径>
需用户裁定	列出停滞或待裁定的事项、已经试过的做法，以及目标与当前截图的对照，请用户从下面三个选项中选择
需补证	列出缺少的环境、账号、数据、工具或目标，以及获取方式；补齐后再 review-ui <计划路径或原范围>。已评单元的差距可以先 apply-ui-review <本报告路径>

需用户裁定时的三个选项：

1. 接受整体现状，记为豁免通过；
2. 接受某处偏差或修改期望，由用户确认后改目标包，下一轮重建基线；
3. 提供素材或方向，然后执行 apply-ui-review <本报告路径>。

• 用户明确表示接受当前的整体界面时，按报告合同追加豁免记录并回读。豁免不能写成已解决。
• 只给建议命令，不自行启动修复、代码复审或差异核查。

调用示例：

使用 $review-ui goal/LOGIN.md
使用 $review-ui goal/LOGIN.md，设计稿在 design/login/，门槛 8.5 分。
使用 $review-ui 验收 http://localhost:5173/orders，目标图 docs/design/orders.png。
使用 $review-ui goal/LOGIN.md，只复查 U2。

项目状态回写

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

每轮实际评审都登记独立的评审 ID，写明被测版本、目标指纹、范围、判定、分数和报告路径；复审关联前轮。协议的 review_type 没有 UI 类型时，登记为 other，并在摘要注明「UI 验收评审」。通过验收不能登记为已合并、已发布或产品终验通过。