@xgent-ai/skills 0.7.7 → 0.7.8

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

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

package/skills/review-ui/references/target-and-capture.md

@@ -20,7 +20,7 @@
 
 - 一个单元既没有目标图也没有规范：不写它的期望，该单元判需补证。
 - 来源之间冲突（例如目标图与规范不一致）：不自行裁定，列为待裁定事项。
-- Phoenix context 是定位材料的线索：缺 CLI 或文档 partial 时仍读实际 DESIGN.md、PRD、brief 与接口原文，并注明缺失部分。profile/default advice 与未知 token 不能替代项目规范或已确认目标；profile 更新只展示差异，不改已冻结的目标，也不把建议值猜成 token 实值。
+- 定位材料后读取实际 DESIGN.md、PRD、brief 与接口原文，注明缺失部分。工具建议不能替代项目规范或已确认目标，不能自动改变已冻结期望，也不把未知 token 猜成实值。
 
 **单元**是一个可以单独验收的页面、弹层或流程，范围覆盖本次计划改动到的界面。状态（默认、加载、空、错误、禁用、成功等）、视口和主题都放进矩阵，不另拆单元。单元数量够判断验收即可，一般 2–8 个。
 
@@ -61,42 +61,62 @@
 
 **比较口径**写明哪些差异不算偏差（示例数据、头像、时间戳、第三方内容），哪些必须一致（文案、顺序、token）。这样评审不会要求改不了的东西，也不会放过该一致的地方。采集时尽量用与目标图相近的数据。
 
-**目标指纹**：使用带算法名的 `phoenix-ui-target-v1`。按 Markdown AST 定位唯一的「单元」「规范要点」节，统一为 LF，保留节内文字顺序与空白；纳入其直接引用的本地附件与引用定义，不递归跟随附件中的链接。附件按项目逻辑路径去重、排序，片段引用也 hash 整个文件；逻辑路径和内容 hash 用长度前缀组合。来源 URL 只作文本，远程图片须本地导出；仓外附件须注册后复制入快照，缺失附件记缺证。managed 循环使用 engine 返回的算法与指纹，不另算一个猜测算法；未知算法不能跨轮比较。「采集」节和变更记录不计入，所以只改采集步骤不重建基线；原地覆盖目标图会改变指纹。
+**目标指纹**：记录「单元」「规范要点」的规范化文本（统一 LF）及其直接引用目标附件的 SHA-256 清单，附件按相对路径排序；再对清单计算 SHA-256。缺失附件记缺证，远程目标图先保存本地。保存计算口径与输入清单，复审沿用同一口径；旧指纹口径未知时直接核对原始目标与附件，不猜相等，也不清零修复历史。「采集」节和变更记录不计入，只有期望或目标附件变化才重建基线。此计算不依赖特定 CLI。
 
 **冻结与变更**：R1 建立后，「单元」和「规范要点」只能由用户修改，或经用户确认后修改，并写入变更记录。不能反过来拿被测实现当目标。
 
 - 用户接受某处偏差时，把它写进该单元的比较口径，注明日期和用户原话；评审会据此不再扣分。
 - 只改「采集」节时，可以直接修改并记录。
 - 指纹一变，下一轮就按重建基线评审。
-- managed 循环由 `review begin` 冻结本轮目标快照、矩阵和 scope；补采只追加采集记录，不改本轮期望。用户确认的期望变更留存原话与差异，在下一轮按新指纹重建基线。
 
 ## 采集
 
-- **真实性**：每张截图都必须是本轮用截图工具在真实运行的产品上拍的：从「采集」节写明的真实入口进入，由真实浏览器、模拟器或桌面应用渲染当前代码。以下都不能冒充截图，一律当作没采到：
+### 先规划证据，再拍图
+
+验收矩阵列的是需要验证的条件，不是截图任务清单。逐项标明「本轮实拍」「本轮实测」「历史复用」或「缺证」，允许多项引用同一证据。首轮覆盖所有单元的必要视觉与交互特征；复审只检查变化、未关闭问题及影响范围内的回归。既没有证据也没有有效复用依据的条件仍是缺证。
+
+- **同状态共用一图**：页面/路由、状态、视口及 DPR、主题、语言、数据条件和被测版本相同，多个问题引用同一原图，并注明区域、元素或文字。问题编号不是截图维度。先查已有材料；新增一张图必须说明它补充了什么信息。
+- **代表帧**：选择必要的默认桌面、最窄长文案语言、深色等样本；只覆盖产品实际支持的条件。普通复审以 6–12 张为预算参考，不是最低任务量或硬上限；简单页面 3–5 张甚至更少即可。预算包含 apply 自检的可复用图片；多页面首轮或真实异常需更多时说明增量信息，不为凑数补拍或漏掉不同页面。
+- **操作与截图分开**：操作必须实际执行并记录观察结果；仅在弹层打开、校验反馈、成功/失败、布局或必要焦点状态发生可见变化时拍关键帧。重复点击、同一禁用入口、画面不变的检查不各拍一张。看不清先放大原图，仍不足才补实拍局部；局部图不能代替页面整体布局证据。
+- **先实测**：优先复用现有脚本，在矩阵条件下验证溢出、可达性、关键文字、状态与交互断言，保存实际结果。成功断言通常不截图，异常或视觉判断需要时补图；断言不能替代层级、字体观感等视觉判断，也不能由少量样本推断整张矩阵通过。
+- **前置阻塞**：先核对环境、账号、数据与状态入口。已有 seed/mock/拦截方法可在允许范围内尝试；同一阻塞条件未变时记录一次原因及解除条件，停止受阻项，继续独立项，不反复启动整轮验收。
+
+### 跨轮及 apply 证据复用
+
+复用前核对原始材料可读、来源版本与目标指纹、采集条件及从该版本至今的影响范围。目标指纹变化时重新建立基线，不继承旧分数。共享组件、token、字体、素材、布局、依赖、数据或运行环境变化可能影响未直接修改的页面，必须纳入复查；无法判断的单元不沿用结论。代码 diff 只辅助判断失效范围，不能直接证明修复效果。
+
+- 未受影响、已独立通过的单元可沿用原证据和整组评分，标明来源轮次及复用理由，不重新打分；已关闭问题不重复复核，除非相关变化或新证据显示回归。
+- 新增/受影响单元与未关闭问题需当前有效实测或实拍。apply 留下的图片在目标、版本、条件均匹配且出处核验通过时直接引用，不搬运、改名或重复拍摄；它只提供事实，评分和关闭仍由独立评审完成。
+- 历史截图标「复用 Rn」，apply 图片标原路径与版本；不写成「本轮新拍」。一张修复后的状态图可同时验证该页多条差距，原图保留作对照。
+- `capture.md` 记录证据类型、原路径/轮次、版本与条件、覆盖的单元/状态/问题、中性有效性标记，缺证单列。复用理由与失效范围留报告；交给评审的清单只含中性出处、覆盖和复用标记；主 agent 的 diff 分析、修复解释和机器检查结论只留报告，不混入评审材料。没有变化、新证据或阻塞解除时续接记录，不创建空轮次。
+
+### 截图真实性与保存
+
+- **真实性**：每张新截图必须用截图工具在真实运行的产品上拍摄：从「采集」节写明的真实入口进入，由真实浏览器、模拟器或桌面应用渲染当前代码。以下都不能冒充截图，一律当作没采到：
   - 设计稿、目标图或它们的导出图；
-  - 上一轮或别处的旧截图；
+  - 上一轮或别处的旧截图冒充本轮新采集（按上述合同明确登记的复用除外）；
   - 为评审临时写的模拟页面或静态 HTML；
   - 手工合成、拼接或修过的图；
   - 只渲染组件的沙箱（如 Storybook），除非该单元本身就以沙箱为入口，并在目标包写明。
 
   为到达某个状态而拦截请求、返回测试数据是允许的，但只能改数据、不能改界面代码，并在 `capture.md` 对应格子注明。
-- **出处可查**：`capture.md` 为每张图记录实际访问的地址、视口宽高、DPR、主题、拍摄时间、所用工具及构建或工作树版本。交给评审前，主 agent 实际开图并核对采集轨迹：文件是本轮新拍的；尺寸与视口相符；画面是目标页面，不是报错页、登录页或空白页。文件存在、mtime 新或 hash 一致不能单独证明这些事实。不合格的重拍，重拍不了就记为没采到。
+- **出处可查**：`capture.md` 为每张图记录实际访问的地址、视口宽高、DPR、主题、拍摄时间、所用工具及构建或工作树版本。交给评审前，主 agent 实际开图并核对采集轨迹：新采集确为本轮拍摄，复用材料保留原始出处并满足复用条件；尺寸与视口相符；画面是目标页面，不是报错页、登录页或空白页。文件存在、mtime 新或 hash 一致不能单独证明这些事实。不合格的重拍，重拍不了就记为没采到。
 - **环境**：优先复用项目已有的 `verify-*` 验证 skill、E2E 脚本或计划写明的走查方式，来启动、登录和造数。被测版本记 HEAD 和未提交改动指纹。构建产物必须来自当前代码：必要时重新构建，或用本次改动的可见特征确认拿到的不是旧包。
 - **一致条件**：视口与像素比相同、字体加载完毕、动画关闭或已结束、网络空闲、数据和时间固定。视口取目标图的画框尺寸。同一版本重拍结果不一致时，记为环境噪声；无法稳定的格子标为不可比，不算实现差异。
 - **命名与存放**：截图存到 `<前缀>.ui-captures/r<n>/<单元>-<状态>-<视口宽>-<主题>.png`，例如 `U1-empty-390-light.png`。
-  - 交互关键帧在每步动作执行之后拍，文件名后加步骤序号，如 `U2-flow-1440-light-03.png`。操作记录写入同目录的 `U2-flow-1440-light.md`，只写实际执行的动作和截图里看到的结果。
-  - 同一视口 ID 同时绑定宽、高、DPR。同宽但高或 DPR 不同时加确定性后缀，如 `-h900-dpr2`；managed 循环沿用 begin 分配的 cell 与文件名。
+  - 交互仅在需要视觉证据的关键转折后拍，文件名后加步骤序号，如 `U2-flow-1440-light-03.png`。操作记录写入同目录的 `U2-flow-1440-light.md`，只写实际执行的动作和截图里看到的结果。
+  - 同一视口 ID 同时绑定宽、高、DPR。同宽但高或 DPR 不同时加确定性后缀，如 `-h900-dpr2`。
   - 各轮首采文件同名，方便逐张对照；同轮补采保留原图，追加 `-a2`、`-a3` 等 attempt 名，不覆盖。
   - 默认截可视区域，目标是整页稿时截整页。
   - 截图要不要提交，按仓库约定。
-- **登记与恢复**：managed 循环用 `review capture add` 及当前 revision 登记；首次 missing 也占 attempt 1，补采递增。同一 cell/attempt/hash 可幂等重放，内容冲突不得覆写。中断后续接原轮，封存后新增证据进入下一轮。
+- **登记与恢复**：在 `capture.md` 中追加采集记录，保留原图和出处。中断后续接原轮；同一材料不重复登记，补采以新的 attempt 文件名保存。
 - **日志**：采集期间顺带把控制台日志和失败请求存到本轮目录，评审结束后再分析。
-- **全量与回归**：即使修复只涉及部分单元，每轮也采集全部格子，因为回归同样会出现在没动过的单元里。
+- **覆盖与回归**：根据实际影响范围选择复查状态，未受影响项复用有效证据；全局样式、共享组件或目标变化须扩大相关范围，不能只看被直接修改的文件。
 - **差分（可选）**：有图像差分工具时，可以给还原模式的单元生成差分图，供评审定位差异。差分比例不直接计分。
 
 ## 机器检查
 
-确定性检查与评审的感知判断分开，在评审结束后进行，结果不交给评审，以免先入为主。由主 agent 写进报告，按影响定严重度后列入差距清单，来源标「机器检查」；之后每轮由主 agent 重新检查这些差距。
+确定性检查前置以筛选异常和减少截图，结果与感知判断分开，不把检查的通过结论交给视觉评审，以免先入为主。由主 agent 写进报告，按影响定严重度后列入差距清单，来源标「机器检查」；之后由主 agent 复查未关闭及受影响的差距；未受影响的已通过检查可复用，注明来源。
 
 所有检查都在运行中的页面上执行：在页面里测量元素尺寸、读取计算样式、注入扫描脚本、用真实按键操作。从代码或样式表推断出的问题（例如「这个容器写死了宽度，窄屏可能溢出」）不算检查结果，只能提示去哪里补拍或实测。按工具可用性和目标包要求选做：
 

package/skills/xgent-app-release/SKILL.md

@@ -16,7 +16,7 @@ when_to_use: "用户会说「发个版」「提案卡在待审」「发布后出
   自动通过并应用清单/产物；后端与网关需分别确认，且每次留档（时间 + diff + 令牌前缀）。
 - **审核档**：其余一切（scopes / ACL 清单 / 依赖 / 跨应用授权 / 服务地址 / 席位 /
   授权文案 scopeLabels / iframe 指向 embedUrl / 部署形态 / 部署前置 env 键清单
-  requiredEnv / 服务账号身份 serviceAccount.clientId / 嵌进门户管理面的管理页 adminPages / service 租户配置 tenantConfig / 首次接入）都会改变权限面，
+  requiredEnv / 服务账号身份 serviceAccount.clientId / 嵌进门户管理面的管理页 adminPages / service 租户配置 tenantConfig / OAuth 标准发现 oauthDiscovery / 首次接入）都会改变权限面，
   ⇒ 提交成功但进入平台管理员的「发布审核」队列，**批准前库里一字不动**。
   被拒绝时 `status` 与 `--wait` 都能看到原因。
 - **`helpEntry`（版头那枚帮助按钮）按【值】分档**，同一个字段两种命运：写 App 内路由
@@ -84,6 +84,10 @@ metricKey 会被上报接口拒收并计入 `rejected`。要声明「部署我
 先读 [references/public-delivery.md](references/public-delivery.md)。现有标准入口是
 `/apps/<key>/…`、`/svc/<key>/…` 或 Sites；审核、部署、网关与业务验收分别核对。
 
+涉及 MCP/OAuth 标准发现配置、`/.well-known/…/svc/<key>` 返回 HTML/404 时，读同参考的
+[OAuth 标准发现发布](references/public-delivery.md#oauth-标准发现发布)。`oauthDiscovery` 只声明精确元数据路由，
+与 `cliAccess` 用户密钥目录、`publicClient` 登录客户端及 Sites 入口分别配置；不要用其中一个替代另一个。
+
 | 你需要 | 从哪来 | 放在哪 |
 | --- | --- | --- |
 | `listingKey` | 平台给的 App 标识，小写字母/数字/连字符。它同时是 `/svc/<key>`、`/apps/<key>/`、scope 命名空间、令牌的 aud —— **四位一体，永不改** | `LISTING_KEY=…` |
@@ -241,6 +245,8 @@ VER=1.4.2      # 地址、令牌、listingKey 都在 .xgent-registry.env 里，
    `references/health-contract.md` 运行其 `scripts/verify-health.ts`，非零退出不得发布。
    平铺与 Envelope 都支持：非 2xx 不通过；2xx 顶层有 `ok` 时必须 `ok === true && data.db === true`；
    没有顶层 `ok` 时按 2xx 判健康。检查脚本与平台同源，不另加包装或字段命名限制。
+   本次有 `oauthDiscovery` 变更时，按 [OAuth 标准发现发布](references/public-delivery.md#oauth-标准发现发布)
+   核对声明与平台 v2 前置；本地 preflight 未校验此字段，零退出不代表元数据或网关已就绪。
 4. **发布。**
    带前端的应用先按 [前端归档与同步验收](references/frontend-archive.md) 生成并持久留存
    `DIST_ARCHIVE`（根下直接是 index.html 的 `.tgz`）与 SHA-256；下面上传的必须就是这份文件。
@@ -261,6 +267,8 @@ VER=1.4.2      # 地址、令牌、listingKey 都在 .xgent-registry.env 里，
    （见下），第 4 步的返回体已经给了版本与 digest，浏览器那一眼照走不误。
    交付包含跨平台同步时，还须核验主平台条目和 `/dist` 的真实字节；没有读取权限时明示
    「前端已发布，主平台归档/可同步性未验证」，不能把发布或投目录成功当作同步验收通过。
+   OAuth 发现变更还须按本次 `proposalId` 确认 delivery，并匿名检查标准/旧地址、JSON 字段、HEAD
+   与 MCP challenge；撤销检查 404，客户端授权与回调另验。没有前端的服务按这些接口验收，不要求打开 App 卡片。
 
 `@xgent/release-cli` 不在公共 npm 上，**它就在第 0 步那个私有包仓里**。取不到包时先分诊，
 别急着换工具：`npm config get @xgent:registry` 是 `undefined` ⇒ 回第 0 步配 `.npmrc`，一条命令就好。
@@ -301,7 +309,7 @@ whoami `200` 而 `/status` `404`，就是这种情况：**令牌没问题，别
 等待后端与网关回执；待审不会自动等待，需加 `--wait-review`。unknown 不能当成功，superseded 表示
 已被后续目标取代。旧门户无 delivery 时会明确提示无法核验网关，不能把兼容退出 0 当完整确认。
 版本与 strict/v2 启用前提见 [公开面与交付确认](references/public-delivery.md)，API 见
-[发布 API](references/publish-api.md)。上述新增能力尚待正式发布与受控启用。
+[发布 API](references/publish-api.md)。目标门户是否已启用，以实际部署与 delivery 回执为准。
 
 ## 镜像要环境变量：**键名归你，值归平台**
 
@@ -632,6 +640,7 @@ App 声明过的某个 `requiredEnv` 键在部署环境里还没有值，这次
 | 产物形状（`base` 双态、tar 根、CSP 与外链、发前在真门户里试） | [references/build-and-package.md](references/build-and-package.md) |
 | 令牌语义、端点原始形状、字段白名单、返回体、`curl` 兜底、CI 范式 | [references/publish-api.md](references/publish-api.md) |
 | 症状 → 原因速查（发布报错 / 线上白屏 / 发了没换版） | [references/troubleshooting.md](references/troubleshooting.md) |
+| MCP/OAuth 发现的 manifest 声明、治理审批、HTTP 验收及撤销；公开页与 CSP | [references/public-delivery.md](references/public-delivery.md) |
 
 报告结果时如实说清：发了哪个 key、哪个版本、proposalId、digest、原始包持久留存位置、
 有没有在浏览器里实际打开过；涉及同步时另报主平台归档是否已验证。

package/skills/xgent-app-release/references/public-delivery.md

@@ -17,12 +17,76 @@ connectSrc 兼容契约；不能凭空添加其他指令后宣称生效。预检
 | 前端静态/SPA 匿名页 | `/apps/<key>/…` | 正确 base、嵌套路由刷新、匿名页不先强制登录；数据授权仍由 App 验证 |
 | 后端直出 HTML | `/svc/<key>/…` | App 适配 cookie Path、form、fetch、Location、资源与预览；后端自己设置 CSP |
 | 站点/独立域名 | `publicEntrypoints` + Sites | 申请 sites 服务特权，满足平台开关、DNS/TLS/路由和租户权益；独立核对站点修订 |
+| MCP/OAuth 元数据 | `oauthDiscovery` → `/.well-known/…/svc/<key>` | 平台发现能力、v2 网关、获批声明和匿名元数据；按下节验收 |
 
 Sites 需要平台启用、登记入口和 DNS，租户具有 sites.enabled/portal.public_sites，自定义域还需
 portal.custom_site_domains。`sites.read/write` 经 privilegedServiceScopes 申请，不是用户权限。
 publicEntrypoints 只声明站点可绑定的后端前缀，不增加门户根代理。新 App 不得占用 `/v`、`/share`。
 历史根路径和 listingKey 改名均需另行迁移授权；改链接前缀不能代替 cookie、子请求和数据归属迁移。
 
+## OAuth 标准发现发布
+
+目标门户须已部署发现能力的迁移、API/controller 与两种运行形态对应的 v2 网关模板；不支持 v1。
+不要求 `PUBLIC_SITES_ENABLED`、Sites 权益或 CSP strict 开关。`@xgent/shared` 从 0.11.1 提供声明类型，
+CLI ≥0.7.0 支持本提案 delivery 查询；包版本和 whoami 成功不能证明目标平台已部署。
+
+合入 App 自己的完整 manifest，递增 version；不要把片段当完整清单发布，也不要作为散表单字段提交：
+
+```json
+{
+  "oauthDiscovery": {
+    "authorizationServer": true,
+    "protectedResources": ["/mcp"]
+  }
+}
+```
+
+非空声明要求最终清单有 deployDescriptor 或 serviceBaseUrl。只接受上面两个键，省略的值分别为
+false、空数组。资源路径填 App 内部路径，如 `/mcp` 或 `/`，不含 `/svc/<key>` 前缀。
+除根 `/` 外，路径由非空的字母、数字、`.`、`_`、`~`、`-` 段组成；禁止单独的 `.`/`..` 段、
+空段、尾斜线、URL、百分号编码、query、fragment、空白和通配符。去重排序，不允许指定域名或 upstream。
+
+| 声明 | 门户 origin 上的标准入口 | App 匿名 GET/HEAD 端点 |
+| --- | --- | --- |
+| authorizationServer=true | `/.well-known/oauth-authorization-server/svc/<key>` | `/.well-known/oauth-authorization-server` |
+| protectedResources 含 `/mcp` | `/.well-known/oauth-protected-resource/svc/<key>/mcp` | `/.well-known/oauth-protected-resource/mcp` |
+| protectedResources 含 `/` | `/.well-known/oauth-protected-resource/svc/<key>` | `/.well-known/oauth-protected-resource` |
+
+`oauthDiscovery` 是元数据路由，`cliAccess` 是门户用户密钥目录；也不能用 publicClient、publicEntrypoints
+替代。App 保持既有 OAuth 与 MCP 鉴权，门户不生成 JSON、不改 issuer/resource、scope、token 或客户端回调。
+
+1. 按本 skill 的配置文件与令牌流程提交 `npx @xgent/release-cli publish --manifest app.manifest.json`。
+   声明新增/变更/撤销均按实际差异进入治理审批；等价重排/去重不进审。记录 proposalId，等待平台管理员批准。
+   本地 preflight 不校验 oauthDiscovery，也不能证明平台能力；提交成功和 pending 都不能报上线。
+2. `npx @xgent/release-cli status --proposal-id <proposalId> --wait` 查询固定提案，要求 `delivery.state=applied`。
+   publish 的 `--wait` 不等人工审批，需连审批一起等用 `--wait-review`。失败、unknown、superseded 按下文四阶段处理。
+3. 从目标配置取门户 origin（无尾斜线）为 `PORTAL_ORIGIN`、App key 为 `LISTING_KEY`，匿名检查实际声明的地址：
+
+   ```bash
+   curl -i "$PORTAL_ORIGIN/.well-known/oauth-authorization-server/svc/$LISTING_KEY"
+   curl -I "$PORTAL_ORIGIN/.well-known/oauth-authorization-server/svc/$LISTING_KEY"
+   curl -i "$PORTAL_ORIGIN/.well-known/oauth-protected-resource/svc/$LISTING_KEY/mcp"
+   curl -I "$PORTAL_ORIGIN/.well-known/oauth-protected-resource/svc/$LISTING_KEY/mcp"
+   curl -i "$PORTAL_ORIGIN/svc/$LISTING_KEY/.well-known/oauth-authorization-server"
+   curl -i "$PORTAL_ORIGIN/svc/$LISTING_KEY/.well-known/oauth-protected-resource/mcp"
+   ```
+
+   GET 须为 200 JSON，标准/旧地址内容一致；HEAD 同状态及 JSON Content-Type、无正文。
+   issuer 为 `$PORTAL_ORIGIN/svc/$LISTING_KEY`；根 resource 与之相同，`/mcp` 资源加 `/mcp`。
+   核对既有 OAuth 端点不变，匿名 MCP 仍有约定的 401 与 WWW-Authenticate。再由目标客户端验证授权页与回调，
+   包括约定的 WorkBuddy / WorkBuddy AI 客户端；HTTP 验收不能冒称客户端通过。
+
+**撤销/回退**：省略字段保留已批准值；null 或空对象清空；对象完整替换，删去资源即撤销该条。
+提交新版本并批准、等待本次 delivery applied 后核对撤销地址 404；恢复旧声明也按新版本审批。
+仅撤销发现不删除 App 旧元数据端点，移除后端配置须同时撤销声明。单租户卸载不撤全局声明；
+停止/下架/删除 listing 随新网关代撤路由，恢复服务后可恢复获批声明。
+
+**分诊**：已声明标准入口的非 GET/HEAD 方法返回 405（Allow: GET, HEAD），未声明/撤销/额外尾段返回 404。
+404 先查获批声明、本次 delivery 与服务状态；HTML 查实际 v2 模板/加载版本；旧地址也失败或非 JSON 查 App。
+请求使用门户 origin，站点域名继续走站点上下文。后端错误透传，不应靠改 issuer 或硬编码宿主端口绕过。
+仅改声明不重部署后端；网关失败交管理员按本提案目标重试，不靠重发相同镜像。报告分别列明平台能力、
+声明批准、delivery、HTTP 与客户端验收结果，不要求所有安装此 skill 的门户都已具备能力。
+
 ## 六类来源声明
 
 `embedCsp` 仅扩展本 App 的 `/apps/<key>/` 托管前端策略，不改变门户壳、沙箱或后端公开 HTML 的 CSP。

package/skills/xgent-app-release/references/publish-api.md

@@ -143,11 +143,14 @@ curl -X POST "$XGENT_PORTAL_URL/api/market/release/<key>" \
 **定级唯一判据：这次提交有没有改变权限面。** manifest 里与当前 listing 相比有治理差异
 （scopes / aclManifest / dependencies / exchangeTargets / serviceScopes /
 privilegedServiceScopes / usageMetrics / serviceBaseUrl /
-seat* / scopeLabels / embedUrl / embedCsp / type / 部署形态…，以及**任何门户不认识的字段**）
+seat* / scopeLabels / embedUrl / embedCsp / oauthDiscovery / type / 部署形态…，以及**任何门户不认识的字段**）
 ⇒ 提案 `pending` 等平台审批；只有版本/产物/镜像/展示字段的差异 ⇒ `auto_approved` 自动通过并应用清单/产物。
 其中 `privilegedServiceScopes`（平台特权 scope 的申请，如 `seats.read`）是最高一档：
 审批人要**逐条勾选确认**才能批准 —— 每条都带上说清用途的 `reason`，等待会短很多；
 已持有的特权 scope 幂等重放不再进审。
+`oauthDiscovery` 的新增、修改、撤销按归一后的差异进审；省略保留，null/空对象清空，对象整体替换。
+它只能放在完整 manifest 内，不是第五个 multipart 字段。v2 前置、路径映射与发布后验收见
+[OAuth 标准发现发布](public-delivery.md#oauth-标准发现发布)；批准不等于标准发现地址已可用。
 **提交即拒**（连提案都不落）的只有四类：manifest 携带密钥值（SA secret / descriptor.env）、
 SERVICE_ONLY scope 写进 `serviceScopes`（申请要走 `privilegedServiceScopes`）、形状非法
 （含 `usageMetrics` 的 key 不在你的 listingKey 命名空间、或声明金额单位），
@@ -213,7 +216,7 @@ SERVICE_ONLY scope 写进 `serviceScopes`（申请要走 `privilegedServiceScope
 
 ## 6.1 按本次提案查询交付
 
-新增契约的版本与启用前提见 [公开面与交付确认](public-delivery.md)：这些能力尚待正式发包/上线；
+契约的客户端版本与目标平台启用前提见 [公开面与交付确认](public-delivery.md)；
 目标门户须提供 delivery，扩展 CSP 还须 strict 与受控 v2 网关。不得仅按包版本标签猜能力已开。
 
 ```bash