Prototype Hifi Pipeline（初版原型 → UI → 高保真流水线）

Overview

• 主路径 Path C（默认）：WorkBuddy 直接生成 token 化高保真 HTML（输入 = 初版原型 + UI 图 + token 表，输出 = 严格按 UI 图、绑定 token 的高保真 HTML）。token 由同一机器持有，无跨工具损耗；四维验收闸在 WorkBuddy 内闭环（第1维直接比对「HTML 计算样式 vs token 表」）。
• 可选 Figma 路径：仅下游特别要求 .fig 时启用，P3 双形态喂 Figma（驻留 skill 首选 / 提示词降级），产出后过同一套四维验收闸。
  关键认知：目标是「严格按 UI 图出高保真」，交付形态不重要——Path C 零跨工具损耗为主路径，Figma 仅 .fig 硬需求时启用。

可信原则层（业务-视觉边界铁律）

> 本段把分散在各阶段的「业务 / 视觉 / 格式」边界收敛为唯一可读契约。来源：用户评审外部「原型转换引擎」文档后要求固化——其三级优先级与业务-视觉冲突铁则表述最利落，此处吸收并映射到本 skill 术语（lofi 母版 = 其 mustKeep 清单；UI 图 = 其 UI-Token / UI 图；UI 规范 token 表 = 其结构化设计规范）。机器闸对映射见 references/behavioral-parity-gate.md §四。

铁律 1 · 三级优先级（冲突裁决唯一顺序）：业务内容 > 视觉样式 > 输出格式。任一屏三者冲突时，先保业务对、再保视觉对、最后才是交付形态。

铁律 2 · 业务以 lofi 母版为唯一基线：组件结构、业务字段、交互、弹窗、状态、页面跳转完全以 lofi 母版（及其 _lofi_inventory.json）为准，不随 UI 图改动业务含义。lofi 有而 UI 图无的元素（演示账号提示、返回键、demo 数据）保留 DOM 与行为，用透明 / 贴合底图处理视觉，不得删除（「UI 图上没有」≠「功能上不需要」）。无初版原型时（Path C-S），业务基线改为源站实测交互清单（逐元素实测的 onclick / 路由 / 弹层 / 状态切换）：hifi 交互须一一对应，清单有而 hifi 缺 = FAIL，清单无而 hifi 有 = 停下问用户，禁止凭空新增。

铁律 3 · 视觉以 UI 图 / Token 为唯一基线：颜色、字号、间距、圆角、阴影、字体、组件尺寸只取自 UI 图与 references/ui-token-spec.md 允许集合，禁止在 Token 之外自定义数值（check_token_usage.py 兜底）。无 UI 图时从 UI 规范 token 表 + 设计系统推断，并在交付报告逐屏标注「推断设计」；连规范都无 → 停下问用户。无初版原型但目标产品可访问（Path C-S）时，视觉基线 = 源站分片实测：token 只约束可变量（主题色 / 字号 / 间距 / 状态 / 空态），图表曲线、图标图形、插画等像素级不可复原的元素一律走分片承载，禁止重绘（见 P3「分片复刻模式」）。

铁律 4 · 完整链路可信（自检仅是第一道防线）：生成后必须逐条逐项强制自检（对照 lofi 母版 / UI-Token / 设计规范打勾），但模型自检 ≠ 最终可信；是否真正合格由 P2 入口双闸 + P3.5 / P4 / P4.5 机器闸（退出码即闸门）判定。凡「靠自审觉得没问题」一律不得放行。

铁律 5 · 热区坐标必须像素实测（禁止目测 / 猜百分比）：image-based 原型的 hotspot 坐标只能来自对底图的像素测量（scripts/probe_elements.py），禁止「大概在这个位置」「按 token 推断应该如此」。两个高频翻车点：

• 变高底图禁用百分比热区：同一屏多个状态若底图高度不同（实测 ZEEDA 设备页 6 态切片分别 1074/1132/1402/1508 px），top: 22% 在各状态指向完全不同的 y → 整体错位。正解：用距容器顶部的固定 px 偏移（1px@750 = 0.52px CSS），必要时按 [data-state] 分别取值。
• 元素语义顺序以 lofi 母版为准：像素只能量出「有几块、在哪」，量不出「哪块是 Solar、哪块是 Schedule」。必须回 lofi-src/ 查该屏的渲染顺序再映射，禁止按视觉猜。

铁律 6 · 点击命中必须用真实鼠标事件验证：check_hotspot_overlap.py 只查热区互相重叠 / 越界，查不出「热区没盖住视觉元素」；行为 trace 用 el.click() 绕过空间定位 → 必然假 PASS。P3.5 之后必须跑 scripts/click_verify_cdp.py：CDP 派发真实鼠标事件点击元素几何中心，断言预期 handler 被调用。首屏外的元素要先 scrollIntoView，并回报 elementFromPoint 便于定位遮挡。

铁律 7 · 活 DOM 与切片图混合时必须保留交互语义：当为 1:1 视觉把某区块做成整图切片（或 below-hero 切片）后，不得把对应活 DOM 整组删除或永久 display:none，否则依赖活 DOM 的交互（折叠/展开/拖动/表单）会失效。正确做法：① 用切片承载视觉；② 保留/复用活 DOM 元素承载交互；③ 对折叠态用不透明遮罩盖住切片区（底色与底图实测一致并新增 token），只隐藏活 DOM 的 body 而保留 header。

铁律 8 · 全局遮罩 / 抽屉必须挂在 #app-frame 层级：bottom-sheet、modal、toast 等全局浮层必须直接放在 #app-frame 内作为全局元素，不能嵌套在 .screen 或 .device-screen 等可能因内容变高而撑大的容器里，否则 position:absolute; bottom:0 会随长内容沉到视口之外。统一复用项目已有的 openSheet/closeSheet + #sheet-mask 系统，若没有则新增全局 #sheet-mask。

铁律 11 · 存在性 ≠ 真实性（遗漏检测必须是「早期基线 + 后期门禁」双锚点，覆盖广义交互缺失，两条路径都要跑）：check_functional_consistency.py（函数名存在性）/ click_verify_cdp.py（handler 被调用）/ audit_all_clicks_cdp.py（遮挡+JS 报错）三道闸都查不出「元素/函数在，但实现是一句占位 toast() / 近空函数 / 锚点要求的真实交互根本没落地」。hifi 只要保留同名函数，差集就为空 → exit 0 假 PASS。故遗漏检测升级为双锚点：
- 早期基线（P2，进 P3 前）：scripts/scan_stub_impl.py --baseline（Path C 扫 lofi / Path C-S 扫 --source-manifest 源站交互清单）在 hifi 尚未构建时就产出「必实现真实交互清单」+「母版轻提示豁免清单」，挂到开工计划供 hifi 构建逐条对账——制作初期就能暴露遗漏风险。
- 后期门禁（P4.5，交付前）：默认（hifi vs lofi）或 --source-manifest（Path C-S）跑 scan_stub_impl.py，必须 exit 0 才放行；GAP>0 或 fragment 内联占位热点>0 → exit 1 阻断。
- 检测面扩宽（不止 toast 占位）：遗漏检测是一个家族——scan_stub_impl.py（真实实现缺失：占位 toast / 近空函数 / 锚点标真实却未落地）/ check_functional_consistency.py（交互元素缺失·断链·退化）/ audit_all_clicks_cdp.py（热点遮挡·死 DOM）/ check_hotspot_overlap.py（热区错位）/ scan_bottom_risk.py（长内容底部栏隐患）。家族内任一闸 FAIL 都不放行，禁止只靠其中一道「看起来过」。
- 双路径覆盖：Path C 以 lofi 母版为锚点；Path C-S（无初版）以源站实测交互清单（--source-manifest）为锚点，二者都要跑早期基线 + 后期门禁。
- 实质性判据＝有状态写入（Device.*=）/ DOM 重渲染 / 弹层 / 导航；只弹 toast 或无实质逻辑者视为未落地。
- 用户报「交互没出来」时，先分清「设计如此」还是「真遗漏」——回锚点（lofi / 源站清单）逐函数比对，锚点本身即轻提示的属预期（需说明），锚点要求真实而 hifi 是桩/近空才是遗漏。禁止凭直觉判断。

铁律 12 · image-based 屏热区禁止用 toast() 占位顶替母版交互：image-based 屏常因「底图上找不到对应交互控件」而把热区写成 onclick="toast('Set start time')"。这直接违反铁律 2（业务以 lofi 母版为唯一基线），且会让功能一致性闸假 PASS（函数同名存在）。正确做法：
- lofi 母版有该交互 → 必须接真实函数并实现母版语义（缺 UI 图时按「推断设计」token 化绘制控件，如时间选择抽屉），并在交付报告「推断设计清单」标注；
- lofi 母版本身就是 toast/提示 → 保留 toast，但在报告注明「母版即为轻提示，非遗漏」；
- 禁止以「底图没有」为由把真实交互降级成 toast。

铁律 13 · 动效与 lofi 对等（v1.24.0）：lofi 的动效声明（transition/animation，已由 _lofi_inventory.json.effects 提取）是可感知交互契约——hifi 弹框/抽屉/列表等动效应与 lofi 一致（速度/方向/淡入淡出等可感知特征），lofi 有声 hifi 硬切 = 交互不对等（WARN，交付报告「动效对账」标注）；lofi 无动效时 hifi 可自带动效但须合理克制，不得因自带动效掩盖交互语义。P4.5 以 effects 为人工锚点逐项对账（机器闸不新增，防止无动效 lofi 假 FAIL）。

铁律 14 · image-based 屏 overlay 必须验证 stacking context（v1.24.1）：在 img 底图上叠 position:absolute overlay 时，仅靠 CSS 写了 z-index 不等于浏览器会生效。img 是 replaced element，在部分浏览器中不建立 stacking context，子元素 z-index 相对于文档 root 而非 img → overlay 被压在底图下方。硬约束：① 必须给 img 加 position:relative; z-index:0；② overlay z-index 必须 > 0 且 < 同级可点击元素（避免阻挡热区）。验证方法：修改后必须肉眼确认 overlay 完整盖住底图对应区域，不能只靠「CSS 属性存在」断言 PASS。

铁律 15 · -content.png / -collapsed-content.png 切片必须验证像素完整性（v1.24.1）：切片图生成时（如从完整 below 图裁剪出 content 区）底部可能被过度裁剪（ZEEDA charging 截断 17px / fault 截断 25px），导致 MC 行等视觉元素底部消失。CSS layout 完全正确（contentH ≤ scrollH），但切片图数据缺失 → 静态扫描完全测不出。硬约束：生成 content/collapsed-content 切片后，必须用 PIL 将其底部 20px 与对应完整源图同一区域做像素比对，差异 >0 即截断 → BLOCK。禁止仅靠「布局层正确」断言视觉层正确。

铁律 16 · 活 DOM 覆盖件必须与被覆盖的底图已印元素「同心 ∧ 同形 ∧ 更大」（v1.30.0 立、v1.31.0 补「同形」）：底图已印了某元素（radio 圆环、图标、开关轨道）而上层再放活 DOM 元素去盖它做交互/状态时，「尺寸比它大」不等于「盖得住」，只有「同心 + 同形 + 更大」三者同时成立才盖得住。v1.31.0 补「同形」：ZEEDA 登录勾选框底图是圆角矩形（圆角率 27.1%），DOM 却画成正圆 border-radius:50%——尺寸明明更大，四角仍各漏 1.07 CSS 底图灰边。判形不能靠肉眼：轴向 run-length 剖面无法区分正圆与圆角矩形（两者穿过圆心的那行剖面完全相同），必须看逐行 bbox 宽度剖面或对角/轴向最远半径之比（ZEEDA 该件对角 8.66 vs 轴向 7.28 CSS → 比值 1.19，绝非正圆）。三条硬约束：① 点元素（圆/小图标）用中心定位——left/top 是左上角语义而 PIL 实测值通常是圆心，必须 transform: translate(-50%,-50%)（区域容器左上角语义本就正确，不适用）；② 覆盖件外径 ≥ 底图元素外径，否则漏边形成「两个错位圆圈 / 圈被切一半」，视觉上极易被误读为「右缘被裁」；③ 圆角率必须与底图一致（≤4pp），形状不同则角上照样漏。用户报「被切」而渲染像素对账保真时，先查覆盖件对位（P3.9），不要回头怀疑渲染管线。

铁律 17 · 用户报 visual bug 时禁止仅靠逻辑推断断言「已修复」（v1.24.1）：逻辑推断（contentH ≤ scrollH / z-index 存在 / CSS 属性写对）只能证明布局层正确，不能证明视觉层正确。硬约束：用户报 visual bug 时，修复后必须对比 UI 原图逐像素测量（PIL 读像素或截图 diff），找到真正根因并确认视觉层对齐，才能断言修复完成。禁止未验证就回复「已修复」。

铁律 18 · 阶段闸点回传（打闸点，v1.30.2）：本流水线每个硬闸跑完必须即时向用户回传「退出码 + 一句结论」——coverage_gate / check_ui_mapping / P3.8 / P3.6 / P4.5（功能一致 · 行为轨迹 · scan_stub）逐闸打点；FAIL 先修复重跑至 PASS 再进下一阶段，禁止攒多个闸一次性汇报（攒闸会让「第一个闸就 FAIL」看起来像全过）。回传内容人读、去壳添魂（只改语气不改数据与结论）。

铁律 19 · 原型是给研发的完整功能呈现参考（非代码交付，v1.40.0 重定位）：高保真原型的下游是研发完全参照产物效果来开发——产物是「完整功能呈现参考」，不是代码交付。因此不要求产物里的元素可被翻译成组件结构（语义标签 <button> / carrier 分工 / 「承载方式实施清单」均非硬交付要求）。但产物必须满足完整功能呈现硬指标：① 内容 / 样式 / 交互必须全——视觉 1:1 + 业务字段全 + 交互真实完整；② 唯一硬闸 = 功能呈现完整性（P4.6）：交互必须真的发生且状态变化在界面上可见——「函数是真的、反馈是死的」（点了 toast 一闪但开关态看不见 / 时间值印在底图改完界面不变 / 自造 Tab 点了列表纹丝不动）= FAIL。与铁律 7 关系不变：切片后不许删活 DOM。可选强化：若用户在 P1.5 明确要「照产物能直接生成代码」，再启用铁律 19 旧版结构约束（P3.11 C 判据开 / P4 第 5 维 / P4.5 子维 8 / P5 实施清单）——这是增强项不是默认。细则与定位判定见 P1.5 / P4.6。

铁律 20 · 文本容器生成时默认带横向溢出兜底（v1.42.0）：所有承载可变文本的元素（标题 / 正文 / 值 / 标签 / 列表项 / 按钮文字 / 卡片描述等）在生成阶段就必须内置横向溢出兜底，禁止把"不溢出"寄托于"数据短所以没事"——ZEEDA 设备页反复踩"本地化长文案 / 大数值把布局撑破"。具体规则：① 弹性 / 网格容器内的文本子项必须 min-width:0（否则 flex/grid 子项默认 min-width:auto 不被压缩，overflow 永不触发）；② 默认 overflow-wrap:anywhere（允许任意位置断词，长串英文 / token / 无空格文案不断行撑破布局）；③ 截断策略按上游 element-spec.json 的 elements[].truncation（single / 2line[N] / auto / none，缺省 auto）选对应工具类——single 加 white-space:nowrap; overflow:hidden; text-overflow:ellipsis，2line[N] 加 -webkit-line-clamp:N; display:-webkit-box; -webkit-box-orient:vertical; overflow:hidden，auto 用 ①② 兜底，none 不约束。本律是 P4.7 横向溢出检测闸（C69）的源头预防层：正常生成应让 P4.7 实测 scrollWidth>clientWidth 几乎不触发，P4.7 仅作交付前兜底（仍会自动 --fix 注入 overflow-wrap:anywhere;min-width:0）。

业务-视觉冲突铁则（两种场景）：
- 有 UI 图：业务内容 / 组件结构 / 字段 / 交互 / 弹窗 / 状态 → 完全依 lofi 母版；视觉外观 / 颜色 / 字号 / 间距 / 圆角 → 依 UI 图与 Token。简言之：内容看母版，样子看 UI。即使 UI 图业务结构与 lofi 不一致，业务也必须以 lofi 为准。
- 无 UI 图：业务仍严格依 lofi 母版；视觉严格依 references/ui-token-spec.md 合理设计；lofi 内若标注「参考 XX 样式 / 类似 XX 样式」，必须严格参照该样式。

禁止项（硬约束）：
- ❌ 禁止删减 / 合并 lofi 母版 mustKeep 元素（含子组件、字段、交互、特殊状态）
- ❌ 禁止 UI 图业务结构覆盖 lofi 母版业务内容
- ❌ 禁止有 UI-Token 时脱离 Token 随意配色 / 定字号 / 定间距 / 定圆角
- ❌ 禁止无 UI 图时脱离 ui-token-spec 与 lofi 样式备注自由发挥
- ❌ 禁止只做模糊、笼统式自检，必须逐条逐项遍历核对
- ❌ 禁止认为自检完就代表结果 100% 可信（外部机器闸才是最终关卡）
- ❌ 禁止改变原有业务字段、交互逻辑
- ❌ 禁止整文件重写 fragment（母版铁律，见 P3）

何时使用

• 用户说「做高保真原型」「按UI图出HTML」「喂给 Figma」「验收 Figma 稿」「这个项目 UI 要求高、走 UI 流程」
• product-prd-prototype 产出初版原型后，用户要对 UI 要求高的页面做视觉稿 / 高保真，或 Figma 出稿后需按规范逐项验收

路径总览（先读这个）

分流决策见 P1：下游必须 .fig → 路径 A/B；无初版原型且目标产品可访问 → Path C-S；否则默认 Path C。

核心流程

P0 动手前资产清点闸（进 P1 前必停 · 用户确认，v1.37.0；「确认」= 对话逐条提醒，非签字表，见 P2 收尾 v1.39.0 形式变更）

> 为什么放在最前：本闸要拦的是「图一直在，但从来没被用上」——这类别的闸一道都查不出
> （切片闸只查已引用、热区闸只查已存在、覆盖件闸只查覆盖件、点击审计只查 handler、
> 功能一致性闸只 diff 函数名、桩检测只查占位实现）。实测代价：ZEEDA 11-device-max-current.png
> 在设计目录存在且在尺寸表登记、但 build 零引用 → 抽屉被代码自绘，连续多轮机器闸全绿
> 直到用户肉眼指出。详见 references/preflight-asset-audit.md。

三步走，产出一份报告交用户确认：

1. 源码读取清点：逐文件登记（js / css / html / json）——大小、是否读完、提取了什么、
   未读部分（严禁只读一部分就宣称读完）。机器辅助 scripts/extract_lofi_inventory.py（C32），
   coverage_gate 须 PASS 才可作锚点。
2. 设计资产清点 + 孤儿扫描：
   python scripts/scan_orphan_assets.py --assets-dir <图目录> --build-dir <产物目录> --registry <登记表> --json _orphan_scan.json
   输出「已引用 / 未分诊孤儿 / 白名单已分诊 / 尺寸表登记但零引用（高危·疑似自绘）」四类；
   exit 0=无未分诊 1=有未分诊 2=参数错。孤儿不允许静默放过——要么补引用，
   要么进白名单写明理由（仅三类合法：中间产物 / 冗余备份须实测举证 / 未启用态保留）。
3. 切图 ↔ 屏 对应表：由 _ui_mapping.json（C40）汇总，逐屏标注「有图 / 推断」+ 图文件 +
   尺寸 + 引用位置 + 研发可翻译性（铁律 19：该屏哪些控件是热区模拟、哪些已是活 DOM）。

报告七段式模板见 references/preflight-asset-audit.md。

卡点：报告产出后必须停下等用户确认，不得边出报告边进 P3。用户未确认的缺失项，
后期任何机器闸都查不出来——这正是本闸存在的意义。

P1 分流判断（先判断走不走 UI 链路、走哪条）

拿到初版原型后判断：
- 走 UI 链路：对外门户/官网/海外 Web 等视觉权重高；用户明示「UI 要求高」；品牌一致性硬约束。不走：中后台/内部工具（明确告知跳过理由）。
- 路径选择：下游必须 .fig → 路径 A/B；无初版原型 + 目标产品可访问 → Path C-S 分片复刻；否则默认 Path C。判断结果须向用户复述确认，不擅自启动。

> Path C-S 触发判定（v1.19.0）：同时满足两条才走——① 没有初版原型（上游 product-prd-prototype 的 prototype/ 不存在，或手上只有一份页面解析报告而无可点击 HTML）；② 目标产品可访问（线上站点能用账号登录、或用户提供了 UI 设计稿 / 整屏截图）。
> - 只满足①不满足②（无初版、也无图可采集）→ 停下问用户索取 UI 图或线上访问凭据，禁止退化成按规范重绘后宣称"复刻"（实测 ZDService 2026-08-28：token 全实测但图表类型/图标图形只能 SVG 占位，用户直接指出"不能严格复现"）。
> - 只满足②不满足① → 走常规 Path C，初版母版优先。
>
> 为何要单独成路径：Path C 的切片手法（hero 切片高度决策闸、整页切片坐标重测闸、视觉让位三件套）与 P3 入口双闸（extract_lofi_inventory.py / check_ui_mapping.py）全部以「初版原型母版 + 用户提供的 UI 设计图」为前提。输入换成「线上产品 + 无初版」时两道闸跑不起来，若不另开路径就会退化成按 token 重绘 + 靠猜补图表/图标。Path C-S 用源站实测交互清单替代初版母版做锚点，视觉还原手法与 P4/P5 验收闸完全沿用。

> P1.5 交付定位确认闸（v1.40.0 重定位为「给研发的完整功能呈现参考」 · 进 P2 前必问）：开工前必须向用户确认——
> 「这份高保真原型的下游交付形态是什么？」
>
> 默认定位（不确认即采用）· 完整功能呈现参考：技能产物是给研发的「完整功能呈现参考」——研发完全参照产物效果来开发，产物本身不是代码交付。核心约束：
> - 内容 / 样式 / 交互必须全：视觉 1:1 + 业务字段全 + 交互真实完整（点了有反应、状态可见、跳转/弹层/状态切换都在）。
> - 不要求可翻译成组件结构：元素不必都做成语义标签 <button>、不必强制 carrier 分工、不必附「承载方式实施清单」。切片承载视觉 + 活 DOM 承载交互都可，只要呈现完整。
> - 唯一硬闸 = 功能呈现完整性（P4.6）：交互必须真发生且状态变化界面可见——「函数是真的、反馈是死的」（点了 toast 一闪但开关态看不见 / 时间值印底图改完不变 / 自造 Tab 点了列表不动）= FAIL。这是「完整功能呈现」的核心，与是否给研发无关。
>
> 可选强化定位 · 研发可翻译蓝图（仅用户明确要「照产物直接生成代码」时启用）：在默认基础上额外要求产物结构可被研发直接翻译（语义标签 + carrier 分工 + 实施清单）。启用后开 P3.11 C 判据 / P4 第 5 维 / P4.5 子维 8 / P5 实施清单。这是增强项不是默认。
>
> | | 完整功能呈现参考（默认） | 研发可翻译蓝图（可选强化） |
> |---|---|---|
> | 受众 | 研发参照产物效果开发（非代码交付） | 同上 + 要结构可翻译 |
> | 内容/样式/交互全 | 必须 | 必须 |
> | 交互完整性（状态可见） | 硬闸 P4.6 | 硬闸 P4.6 |
> | 语义标签 <button> | 不必 | 必须（P3.11 C） |
> | carrier 分工 + 实施清单 | 不必 | 必须（P3.11/P4/P4.5/P5） |
> | 图表曲线 | 可留切片 | 建议活 DOM |
>
> 关键认知（v1.40.0）：默认定位下「给研发」与「给人审」仍是同一件事——研发看产物效果、人审核交互逻辑，都要产物完整且交互真实。区别只在「产物要不要顺带可被翻译成代码」（可选强化才需要）。不要把默认定位理解成「交互可以松」——恰恰相反，默认定位的硬指标就是交互完整性（P4.6），视觉闸全绿而交互静默的缺陷（ZEEDA v3 实证 5 处）照样 FAIL。
> （纯客户演示：用户明确说只看视觉、不要交互 → 可豁免 P4.6，但必须在 kickoff-plan 与交付报告显式标注定位，且 lofi 母版有的交互仍应保留。）

P2 组装输入包（四件套，Path C 与 Figma 路径共用）

> 个人知识库前置读取（知识库协同，可选增强）：进入 P2 前，如个人知识库（$HOME/Doubao/chats/2026-09-02/new-chat/knowledge-hub/personal-kb/，Obsidian vault；路径按 KB-SYNC 技能实际配置填写）存在则读取：
> 1. 04-UI设计规范库/ 全部（视觉Token/组件规范/交互范式）——Token 来源优先级最高，高于上游 ui-tokens.json
> 2. 06-个人偏好/产品风格偏好.md + 交付格式偏好.md——对齐用户视觉风格和交付要求
> 3. 02-技能经验/prototype-hifi-pipeline/使用技巧.md + lessons.md 摘要（先辅，快速认知）
> 4. 03-项目档案/{项目名}/03-设计资产/——读取项目历史设计资产和决策
> 5. 09-外部文档切片/ 设计规范类——引用外部设计规范（只读，写入归整理任务）
> 6. 需要细节时读技能自带 references/lessons-learned.md 全文（后主）
> 两层协同：技能自带写全文，知识库写摘要+回链，不重复（完整规则见 @skill:knowledge-hub-sync，KB-SYNC 唯一权威源，本地无副本）。如路径不存在则跳过，不影响 P2 流程。

> 能力确认闸（通用纪律，v1.8.0 由 v1.7.4 读图闸泛化）：进入 P2 提取前先逐项确认本环境/本模型满足全部前置条件，任何一项不满足 → 立即显式告知用户并给出二选一方案，禁止猜测、禁止擅自降级、禁止自由设计：
> - 读图能力：模型能否直接读 UI 图（是否被 content filtered 拦截）。不能 → ① 纯 stdlib PNG 像素测量脚本（probe_*.py 逐点色值走查 + 多状态图交叉印证）；② 用户给文字规范 + 坐标标注（v1.7.2 实战：本会话模型读图被过滤，已靠纯 stdlib 测量兜底）。
> - v1.11.0 补充 · 读图是间歇性能力，禁止一次性判定：实测同一会话内 Read 同一 PNG 会先返回 "Content filtered"、稍后又成功返回图像——读图能力不稳定，既不能靠「上一轮读过」推断本轮还能读，也不能靠「上一轮被拦」推断本轮不能读而擅自降级。纪律：① 每次要做视觉判断前重新实测（真的去 Read 一张图，不凭记忆下结论）；② 本轮实测失败 → 停下来问用户（按上条二选一），禁止用「图上大概是这样」「按 token 推断应该如此」继续推进；③ 一旦成功读到图，须逐屏比对后再写 HTML，不得读完一张就推断其余屏。
> - 依赖可用性：所需脚本/组件/库（agent-browser、jsdom、Pillow、切片脚本等）是否在位且可跑。缺 → 报缺口 + 给「补装 / 换方案」两选项，禁止跳过该步骤硬交付。
> - UI 图语义可判定：UI 图上的元素语义（图标含义/交互归属）能否确定。不能确定（如 navbar 图标与 lofi 函数的映射关系）→ 问用户，禁猜（实战案例：hero 首图标旧项目是 notifications、当前 UI 图实为 4G 信号 → 正确映射 toggleConnectionMode()）。
> - 方法论明确性：本步骤做法是否已有明确定义（本 skill 各节/手册）。无既定做法且影响产出形态 → 先向用户提方案选择，禁止自创默认。
> - 铁律：宁可停下来问，不可猜着做。「模型不满足条件必须提出」是全流程纪律，不限于读图。
> 动手前先确认「唯一权威目录」（v1.15.0 · 血的教训）：本 skill 的产出地是 上游 product-prd-prototype 的 prototype/ 目录（本 skill 不另起目录）。但同一个项目在磁盘上可能存在多个 prototype 副本（历史归档、精简副本、workspaces 下的旧拷贝），改错目录 = 全部白做。开工前必须：
> 1. 先读项目长期记忆（MEMORY.md / 工作区 .workbuddy/memory/）里记录的权威路径；
> 2. 用磁盘事实确认，不凭记忆也不凭会话摘要——判定信号（应同时具备）：prototype/ 下含 lofi/（初版）、fragments/（分片）、ui-source/（UI 图）、_ui_mapping.json、_lofi_inventory.json；若上游 product-prd-prototype 交付了 _manifest.json，以其 product/version 与目录内容交叉印证（上游 manifest 见 assets/prototype-manifest-example/）；
> 3. 发现多个候选 → 停下问用户，禁止"看起来像"就动手。
> 实证：ZEEDA 海外 App（2026-08-30）因记忆里路径少了一级 projects/ 而指向不存在的目录，随后在精简副本里连续改了两轮登录页（各耗一下午），对交付物零影响。根因是"凭记忆的路径"从未被磁盘事实验证过。
>
> P2 硬前置 · UI 图规范化提取（不可跳过）：进入 P3 前必先从 UI 图/规范源完成三件事并经用户确认，否则禁入 P3：
> 1. 提取 token 表：色值/字号/间距/圆角/状态——须来自 UI 图，不得凭空设计；
> 2. 组件约束清单：逐组件绑定 token + 禁改项；
> 3. 屏↔图对照矩阵：全部屏逐一标注——有 UI 图（UI 图最高权威，1:1 复刻，缺图标/背景图立即停下索取）/ 无 UI 图（读规范推断并在交付报告标注「推断设计」）。v1.10.0 起该矩阵不再是文档句子，而是机器产物 _ui_mapping.json + 机器闸，见下「P2 硬前置（三）」。
> 降级声明（强制）：环境无法读图时须显式告知并索规范文字/对照矩阵，不得静默跳过提取直接自由设计。
> 全流程硬规则 · 不确定就问：P2/P3/P4/P4.5 全程凡 UI 图/规范/lofi 都无法确定的元素，停下问用户，禁止自由发挥。
> 怎么问（v1.46.0 · 分两类）：澄清型提问一次一问（不拿问题清单轰炸；停手信号＝能一句话复述四要素且用户确认，或能说出用户没想到的盲点）；追问 3 轮不收敛 → 直接启动 P3 首屏对齐闸做最小初稿让用户对着实物改；确认型清单不适用本纪律（P0 报告 / kickoff-plan / 首屏三件事仍逐条列全）。细则见 references/ask-discipline.md。
>
> 无 UI 图处理规则（v1.9.3 · 回答「无对应 UI 图时怎么办」）：「无 UI 图 ≠ 无约束」，视觉与交互必须分开处理——
> - 视觉：无 UI 图时，从 UI 规范 token 表 + 设计系统推断（色值/字号/间距/圆角全部绑定 token，不得凭空设计），并在交付报告逐屏标注「推断设计」；若连规范/设计系统都无 → 停下问用户，禁止自由发挥（见上条硬规则）。
> - 交互（最高约束）：无论有无 UI 图，行为模型一律以 lofi 初版原型的 _lofi_inventory.json 为唯一契约——导航目标/toast/modal/sheet/状态切换/输入逐项 1:1 复用，禁止在无 lofi 对应的情况下凭空新增跳转或改绑目标。hifi 每保留/新增一个热点，必须能在 lofi 清单里找到对应交互；找不到的一律停下问用户。
> - 反例（实战 2026-08-28 ZEEDA）：solar-config / lb 两屏的 goto('app-rs485') 热点，是从 more-settings 复制 fragment 时的残留，业务上太阳能配置页/负载均衡页不该跳 RS485 串口页，且 lofi 这两屏本无任何 rs485 交互——即「无 UI 图就自由发挥 + 不锚定 lofi」的典型代价。无 UI 图时交互必须回溯 lofi 清单，不能照抄别的屏。

> P2 硬前置（二）· 初版原型深度预解析（lofi 为可点击 HTML 时必做）：进入 P3 前跑 extract_lofi_inventory.py 产 _lofi_inventory.json（全屏/交互/导航图/浮层清单），双轨用途——P3 做时对照认领交互出「任务方案 vs lofi 清单」对比表；P4.5 子维6 与双原型比对以之为锚点。细则见 references/behavioral-parity-gate.md §一。非可点击 HTML 跳过并标注。
> 提取维度（v1.24.0 专业补全 · v1.26.0 加 id_map）：除页面/交互/导航/浮层外，还提取——字段约束（maxlength/required/disabled/readonly/min/max/step/pattern → fields[].constraints）、默认态（checked/selected → fields[].defaults）、选项集（select option / radio 组 → option_sets）、动效声明（CSS 与 inline 的 transition/animation → effects）、定时器（setTimeout/setInterval → timers）、滚动类（scroll 事件，触底加载归 state）、全量 id 元素索引（id_map：所有带 id 元素含非表单，供约束对等/id 对等锚点，v1.26.0）。全部「存在则提取」，不新增 coverage FAIL 语义。

> P2 补充·上游 screens.json 结构 + Token 补充契约（v1.23.1）：除 _lofi_inventory.json 行为基线外，若上游 screens.json 已含 v1.9.73+ 结构化 components[]（mustKeep/businessDesc/tokenRef），hifi 将其作为结构与 Token 补充契约消费——tokenRef.role 直接映射到 ui-tokens.json 的 token 类别，减少高保真重新猜样式；可用 scripts/crosscheck_screens_contract.py 预检 screens.json 是否 hifi-ready（默认 WARN 不阻断）。行为仍以 lofi 为准，screens.json 只补结构/Token 视图，不替代 lofi 行为基线。另：若上游 prototype/ui-tokens.json（product v1.9.76 共享契约）存在，按 input-package.md §1 最高优先级直接采用，不重抽。
>
> P2 补充·上游 element-spec.json 元素规格契约（v1.25.0 声明 · v1.29.0 加预检）：若上游 prototype/element-spec.json（product-prd-prototype v1.9.78+ 逐屏元素规格交付表）存在，先跑 python scripts/crosscheck_element_spec.py --spec <上游>/prototype/element-spec.json（默认 WARN 不阻断、--strict exit 1、--selftest 自检），再按 input-package.md §0 读取消费——geometry 作元素几何参考基线（热区坐标仍须自身像素实测，铁律 5 不豁免）、animation 是动效语义化规格（与 lofi effects 同源互认，以其为主导）、modals[].type 与 lofi overlays 分类有映射表、modals[].fields 与 lofi 字段维度交叉印证。行为仍以 lofi 为准，element-spec 只补规格视图，不替代行为基线。
>
> P2 补充·上游承载方式（carrier）跨技能契约（v1.38.0 新增 · 铁律 19）：crosscheck_element_spec.py 现同时校验上游的 screens[].carrier / screens[].carrier_reason / elements[].carrier（值域 slice|live-dom|hybrid；屏级还须 carrier_reason ≥8 字）。上游未产出该字段时 SKIP（exit 0，不阻断）——它是可选增强字段。
> 若上游给了 carrier，hifi 直接采用、不再自行决策；上游没给，由 hifi 在 _ui_mapping.json 逐屏声明并在 kickoff-plan §5 交用户确认（对话逐条提醒，非签字）。
> 给上游的补丁提案（含字段定义/值域/判据/兼容性/落地步骤）见 references/carrier-contract-proposal.md——上游采纳后，「PRD 组件 → 最终实现结构」这条链路才有机读可追溯性；不采纳则决策点后移，hifi 侧仍闭环但需用户确认兜底（对话逐条提醒，非签字表）。
>
> SPA 铁律（v1.9.0）：lofi 常见两种架构——① 多 fragment（NN-name.html 各屏独立）；② SPA（index.html 是空壳容器，屏与交互全写在 app.js 的模板字符串里）。解析器必须两种都扫（.html 与 .js 同等对待），否则 SPA 项目 inventory 恒为 0，P4.5 在残缺基线上校验。判据：跑完看 coverage.by_file——若交互只来自 index.html 或为 0，而 .js 体积明显偏大（如数百 KB），即 SPA 漏扫，须修解析器而非判「lofi 无交互」。
>
> 交互分类完整性（v1.9.0 · v1.24.0 补滚动/定时器）：type 现为 nav / back / modal / sheet / toast / state / input / handler / unknown 九类。除跳转与浮层外，状态切换（switchTab/toggle/set/pick/confirm/step）与表单输入（oninput/onchange/onsubmit）同样是有锚点的交互，hifi 漏做即属不对等；handler 表示「有事件绑定但语义待人工确认」，须人工过一遍而非当噪声丢弃。v1.24.0 补充：scroll 事件入册（触底加载/滚动定位，回调含 load/next/more 归 state 否则 handler）；setTimeout/setInterval 驱动行为入 timers（倒计时/轮询/自动跳转，P4.5 对账时作人工锚点）。
>
> P2 硬前置（二）· 初版预解析有效性闸（v1.8.4）：_lofi_inventory.json 必须非空且可用：屏清单 > 0、interaction_count > 0、导航图非空。若出现 interactions: []、interaction_count: 0 或空 nav_graph，立即停止并报告「初版预解析为空，未捕获到可点击交互」——禁止当作「lofi 无交互」而在 P4.5 中静默假 PASS。修复路径：检查 extract_lofi_inventory.py 是否正确读取了 prototype/lofi/ 目录、lofi 的 onclick 是否写在可识别元素上、或请用户提供手工标注的交互清单。空 inventory 时 P4.5 子维1 结论只能标 FAIL/未验证，不得以「0 差异」放行。
>
> P2 硬前置（二）· 解析完全性机器闸（v1.10.0 · 缺口 A 根治）：extract_lofi_inventory.py 自身退出码强制，取代原「看一眼 coverage」的人工约定。exit 1 四情形 = screens=0 / interaction_count=0 / nav_graph 空 / coverage.uncovered 非空（扫到却零交互，差集 scanned_files − by_file.keys() − --exempt）/ read_failed 非空。豁免必须显式 --exempt 且写入 coverage.exempt 留痕（禁止改脚本绕过）；files_zero_interaction 恒保留区分位。产物字段见 coverage.{scanned_files,read_failed,files_zero_interaction,exempt,uncovered,gate}。铁律：coverage_gate=FAIL 时禁止进 P3、禁跑 P4.5（细节与判据见 behavioral-parity-gate.md §一「覆盖率自检」）。
>
> P2 硬前置（二）· 解析完整性机器闸（v1.11.0 · 缺口 C 根治 · 非空 ≠ 完整）：v1.10.0 的闸全是「非空」判据（screens=0 / interaction_count=0 / nav_graph 空 / uncovered 非空 / read_failed 非空），没有一条验「完整」——18 屏与 53 屏同样判 PASS。实测 ZEEDA：lofi 声明 50 个 function getXxxPage() 页面函数，旧解析器只认 PAGES=[…] 注册表（该项目根本不存在），screens 只剩 navigateTo() 字面量目标 → 只捕获 18/53（34%）；表单字段则完全不抽取（19 个 <input id=…> 一个都没进清单）。后果：P4.5 报的 id:authcode / id:bindcfgname / id:lbblecurpwd 一长串「hifi 缺失」实为 lofi 锚点自身残缺，而下游在残缺基线上得出「交付范围内 0 回归」的假结论。v1.11.0 修复：① 新增 PAGE_FN_RE/PAGE_FN_ARROW_RE 探测页面函数（驼峰→kebab，写 screens + 新增 page_fns）；② 新增 FORM_TAG_RE/FORM_ATTR_RE 抽 input/select/textarea 的 id/type/name/placeholder（新增 fields）；③ coverage 新增 page_fn_count/screen_count/field_count 三对账位；④ 新增完整性 FAIL 判据——page_fn 声明了却未全部进入 screens → FAIL 并逐项列出漏项。铁律：拿到 inventory 先看 page_fn_count vs screen_count、field_count 两个对账位；二者不等，或 field_count=0 而原型明显有表单 → 判解析不完全，禁止进 P3、禁跑 P4.5。
>
> P2 硬前置（三）· 屏↔UI 图依据机器闸（v1.10.0 · 缺口 B 根治）：屏↔图对照矩阵由文档句子升级为机器产物。流程：① --emit-template 由 _lofi_inventory.json 生成/合并 _ui_mapping.json 骨架（重跑保留已填字段）；② 逐屏填 ui_source（有图 1:1 复刻）或 inferred:true+inferred_reason(≥8字)+inferred_basis∈{token-table,sibling-screen,spec-text}；
③ （v1.38.0 新增）逐屏填 carrier∈{slice,live-dom,hybrid} + carrier_reason(≥8字)；
④ check_ui_mapping.py --ui-dir … [--delivery-report …] 校验。
> 核心拦截 F3 = 既无 ui_source 又未声明 inferred（靠猜）；另 F1 矩阵空/重复屏、F2 漏屏、F4 图文件不存在、F5 推断屏未进交付报告「推断设计清单」、F6 承载方式缺失/非法/无据（v1.38.0 硬闸）；W1/W2/W3 三 WARN。脚本先读 inventory.coverage.gate，缺口 A 未过则拒跑。铁律：exit≠0 禁止进 P3 写 HTML（细则见 behavioral-parity-gate.md §三）。
>
> F6 为何是硬闸（铁律 19）：F3 只回答「照哪张图做」，F6 回答「这个屏的可交互元素是活 DOM 还是沉在底图」——后者才决定研发能不能照着生成代码。矩阵里不写 carrier，等于把结构决策推迟到 P3 交给临场发挥。判据只有一条：研发拿到原型后，这个元素需要被写成组件 / 绑定事件 / 有状态吗？ 是 → live-dom；否、且像素级不可复原（背景纹理/渐变底/插画/图表曲线/图标图形）→ slice。默认 exit 1 硬闸；存量项目（矩阵已成型、无 carrier 字段）可加 --allow-missing-carrier 逃生，但必须在报告 WARN 留痕，且 carrier 非法值 / carrier_reason 过短仍一律 FAIL 不放过*（逃生阀只放「没写」，不放「写错」）。

> P2 硬前置（四）· 上游 schema-drift 溯源提示（v1.14.1 · 承接 product-prd-prototype v1.9.74）：若上游 screens.json 由 Mode B 摄入外部/遗留资产并经 bootstrap-legacy.py --scan-drift 字段基线化，会带 schemaDrift / origin:"external" / schemaUpgraded:true / upgradedFrom:"flat-string" 标记（详见 product-prd-prototype references/changelog.md v1.9.74）。进 P3 前跑 python scripts/check_upstream_drift.py --prototype-dir <上游 prototype/>，脚本会列出须对照真实 UI 图 / PRD §4.2 复核的屏与组件（其 businessDesc 是基线化推断所得，置信度低于原生 PRD 产出）。纪律：这些屏/组件的 hifi 制作禁止直接信任推断语义，必须回真实 UI 图与 PRD §4.2 复核字段名/枚举/必填/交互，缺失或不一致项停下问用户；默认 WARN 不阻断（exit 0，对齐 deliver.py schema-drift WARN），可加 --strict 升为 exit 1 硬卡；上游 screens.json 无相关标记时脚本直接 exit 0，本条步骤可跳过，不影响既有流程。落地动作见 references/input-package.md §7。

> P2 硬前置（五）· 初版遗漏预扫描（early omission baseline，双锚点·v1.23.0）：进入 P3 写 HTML 前，先对初版/源站跑 scripts/scan_stub_impl.py --baseline（Path C 扫 lofi/app.js；Path C-S 扫 --source-manifest <源站交互清单.json>），产出两份清单并挂到开工计划（kickoff-plan）供 hifi 构建逐条对账：
> 1. 必实现真实交互清单：锚点中标注为真实实现的交互（含 Device.*= / innerHTML= / navigateTo / showModal / getLockState() 等信号）——hifi 必须真实落地，禁止降级为 toast 或近空函数；
> 2. 母版轻提示豁免清单：锚点自身即桩/轻提示的交互——hifi 同处理不判 GAP（须向用户说明「母版即为轻提示，非遗漏」）。
> 为何早期扫：hifi 尚未构建时就能知道「哪些交互是遗漏高风险」，把排查从「交付后用户肉眼发现」前移到「制作初期」。本步骤为强制必跑（生成报告，exit 0），与 P2 硬前置（二）初版预解析互补（后者查「锚点完整」，本步查「锚点里哪些交互绝不能变桩」）。早期扫描只出报告、不阻断；真正的阻断在 P4.5 后期门禁。

按 references/input-package.md 产出，四件必含：
1. UI 规范 token 表：从 references/ui-tokens-template.md 复制并填充/裁剪；
2. 页面清单 + 每页状态矩阵：默认态/加载/空态/异常/禁用，逐页勾选（AI 最容易漏的）；
3. 组件约束清单：点名组件名 + token + 禁改项（如「主按钮 hover 只允许 #2447C9」）；
4. 信息来源：初版原型路径（product-prd-prototype 的 prototype/ 优先）+ UI 设计稿引用。

输出落位（关键约定）：高保真产物写回 product-prd-prototype 的同一 prototype/ 根目录（初版→高保真单文件夹闭环）；组装输入包前，先将初版原型整目录移入 prototype/lofi/ 保留（可追溯、不与上游重跑冲突）。不另起目录。

P2 收尾 · 开工计划确认闸（进 P3 前必停 · kickoff-plan.md）

> 为什么单独成闸：P2 已产出 token 表 / 状态矩阵 / 组件约束清单 / _ui_mapping.json 屏↔图矩阵，但这些是分散的多份产物，没有一份「合并件」让你一次性对账确认。你明确要求「开工前出一份计划：页面对应关系 + 跳转 + 哪些是我自己设计的 + 参看哪个页面/哪份规范，确认完再动手」。本闸把上述产物合并成一份 kickoff-plan.md，在 P3 写第一行 HTML 之前暂停等你确认。

> v1.39.0 形式变更 · 确认 ≠ 签字（用户原话：「签字是什么意思，只要提醒我确认就行了」）：
> 不要搞签字表格仪式（确认人/日期/结论那种填空表用户不买账，也不知道为什么要在文件里签名）。
> 正确做法是：在对话里把待确认事项逐条列出来提醒用户，用户回复「同意」或逐条修改即可。
> kickoff-plan.md 的 §6 相应写成「待确认项清单」（每条带「已确认 / 待确认」状态），而不是签字表。
> 闸的实质是「未得到用户确认不得开工」，形式是提醒、不是签字——换形式不换实质。

步骤：
1. 跑合并脚本（机器辅助，减少自由发挥）：
bash python scripts/emit_kickoff_plan.py --inventory _lofi_inventory.json --mapping _ui_mapping.json --out kickoff-plan.md
自动合并出六节——§1 页面对应矩阵（每屏：有 UI 图 1:1 / 自设计·推断 + 视觉依据）；§2 跳转锚定说明（取自 lofi nav_graph，标「全部继承 lofi，无自设计跳转」）；§3 自设计清单（所有 inferred 屏）；§4 待确认遗漏项（既无 ui_source 又未声明 inferred 的屏，或 lofi 无的 W1 新增屏——疑似设计遗漏，须你拍板）；§5 承载方式决策表（v1.39.0 · 每屏 carrier = slice / live-dom / hybrid + 理由，并列出该屏「可交互元素中哪些是热区模拟、哪些已是活 DOM」）；§6 开工前确认清单（逐条待确认项 + 状态，不是签字表，见上方 v1.39.0 形式变更）。
2. 暂停，把 kickoff-plan.md 交你确认，重点看五件事：① 页面对应是否齐全（有无漏屏）；② 跳转是否全部锚定 lofi（有无我擅自新增的跳转）；③ 哪些屏是自设计的、参看的是哪个相似屏/哪份规范（你认可吗）；④ 待确认遗漏项（lofi 无 + UI 图无 的疑似遗漏）你想怎么处理（补/不补/记差异）；⑤ 承载方式决策表：逐屏确认「哪些控件用切片、哪些用活 DOM」——研发蓝图定位下，凡是可交互控件被标成 slice/热区模拟的，都要逐条过一遍。
3. 你在对话里明确确认通过后才进 P3；任一处要改 → 回 _ui_mapping.json / 输入包改完重跑本脚本，重新确认。禁止未确认即批量铺开（与「首屏对齐确认闸」互补：本闸卡「开工范围对不对」，首屏闸卡「单屏方向对不对」）。
提醒方式：把待确认项逐条贴在对话里等回复，不要只在文件里写好就当确认过了；用户回「同意/按你的判断来」即视为通过，回某条要改就改完重跑再确认。

> 纪律：本闸是人工确认闸（非机器退出码闸），与 P3 入口双机器闸（coverage_gate / check_ui_mapping）互补——机器闸卡「锚点可不可信、靠不靠猜」，本闸卡「范围与自设计决策你认不认」。两者任一未过都禁止进 P3。

P3 出高保真（Path C 为主 / Figma 可选）

> P3 入口双闸（v1.10.0 · 写第一行 HTML 之前必须两个 EXIT=0）：
> bash > python scripts/extract_lofi_inventory.py --dir prototype/lofi --out _lofi_inventory.json [--exempt "…"] # 闸1 解析完全性 > python scripts/check_ui_mapping.py --inventory _lofi_inventory.json --mapping _ui_mapping.json --ui-dir <UI图目录> # 闸2 视觉依据 >
> 任一 exit≠0 → 停止，禁止开工。地基 FAIL 时 P3.5/P4/P4.5 四道验收闸全部退化为假 PASS。

> lofi 母版铁律（v1.13.0 · 最高优先级，先于任何视觉改动）：低保真原型是高保真的基础母版——高保真 = 「lofi 的 DOM 结构与交互」+「UI 切图与样式」的合并，不是照着 UI 图重画一张。执行顺序与硬约束：
> 1. 禁止整文件重写 fragment。改某一屏只能在 lofi 对应 getXxxPage() 的 DOM 之上增删改，禁止 Write 覆盖式重写 fragments/<screen>.html。整文件重写是「掉交互、掉样式」的头号根因（实测 ZEEDA 2026-08-30：login 屏被整文件重写 4 版，每版都丢一批 lofi 事件与字段，用户被迫反复返工；check_functional_consistency.py 实测 24 个 lofi 元素在 hifi 缺失）。
> 2. 母版落地三步：① 先把 lofi 该屏模板字符串逐节点搬进 fragment（保留全部 id、onclick/oninput/onchange、文案调用、条件分支），此时视觉粗糙但功能 100% 对等；② 再叠加 UI 切图与样式（hero 底图、token 化覆盖层、组件样式）；③ 视觉与 lofi 结构冲突时只改样式不改结构——需要弱化某个 lofi 节点就用 CSS（opacity/color:transparent/定位），禁止从 DOM 里删掉它（删了 P4.5 子维1 必判功能丢失）。
> 3. 字段与事件一个都不能少：_lofi_inventory.json.fields 里每个 id、每个事件属性，hifi 必须一一对应保留。lofi 有而 UI 图没有的元素（如登录页 demo 账号提示行），保留 DOM 与行为，用透明/贴合底图处理视觉，不得删除——「UI 图上没有」不等于「功能上不需要」。
> 4. 顺序铁律：先功能一致，再对视觉。每屏做完先跑 check_functional_consistency.py 确认「lofi 有 → hifi 无」清零，再做 UI 图 1:1 比对与 P4 四维验收。功能未清零的屏不得进入视觉验收，否则「看着像对了却点不动」会反复返工。
> 5. 与既有铁律的关系：本条是母版总纲，高于「hero 切片高度决策闸」「底图已印覆盖层铁律」「一图一态铁律」等具体手法——那些只回答「视觉怎么还原」，本条回答「结构从哪来」。冲突时以本条为准：先保 lofi 结构完整，再谈视觉还原手法。
> 6. 重写准入门槛（v1.13.0）：lofi 已有的元素/交互，一律沿用，禁止重写；只有当 lofi 本身「没有」或「残缺」时，才允许重写。落地判据：
> - ① 动手前先问"lofi 有没有"——查 lofi/<页面函数>（含其调用的一级 helper）。lofi 有 → 搬，不是重写；lofi 无 → 才允许新写。
> - ② 允许重写的三种情形，且必须在产物注释与交付报告中标注「lofi 缺失·重写」：(a) lofi 无对应页面函数/元素；(b) lofi 有但内容残缺（如只有占位、条件分支未实现）；(c) UI 图驱动的状态切换器/overlay 等 lofi 结构性不具备的能力（如 setScreenBg、showOverlay/hideOverlay）。
> - ③ 不属于重写、无需标注的两类：(a) 等价替换改名（lofi navigateTo→hifi goto、lofi showToastT→hifi toast）；(b) 骨架容器 id（为承载 lofi 数据回写而新增的纯容器，如 bindRegionValue）。
> - ④ 双向对账硬要求：交付前必须同时跑正向（lofi→hifi 缺失）与反向（hifi→lofi 超出）。正向必须清零；反向必须逐条登记并给出归类（沿用/等价替换/骨架容器/lofi 缺失·重写/越界重写）。出现"越界重写"（lofi 有完整母版却被另起炉灶改了 DOM 体系）必须停下来问用户，不得默认放行。
> - ⑤ 反向对账可用 scripts/… 或项目内 parity_screen.py --reverse；注意排除三类噪声：app- 前缀 section id、app.js 全局运行时函数、lofi 以字符串参数传给 helper 的 id（如 getAuthPwdField('authPwd', …)）。

• Path C（主，默认）：用输入包 + UI 图生成 token 化高保真 HTML/CSS。
• 严格按 UI 图还原视觉（布局/层级/间距/状态），色值/字号/间距/圆角全部绑定 token（CSS 变量，不写死）；
• 每页按状态矩阵产出必备状态，禁止只出主界面；
• 输出可点击 HTML 原型（可直接进开发）；
• 承载方式三选一（v1.38.0 · 铁律 19 上提到主路径，此前只写在 Path C-S 分支里）：每个屏、每个区块进 P3 前必须定好并登记进 _ui_mapping.json 的 carrier，不能边做边定。三种：
  | 承载方式 | 适用 | 研发拿到什么 |
  |---|---|---|
  | slice 切片 | 像素级不可复原的视觉：背景纹理 / 渐变底 / 插画 / 图表曲线 / 图标图形 / 带底纹的卡片头 | 一张图 |
  | live-dom 活 DOM | 可变量：随状态/数据变化的数值、输入项、按钮、列表、空态、多语言文案、hover/禁用态、动效 | 可直接翻译的组件 |
  | hybrid 混合 | 切片打底承载静态装饰 + 活组件覆盖其上承载数据与交互 | 图 + 组件分层 |
  唯一判据：研发拿到原型后，这个元素需要被写成组件 / 绑定事件 / 有状态吗？ 是 → live-dom；否、且像素级不可复原 → slice。
  禁止用 token 重绘去「还原」图表曲线、图标图形、插画（实测 ZDService 2026-08-28：token 全实测，但 7 个 ECharts canvas 的系列类型、菜单图标图形只能 SVG 占位，用户判定「不能严格复现」）。
  反模式（铁律 19 明令禁止）：把可交互控件印进整屏底图，再用透明热区 + 覆盖件模拟——演示型定位下能过所有视觉闸，但研发照此生成的是「整图 + 透明热区 div」的不可维护代码，直接与「和最终实施一样」背离。
  内容必须真实：禁占位文字 / 凑数数字（"Lorem ipsum"、1234、TODO）——研发照着填字段与文案，原型的假数据会变成产品的假数据。
• 混合模式（lofi 基座 + hero 切图，v1.7.2；v1.8.0 固化为八步手册）：接力 lofi 原型时保留其业务函数做骨架，切 UI 图静态区（hero）做视觉资产，交互元素代码绘制；UI 截图是 design source of truth，lofi parity 仅约束跳转目标等不可见行为，视觉冲突时视觉优先。完整实施按 references/hybrid-mode-guide.md 八步清单执行（lofi-src 提取 → 资产盘点复用 → 图片名映射 → token 替换 → hero 切片 → fragment 迁移 → 图标 parity 逐屏核对（旧项目语义不能照搬）→ rebuild + 验证最小集）；已验证做法直接套用 references/success-patterns.md 范式。
• sticky tabbar 铁律（v1.7.2）：代码屏含可滚动内容（scrollHeight>clientHeight）时，tabbar/底部栏必须 position:sticky; bottom:0（作用域选择器）——absolute+bottom:0 会随内容滚动并永久遮挡末尾内容，padding-bottom 救不回；仅不可滚动屏可用 absolute。
• 长内容屏底部固定栏铁律（v1.19.0 · 长内容/长图下 absolute 的「中部伪影」）：长内容屏（渲染高 > 视口 844）的底部固定栏一律用「flex 列 + 内部滚动」，禁止 position:absolute; bottom:0——
  • 正确模式（与已验证的 Device 页一致）：.screen { display:flex; flex-direction:column; overflow:hidden } + 内容区 .xxx-scroll { flex:1 1 auto; min-height:0; overflow-y:auto } + tabbar 作为 flex 兄弟节点 flex:0 0 auto; height:67px; position:relative。
  • 为何：.screen 本身是 position:absolute; inset:0; overflow-y:auto 的滚动容器，absolute; bottom:0 的子元素在滚动坐标系里钉在 844px 处——视口截屏看是对的，但全页渲染/长图截屏/滚动合成下会浮在页面中部，且滚动后随内容滚走。视口内正确 ≠ 长图下正确。
  • 豁免三类（勿误报）：① tabbar 内部热区（父级已 position:relative，absolute 是相对 tabbar 而非 screen）；② position:fixed 的 frame 级浮层（有 transform 的 frame 内 fixed 解析到 frame 边缘，天然钉底）；③ 无任何 fragment 使用的死 CSS 类。
  • 验证必须按「屏 × 状态」展开：变高多状态底图的默认态可能不超视口，而 charging/realtime 等态超出——只测默认态会漏掉真正的风险态。先跑 scan_bottom_risk.py（静态）再跑 verify_bottom_pin_cdp.py（运行时），静态只能证「没有这种写法」，运行时才证「滚到底后还在底」。
• hero 切片高度决策闸（v1.8.3）：混合模式不是只能切 y=0..550 hero 区。决策规则——读取 UI 图下半部：若下半部是纯文本行/参数列表（可用 token 化组件等价还原）→ 切 hero + 代码绘制下部；若下半部是独立视觉卡片（能量流图/汽车插画/彩色横幅/带图列表行/状态差异图）→ 必须将切片扩展为整页底图（裁掉底部 tabbar 后直铺），每状态一张完整图，禁止用 token 文本行替代视觉卡片。扩展后 P3.5 热点审计必须重新跑，确保新增下部热点不重叠、不越界、>=24x24。
• 整页切片后热点坐标重测闸（v1.8.4）：当 hero 从 y=0..550 扩展到整页底图后，原有 hotspot 坐标（基于 hero 区高度 550px）全部失效，必须按新底图高度（通常为 1624–2058px 源图）重新像素测量并换算到 390×844 原型帧。禁止直接沿用旧 hero 区百分比/绝对坐标。重测后 P3.5 审计通过方可进入 P4。
• 图片盒百分比坐标铁律（v1.9.1 · 整页切片的强制结构）：整页切片后各状态底图渲染高互不相等且不等于帧高 844（实测 ZEEDA：standby/fault/standby74=766、clean=797、charging=937、realtime=992）。因此 image-based 屏必须采用如下结构，禁止用 position:absolute 底图 + inset:0 热点层（该写法把热点锁在 844 帧坐标系，图高一旦 ≠844 就整体错位）：
  html <div class="hero-wrap"> <!-- position:relative; 高度由图片自然撑开 --> <img class="hero" src="…"> <!-- display:block; width:390px; height:auto --> <div class="hero-hotspots"> <!-- position:absolute; top/left:0; width/height:100% --> <button class="hotspot" style="left:4.10%;top:78.76%;width:91.79%;height:7.90%;" …> </div> </div> <nav class="tabbar">…</nav> <!-- 必须在 hero-wrap 之外、screen 之内 -->
  换算：left/width 以 390 为基准，top/height 以该屏底图渲染高（= 源图高 × 390/源图宽）为基准。这样任意图高、任意滚动位置热点都锁定在图片上，零错位。
• tabbar 必须在滚动容器内且位于图片盒之外（v1.9.1）：fixed 不占文档流 → 图片底部内容被永久遮挡且滚不到（实测 charging 页底部 78px 不可达）；sticky 占文档流并吸附滚动容器底部，内容可完整滚到底。tabbar 若被放进 .hero-wrap 内部，百分比热点层会与它错位。
• 底图已印文字/按钮覆盖层铁律（v1.9.2–1.9.3）：当 UI 图底图上已经印有按钮/文字（如登录页的蓝色 "Log In" 胶囊），需要覆盖或随场景切换文案时，禁止用透明/半透明装饰层叠在原图文字上——几何稍有偏差就会露出底字，形成明显重影。必须：① 覆盖层本身是不透明的 token 化组件（使用 background 或 token 化底色，例如 --color-primary: #1677FF 与 --color-primary-deep: #084AFF 的水平渐变，完全匹配底图实测色）；② 覆盖层几何必须 ≥ 底图实测包围盒并外扩 2~4px（用 probe_login_btn.py 类像素探测测到亚像素：实测 art3.png 主按钮源图 x84..665、y1242..1339 → 390 帧坐标 43.7/645.8/302.6×51；最终覆盖层用 40/642/310×57 + 圆角 11px，每边外扩 2.3~3.7px）——亚像素抗锯齿下「严格等于」会在覆盖层外侧漏出底图圆角/底部蓝边，必须外扩包住；③ 渐变须多 stop 精确匹配底图非线性色阶（probe_login_btn2.py 多点取色确认底图渐变非线性，中部 #1269FF；线性插值中段偏深肉眼可见色差）：linear-gradient(90deg,#1677FF 0% 12%,#1575FF 35%,#1269FF 50%,#0E5DFF 65%,#084BFF 87%,#084AFF 100%)；④ 文案放在交互元素本体内部渲染（如 <button class="hotspot hs-login-submit">…<span id="authSubmitLabel">Log In</span></button>），禁止再用 pointer-events:none 的 sibling 装饰层跨元素叠字；⑤ 外环像素验证：正常缩放截图 + getBoundingClientRect×devicePixelRatio 定位，断言覆盖层外环左/右/上蓝像素=0（下外环仅覆盖层自身圆角抗锯齿属正常），杜绝 agent-browser 1:1 截图不保留 transform 状态而误判露边；⑥ 校验：smoke_test.js 断言无独立 .auth-submit-label、文案在按钮内、覆盖层每边包住底图且外扩 ≤5px、背景为 gradient 且无 transparent。
• 首屏对齐确认闸（v1.7.3 新增）：批量产出前先产 1 个代表性屏（含 hero + 1 个典型组件 + ≥1 个状态）按 token 全量还原，交用户确认「视觉方向 / 组件还原度 / 整体保真度」三件事；用户明确确认通过后才按同标准批量复制其余屏。用户要求调整时先修该屏并重新确认，禁止未确认即全量铺开——避免全屏做完才发现整体风格/还原度有偏差，返工成本极高。
• 一图一态铁律（v1.11.1 新增）：image-based 屏的每个可视状态必须有对应 UI 图；禁止把有图状态（如 login）的底图当作无图状态（如 register、验证码、密码设置）的通用背景，然后在上面靠猜坐标叠热点/输入框。无 UI 图的状态必须拆为独立 token-inferred 屏（白底/规范背景 + 代码绘制组件），在交付报告的「推断设计清单」与屏上明确标注「推断设计 · 无 UI 图参考」。违反 = 坐标错位、视觉异常、用户质疑，P3.5/P4 均不得通过。
• 底图已印元素的「视觉让位」铁律（v1.15.0）：上一条解决「底图上印了个按钮，我要改它」；本条解决更常见的「底图上已经印好了一整片内容（卡片/tabbar/列表），代码层却又画了一遍」。症状：像素差异呈成片文字行均匀分布、且自绘 DOM 的条目数与底图文本行数一致。正解三件套：
  ① 切片承载——把 UI 图静态视觉区切片直铺（可 hero 区 + 下部区各一张，或整页一张），视觉完全来自设计稿；
  ② 隐藏自绘——把代码重绘的同类元素 display:none（只隐藏，禁止删 DOM，删了违反母版铁律第 2 条、P4.5 必判功能丢失），CT 告警 / 恢复按钮 / 未绑定引导等底图上没有的 overlay 保留可见；
  ③ 透明热区——在切片容器上叠热区承接点击（底图 tabbar 用 bottom:0 + 等分宽度的透明热区，高度按像素探针实测值，ZEEDA 为 129px@750 → 67px@390）。
  实测 ZEEDA 设备页：代码绘制卡片差 13-15% → 改 hero+below 双切片后 3.5-4.8% → 再修「底图 tabbar 与代码 tabbar 双重绘制」后 2.04-2.48%，几何校验 0.000-0.061%。
  排查口诀：差异成片且看不出逻辑 → 先查「底图是不是已经印了、本层又画了一遍」。

• 分片复刻模式（Path C-S，v1.19.0 · 无初版原型时严格 1:1 复现目标产品）：输入是「线上可访问的目标产品 / UI 稿」而没有初版原型时，用按组件区块分片替代整屏重绘。完整实施按 references/slice-replication-guide.md 八步执行，此处列硬约束：

  • 承载方式三选一（进 P3 前逐区块定好并登记）：每个区块按性质选一种——① 整块切片（视觉密度高、代码重绘必走样的区块：图表本体、图标组、地图、插画、带底纹的卡片头）；② token 化活组件（可变量区块：随状态/数据变化的数值、空态、多语言文案、hover/禁用态）；③ 切片 + 活组件叠加（切片承载底图与静态装饰，活组件覆盖其上承载数据与交互）。禁止用 token 重绘去"还原"图表曲线、图标图形、插画——这类元素像素级不可复原，只能切片（实测 ZDService 2026-08-28：token 全实测，但 7 个 ECharts canvas 的系列类型、菜单图标图形只能 SVG 占位，用户判定「不能严格复现」）。
  • 分片即交互宿主（本模式最大收益，务必用足）：整屏切片要叠透明热点、坐标必须像素实测（铁律 5/6 + P3.5/P3.6 两道闸）；按区块分片后，区块内部的菜单项、按钮、卡片本身即真 DOM，交互由元素自己承载，热点坐标问题被结构性消解。因此分片粒度应切到「可交互组件」一级，不是越粗越好。
  • 区块清单是机器产物：分片前先产 _slice_manifest.json（区块 id / 源站选择器 / 分片文件名 / 实测盒模型 / 承载方式 / 该区块交互清单），由采集脚本或像素测量填充。无清单禁止进 P3——与 _ui_mapping.json 同等地位，是 P4 维度四的对照基准。
  • 源站交互清单替代初版母版做锚点：P4.5 无初版可比对时，以源站实测交互清单（页面解析报告的交互流，或逐元素实测的 onclick / 路由 / 弹层）为唯一契约——hifi 每个交互必须能在该清单找到对应项，找不到的停下问用户，禁止凭空新增；清单里有的交互 hifi 必须可达，缺失即 FAIL。禁止用「hifi 自查 0 差异」替代锚点比对。
  • 一图一态在分片下同样成立：空态 / 加载 / 异常态必须采集对应状态的分片，禁止把有数据的图表分片当作空态底图再叠「暂无数据」文字（违反 v1.11.1 一图一态铁律）。
  • 采图前置：源站截图一律走 CDP（scripts/capture_screens_cdp.py 或 slice_capture_cdp.py），禁用 agent-browser set viewport 与 Chrome --window-size（前者持续 EOF、后者 CSS 视口不变 → 缩放假阳性，见 v1.15.0 截图工具铁律）。需登录的站点先完成登录再采集，采集视口须与目标原型视口同一纵横比。
  • 不改既有流程：本模式只新增「输入侧采集 + 承载方式决策」，P4 四维、check_token_usage.py 三维闸、P5 交付收口全部照跑；分片文件名与区块 id 进交付报告「分片复刻清单」。

• 路径 A · Figma 驻留 skill：assets/figma-agent-skill-template.md + token 表渲染单文件 .md → 指引用户上传 Figma（付费席位）→ 之后以 /命令（如 /zd-web-standards）触发并附输入包要点。

• 路径 B · Figma 提示词（降级）：按 references/figma-prompt-templates.md 的 Prompt DNA 生成提示词，用户贴进 Figma Make / First Draft。

P3.5–P3.11 验证闸群（image-based / Path C-S 必做，逐闸 exit-code 硬闸）

> 完整操作细则（全部判据 / 实测陷阱 / 命令示例 / 负向测试）见 references/gate-manual-p3.md——本处只留闸位与放行条件。

> 三条跨闸纪律：① 新增闸必须做负向测试（还原缺陷原值确认能报错），否则不算落地；② 闸报的数必须用独立口径对账一次（v1.39.0 教训：新闸首跑 141 处 vs 独立实测 175 处，差 34 的根因是闸自身漏报，不是产物问题）；③ 闸报绿 ≠ 没问题——逐闸跑完即时回传退出码 + 一句结论（铁律 18），FAIL 先修复重跑再进下一阶段。

P4 一致性验收闸（出稿后回来找我验收；原四维 + v1.38.0 第 5 维研发可翻译性）

按 references/acceptance-checklist.md 逐项核对，前四维全过才放行：
1. 色值/色板：Path C 读 CSS 变量核对 token 表 + check_token_usage.py 源码三维扫（必跑）；Figma 路径 check_tokens.py 比对变量 JSON（详见 mcp-acceptance.md）；
2. 字号/间距/栅格：对照 token 表逐项核对；
3. 组件形态与状态：规范形态 + hover/disabled/空态齐全；
4. 页面/状态覆盖：对照 P2 状态矩阵逐格核对；
5. 研发可翻译性（v1.38.0 新增 · 铁律 19 · 仅可选强化定位必过）：默认定位（完整功能呈现参考）不要求此维——产物不是代码交付，研发参照效果自实现。仅当用户在 P1.5 明确要「结构可翻译」时本维才启用：前四维验「看起来对不对」，此维验「研发能不能照着生成代码」。硬闸即 P3.11 check_carrier_split.py（不带 --allow-nonsemantic），报告须附其结论（承载方式分布 / 反模式屏数 / 非语义交互数 / 占位文案数 / exit code）。人工复核三件事：
- 分工是否站得住：每屏 carrier 与 kickoff-plan §5 决策表一致；凡标 slice/hybrid 的屏，逐条确认「这里的交互元素真的像素级不可复原吗」——可交互控件被标成 slice = 反模式。
- 内容是否真实：无占位文字 / 凑数数字（研发照着填，原型假数据会变成产品假数据）。
- 动效是否活 DOM：随状态变化的过渡/动画必须是 CSS 过渡或活组件，不是「切片 A 换切片 B」的假动效。
仅可选强化定位：check_carrier_split.py exit≠0 → 本维 FAIL，打回（与 P4.5 独立出结论，任一 FAIL 不放行）。默认定位跳过本维，改跑 P4.6 功能呈现完整性闸。
6. overlay 视觉自动比对（可选增强）：capture_screens_cdp.py 逐屏截图 + pixel_report.py 出双指标报告 + check_visual_overlay.py 块级像素 diff，需 Pillow + websocket-client，非硬阻断（指引见 overlay-capture-guide.md）。
- 截图工具铁律（v1.15.0）：agent-browser set viewport 与 Chrome --window-size+--force-device-scale-factor 均不可用于像素比对（前者持续返回 EOF；后者 CSS 视口并未改变，页面带外框 → 缩放假阳性）。一律用 scripts/capture_screens_cdp.py（CDP 直连）。
- 双指标判读（v1.15.0）：块 diff 天然偏保守（块内 1 像素超标即整块计差异；实测设备态块级 2.24% 而逐像素仅 0.77%）。判读顺序固定为 几何校验（临时注入 image-rendering:pixelated 后重测，为 0 即坐标/缩放完全 1:1）→ 逐像素 → 块 diff。禁止只报块 diff 下结论。

任一维不过 → 打回报告（条目 + 期望值 vs 实际值 + 修改指引），验收结论按 references/acceptance-report-template.md 落盘。

P4.5 / P4.6 / P4.7 验收闸群（P4 后、P5 前硬闸）

> 完整操作细则见 references/gate-manual-p4.md——本处只留闸位与放行条件。

P5 交付收口

> 个人知识库收尾沉淀（知识库协同，可选增强）：验收全过后，如个人知识库存在则写入：
> 1. 踩坑全文 → 技能自带 references/lessons-learned.md（强制）
> 2. 踩坑摘要+回链 → 知识库 02-技能经验/prototype-hifi-pipeline/lessons.md
> 3. 成功范式同理（全文写技能自带，摘要写知识库）
> 4. 设计规范回流：本次验证的新 Token/组件/交互范式 → 追加到 04-UI设计规范库/ 对应文件
> 5. 项目档案：高保真原型 + 产物索引 → 写入 03-项目档案/{项目名}/03-设计资产/ 和 04-产物索引.md
> 6. 可复用资产：通用组件/模板 → 移入 03-项目档案/{项目名}/07-可复用资产/

验收全过后输出交付清单：高保真页面清单（Path C = HTML 可直接进开发 / Figma = .fig）、仍为线框的页面清单（含原因）、token 比对差异报告、遗留风险。

> P5 硬规则 · 可选强化定位下须附「承载方式实施清单」（v1.38.0 新增 · 铁律 19 · 仅可选强化定位）：默认定位（完整功能呈现参考）不需要此清单——研发参照产物效果自实现，不消费我们的结构。仅可选强化定位下需要：交付物除「能点的原型」外，还要让研发知道每一块该怎么实现。清单由 kickoff-plan §5 + check_carrier_split.py 报告合并而成，逐屏三列——
> | 屏 | 承载方式 | 研发实施指引 |
> |---|---|---|
> | device-home | hybrid | 能量流图/卡片阴影用切片 xx.png；数值区、按钮、滑块用活组件，绑 Device.* 数据源 |
> | login | live-dom | 全部为组件：输入框绑校验、按钮绑提交，无底图依赖 |
> | … | … | … |
>
> 并附两类显式标注（不标注 = 研发误当可交互/可复用）：
> 1. 切片区：列出全部切片文件 + 对应屏 + 「此处不可交互，改动需回设计稿重切」；
> 2. 已接受的热区模拟：确有业务理由必须沉在底图的控件，逐条写明理由与「后续重构建议」。
>
> 仅可选强化定位：无本清单不视为交付完成——研发拿到原型若还要自己猜「这块是图还是组件」，就等于原型白做。

> P5 硬规则 · 默认定位交付物须附「功能呈现完整性报告」（v1.40.0 新增）：默认定位下，交付物除 index-standalone.html 外，必须附 P4.6 的 state-report.md（功能呈现完整性报告）——列出全部交互函数的最终判定（PASS / DEFECT）+ DEFECT 整改清单（函数 / 屏 / 缺陷形态）。这是「完整功能呈现」的验收证据：研发/审核者一眼可见「每个可点的东西是否真的有反应、状态是否可见」。DEFECT > 0 的产品不视为交付完成。

> P5 硬规则 · 交付物精简（默认只出一个文件）：
> - 唯一交付物 = index-standalone.html（自包含：CSS/JS 内联 + 图片 base64，双击/卡片预览即可用）：python scripts/build_standalone.py <prototype_dir>。
> - standalone ≤ ~5MB → 直接交付 standalone，不另出 zip。
> - standalone > ~5MB → 交付 zeeda-hifi.zip（含 multi-file 版 + README），standalone 留在项目供 http.server 测试用但不作为交付物。
> - 级联重建（v1.7.2）：改过 fragments/*.html 后必须 python scripts/rebuild_all.py <prototype_dir>（fragments→index.html→standalone 一键级联；--check-only 干跑；zip 打包须显式排除调试目录：__pycache__/screenshots/归档目录等）——build_standalone.py 只读 index.html，不重组会静默交付旧坐标（zeeda 2026-08-26 实际踩坑：fragment 已修但 standalone 仍跳错页）。
> - index.html（multi-file 版）= 开发产物，不是交付物——留在项目目录供二次开发 / agent-browser 行为轨迹测试用，不单独交付给下游。
> - 禁止同时交付 standalone + zip + index.html 三件套——按体积二选一，避免冗余。

输出契约（验收报告必含字段）

页面/状态覆盖矩阵、四维逐项结论（PASS/FAIL/未验证）、P4.6 功能呈现完整性报告（交互函数 PASS/DEFECT 分布 + DEFECT 整改清单）、FAIL 项期望值 vs 实际值、打回或放行结论、置信度与未验证项声明。未实际核对的项必须标「未验证」，禁止虚构结论。默认定位下四维查视觉、P4.6 查交互完整性——两者任一 FAIL 不放行。

异常与边界

• 下游特别要求 .fig → 路径 A/B，否则默认 Path C，不强行引入 Figma 依赖；Figma 付费席位 / agent beta 不可用 → A 降级 B + 降级说明。
• Figma MCP 未连接 → 验收走人工清单（check_tokens.py 仍可做「导出变量 JSON vs token 表」离线比对）。
• 用户直接丢 Figma 链接验收但无输入包 → 先按 P2 反向补最小输入包再验收。
• 本 skill 不产出 PRD 与初版原型（product-prd-prototype 的事），只从初版原型之后接力。

需求与验收标准（G1）

• 需求来源：固化「初版原型 → UI → 高保真」流程，卡死与 UI 规范/UI 图的偏差（详见关联索引）。关键约束：① Path C 主路径（直接出 token 化 HTML）；② Figma 仅 .fig 需求；③ 漂移四维全卡；④ token 模板可替换；⑤ 上游接力 product-prd-prototype；⑥ P4.5 功能一致性闸（lofi 交互不丢/不错/不退化）；⑦ 交互对等底线 + UI 图最高权威 1:1 + 不确定就问；⑧ overlay 为可选增强非硬阻断；⑨ P2 初版预解析硬前置（_lofi_inventory.json）；⑩ P4.5 子维6 行为轨迹真测试闸（exit code 闸门）；⑪ P3.5 热点空间审计硬闸（image-based 原型必跑 check_hotspot_overlap.py，热点重叠=FAIL；坐标估错=不可见破坏，行为轨迹测不到）。
• 验收标准：① 触发词可进入完整流程；② 四件套产物齐备；③ check_tokens.py 自测通过且退出码可判定；④ forge_check 无 BLOCK；⑤ UAT 用户确认后封包；⑥ check_functional_consistency.py 自测通过且 P4.5 无 FAIL；⑦ check_sheet_parity.py 自测通过且弹框层无未分诊 FAIL；⑧ check_token_usage.py 自测通过且生成源码三维全 0；⑨ check_visual_overlay.py 自测通过（Pillow 缺失→2 跳过），其 FAIL 仅作证据增强、不阻断放行；⑩ extract_lofi_inventory.py --selftest 通过且 lofi 可点击 HTML 时产出 _lofi_inventory.json；⑪ compare_traces.py --selftest 通过且 P4.5 子维6 行为轨迹真实差异清零（exit 0）方可放行；⑫ check_hotspot_overlap.py --selftest 通过且 P3.5 热点重叠归零（exit 0）方可放行。
• 迭代若偏离原验收，须在关联索引「变更记录」说明。

运行环境（G8）

• Python 3.10+（标准库为主）；check_visual_overlay.py 像素级 diff 需可选依赖 Pillow（pip install pillow），缺失则自动降级尺寸粗检并标「未验证」；extract_lofi_inventory.py / compare_traces.py 纯标准库（无第三方依赖）；v1.15.0 新增 capture_screens_cdp.py / pixel_report.py 需 pip install websocket-client（纯 Python，用系统 Chrome，无需下载 Playwright 浏览器）
• 外部依赖：Figma 及 Figma MCP（可选，仅 .fig 路径，未连接降级人工清单）；agent-browser（P4.5 子维6 行为轨迹真测试必用，逐屏真实点击采集轨迹；不可用降级人工录屏 + 手填同 schema trace JSON 仍走 compare_traces 比对；注意：其 set viewport / set device 子命令实测持续 EOF，像素比对截图改用 capture_screens_cdp.py）；系统 Chrome（v1.15.0 起为 overlay 截图必用，走 CDP）；上游 product-prd-prototype skill（读 prototype/ 产物，只读）
• 自检入口：scripts/check_tokens.py、check_functional_consistency.py、check_sheet_parity.py、check_token_usage.py、check_visual_overlay.py、extract_lofi_inventory.py、compare_traces.py、check_hotspot_overlap.py、check_upstream_drift.py（v1.14.1，上游 schema-drift 溯源标记解析）、capture_screens_cdp.py / pixel_report.py（v1.15.0，CDP 截图 + 逐像素报告）、probe_elements.py / click_verify_cdp.py / crop_png.py（v1.16.0，像素探针 + P3.6 点击命中闸 + 裁图） 含 --selftest 的脚本清单见上（21 个，非全部）

脚本能力边界（能力面前置声明）

> 本 skill 带 50+ 个脚本。共同边界先讲清，避免被当成"跑一遍就全自动"：

1. 以只读校验为主：绝大多数闸脚本只读不改产物（HTML / CSS / JS 一个字节都不动），只出报告与退出码。
2. 少数可修复：带 --fix 的（如 P4.7 溢出注入）只做注入式最小修复——不改结构、不改文案、不动交互。
3. 网络仅本机：CDP 类脚本只连 127.0.0.1 / localhost，无外联、无上传。
4. 删除仅限自建临时夹具：脚本只删自己在 --selftest 里建到系统临时目录的夹具，不删任何用户产物。
5. 人工确认前不落产物：脚本产出的是草稿 / 报告 / 机读件；真正改产物一律在人工确认后由 Agent 执行（对应 P3 逐屏与首屏对齐闸）。
6. 退出码语义：0 = 通过；1 = 有未过项（= 暂停点，需人工介入）；2 = 参数错。
7. 可复核：单脚本 --selftest；全量矩阵 scripts/audit_smoke.py（compile + selftest + --help 契约 + CDP 目标选择体检 + forge 四维）。

配套资源

• scripts/：scan_orphan_assets.py（v1.37.0 P0 孤儿设计资产扫描闸——设计目录里有、但产物零引用的图片；补既有 6 类闸全部查不出的「图一直在却没被用上」盲区；exit 0=无未分诊 / 1=有未分诊 / 2=参数错；--allowlist 白名单须逐条给理由，仅三类合法：中间产物 / 冗余备份须实测举证 / 未启用态保留；--registry 追加查「尺寸表登记但零引用＝疑似自绘替代」高危类；--json 机器可消费；--selftest 6/6 正+负样本）、check_tokens.py（token 比对）、check_token_usage.py（源码级三维闸）、check_functional_consistency.py（功能一致性 diff）、check_sheet_parity.py（弹框对等性）、check_visual_overlay.py（overlay 像素 diff，可选增强）、extract_lofi_inventory.py（P2 预解析→inventory JSON）、trace_lofi.js/trace_hifi.js（P4.5 子维6 行为轨迹采集）、compare_traces.py（P4.5 子维6 机器比对闸）、check_hotspot_overlap.py（P3.5 热点空间审计——重叠检测+报告，含 --selftest）、check_upstream_drift.py（v1.14.1 P2 上游 schema-drift 溯源检查，消费 product-prd-prototype v1.9.74 在 screens.json 打的 schemaDrift/origin/schemaUpgraded 标记，默认 WARN 不阻断）、crosscheck_screens_contract.py（v1.23.1 P2 上游 screens.json 结构契约预检，消费 v1.9.73+ 结构化 components[] 的 mustKeep/businessDesc/tokenRef，确认 hifi-ready，默认 WARN 不阻断）、crosscheck_element_spec.py（v1.29.0 P2 上游 element-spec.json 元素规格契约预检，消费 product v1.9.78+ 逐屏元素规格交付表——geometry 四键完整性 / animation.type 值域 / modals[].type 值域 / 交互须含 desc / 弹框字段须含 name，默认 WARN 不阻断、--strict exit 1、--selftest 正/负样本）、verify_state_feedback.py（v1.40.0 P4.6 功能呈现完整性闸——四步验证法：静态调用图 BFS 枚举 onclick/onchange→建索引→求可达→只在 DOM 层原语判定视觉反馈；可选 --runtime CDP 真点击 before/mid/after 三截图 PIL diff + 运行时 DOM/toast/modal 快照 + 受控重测合并判定；分档 SILENT_STATE/WEAK_FEEDBACK/EMPTY/NO_IMPL=DEFECT（exit 1 禁进 P5）、STATE_VISIBLE/NAV_OR_UI=PASS；--selftest 断言六分档正/负样本；--runtime 需 websocket-client+Chrome+Pillow，缺失降级 WARN）、build_standalone.py（P5 单文件内联；v1.22.0 起同时支持 CSS url(...) 与 <img src> 两类图片引用——Path C-S 分片直铺用 <img> 承载，旧版只认 CSS 会产出 imgs=0 的裸奔 standalone；sanity 查四类残留：<link> / <script src> / url() / 非 data: 的 <img src>）、rebuild_all.py（fragments→index→standalone 级联重建 + zip 打包）、capture_screens_cdp.py（v1.15.0：CDP 直连精确截图，像素比对唯一可靠方案，dsf = UI图宽/视口CSS宽，含 --expect 尺寸断言与 --js-map 按屏注入状态）、pixel_report.py（v1.15.0：逐像素差异报告，与块级 diff 互补）、probe_elements.py（v1.16.0：纯 stdlib PNG 元素探针，热区坐标唯一合法来源；rows/bands/boxes/cols/xext/map/blocks 七模式，map 为 ASCII 版式地图，在"看不见图"时还原整屏结构）、click_verify_cdp.py（v1.16.0：P3.6 点击命中验证闸，CDP 真实鼠标事件点击元素几何中心并断言 handler）、crop_png.py（v1.16.0：纯 stdlib 裁剪/缩放，把底图局部导出成小图供人读或模型读）、measure_device_hotspots.py（v1.16.0：变高多状态底图的 per-state 热区测量与 CSS 生成范例）、check_hotspot_vs_slice.py（v1.28.0：P3.8 切片-热区静态对账闸，纯 stdlib（E 项需 Pillow），秒级无需浏览器——以切片尺寸权威表 _slice_meta.json 为唯一基准，把 CSS 热区坐标反算回 750 坐标系对账，A 溢出切片/B 切片尾部留白>8行/C top<0 → FAIL，D 压内容底边 → WARN，E 切片实际尺寸≠权威表 → FAIL；支持 --json 与 --css <path>（后者用于负向测试）；无 _slice_meta.json 时明确报错而非静默 PASS）、rebuild_all.py（v1.28.0 升级：新增 run_gates() + pick_python(prefer_pil=True)，构建前先跑「切片完整性 --check --meta」与「热区 vs 切片对账」两闸，失败即中止；pick_python 逐个探测托管解释器挑带 PIL 的那个，不再盲信 sys.executable）、audit_all_clicks_cdp.py（v1.18.0：全 41 屏 + 6 态广义点击审计——命中遮挡 + JS 报错双闸，遍历全部可点击元素，scrollIntoView 修正 + 隐藏 DOM 归 SKIP-INVIS，输出 _audit_clicks.json，FAIL 即 exit 1）、scan_bottom_risk.py（v1.19.0：长内容屏 + 底部 absolute 锚定隐患静态闸，纯 stdlib 无需 Pillow——A 维按 源高×390/源宽>844 判长内容、B 维抽 CSS 类规则与 fragment inline style 的 absolute|fixed|sticky + bottom:*，命中「A 且 B」即高危，exit 1）、verify_bottom_pin_cdp.py（v1.19.0：底部栏钉底运行时闸，CDP 真实浏览器按「屏 × 状态」逐态 goto → 找滚动容器 → 滚到底 → 断言 tabbar getBoundingClientRect().bottom≈844 且内容全可达）、slice_capture_cdp.py（v1.20.0：Path C-S 分片采集——按 _slice_manifest.json 区块清单对目标产品批量截图，并把实测盒模型/图片尺寸回写清单；复用 capture_screens_cdp.py 的 CDP 连接层；含 --selftest；无 websocket-client 或 Chrome 时退出码 2 并给出「整屏截图 + crop_png.py 逐个裁」降级路径）、scan_stub_impl.py（v1.21.0 引入 · v1.23.0 升级为双锚点遗漏探测闸，纯 stdlib、含 --selftest）：专治「存在性 ≠ 真实性」——GAP＝hifi 纯占位 toast()/近空函数 而锚点（lofi 同名函数 / --source-manifest 源站交互清单）标注该交互为真实实现（真实信号 Device.*= / innerHTML= / appendChild / showModal / getLockState() / navigateTo）；WARN＝实现变浅（有状态写入但相对锚点缺重渲染/锁定校验）；另扫 fragment 里 onclick="toast(...)" 的内联占位热点。支持 --baseline（P2 早期基线：仅扫初版/源站、hifi 未构建即产出「必实现真实交互清单」+「母版轻提示豁免清单」）与 Path C-S 的 --source-manifest；P4.5 作为硬 exit-code 闸门（GAP>0 或内联热点>0 → exit 1 阻断），与 P2 早期基线同源、双锚点闭环。功能一致性闸与 click_verify 都查不出这类「同名桩/近空函数」）、check_cover_piece.py（v1.31.0：P3.9 通用覆盖件对位闸，取代单件模板 check_solar_radio.py——A 同心≤0.5 CSS / B 覆盖（渲染外边界≥底图、容差 0.0）/ C 不过冲≤+1.2 / D 同形（圆角率差≤4pp）/ E 单环（实心件 24 向必须只有 1 条描边色带，补 B 的盲区）；配套 cover_piece_spec.example.json（只存非像素信息，期望值运行时从底图实测导出）与 measure_shape.py（逐行半宽剖面定形，区分正圆 vs 圆角矩形，--mode solid|ring，含亚像素中心修正与 GAP=4 半宽段扫描）；跑在带 PIL 的解释器上，内部 subprocess 用带 websocket 的解释器截图；--only <子串> 可单跑一件，底图拟合 RMSE>1.0 出 WARN）、measure_shape.py（v1.31.0 定形工具，见上）、cover_piece_spec.example.json（v1.31.0 覆盖件清单模板，见上）、check_solar_radio.py（v1.30.0：P3.9 活 DOM 覆盖件对位闸单件模板，v1.31.0 起被 check_cover_piece.py 取代、保留作最小范例，运行时 CDP 把 .solar-radio 实测圆心/外径反算回 750 坐标系与 PIL 基准对账——A 圆心 x 漂移>4 / B 圆心 y 漂移>6 / C 外径<底图 31（盖不住→双圈）/ D 越界 → FAIL；改常量即可复用于其它「点元素覆盖底图已印元素」场景；导航序列须先 goto('<screen>') 再 showOverlay()，否则祖先 display:none 使 rect 恒为 0×0；需 websocket-client，用带 websocket 的解释器跑）。其中含 --selftest 的脚本已在上文逐个标出（19 个，JS 除外），其余工具/CDP 验证脚本无 selftest、用 --help 查看用法。v1.33.0 审计维度补全闸：audit_smoke.py（全脚本冒烟矩阵：compile+selftest+--help 秒退+forge 四维一键）、golden_regress.py（跨版本视觉回归基线：截图指纹对账防无声回退）、text_consistency.py（文案对账：lofi 按钮/占位/label 在 hifi 缺失或篡改 FAIL）、value_echo.py（数据回显数值断言 spec 驱动，产出注入 JS）、state_chain.py（跨屏状态链路对轨迹逐链可达性，断链 FAIL）、audit_boundary_states.py（空/错误/加载边界态痕迹核对）、check_a11y_basic.py（交互元素缺可访问名静态 WARN）、check_multi_viewport.py（响应式探测+多视口复跑矩阵）。v1.34.0 专业度补全闸**：fidelity_report.py（保真度综合评级：视觉/交互/状态/契约四维量化评分聚合、低于阈值 WARN、落 fidelity-report.json）、check_animation_parity.py（动效保真对账：element-spec.animation vs hifi 声明，契约有声 hifi 无 FAIL）、check_contract_fulfillment.py（契约实现完成度出口对账：上游契约 id 锚点实现率，落 _fidelity_contract.json 供评级聚合）、audit_boundary_states.py 升级 --require（按屏声明必要边界态，缺 FAIL——强制级）。操作细则见各 references 文档。
• rebuild_all.py 打包陷阱（v1.15.0）：该脚本会把 prototype 目录下所有文件打进 zip。为绕过沙箱删除限制而 rename 的旧 zip 备份（*.zip.bak/old2/old3）若留在目录内，会让包从 48MB 膨胀到 202MB；同理 CDP 的 --user-data-dir 也必须放在 prototype 之外。交付前须确认目录内无历史备份与临时目录。
• references/：ui-tokens-template、ui-token-spec（UI 视觉 Token 完整集合，v1.14.0：状态色/字体族/字重/阴影/组件尺寸/图标/暗色模式全集，机器兜底 check_token_usage）、input-package、figma-prompt-templates、acceptance-checklist、functional-consistency-checklist、mcp-acceptance、acceptance-report-template、overlay-capture-guide、behavioral-parity-gate（P2 预解析 + P4.5 子维6 操作手册 + §四 业务-视觉边界铁则→机器闸映射）、dsl-schema（原型结构化契约 Schema + 字段级刚性校验 R1-R5，v1.14.0：把 type 级校验升级为字段级，对齐三道机器闸）、hybrid-mode-guide（P3 混合模式八步实施手册，v1.8.0）、success-patterns（成功经验范式，v1.8.0：混合模式/级联重建/stdlib PNG 工具链/双层验证/token 换肤/图片名映射 6 范式）、slice-replication-guide（Path C-S 分片复刻八步手册，v1.20.0：无初版原型时按组件区块分片直铺、严格 1:1 复现目标产品——承载方式三选一 / 分片即交互宿主 / 源站交互清单为锚 / 一图一态 / 高频坑）、preflight-asset-audit（v1.37.0 P0 动手前资产清点闸手册——源码读取清点 / 设计资产清点 / 切图↔屏对应表 / 七段式报告模板 / 孤儿分诊规则；含铁律19 研发可翻译性分工边界速查表：切片只承载像素级不可复原视觉，可交互/有状态/有动效元素必须活 DOM）、accepted-parity-whitelist.example.json（白名单模板）、skill-research、association-index、lessons-learned、gate-manual-p3 / gate-manual-p4（v1.43.0 P3/P4 闸群完整操作细则——原文外置，正文只留闸位速查表与放行条件）、ask-discipline（v1.46.0 提问与确认纪律——澄清型一次一问 / 可判定停手信号 / 3 轮上限→首屏闸做最小初稿；确认型清单不适用；v1.50.2 补第六节：给选项/方案须带推荐）、plan-gate（v1.50.2 计划闸细则——试跑计划四要素 + 确认闸 + 与既有确认闸/forge C38 的分工，正文同名节只留速查）**
• assets/figma-agent-skill-template.md：Figma 驻留 skill 生成模板（仅 Figma 路径）
• v1.50.0 新增：references/note-contract-proposal.md（给上游 product 的机读件 _note 契约补丁提案——字段定义 / 唯一判据 / 反模式 / 兼容性 / 上游落地步骤 / 拒绝时的替代方案；未采纳不阻断）。
• v1.49.0 新增：scripts/check_confirmations.py（人工确认留痕凭据检查——查四个必需人工闸在 _confirmations.json 里是否留有记录；WARN 级不阻断，仅 --strict 时 exit 1；只校验"有没有"、绝不生成内容；--selftest 5 组）+ references/artifact-conventions.md（机读件约定——_note 自述字段 + 消费方忽略 _ 前缀键 + 机读件归属表 + 人工确认留痕规范 + 给上游的 _note 契约提案）。
• @skill:knowledge-hub-sync（外部引用 KB-SYNC）：个人知识库（Obsidian）协同/沉淀规范唯一权威源（本地副本已迁出）

质量基线（harness 工程思路）

• 可观测：机器闸含 --selftest 的脚本清单见上（21 个，非全部） 与差异报告；验收报告落盘。
• 可复现：机器判定退出码，不靠「看起来没问题」。
• 质量门：四维闸 + P4.5 + forge_check，任一 FAIL/BLOCK 不放行。
• 回归守卫：易回归点记入 lessons-learned。

成功范式（默认复用，防自由发挥）

本 skill 自带 references/success-patterns.md（16 个已验证范式：混合模式 / 级联重建 / 纯 stdlib PNG 工具链 / 双层验证 / token 化换肤 / 图片名映射表 / CDP 精确截图（v1.15.0） / 底图已印元素视觉让位三件套（v1.15.0） / 双指标验证（v1.15.0） / 像素探针量坐标（v1.16.0） / 变高多状态底图用固定 px 热区（v1.16.0） / 点击命中验证闸（v1.16.0） / 分片复刻（v1.20.0） / 切片尺寸权威表 + 热区静态对账（v1.28.0） / 活 DOM 覆盖件同心对位（v1.30.0） / 覆盖件闸：期望值运行时实测 + 计数判据补度量判据盲区（v1.31.0））。任何高保真任务上手前先 Read 本文件——命中任一覆盖场景即直接套用已验证做法、再在此基础上调整，禁止从空白自由发挥；P3 混合模式八步实施时必读（与 hybrid-mode-guide.md 配合）。

结果上报须带证据（禁止凭记忆与猜测断言）

> 向用户汇报任何结论 / 结果 / 状态时，两条缺一即违规：
> 1. 附可验证证据——命令输出、文件读取内容、检查器 / 测试报告、退出码、日志片段；无证据不结论，结论须能被证据回溯。
> 2. 严禁猜测 / 假设 / 推断——拿不准、未验证、未读取的部分必须明说「未验证 / 未读取」；"大概率是 X""应该就是 Y""我记得"这类无依据表述等同猜测，须先查证再下结论。
>
> 与既有条款的关系：「能力确认闸」禁"猜着降级"、「回忆与检索纪律」禁"不确定记忆当事实复述"——本条是同一「宁停勿猜」纪律在输出环节的投影。

计划闸（先分流 → 决策类请确认 / 过程类自主决定）

> 前置分流（先做这一步，防"过程性细节也去打扰用户"）：动手前先分类——决策类（影响范围 / 取舍 / 风险成本 / 交付物形态 / 用户明确要求）→ 走确认闸；过程类（文件组织 / 实现方式 / 命名 / 内部步骤 / 验证手段）→ 直接实施，在交付说明写「自主决定 + 依据」，用户事后可否决。判据："把这个问题摆给用户，他能给出有信息量的回答吗"——拿不准默认不打扰；过程类若超范围或风险升级 → 转为决策类、停下确认。
> 触发（仅决策类需走）：① 影响面大（改质量门 / 核心流程 / 纪律）② 不可逆或难回滚 ③ 用户明确要求「先给计划」。小改动可跳过，但须注明「影响面小，未走计划闸」。
> 动作：动手前出试跑计划四要素——动哪些（目录 + 新建/改/删文件清单）· 每步做什么（顺序，含先建索引）· 怎么验证（能先试跑的先跑出证据）· 怎么回滚（备份位置 + 还原方式）；并带推荐（推荐项 + 理由，不硬凑）。
> 确认闸：用户确认后才实施；偏差超出计划 → 停下重新确认，不擅自扩大。
> 与既有确认闸的分工：kickoff-plan / 首屏对齐闸卡"做什么算对"，本闸卡"怎么做 · 怎么验 · 怎么退"——互补不可互替。细则见 references/plan-gate.md。

自我迭代（防复发，去重 + 提升）

本 skill 自带 references/lessons-learned.md。每次测试/迭代的问题、根因、修复必须当场追加（forge_check 强制核查，缺失即 BLOCK）。读经验三动作（v1.47.0，缺一不可）：① 读自身——动手前先 Read 本文件与 success-patterns.md 逐条核对；② 读同类——迭代时读被改对象的 lessons，且成功范式必须做同类匹配（结论可为「无同类」，但动作不可跳过）；③ 留痕——「读了哪些 / 命中什么 / 套用哪条」登记进 association-index.md 的 G4「经验检索记录」段（成功、失败、跳过均须登记，跳过写明原因）。细则见 references/lessons-learned.md 头部。
经验沉淀去重（C40 硬闸）：① 追加 lessons-learned / success-patterns 条目前先 grep 检索，命中已有同类条目则用 See Also 关联 + Recurrence-Count 累计，不新建重复条目；② 同类问题累计 ≥3 次时，把教训提炼为一句预防规则写入本文件对应节（或起草泛化补丁），并将原条目标记 Status: promoted——教训要及时消化为规则，不是越积越多（v1.25.1：「能力在位 ≠ 对新承载方式通用」家族已 promoted）。
回忆与检索纪律（v1.25.1）：回答"上次怎么做的/这个坑踩过吗"类问题时，先检索 lessons-learned.md / success-patterns.md 沉淀并引用原文（版本/条目）；未检索到或不确定时明说"未在沉淀中找到"，禁止把不确定记忆当事实复述（与 C37 互补）。渐进式加载：本 skill 体积大（超 5 万字符），读取时先 grep 定向取数、append 不重读全文，按需取段落即可，避免上下文膨胀。
大任务拆解与诚实读取（v1.50.2）：① 实施前先评估任务规模——目标文件 / 代码 / 数据量超出「单次可完整读取并处理的上下文预算」时，必须拆为可独立验证的子任务并逐项实施、逐项验证，禁止一次性硬塞超长上下文导致遗漏或失真；② 严禁只读一部分就宣称「已读完 / 已完成」——未读部分如实标注，汇报时说明读取范围与未覆盖项（与 P0 源码读取清点的清点纪律同源，C38 同族）。细则与分工见 references/plan-gate.md §六。
外部提案 / 审查的处理（v1.47.0）：收到外部方案、提示词、审查报告或建议清单时——影响面大才做业界对标（要改质量门 / 核心流程 / 纪律 / 引入外部体系）；三步＝提炼主张 → 业界对标（权威源优先）→ 三栏结论（采纳 / 部分采纳 / 拒收 + 逐条依据），查不到依据就明说无依据、退化为工程判断；三条边界＝只加证据不替用户决策 / 不照搬须说明适配性 / 来源分层信任。范式见 references/success-patterns.md 范式21。

版本历史

> 详细变更记述见 references/association-index.md「变更记录」段与 references/changelog.md（按版本号逐条展开），此处只留一行式索引。
- 1.50.3（2026-09-17）计划闸补「前置分流」（对齐 skill-forge v1.5.22）：核查发现 forge 已从 v1.5.21 前进到 v1.5.22，给计划闸加了先分流再决定是否请确认——决策类（影响范围 / 取舍 / 风险成本 / 交付物形态 / 用户明确要求）走确认闸；过程类（文件组织 / 实现方式 / 命名 / 内部步骤 / 验证手段）直接实施 + 交付说明写「自主决定 + 依据」，用户事后可否决。判据＝「把问题摆给用户他能给出有信息量回答吗」，拿不准默认不打扰；过程类超范围 / 风险升级 → 转决策类停下确认。背景：v1.50.2 落的是 v1.5.21 版计划闸（一律出计划请确认），在 v1.5.22 下已过时、且违反「过程类别打扰用户」——本条即修正。正文「计划闸」节新增前置分流行，细则补入 references/plan-gate.md；同步压缩版本历史索引（只留最新 2 条 + 无计数指针）。PATCH。
- 1.50.2（2026-09-17）对齐 skill-forge v1.5.19/1.5.20/1.5.21（覆盖核查后补齐三条真缺口）：核查确认 v1.5.19（修 C48 两项缺陷）无需动作；补齐——① 新增「计划闸」（对齐 v1.5.21 Phase 0.9）：动手前出试跑计划四要素（动哪些 · 每步做什么 · 怎么验证（能先试跑的先跑出证据）· 怎么回滚）+ 确认后才实施 + 偏差停下重确认；小改动可跳过但须注明；细则落新增 references/plan-gate.md（C73），并写明与 kickoff-plan/首屏闸的分工（它们卡"做什么算对"，本闸卡"怎么做·怎么验·怎么退"，不可互替）；② 新增「结果上报须带证据」节——核查发现 forge C37 的机器 PASS 原系关键词级（判据＝全文匹配 证据|退出码|可验证 与 猜测|假设|推断，不做语义定位），而 hifi 命中的两处语义不同（"验收证据" / 能力确认闸"禁猜降级"）→ 本轮补成文的运行时指令：无证据不结论 + 严禁猜测/假设/推断 + 未验证须明说；③ ask-discipline.md 补第六节「给选项/方案须带推荐」（对齐 v1.5.20）：原文件声明对齐 Phase 0.8 却只有 5 节、全文「推荐」0 次（名义对齐、实际漏条），补推荐项+理由、其它项适用条件、禁止只罗列不表态、无更优项时明说。另：版本历史索引再压缩（保留最新 3 条 + 指针，移出 5 条——压缩前先核 changelog 覆盖度，零丢失）。PATCH。
- 更早版本（1.50.1 及以前）：完整记述见 references/changelog.md（按版本号逐条展开）与 references/association-index.md「迭代维护记录」段，此处不再逐条列出。