@xgent-ai/skills 0.6.0 → 0.7.1

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 整改」里程碑。用户豁免须有真实原话、日期、版本与剩余影响，追加在该轮报告验收判定之后的生成块里，不能从勾选框或修复者自述推断豁免或已解决。

package/skills/review-ui/references/report-contract.md

@@ -0,0 +1,148 @@
+# UI 验收报告合同
+
+## 落盘与命名
+
+- 以下路径与人工轮次规则适用于纯 Markdown 循环。Phoenix managed 循环沿用同样的报告文件名（首轮 `<前缀>.ui-review.md`，之后 `<前缀>.ui-review.r<n>.md`），按 [协议](phoenix-review.md) 由索引分配并续接 round/revision，最新轮次以索引为准；JSON 是权威状态，Markdown 是投影，不手写生成区。缺少匹配 engine 时只读，不改计分、处置、计数或生成文本，也不新建前缀绕过旧循环。
+- 默认保存完整 Markdown 报告、本轮截图、采集清单和评审原始结论，不询问是否保存。它们是下一轮评审的输入，不能只放在聊天里。
+- 首轮报告的路径按以下顺序确定：
+  1. 用户指定的路径；
+  2. 附带本地计划时，计划同目录的 `<计划名去扩展名>.ui-review.md`；
+  3. 仓库已有的报告目录；
+  4. `docs/reviews/<主题>.ui-review.md`。主题取页面或路由名，路径中的特殊字符换成 `-`。
+- 首轮报告路径去掉 `.ui-review.md` 后缀（不是这个后缀时去掉 `.md`），就是本循环的**前缀**。其他文件都按前缀命名：
+
+| 文件 | 路径 |
+| --- | --- |
+| 目标包 | `<前缀>.ui-target.md`；导出的目标图放 `<前缀>.ui-target/` |
+| 第 n 轮报告 | 首轮 `<前缀>.ui-review.md`，之后 `<前缀>.ui-review.r<n>.md`，n 取已有最大轮次加 1 |
+| 第 n 轮截图 | `<前缀>.ui-captures/r<n>/` |
+| 第 n 轮采集清单 | 同目录的 `capture.md` |
+| 第 n 轮评审原始结论 | 同目录的 `judge.md` |
+| 修复记录（没有计划时） | `<前缀>.ui-review.applied.md` |
+
+- 每轮另存，不覆盖历史轮次。用户给某轮指定的路径已被占用时，另存为未占用的名称并说明。不把报告写进计划、目标包或代码文件。
+- 报告由主 agent 单独写入，写完回读核对。写入失败时说明未落盘及目标路径，并在聊天中给出完整内容。
+- managed 循环只由 `review finalize` 生成报告，操作退出 0 不等于验收通过。`confirmation_required` 时保留草稿，完成确认后再裁定；封存结果与各位评审原文不可覆盖。生成区被手改时先另存手改文本及 hash，再用显式 `review import`（projectionRebase）按权威事实恢复生成区；手改内容只有经 `capture add` 或 `apply record` 以当前 revision 重新提交才成为事实，不静默覆盖。
+
+## 采集清单与评审原始结论
+
+**`capture.md`** 在采集完成后写入：被测版本、目标指纹、采集条件；每张截图对应的单元、状态、视口和主题，以及它的出处（实际访问的地址、拍摄时间、所用工具，拦截了哪些请求）；没采到的格子及原因。它会交给评审当作看图的清单。下一轮比较目标指纹时，读的也是它，不必打开报告。
+
+各位评审原文独立保存，不被确认评审或合并覆盖。**`judge.md`** 是本轮评审结论的合并，只包含三部分：
+
+- 各单元的四个维度分、单元总分和每个维度的理由；做了确认评审或重评时，每个单元选总分较低的那位评审的一整组四维分与理由，不逐维拼接；差距保留全部评审的并集；同一批材料的多位评审对同一条旧差距结论不同时，按 回归 > 仍存在 > 部分解决 > 待核实 > 已解决 > 不再适用 取最靠前的一项，任何一位给出未关闭或待核实的结论都优先于关闭结论；
+- 评审来源的全部未关闭差距：本轮复核后仍未关闭的旧差距（沿用编号，附最新状态），以及本轮新增的差距（已换成正式编号）；
+- 建议。
+
+`judge.md` 不写门槛、判定、机器检查、主 agent 核实的差距、核对说明和任何修复信息。下一轮评审只通过它了解上一轮的结论。
+
+## 报告结构
+
+1. **评审对象**（紧跟标题），一行表格：
+
+| 轮次 | 开发计划 | 目标包 | 被测版本 | 截图 | 上轮报告 |
+| --- | --- | --- | --- | --- | --- |
+| R<n>；重建基线或限定范围时注明 | [<计划标题>](<相对路径>)，没有写「无」 | [<目标包>](<相对路径>) · 目标指纹前 12 位 | HEAD 短 SHA，含未提交改动时加指纹；访问地址 | [r<n>](<相对路径>) | [<上轮报告>](<相对路径>)，首轮写「无」 |
+
+2. **验收判定**：首行写判定（见下文），再写本轮分数与门槛、停滞预警或待裁定标记，以及 1–3 句理由。
+3. **评分**：每个单元的四个维度分和单元总分；本轮分数；历史最佳；门槛。做了确认评审或重评时，列出各位评审的单元分和最终取的较低分。
+4. **轮次轨迹**：复制上一轮的表格，再追加本轮一行。
+
+| 轮次 | 本轮分数（最低单元） | 历史最佳 | 未关闭 P0/P1 | 重构轮 | 备注 |
+| --- | --- | --- | --- | --- | --- |
+| R1 | 5.5（U2） | 5.5 | 3 | — | 首轮 |
+| R2 | 7.0（U1） | 7.0 | 1 | — |  |
+
+5. **上轮差距复核**（复审才有），表头为：编号 | 上轮严重度与摘要 | 上轮处置（取自修复记录） | 本轮结果 | 依据。
+   - 评审来源的差距由本轮评审复核；机器检查和主 agent 核实的差距由主 agent 重新检查。
+   - 本轮结果只用这几种：已解决、部分解决、仍存在、回归、待核实、不再适用、本轮未复核。
+6. **差距清单**：所有未关闭的差距，即除已解决、不再适用以外的全部旧差距，再加本轮新增的。按 P0 → P3 排序，同一严重度内按可挽回分从高到低。属于待裁定事项的，在标题上标出。
+7. **待裁定事项**：每项写清原因、相关差距、已有的尝试和可选项。
+8. **建议（不扣分）**。
+9. **机器检查**：检查项、工具与版本、结果、对应的差距编号；没检查的写明原因。
+10. **采集与覆盖**：
+    - 环境与被测版本，采集工具与条件，目标文件的 hash 清单；
+    - 已采和未采的格子，未采的原因，以及补采记录；
+    - 环境噪声；
+    - 评审方式：派了几位 subagent、怎么分组、有没有确认评审或重评、是否单上下文评审；
+    - 主 agent 对评审结论的核对说明（见下文）。
+
+## 差距格式
+
+```markdown
+### UI-03 · [P1] 窄屏筛选栏挤压表格（U1 · 布局 · 可挽回 1.0）
+
+- 位置：[U1-default-390-light.png](<相对路径>) 顶部筛选栏
+- 现状 → 期望：筛选控件横排，表格只剩约四成宽，还出现了横向滚动 → [orders-m.png](<相对路径>) 中筛选收成一个「筛选」按钮，表格占满宽度
+- 修法：窄屏下把筛选项收进抽屉，复用现有 Drawer；去掉表格容器的固定最小宽度
+- 来源：评审 R2（机器检查或主 agent 核实时注明）
+```
+
+- 每条差距都必须指向本轮实拍的截图或页面实测结果。读代码产生的怀疑不进清单，可以写进「采集与覆盖」，作为下一轮补拍或实测的线索。
+- 编号用 `UI-<两位序号>`，同一问题跨轮沿用原编号。
+- 评审给新差距时先用临时编号。主 agent 合并时按顺序换成从未用过的正式编号，不重排，也不复用已关闭的编号。
+- 重建基线后，仍适用的旧差距沿用编号，不适用的标「不再适用」。
+- 主 agent 认为评审看错时，只在差距下附「核对说明」，写清截图里实际看到的事实。核对说明不改分、不删差距，也不改变门槛项；由修复方核实后决定是否不采纳，下一轮由评审复核。
+- managed 循环中新旧编号由显式映射登记：`review judge add --mappings` 的每项 `{key, id, basis}` 写明评审的临时编号、同单元已有的正式编号和判为同一问题的依据；上一轮指每个单元最近一次覆盖它且有评审结论的轮次，覆盖了却没有任何评审结论的轮次不算。缺少该轮评审自述或截图时先补材料，不凭相似描述自动合并、关闭旧差距。
+
+## 计分与门槛
+
+- **单元分**：评审给的四个维度分之和；做了确认评审或重评时，取其中较低的。
+- 分数与门槛按原始有限十进制数精确比较；可用小数或科学计数法，不加 epsilon、不先四舍五入，也不另设 0.01 步长。首次将判通过且最低单元分严格小于「门槛 + 0.5」时必须确认；恰好等于时不强制。
+- **全量轮**：用户没有限定范围、应当采集目标包全部单元的轮次。全量轮全部单元都评到分时，才有**本轮分数**，即各单元分中的最低值。**历史最佳**是自上次重建基线以来本轮分数的最高值。
+- **门槛**：默认 8/10。用户指定其他门槛时从其规定，记在报告里，后续轮次沿用。门槛不写入目标包，也不告诉评审。
+- **门槛项**：未关闭的 P0/P1 差距，不论来自评审、机器检查还是主 agent 核实。
+- **单元达标**：单元分 ≥ 门槛，且该单元没有门槛项。
+- **待裁定事项**：单靠修改解决不了、需要用户决定的事。包括：
+  - 停滞的差距（见下文）；
+  - 修复记录中最近一轮对它的最终处置为不采纳，但下一次评审仍判存在（仍存在、部分解决或回归）的差距；
+  - 修复记录中最近一轮对它的最终处置为待决定或阻塞、仍未解除的差距；
+  - 目标图与规范之间的冲突。
+
+  一旦成为待裁定事项，就一直保持，直到用户就它给出方向，或评审判它已解决、不再适用。修复方跳过它时记「待决定」，不记「未处理」。
+- **可修复的差距**：未关闭、且不属于待裁定事项的差距。
+
+## 停滞
+
+逐个范围判断。范围有两种：**全局**；或**某条差距**，它的重构针对差距所在的单元。是否做过重构轮，以修复记录为准。自上次重建基线以来，每个范围最多重构一次。
+
+显式导入的旧循环若尝试或重构历史无法确定，次数保持未知，不能当作零、推定已尝试或再次领取重构机会；先补证，或由用户确认新基线和旧差距处置。原历史及源 hash 保留。
+
+**预警条件**，满足任一即成立：
+
+- **全局平台期**：本轮分数低于门槛；自上次重建基线以来已有至少 3 个有本轮分数的轮次；本轮的历史最佳，比两个这样的轮次之前的历史最佳提高不到 1.0。
+- **顽固差距**：某条 P0–P2 差距，自评审上一次判它以来，修复记录中有一轮对它的最终处置（同一轮以最后一次登记为准）是已修改待评审，而本轮评审仍判它仍存在或回归；或者它已连续两次被判部分解决，且两次之前都被修改过。它与不采纳形成的待裁定分别判断，可以同时成立。
+
+**判定**：
+
+- 预警条件成立，且该范围还没重构过：发**停滞预警**，要求下一轮修复对该范围做重构轮。
+- 上一轮已发预警，但修复方没做重构轮：再次发预警，不判停滞。
+- 预警条件成立，且该范围已经重构过：该范围**停滞**。差距停滞后成为待裁定事项；全局停滞时，判需用户裁定。
+
+## 验收判定
+
+按以下顺序，取第一个成立的判定，写在「验收判定」首行；最终回复也先给它。
+
+1. **需补证**：属于以下任一情况。写明缺什么、怎么补；报告照常列出已评单元的分数和差距，修复方可以先修这些。
+   - 全量轮中有单元或必需的格子没采集到，包括截图不符合真实性要求的；
+   - 有 P0/P1 差距补采后仍判待核实（截图看不出）；
+   - 应用起不来；
+   - 两次派发评审都没拿到有效结论；
+   - 目标包缺少某个单元的期望。
+2. **通过验收**：全量轮；本轮分数 ≥ 门槛；没有门槛项；需要确认评审时，确认后仍达标。剩下的 P2/P3 差距（包括待裁定的）不阻止通过，列为可选的打磨项。
+3. **需用户裁定**：属于以下任一情况。列出待裁定事项、已经试过的做法、截图对照和可选项。
+   - 全局停滞；
+   - 尚未通过，且已没有可修复的差距；
+   - 剩下的门槛项都是待裁定事项，而分数已达门槛（限定范围的轮次看范围内各单元分）。此时继续修 P2/P3 也无法通过。
+4. **需要修改**：其余情况。按需带上标记，例如：
+   - 「需要修改 · 停滞预警（全局）」
+   - 「需要修改 · 停滞预警（UI-07 所在 U3）」
+   - 「需要修改 · 待裁定（UI-04、UI-09）」
+5. **用户豁免通过**：用户明确接受当前的整体界面。在本轮报告的验收判定后追加记录：日期、用户原话、被测版本、豁免的差距编号及剩余影响。原分数和差距不改写，豁免不算已解决，也不从勾选框或修复者的表述推断。managed 循环在本轮封存后用 `review finalize --expect-cycle-revision` 追加，记录作为生成块写在该轮报告的验收判定之后，封存正文不变。
+
+**限定范围的轮次**按同样规则判定，只有两点不同：
+
+- 没有本轮分数，不判全局平台期；
+- 范围内单元都达标时判需补证，并说明要一轮全量评审才能判通过。
+
+验收判定只表示界面在所测版本和条件下的验收结论，不是合并、发布或产品终验的授权。