@xgent-ai/skills 0.5.0 → 0.7.0

package/skills/review-prd-dev-gaps/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: review-prd-dev-gaps
-description: 接受 PRD 与已完成的开发计划，追读里程碑完成记录并核对实际实现，将差异分为明确遗漏、合理变更和需用户 Triage 的实现差异；通过交互式问答确定处置，有 follow-up 时调用 dev-plan 创建 gaps plan。用于开发完成后的需求覆盖核查，不用于评审 PRD 质量、计划设计或单次代码 diff。
+argument-hint: "<已完成开发计划...> [PRD] [上轮报告] [复审/完整核查] [G-ID/范围] [仅报告] [报告路径]"
+description: 用于开发完成后的 PRD 覆盖核查；不用于 PRD 质量、计划设计或单次 diff 评审。对照已完成计划、记录和实现，区分遗漏与变更，交互裁定差异，必要时生成 gaps plan。
 ---
 
 # review-prd-dev-gaps · PRD 与开发交付差异核查
 
 目标：回答 **PRD 要求的能力实际上交付了什么，哪些漏做了，哪些调整有充分依据，哪些差异需要用户拍板，以及还要补什么。** 以 PRD 建立完整覆盖账本，以计划、完成记录和实际行为交叉核实，不把「计划已完成」等同于「PRD 已实现」。
 
-默认交付完整差异报告；存在应跟进事项时，再实际调用 `dev-plan` 产出独立 gaps plan。`references/` 相对本文件解析，回复语言跟随用户。
+默认交付完整差异报告；存在尚未被已有计划承接的已确定跟进事项时，再实际调用 `dev-plan` 产出独立 gaps plan。复审先核对已有计划，用户限定仅报告时不生成计划。`references/` 相对本文件解析，回复语言跟随用户。
 
 ## 边界
 
-- 输入为 PRD、已完成开发计划及其引用的完成记录；代码仓、测试、运行证据和历史决策用于核实。目标无法唯一确定时询问文档/仓库位置，先做不依赖该信息的调查，不擅自选择相邻文档。
-- 默认只写差异报告和新 gaps plan。原 PRD、原计划、完成记录和代码保持只读；文档同步也列为 follow-up，不自动修改历史完成事实。不自动实施、创建 issue、发布或发送评论。
+- 输入为 PRD、已完成开发计划及其引用的完成记录；代码仓、测试、运行证据和历史决策用于核实。只给计划时，从计划顶部「需求来源」定位 PRD 与期次（`P1` 即第 1 期），核查范围为 PRD 分期中落在该期的需求与验收，跨期需求只核对本期部分并保留终验期去向；用户另给范围时从其要求。计划没有需求来源且未给 PRD 时询问。目标无法唯一确定时询问文档/仓库位置，先做不依赖该信息的调查，不擅自选择相邻文档。
+- 默认写差异报告、新 gaps plan 及已启用台账的事实索引（见文末）。原 PRD、原计划、完成记录和代码保持只读；文档同步也列为 follow-up，不自动修改历史完成事实。不自动实施、创建 issue、发布或发送评论。
 - 只核对 PRD 及已确认变更承诺的范围，不新增产品机会，不设问题数量或 top-N 截断。明确不在本期的需求保留追踪去向，不当成本期遗漏；未获确认的删减/延期不能算范围外。
 - 参考 `gen-specs-as-issues` 的文档对照实际行为、用户旅程和依赖分析思路，不继承其问题配额、评分公式或 issue 创建流程；运行时不依赖该参考技能。
 
@@ -24,6 +25,19 @@ description: 接受 PRD 与已完成的开发计划，追读里程碑完成记
 4. 核对完成声明与记录：里程碑退出条件、跳过/失败测试、局部验收与阶段终验是否一致。原计划实际未完成时说明输入前提不成立，继续核对可确认部分，不能把未完成项包装成「完成后新发现」的遗漏。
 5. 读取 [references/report-contract.md](references/report-contract.md)，确定报告路径，建立 `PRD → 计划/里程碑 → 完成记录 → 实际行为/验证` 的追踪账本。**从 PRD 向下追踪**，防止只审计划已有条目而漏掉从未进入计划的需求。
 
+## 修复效果复审
+
+用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+
+- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
+- 读取上轮 G-ID、D-ID、原计划及已有关联 gaps plan 和完成记录；沿用仍有效的用户决定。只给 gaps plan 时，沿其需求来源找到原计划与上轮差异报告，一并核对。逐项核对需求是否补齐及直接受影响的用户路径，不因计划自报完成关闭缺口。复审模式的覆盖账本标明本次范围，其余保留“本轮未复核”，不能冒称全 PRD 已覆盖。
+- 先查已有 gaps plan 是否承接剩余事项；已承接则链接原任务及真实进度，不重复创建计划。只有尚未承接且范围已确定的新增 follow-up 才进入第 5 节；“仅报告/只复核”只交付报告与后续建议，不调用 dev-plan 创建或修订计划。
+- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+
+```text
+$review-prd-dev-gaps docs/PRD-login.md goal/LOGIN.md goal/LOGIN-gaps.md，对照 goal/LOGIN.prd-dev-gaps.md 复审修复效果，逐项记录结果。
+```
+
 ## 2. 核实功能实现情况
 
 - 每个在范围内的需求/验收条件都要有覆盖行。一个需求部分满足时拆出未满足条件，不用已实现的主路径掩盖权限、异常、状态反馈或边界行为的缺口。跨里程碑能力检查最终用户旅程，不能只拼接各局部的完成声明。
@@ -71,9 +85,9 @@ description: 接受 PRD 与已完成的开发计划，追读里程碑完成记
 形成一份有来源的 follow-up 清单：未被明确豁免/延期的 A；C 决策要求的补齐或替代实现；B 或接受现状后必要的文档同步、验证补齐。证据缺口只有形成具体、已确定范围的调查/验证任务才纳入，不能包装成未经证实的修复需求。合并同根因任务，保留所有 G-ID/需求关联。
 
 - 已满足、无后续动作的 B、明确豁免或已延期到别期的事项不进入本次实施范围；报告保留理由、去向和重新评估条件。全部无 follow-up 时明确写「无需 gaps plan」，不创建空计划。
-- 清单非空时，**实际定位并读取可用的 `dev-plan/SKILL.md`，按其写计划流程、骨架和校验生成独立 gaps plan**；不止建议用户以后调用，也不在本技能复制一套开发计划模板。缺少该技能时查找可用安装位置；仍找不到则保留报告和交接清单，说明计划生成受阻，不能声称已创建。
+- 先按 G-ID、需求及实际范围核对已有 gaps plan；已承接事项链接原任务，不重复建计划。仍有未承接的已确定增量且用户未限定仅报告时，**实际定位并读取可用的 `dev-plan/SKILL.md`，按其写计划流程、骨架和校验生成独立 gaps plan**；不止建议用户以后调用，也不在本技能复制一套开发计划模板。缺少该技能时查找可用安装位置；仍找不到则保留报告和交接清单，说明计划生成受阻，不能声称已创建。
 - 交给 `dev-plan` 的输入：PRD、原计划及相关记录路径，差异报告、代码基线，选定 G-ID 和 D-ID，已确定目标与验收、排除/延期项、相关代码证据和依赖。原 PRD 提供来源，用户确认的变更提供新目标，当前代码提供起点；不能让下游再次按旧 PRD 推翻已确认决定。
-- 使用 `<原计划名>-gaps` 作为默认代号，输出目录、重名处理和最终状态遵守 `dev-plan`。保留 PRD 需求 ID，并追踪 `需求 → G-ID/D-ID → gaps 任务/里程碑 → 验收`；只规划增量，不重做已完成里程碑，不复制旧计划的完成记录，初始化新计划未开始的进度。
+- 使用 `<原计划名>-gaps` 作为默认代号，输出目录、重名处理和最终状态遵守 `dev-plan`。gaps plan 的需求来源写同一 PRD 与期次，并注明补齐的原计划，使其代码验收通过后可再次核查。保留 PRD 需求 ID，并追踪 `需求 → G-ID/D-ID → gaps 任务/里程碑 → 验收`；只规划增量，不重做已完成里程碑，不复制旧计划的完成记录，初始化新计划未开始的进度。
 - 未决 C 不得作为已选方案进入计划。若仍在等回答，先保存报告；独立且已确定的 follow-up 可先成独立范围的计划，显式排除待决项。未决项影响该计划范围或关键依赖时按 `dev-plan` 标 `Blocked`，不能用假设绕过；不得把部分计划说成全部差异已处理。
 - 计划生成后回读，检查范围、决策、验收与报告一致，并在报告中回填实际路径、状态和 G-ID 去向。默认到计划交付为止，不开始执行 gaps plan。
 
@@ -82,3 +96,17 @@ description: 接受 PRD 与已完成的开发计划，追读里程碑完成记
 按报告合同保存并回读完整报告，检查：PRD 覆盖无静默漏行，A/B/C 有证据，待核实与待决未伪装成已解决，用户决定已落实到 follow-up，计划只含确认范围且链接真实。结束前核对输入/代码基线是否变化，只复核受影响结论。
 
 最终回复给报告链接、三类差异数量、待核实/待决数量，以及 gaps plan 的实际链接与状态（或无需生成/受阻原因）。报告落盘、用户决策、计划生成分别说明完成情况；有未决/缺证时不宣称整份 PRD 已完整交付。
+
+结尾给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex `$review-dev-plan`、Claude Code `/review-dev-plan`），路径填实际文件。
+
+- 生成了 gaps plan：`review-dev-plan <gaps 计划路径>`，之后与普通计划同一回路：评审处置、解除阻塞、`/goal` 开发、代码评审验收，通过后可再次核查本期覆盖。
+- 无需 gaps plan 且没有待决或缺证：说明本期 PRD 覆盖核查完成，跨期需求的终验期仍以 PRD 为准。
+- 尚有待决或缺证：列出待用户决定的问题或补证方式，处理后再次 `review-prd-dev-gaps <计划路径>`。
+
+只给出建议命令，不自行开始执行 gaps plan。
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+登记独立差异核查对象及 PRD/计划关联、版本、待决与 follow-up 去向；复审关联前轮，保留未覆盖 G-ID 及历史结论。新 gaps plan 保持独立对象，关联原计划和差异 ID，不改变原计划的历史完成记录。

package/skills/review-prd-dev-gaps/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "PRD 开发差异核查"
   short_description: "核对 PRD、完成计划与实际交付，分流遗漏、合理变更和用户决策，按需生成 gaps plan"
-  default_prompt: "使用 $review-prd-dev-gaps 核对指定 PRD 与已完成开发计划，追读里程碑记录并核实实际实现，保存三类差异报告；交互确认需 Triage 的差异，有 follow-up 时调用 dev-plan 创建 gaps plan。"
+  default_prompt: "使用 $review-prd-dev-gaps 核对指定已完成开发计划（从其需求来源定位 PRD 与期次），追读里程碑记录并核实实际实现，保存三类差异报告；交互确认需 Triage 的差异，有 follow-up 时调用 dev-plan 创建 gaps plan，并提示用 review-dev-plan 评审。"

package/skills/review-prd-dev-gaps/references/report-contract.md

@@ -7,6 +7,20 @@
 - Triage 前先保存已有核查结果和待决问题；回答到达后在同一报告更新决策和去向，计划交付后补真实链接。恢复会话时先读报告、确认基线与已有决定，避免重复询问。
 - 用户明确仅聊天/不写文件时在聊天中交付完整内容，该限制同时传给 `dev-plan`。工具不能写入或写入失败时说明「未落盘」及原因，保留完整内容和未完成项，不链接不存在的文件。
 
+## 复审记录
+
+复审报告在标题及评审对象之后注明：上轮报告的相对链接与版本、所审对象的前后版本、本轮范围、已有处置记录链接，以及“修复效果复审”或“完整重审”。历史报告与原结论保持不变；默认按本合同另存新报告。
+
+在原报告结构中增加“上轮问题复审”表，与本轮新增问题分开：
+
+| 来源报告 / G-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
+- 来源身份使用“报告路径/原始版本 + G-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
+- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
+- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+
 ## 报告结构
 
 ### 1. 结论与范围

package/skills/review-ui/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: review-ui
+argument-hint: "[开发计划] [页面URL/路由] [设计稿/目标图] [上轮报告] [复审/重建基线] [单元/范围] [门槛分] [报告路径]"
+description: 用于界面实现后的 UI/UX 验收或修复复审；不用于代码 diff 评审、直接修复或从零设计。只认运行中界面的实拍截图与实测，不凭代码推断效果；由独立评审打分列差距，判定是否通过。
+---
+
+# 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 评审协议](references/phoenix-review.md) 核对固定版本 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. 按 [报告合同](references/report-contract.md) 的命名规则确定前缀和轮次。人工循环取已有最大轮次；managed 循环读索引，未结束轮次续接原 round/revision，不自行加一。已有本循环的报告时，本轮为复审；每个单元的「上一轮」是最近一次覆盖它且有评审结论的轮次；覆盖了却没有任何评审结论（如全部缺证封存）的轮次不算。
+3. 按 [目标包与采集](references/target-and-capture.md) 定位或建立目标包，并计算目标指纹。指纹与上一轮 `capture.md` 记录的不同，说明期望或目标图变了，本轮就是**重建基线**：历史最佳分、停滞判定和重构记录都从本轮重新开始。只改「采集」节不影响指纹。
+4. 目标包建立后，本技能不改写其中的期望，只能修改「采集」节并记入变更记录。目标图与规范互相矛盾时，列为待裁定事项；某单元既没有目标图也没有规范时，该单元需补证。其他单元照常评审。
+
+## 2. 采集本轮截图
+
+1. 按目标包启动或连接被测环境，记录被测版本（HEAD、未提交改动指纹或构建号）和访问地址，并确认运行的是当前代码而不是旧构建。为评审临时启动的服务放在后台运行，记下停止方式，结束前停掉。只用测试账号和种子数据，不对真实业务数据写入或做破坏性操作。
+2. 每轮采集目标包的**全部**格子（单元 × 状态 × 视口 × 主题），这样才能发现回归。用户限定范围时只采该范围，其余标「本轮未复核」。每轮在相同条件下重拍，不挑好看的角度或数据。
+3. 每张截图都必须本轮在真实产品上实拍，要求见 [目标包与采集](references/target-and-capture.md) 的「真实性」。设计稿、旧截图、为评审写的模拟页面等不合要求的图，一律当作没采到。
+4. 交互单元按步骤实际操作，每步动作之后拍关键帧，包括键盘走查时的焦点帧。操作记录只写实际执行的动作和截图里看到的结果，不写「应该会」「预期会」之类的推断。采集期间顺带保存控制台日志和失败请求，留到评审之后再分析。
+5. 状态到达不了时，先找项目已有的造数、mock 或路由拦截手段。仍采集不到的格子写明原因，不用相近状态冒充。
+6. 按报告合同保存被测版本、目标指纹、采集条件、每张图对应的格子和出处，以及没采到的格子。人工循环写 `capture.md`；managed 循环用 `review capture add` 登记并回读生成的清单，补采追加 attempt，不覆盖原图或旧记录。
+
+## 3. 独立评审
+
+按 [独立评审](references/judge.md) 派发和复核：
+
+- **每轮派一个全新上下文的 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 <本报告路径>`。
+
+- 用户明确表示接受当前的整体界面时，按报告合同追加豁免记录并回读。豁免不能写成已解决。
+- 只给建议命令，不自行启动修复、代码复审或差异核查。
+
+调用示例：
+
+```text
+使用 $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`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存及 managed 能力异常时的只读边界优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+每轮实际评审都登记独立的评审 ID，写明被测版本、目标指纹、范围、判定、分数和报告路径；复审关联前轮。协议的 `review_type` 没有 UI 类型时，登记为 `other`，并在摘要注明「UI 验收评审」。通过验收不能登记为已合并、已发布或产品终验通过。

package/skills/review-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "UI/UX 验收评审"
+  short_description: "只认运行中界面的实拍截图，由独立评审打分并列出可执行差距，判定 UI 验收是否通过"
+  default_prompt: "使用 $review-ui 对指定界面做 UI/UX 验收。先识别循环：新无历史且真实能力匹配时可 begin managed；已有人工历史须显式 import。已有 managed 索引时核对固定 engine 与实际协议，不匹配就只读并说明恢复方法，不猜 JSON 字段。按目标矩阵实拍真实界面，派全新上下文独立评审，保留原文并按合同确认、合并和裁定；managed 操作由 engine 登记与投影，人工流程照常落盘。回读后汇报实际判定、分数、差距和下一步命令。"

package/skills/review-ui/evals/fresh-context.md

@@ -0,0 +1,52 @@
+# 全新上下文验证
+
+此文件用于维护两项 UI skill，普通任务不加载。下列是自然请求和评测侧判据，尚未执行；不能作为 installed-provider、真实 native CLI 或具体产品 UI 的通过记录。
+
+## 源码 description 路由
+
+给候选会话两份当前源码 description 与原请求，请它只返回 `review-ui`、`apply-ui-review` 或 `none`。不加载正文，不给期望答案或失败信号；这只验证这两个候选间的选择，`none` 不证明其他 skill 被正确执行。全文与前 100 字符分别检查，若内容相同则记录这个事实。
+
+| ID | 原请求 | 评测侧期望 |
+| --- | --- | --- |
+| T1 | 订单页已经实现了，我想按目标图验收并列出下一轮能修的差距。 | review-ui |
+| T2 | 刚按上一轮意见修完登录页，请对当前页面和目标图做一次复审。 | review-ui |
+| T3 | 按这份 UI 验收报告处理 UI-04 和 UI-07，修完留证据交回复审。 | apply-ui-review |
+| T4 | 这份 UI 报告要求重构 U3，请核实后修这一单元，其他部分保持范围。 | apply-ui-review |
+| T5 | 帮我评审这次代码 diff 的并发和错误处理问题。 | none |
+| T6 | 我想给新产品找几种视觉方向和参考，现在还没有界面实现。 | none |
+| T7 | 从现有页面提炼颜色和字体规范，更新 DESIGN.md。 | none |
+| T8 | 没有 UI 评审报告，直接帮我实现一个新的订单列表页。 | none |
+
+## 正文执行
+
+每题显式要求读取待测源码 `SKILL.md` 及适用引用；只提供原请求与隔离项目材料。材料可包含真实产品/文档，或明确标记的协议合同 fixture；后者只能验证指令边界，不能冒充真实 CLI 返回或 native acceptance。不要向候选提供本表判据。
+
+| ID | 原请求与材料 | 评测侧观察 |
+| --- | --- | --- |
+| E1 | 使用 review-ui 核查订单页是否具备验收材料；目前应用无法启动，没有 Phoenix CLI，先读计划、partial DESIGN.md 与 PRD，暂不保存。无 managed 索引。 | 读取原文，区分已知与 partial；不凭代码/建议计分，列真实采集缺口 |
+| E2 | 使用 apply-ui-review，先核实这份人工 UI 报告，不改文件、不提交。报告、目标、接口和 CSS 可读，页面无法运行。 | 直接读原文；CSS 不能证明不采纳或已解决；AND 接口不被发明成 OR |
+| E3 | 使用 review-ui 续接这个循环，先补上 r3 未采到的格子。材料载明 managed 索引已存在，固定 engine 不可用。 | 停在只读与未登记素材；不重新 begin、人工写分或猜版本 |
+| E4 | 使用 apply-ui-review 按本轮报告修 UI-04。材料载明 managed 索引存在，固定 engine 不可用。 | 先读状态/恢复依赖，不改产品、目标或处置 |
+| E5 | 请按 review-ui 合同核查这次评审材料与下一步；两位评审对同一单元给出交叉维度分，旧轮未覆盖该单元，材料有完整报告链接。只读。 | 保留整组低分与全部差距；最近覆盖轮而非最新轮；不把完整报告/修复信息传给评审；不把 fixture 分数宣称为产品验收 |
+| E6 | 使用 apply-ui-review 接续旧循环。旧报告发过重构预警，一份修复记录缺失；这次先核实范围，暂不实现。 | 历史不明不当零；不领取新重构次数，不改目标或旧评审 |
+
+## 可复现执行与留证
+
+先保存实际 `codex exec --help` 和 `codex --version`，确认当前 runner 支持以下形状；参数变化时按实际帮助调整。每题新启动，不使用 resume/fork，不设置 model、effort、provider、HOME、CODEX_HOME 或个人配置覆盖。
+
+```sh
+codex exec --ephemeral --sandbox read-only --skip-git-repo-check \
+  --cd /绝对路径/隔离题目 --json --color never \
+  --output-last-message /绝对路径/证据/final.txt - \
+  < /绝对路径/证据/input.txt \
+  > /绝对路径/证据/trace.jsonl \
+  2> /绝对路径/证据/stderr.log
+```
+
+只读题用 `read-only`。确需实现/保存的题改用 `workspace-write`，只让新建 case fixture 可写；保存前后路径、hash 与 diff，检查未写共享源码或其他题。设置评测侧合理超时并保存首次退出码；超时、认证或 runner 故障保留完整首跑，不重试刷分，确认子进程退出与文件静止后才结束该题。
+
+每题保存源码路径/hash、原输入、runner/provider 版本、实际模型与 effort、完整 JSONL 工具轨迹、原始输出、退出码及耗时。预期答案在评测侧逐题核对，分别记 pass、fail、unrun、incomplete 或 open-materials；明确执行了原文阅读、真实开图、子评审、CLI、写入中的哪些。没有最终回复或未读到所需材料不能算通过。
+
+源码与引用的哈希在整轮前后核对不变。受维护者已读判据影响的开放材料结果单独标注；协议 fixture、description 路由、正文解释、真实 CLI 与安装后 provider 会话分别记录，不互相替代。
+
+源码修订后保存旧源快照与所有首跑，再为受影响场景建立带新版本/hash 的独立变体；不覆盖原题、首跑或结果。全新无旧历史且匹配 engine 的实际 begin，以及真实 capture/packet/judge/finalize/apply/import 恢复，须等可用的真实 CLI 后另验，不能用合同 fixture 或 stub 代替。

package/skills/review-ui/evals/scenarios.md

@@ -0,0 +1,41 @@
+# review-ui 行为验收
+
+以下是待执行的场景，不是通过记录。请在隔离副本中运行，保留目标包、截图、`judge.md`、报告和派发记录。执行者只拿到自然请求、项目材料和待测技能，不拿本表判据。维护本技能时使用；普通评审任务不必加载。
+
+| 场景与请求 | 应观察的行为 | 失败信号 |
+| --- | --- | --- |
+| 代码评审已通过，计划有前端改动并链接设计稿导出图：「review-ui goal/X.md」 | 建立目标包，摘录规范原文并计算指纹；在真实渲染中全量截图；派全新 subagent 评审；保存 `judge.md`；报告含单元分、差距清单、轨迹和判定 | 读代码给分；只截首页一张；主 agent 自己打分；目标包写了门槛分或只写需求编号 |
+| 没有设计稿，只有 DESIGN.md 和 PRD 的 UAT | 用规范模式，期望都引用规范要点；找不到依据的列为建议，不扣分 | 按个人口味扣分；编造目标图细节 |
+| 复审时，上一轮差距清单里有机器检查条目，报告写着门槛 | 评审只拿目标包、截图和上一轮 `judge.md`；机器检查差距由主 agent 重新检查 | 把完整报告或机器检查结果交给评审；提示里提到门槛 |
+| 评审给了 8.3，但机器检查发现主路径用键盘提交不了 | 列为 P1 门槛项，判需要修改 | 分数过线就判通过 |
+| 本轮将判通过，最低单元 8.1 | 派确认评审，每个单元取较低分；仍达标才判通过 | 只凭一位评审就通过 |
+| 评审对某条 P1 的状态看不出 | 补采这些格子，再就它们派一位全新评审；仍看不出则判需补证，并照常列出已评单元的差距 | 把看不出的 P1 从清单里删掉后判通过 |
+| 评审说按钮是蓝色，截图里看着是绿色 | 只在该差距下附核对说明；分数、差距和门槛项都不变，交修复方核实，下一轮由评审复核 | 主 agent 改分、删差距，或换一位评审重评后采用更高的分 |
+| 最后一轮各单元 8.7 以上，但还有一条 P1，主 agent 认为评审看错 | 仍判需要修改；修复方核实后可以不采纳，下一轮由全新评审复核 | 以主 agent 的核对为由去掉门槛项后判通过 |
+| 本轮分数 8.6；唯一的 P1 已是待裁定事项（修复方上一轮不采纳，评审仍判存在），另有几条新 P3 | 判需用户裁定，因为继续修 P3 也无法通过 | 判需要修改，让循环继续修 P3；修复方跳过该 P1 后记「未处理」，导致它下一轮又变回可修复 |
+| R2–R4 的分数分别为 6.8、7.0、7.3，门槛 8 | 判需要修改 · 停滞预警（全局），要求下一轮修复做重构轮 | 继续给微调建议，不提示停滞 |
+| R3 为 8.2 但有一条 P1；R4 为 8.3，修复记录标已修改的该 P1 连续第二轮部分解决 | 不判全局平台期（分数已过门槛）；对该差距所在单元发停滞预警 | 因 2 轮内涨不满 1 分就要求全局重构 |
+| R4 发了全局预警，修复记录显示做了全局重构，R5 从 7.3 涨到 7.4 | 平台期仍成立，判全局停滞，转为需用户裁定 | 因为分数涨了一点就再发一次预警，循环下去 |
+| 修复方上一轮对一条 P1 标不采纳并给出 token 依据，本轮评审仍判存在，另有 5 条可修复差距 | 判「需要修改 · 待裁定（该差距）」，请用户决定该项，其余照常修复 | 整个循环停下；或者每轮反复判需要修改，永不收尾 |
+| 只复查 U3：U3 的差距做过重构轮，本轮仍存在 | 该差距判停滞，成为待裁定事项；不判通过 | 限定范围就不判停滞；或宣称整体通过 |
+| 当前对话刚完成该界面的修复，又派不出 subagent | 不在本对话打分，给出在新对话运行的命令 | 自己评自己的修复 |
+| 设计师原地覆盖了 `design/orders.png`，目标包文字没动 | 目标指纹变化，本轮为重建基线，历史最佳和停滞判定重新开始 | 只比目标包文字，沿用旧基线判停滞 |
+| 只在「采集」节补了等待条件 | 指纹不变，不重建基线 | 因目标包文件变了就重置停滞判定 |
+| 应用起不来或没有截图工具；agent 读了组件代码，觉得布局与设计稿一致 | 判需补证，不打分、不出差距，说明缺什么、怎么补 | 根据代码给分、开差距或判通过 |
+| 截图目录里混入了设计稿导出图、上一轮截图，或为评审临时写的 demo 页面截图 | 抽查发现后当作没采到并重拍；重拍不了判需补证 | 拿这些图交给评审打分 |
+| 操作记录写着「点击提交后应显示成功提示」，但没有对应的关键帧 | 视为该状态没采到，实际操作后补拍 | 把推断当观察交给评审 |
+| 机器检查时读 CSS，发现容器写死了宽度，推断窄屏会溢出 | 不算检查结果；在 390 宽的页面上实测，测不了就写未检查 | 把推断写成机器检查差距 |
+| 多轮后通过，UI 修复登记了「UI修复」提交 | 给出最新截图，问用户是否继续打磨；下一步 `review-code <计划>` 复审这些提交，再按来源提示差异核查 | 自动启动代码复审；漏掉 UI 修复带来的代码改动 |
+| 用户要的是代码 diff 评审，或想找新的视觉方向 | 转到 `review-code` 或 `design-reference` | 触发本技能，截图打分 |
+| 「没有 Phoenix CLI；这里有部分 DESIGN.md、PRD 和目标图，先核查这页能否验收」；没有 managed 索引 | 直接读实际原文，注明 partial；人工流程继续，缺真实采集时需补证 | 把缺 CLI 当作不能读规范；凭建议或代码给分 |
+| 「首次验收这个页面」；无索引、无旧历史，匹配 engine 与 review verbs 可用 | 真实能力探测后 begin managed；没有能力时人工流程 | 无索引就永远人工；旧 Markdown 历史被自动 begin 清零 |
+| 「续接订单页验收，先补上 r3 未采到的格子」；已有 managed 索引，匹配 engine 不可用 | 只读历史、收集未登记素材，说明固定版本恢复方法；不计分、不写生成区、不 begin 新轮 | 静默人工降级；删索引、新前缀或重置轮次 |
+| 「继续上次中断的订单验收」；同前缀有未结束 round | 读取原 round/revision 续接；capture 追加 attempt | 再分配一轮；覆盖首采或旧评审原文 |
+| 「这次只评 U2」；U2 当前完整，上一轮覆盖 U2 的轮次早于最新报告 | packet 只含 U2 白名单和最近覆盖 U2 的截图、评审自述 | 把最新完整报告、修复说明或机器检查交给评审；按最新文件代替每单元上一轮 |
+| 「修好了，再验一次」；最新一轮因沙箱起不了服务全部缺证封存、没有评审结论 | packet 的上一轮取更早有评审结论的覆盖轮的截图与评审自述，待复核旧差距取最新一轮仍未关闭的清单 | 只给旧差距编号让评审凭空复核；把缺证轮当作上一轮结论 |
+| 最低分恰好 8.5，门槛 8；另有确认评审 A/B 的维度交叉高低 | 严格边界不强制确认；需合并时选总分低者整组四维和理由、差距并集 | epsilon 或取整改变边界；逐维取最小拼造评分；丢弃高分评审的差距 |
+| 「把旧 Markdown 循环接到 Phoenix」；一次摘要遗漏重构记录 | 逐份核对再显式 import；历史未知不填零，旧文件/hash 保留 | 自动猜全部轮次、关闭旧差距或新领重构机会 |
+| 「报告里我补了几句话，继续这轮」；补充落在 managed 生成区 | 保留原文/source hash，核对允许导入范围与 revision | 覆盖用户文字；封存历史或原始评审被回写 |
+| 「context 里有 profile 建议，也发现了两份旧 brief，按这些把本轮目标更新一下」 | 区分建议、已接受/可用和 stale/ambiguous；冻结目标不因 profile 更新自动变化 | default advice 替代项目规范；未确认 brief 成为像素目标 |
+
+路由与正文验证方法见 [全新上下文验证](fresh-context.md)。结构检查覆盖 frontmatter、description 全文及前 100 字符、相对链接。试跑另行记录输入、产物、实际执行范围和限制；场景通过不代表任何具体产品界面已验收。

package/skills/review-ui/references/judge.md

@@ -0,0 +1,102 @@
+# 独立评审
+
+## 派发
+
+- 每轮派**全新上下文**的 subagent，模型继承主 agent。评审只读，不改文件，不再派生其他 agent。
+- 只给以下材料：
+  - 目标包；
+  - 本轮各单元的截图，以及本轮的 `capture.md`（每张图对应的单元、状态、视口和主题）；
+  - 交互关键帧与操作记录；
+  - 差分图（可选）；
+  - 复审时，每个单元上一轮（最近一次覆盖它且有评审结论的轮次；覆盖了却没有任何评审结论的轮次不算）的同名截图，以及那一轮 `judge.md` 中该单元的部分。目标包自那一轮以来有变更时，附上目标包完整的「变更记录」节，作为目标事实；变更条目不标单元或轮次，不做筛选。
+- 不给以下材料：代码、diff、提交说明、修复记录、修复者自述、完整报告、机器检查结果、门槛分、主 agent 的看法。
+- 一位评审要能逐张细看图片（本轮、目标、上轮合计，经验上一组不超过约 30 张）。超出时按单元分组并行派发，每位拿同一份提示和各自单元的材料。并发受实际槽位限制，不够就分批，但不能漏单元。
+- 发送绝对路径。评审打不开图片时，按派发失败处理。
+- managed 循环由 `review judge-pack` 生成白名单材料并记录 packet hash；限定单元只纳入当前范围中材料完整的单元。上一轮材料必须按单元取最近一次有评审结论的覆盖轮，只提供该单元评审自述；待复核的旧差距取最新一轮仍未关闭的清单，不能链接完整报告代替。缺失旧差距材料先补证。
+- packet 只提供上述材料，评审不沿链接打开被排除的文件。记录实际模型、effort、开图与工具轨迹；packet 生成成功不证明宿主已隔离文件权限。
+
+## 评审提示
+
+主 agent 填好花括号里的内容后，原样发送：
+
+```text
+你是独立的 UI/UX 验收评审，只读，不修改文件，不派生其他 agent。请判断当前产品界面离目标还差多少，按标尺打分，并给出完整、可执行的差距清单。
+
+材料（只打开这里列出的文件和目录；目标包里指向其他文件的链接，除目标图外都不要打开）：
+- 目标包：{路径}（单元、目标图、规范要点、比较口径）
+- 本轮截图与交互记录：{目录}；每张图对应的单元、状态、视口和主题见 {capture.md 路径}
+- 上一轮截图与评审结论：{各单元的目录与 judge.md 路径}（首轮没有）
+- 差分图（可选）：{目录}
+
+逐个单元打分，可以给小数：
+- 布局（0–3）：区域结构，主要组件的位置、尺寸、对齐、间距和层级；每个视口下的排布、换行和滚动；有没有溢出、遮挡、截断。
+- 视觉（0–3）：配色与用色语义，字体（字族、字号、字重、行高），对比度，图标与图片，圆角、边框和阴影，主题；是否与规范 token 一致。
+- 交互与状态（0–3）：主路径能否走通；加载、空、错误、禁用、成功等状态及反馈；悬停、焦点、按下态；键盘操作与焦点可见；表单校验与提示；过渡是否帮助理解。
+- 细节（0–1）：逐处细抠文案、数字与日期格式、图标对齐、像素级间距、截断与省略、多语言。一个像素都不应不同。
+
+锚点：
+- 3 分：与目标一致，只剩应归入「细节」的微小差异。
+- 2 分：方向与结构正确，但有设计师或用户一眼就能看出的偏差。
+- 1 分：只有部分正确，有结构性偏差或多处缺失。
+- 0 分：缺失、根本不同或不可用。
+- 细节维度：1 分 = 逐处比对没发现差异；0.5 分 = 有若干小差异；0 分 = 差异很多。
+每个维度用一句话说明为什么不是更高一档。
+
+要求：
+1. 挑剔、精确、完整。差距很多就列一份很长的清单。目标是另一位 agent 照单修完回来后，分数明显提高。
+2. 每个单元的失分都要能由差距解释：该单元各条差距的「可挽回分」相加，约等于 10 减去单元分，误差不超过 0.5。
+3. 每条差距都要可执行，写清以下内容：
+   - 单元与截图中的位置（区域、元素或文字）；
+   - 「现状 → 期望」，期望引用目标图的位置或规范要点；
+   - 具体修法：改哪个组件、用什么布局方式、哪个 token 或属性、什么素材、什么结构；
+   - 严重度和可挽回分。
+   不要写「看起来廉价」「不够精致」这类话，要说出造成这种观感的具体原因和改法。
+4. 期望在目标图和规范要点里都找不到依据的，单独列为「建议」，不扣分。按目标包的比较口径，忽略示例数据之类的差异。
+5. 需要推倒重做布局、换组件或重做素材时，直说，不要粉饰。目标是做到与目标一致，不要放水。
+6. 只依据截图与记录下判断，不凭常识、经验或对常见实现的了解去推测界面效果。没拍到的状态既不算通过也不算失败；图缺失、模糊或看不出状态时，写明哪张图看不出什么。
+7. 有上一轮评审时，保持评判尺度一致，但不必维持或提高分数；变差了就给更低的分。逐条给上一轮差距标：已解决、部分解决、仍存在、回归、待核实（看不出）、不再适用。同一问题沿用原编号；新问题用临时编号「新-1」「新-2」……
+8. 未评单元不补零分或假结论；保留这次输出作为评审原文。managed 输入由你本人输出，或由主 agent 忠实转换并保留原文与转换依据，不能替你补分、改理由或删差距。
+
+严重度：
+- P0 阻断：主任务无法完成；内容或数据错误、不可见；必需视口的布局崩坏。
+- P1 严重：用户会明显困难或误解；主路径不满足 WCAG AA（对比度、键盘、焦点）；主要区域与目标明显不符。
+- P2 一般：能察觉的偏差，但不妨碍完成任务。
+- P3 打磨：几乎察觉不到的细微差异。
+
+输出：
+1. 评分表：每个单元的四个维度分和单元总分，每个维度附一句理由。
+2. 上一轮差距复核表（首轮省略）。
+3. 差距清单：所有仍未关闭的差距，包括沿用编号的旧差距和新差距。先按严重度、再按可挽回分排序。每条写编号、单元与截图、维度、严重度、现状 → 期望（依据）、修法、可挽回分。
+4. 建议（不扣分）。
+5. 看不出的格子：哪张图、看不出什么。
+6. 总评：最低分单元及主要原因；哪些地方需要结构性改变。
+```
+
+## 复核
+
+- **完整性**：每个单元都有分；每条差距都有截图位置和依据；可挽回分与失分大致相符；上一轮差距都有复核结果。有缺项时，工具支持续接就让同一位评审补齐；否则只就缺的单元另派一位全新评审。
+- **看不出的格子**：只有评审自己报告看不出时才处理。主 agent 先补采（调整目标包的「采集」节并记录），再派一位全新评审重评涉及的单元。每个单元取总分较低的那位评审的一整组四维分与理由，全部差距取并集，不逐维拼接。补采后仍看不出的，标待核实。
+- **事实抽查**：打开对应截图，核对评审描述的现象。认为评审看错时，只在报告该差距下附核对说明，写清截图里实际看到的事实。
+- **主 agent 不改分、不删差距、不改门槛项，也不因争议换评审重评**。有争议的差距交给修复方核实，下一轮由评审复核。自己发现的额外问题，必须附本轮实拍截图或页面实测结果，才能以「主 agent 核实」为来源列入清单；它们不改分数，是 P0/P1 时计入门槛项。
+- **确认评审**：本轮将判通过、但最低单元分严格低于「门槛 + 0.5」时，用同一批材料再派一位全新评审；恰好等于时不强制。每个单元保留总分较低那位的一整组评分与理由，差距取并集；同一条旧差距结论不同时，按 回归 > 仍存在 > 部分解决 > 待核实 > 已解决 > 不再适用 取最靠前的一项，任何一位给出未关闭或待核实的结论都优先于关闭结论。去重须有明确编号映射（managed 循环用 `review judge add --mappings` 登记 `{key, id, basis}`），不丢弃另一位发现的差距。managed 循环沿用本批 packet，`confirmation_required` 时还不能封存。
+- **合并与编号**：主 agent 合并各位评审的结论，把临时编号换成正式编号，按报告合同写入本轮的 `judge.md`。
+- **原文与登记**：每位评审原文分别保存，不由合并文件替代。managed 循环用 `review judge add` 绑定 packet、原文 hash 与当前 revision；结构化输入只作忠实转换。发现缺项只能补齐缺项，不能重写已给出的分数与理由或替未评单元造结果。
+
+## 来源与有意取舍
+
+本评审改编自 `local/workflow.md`（Dream Loop Pro，一个用于 3D 场景还原的循环）：实现 → 截图 → 全新上下文的评审 → 照单修复 → 再评。原流程按构图、光照、材质各 0–3、细节 0–1 打分，≥ 8 分收工；最佳分 2 轮内没涨满 1 分，或同一差距连续被点名，就从整体上重新思考做法；重构仍无效就交给人裁定。实践中 8 分以上基本达到预期。
+
+保留的部分：独立评审、四个维度的 10 分制、挑剔的口吻、完整可执行的清单、用上一轮结论校准尺度、8 分门槛、两段式停滞处理。
+
+为 UI/UX 验收做的调整：
+
+- **维度**：换成布局、视觉、交互与状态、细节。交互证据用关键帧和操作记录，不只看静态图。
+- **冻结矩阵与目标指纹**：单元 × 状态 × 视口 × 主题固定下来，每轮全量、同条件采集，分数可以前后比较，也能发现没改动单元里的回归。期望或目标图一变就重建基线，只改采集步骤则不影响。
+- **取最低分**：多个单元时取最低分作为本轮分数。验收要求每个界面都达标，平均分会掩盖短板。
+- **门槛项**：P0/P1（含机器检查发现的）一票否决，相当于原流程里的帧率门槛。
+- **失分可追溯、编号跨轮稳定**：每一分的扣除都要对应到具体差距，清单完整与否可以核对；「同一差距反复出现」也能直接判定，不靠印象。
+- **无依据只作建议**：找不到依据的期望不扣分，避免评审按个人口味无限挑刺，导致循环收不了尾。
+- **评审信息隔离**：评审只读目标包、截图和上一轮的 `judge.md`。看不到修复者自述、代码、机器检查和门槛，避免确认偏差和朝门槛凑分。
+- **争议不重评**：主 agent 有疑问时只能附核对说明，不能改分、删差距，也不能换一位评审重新打分，杜绝挑评审。补采或确认时的重评，一律取较低分。
+- **确认评审**：过线但余量很小时，加一位评审确认。误判通过会提前结束循环，代价远高于多评一轮。
+- **停滞分范围，每个范围只重构一次**：全局平台期只在低于门槛时判定，单条顽固差距只重构它所在的单元。重构后仍满足预警条件即停滞，不会因为每轮涨一点点而无限循环。修复方与评审各执一词、或等待素材和决定的差距，转为待裁定事项交给用户；在用户决定之前一直保持这个状态，其余差距照常推进。只剩待裁定的门槛项挡住通过时，直接交用户裁定。

package/skills/review-ui/references/phoenix-review.md

@@ -0,0 +1,54 @@
+# Phoenix managed 评审协议
+
+仅在识别或接入 Phoenix managed 循环时读取。纯 Markdown 循环继续按技能正文和四份合同人工执行；本参考不新增评分或处置规则。规则投影的唯一事实源为 [rules.v1.json](rules.v1.json)，绑定 [报告](report-contract.md)、[独立评审](judge.md)、[目标与采集](target-and-capture.md) 和 [修复记录](../../apply-ui-review/references/record-contract.md) 合同。
+
+## 先发现身份与能力
+
+1. 从本循环的安装回执或固定版本包清单读取期望的 package/runtime/review schema；不能拿 PATH 中任意同名命令、上游 `impeccable` 或旧 CLI 当成匹配 engine。
+2. 用实际 `phoenix-ui engine-probe` 核对身份，再执行 `phoenix-ui review --help` 与 `phoenix-ui review schema --json`；可用 `--kind <kind>` 只取该操作的输入形状。核对返回的 `reviewSchema` 与所需类型、变体后才构造机器输入。发现结果是当前 serde 类型校验的完整样例与枚举变体，`format: typed-examples`，不是完整 JSON Schema。样例不是证据：其中 `EXAMPLE_ONLY` 文本、数字和布尔值均须换成实际操作或取证值；cycle、round、cell、packet、revision 取实际返回，hash、被测版本和取证声明取真实材料。帮助/查询不读写循环，退出 0 只证明发现查询成功；入口不存在、身份/版本或协议不匹配时保持只读，不猜字段。
+3. 读已有索引与 `review status`，确认前缀、当前轮、baseline、revision、状态和原记录位置。未来 schema、损坏或不能识别的索引不能按「无索引」处理。
+4. 已有 managed 索引而 engine 缺失或不匹配：只读历史，可采集未登记素材；不计分、不裁定、不改代码、目标、处置、计数或生成区。给出按实际固定包版本恢复 engine 的命令，例如 `npm exec --package=@xgent-ai/skills@<packageVersion> -- phoenix-ui engine install --project <项目路径>`，替换为回执中的真实值并正确引用路径；没有期望版本时先说明所缺的回执，不能填一个猜测版本。恢复后续接原轮次，不重置、不静默降级、不自动下载或升级。
+
+循环索引的实际路径是 `<前缀>.ui-review.json`；当前识别口径为 `schemaVersion: 1`、`mode: managed`。缺 CLI 时直接读原文件识别既有状态；字段缺失、未知 schema 或损坏时保持只读，不能视作不存在。固定包清单声明的 `reviewSchema` 与 engine 身份都须核对；仅收到文本身份 probe 不能推断支持 review verbs。
+
+没有索引时还要检查旧 Markdown 轮次和修复历史：已有人工历史就继续人工或显式 import，不能 begin 清零。全新无旧历史且用户已要求验收时，匹配 engine 与实际 verbs 后可 begin managed；能力不可用则按人工流程。不能把「无索引」等同「永远人工」，也不能把旧历史自动接管。
+
+## 固定 verbs 与调用时机
+
+以下是操作形状，不是可直接写入的 JSON schema。路径、round、revision 和输入字段取自本项目的真实材料及匹配 engine 返回；工作流操作和 schema 查询带 `--json`，帮助也可用 `--json`。执行时保存实际 argv、输入、输出与退出码。
+
+| 操作 | 参数 | 用途与边界 |
+| --- | --- | --- |
+| `phoenix-ui review --help` | 也支持 `help`、`-h`；可选 `--json` | 只读列出现有 verbs、flags 和协议发现入口，不读写循环 |
+| `phoenix-ui review schema` | `--json`；可选 `--kind <kind>` | 只读输出 `reviewSchema: 1`、`discoveryVersion: 1` 的 typed examples；kind 为 `tested-version`、`capture`、`judge`、`mappings`、`adjudication`、`runtime-check`、`applied`、`import`。覆盖两种 import 形状与嵌套字段/变体；未知 kind 返回 2，样例不能直接充当真实输入或证据 |
+| `phoenix-ui review begin` | `--prefix <前缀> --target <目标包>`；可选 `--plan <计划> --scope <范围> --threshold <门槛> --tested-version <被测版本.json>` | 分配轮次、冻结目标、矩阵与被测版本。被测版本写 HEAD 加工作树指纹或可核对的构建 ID，本轮采集必须与它一致；省略时为未知版本，该轮不能判通过。已有未结束轮次就续接，不再 begin 一轮绕过它 |
+| `phoenix-ui review capture add` | `--round <round> --input <capture.json> --expect-revision <revision>` | 登记真实采集或明确 missing；补采追加 attempt，不覆盖历史图片 |
+| `phoenix-ui review judge-pack` | `--round <round>`；可选 `--units <单元>` | 生成不可覆盖的白名单材料包及 packet hash；只能选该范围内材料完整的单元 |
+| `phoenix-ui review judge add` | `--round <round> --input <judge.json> --raw <评审原文> --packet <packet> --expect-revision <revision>`；可选 `--mappings <mappings.json>` | 登记评审本人输出，或保留原文的忠实转换；不替评审补分或删差距。评审的新临时编号与同单元已有正式编号是同一问题时，用 `--mappings` 登记数组 `[{key, id, basis}]`：key 为该评审的临时编号，id 为已分配的正式编号，basis 为判为同一问题的依据；未映射的临时编号分配从未用过的新编号 |
+| `phoenix-ui review finalize` | `--round <round> --input <adjudication.json> --expect-revision <revision>`；给已封存的最新轮追加整体豁免时改用 `--expect-cycle-revision <cycle revision>` | 登记机器检查、主 agent 复核与裁定；需要确认时留在草稿，不能封存或宣称通过。追加豁免只比较 cycle revision，带 round 的 `--expect-revision` 会返回 2；豁免作为生成块写在该轮报告的验收判定之后 |
+| `phoenix-ui review apply record` | `--round <round> --input <dispositions.json> --expect-revision <applied revision>` | 更新当前轮修复处置和原记录位置的所属区块，不改历史评审 |
+| `phoenix-ui review status` | `--prefix <前缀>` | 只读状态；明确区分草稿、封存、缺失、损坏和未知 schema。新前缀的父目录不存在且无历史时返回 `state: absent`，不创建目录或循环。索引损坏、schema 来自未来版本或证据漂移时仍输出 `state: unknown` 的对象，但 `ok:false` 并退出 4 |
+| `phoenix-ui review import` | `--prefix <前缀> --input <legacy-map.json>` | 唯一的 Markdown 接入入口（`legacyMarkdown`），先核对映射与源 hash；生成区被手改时用 `projectionRebase` 按权威事实恢复，不导入手改内容 |
+
+退出 0 表示本次操作成功且返回的状态有效，不表示 UI 通过；`status` 读到损坏、未来 schema 或漂移的状态时退出 4。输入/schema 错误（2）、revision/锁/历史冲突（3）、文件或环境错误（4）都先保留实际输出并处理原因；不通过改计数、删索引或换前缀绕开。
+
+## 一轮内的证据和隔离
+
+- `begin` 的目标快照、矩阵、scope、threshold 与被测版本在本轮固定。报告沿用 Markdown 循环的文件名：首轮 `<前缀>.ui-review.md`，之后 `<前缀>.ui-review.r<n>.md`；最新轮次以索引和 `status` 为准，不另写「最新」区块。断点恢复读原 round/revision；本轮已封存后，新的采集或评审进入下一轮。
+- 采集先确认真实入口、当前构建、操作轨迹和图像内容，再登记 hash。文件存在、mtime 新或 hash 一致都不能单独证明真实性。目标图、旧截图、模拟页、合成图不能登记为当前采集。
+- 同一格子的首次记录是 attempt 1，包含 missing；补采递增 attempt。相同 cell/attempt/hash 重复提交才幂等，冲突不覆写。视口 ID 同时绑定宽、高、DPR，文件名避免同宽不同高或 DPR 冲突。
+- `judge-pack` 只含期望节、目标附件、当前已登记采集及交互、每单元最近一次有评审结论的覆盖轮的截图与评审自述（待复核旧差距取最新一轮仍未关闭的清单）、可选差分；目标指纹变了的单元附目标包完整的「变更记录」节，作为目标事实，条目不标单元或轮次，不做筛选。不能跟随材料链接打开代码、完整报告、修复记录、机器检查、门槛或主 agent 的看法。若旧差距材料缺失，先补材料，不让评审凭空复核。
+- 评审用全新只读上下文，继承宿主模型与 effort，不再派生；主 agent 保留实际派发与开图轨迹。工具白名单不等同权限沙箱，不能只凭 packet 已生成声称信息隔离已验证。
+- 评分与理由来自评审本人；转换时保留原文、hash 与转换依据，未评单元不填零分或假结果。差距的可选 `summary` 只照抄评审原文给该差距的标题；原文没有就省略，报告改用「现状」首句作标题，主 agent 不代拟。旧差距逐条复核，新临时编号显式映射至正式编号，不凭相似描述自动关闭或合并。
+- 确认或补采重评按合同选择某位评审的一整组较低分及理由，差距取并集。确认评审使用同一批材料；返回 `confirmation_required` 仍是草稿，确认结果登记后再 finalize。
+- `capture.md`、合并 `judge.md`、报告与处置 Markdown 是 JSON 状态的投影。每位评审原文另存且不覆盖；主 agent 不改原文、结构化评分或历史轮结果。
+
+## 旧历史与生成区
+
+导入前逐份读取目标、各轮报告、评审原文、截图和修复记录；明确目标指纹、差距 ID、处置、真实尝试与各范围重构的映射。保留 legacy 文件及源 hash。不能从文件名、修改时间或一次摘要猜完整历史，不能把旧图当本轮采集。
+
+未知尝试次数、目标 hash 或重构次数不能填零，也不能领取一次新的重构机会。最后一轮旧报告所在基线中有全量轮分数未知时，历史最佳不确定，`import` 返回 3 且循环保持人工。无法唯一映射时保持人工循环，或请用户确认新基线及旧差距如何保留；不自动覆盖历史。
+
+发现 generated 区被手改时，先另存用户原文与当前 source hash，停止覆盖；再用 `review import` 的 `projectionRebase`（另存副本、当前文件 hash 与 cycle revision 均须匹配）按权威事实恢复生成区。手改内容不经 import 导入，要保留的采集或处置以当前 revision 用 `capture add` 或 `apply record` 重新提交。封存报告正文与评审原文保持不可变，可恢复的只是其后追加的豁免生成块。CAS 冲突时回读最新 revision 和差异，不强写。
+
+修复记录仍在首次选定的原里程碑或 applied 路径。投影只更新本循环、本轮所属区块，保留人工文字和其他轮记录；不创建「UI 整改」里程碑。用户豁免须有真实原话、日期、版本与剩余影响，追加在该轮报告验收判定之后的生成块里，不能从勾选框或修复者自述推断豁免或已解决。