coding.mjs: 新增静态原型渲染门 Preview——截图基线 + 原型交互冒烟硬门

前端段开头一次性 Playwright headless 渲染 prototype/**/*.html 本身：截图归档为可视化基线 + 跑原型自带交互点击冒烟 + 捕获 JS/console 错误。与行为门正交（Preview 测静态原型、Behavior 测实现）。硬门：渲染失败 / 脚本未捕获异常(jsErrors)→仲裁(只许 retry/halt)，halt 即停下等人工回 plan/add-req 修原型后重跑（coding 不改原型源码）；console.error advisory；环境未就绪(Playwright/浏览器缺失)才 retry→仲裁降级；无 prototype/ 跳过。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coding.mjs: 新增静态原型渲染门 Preview——截图基线 + 原型交互冒烟硬门
前端段开头一次性 Playwright headless 渲染 prototype/**/*.html 本身：截图归档为可视化基线 + 跑原型自带交互点击冒烟 + 捕获 JS/console 错误。与行为门正交（Preview 测静态原型、Behavior 测实现）。硬门：渲染失败 / 脚本未捕获异常(jsErrors)→仲裁(只许 retry/halt)，halt 即停下等人工回 plan/add-req 修原型后重跑（coding 不改原型源码）；console.error advisory；环境未就绪(Playwright/浏览器缺失)才 retry→仲裁降级；无 prototype/ 跳过。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
yanghl
1 parent bc9f593a
Showing 2 changed files with 194 additions and 1 deletions
README.md
workflows/coding.mjs
@@ -54,6 +54,11 @@ Claude Code 插件：ERP / 后端管理系统全流程开发框架。
      │
      └─ B-前端（后端全部打里程碑后，整体 1 个里程碑 tag）
           runBranchSetup(frontend-phase)
+          → 静态原型渲染门 preview（前端段开头：Playwright headless 逐页渲染 prototype/**/*.html 本身
+            → 截图归档为可视化基线 + 跑原型自带交互点击冒烟 + 捕获 JS/console 错误。与行为门正交——
+            前者测静态原型、后者测实现。硬门：原型渲染失败 / 脚本未捕获异常(jsErrors)→仲裁(只许 retry/halt)，
+            halt 即停下等人工回 plan/add-req 修原型后重跑（coding 不改原型源码）；console.error 仅 advisory；
+            唯环境未就绪（Playwright/浏览器缺失）才 retry→仲裁降级。无 prototype/ 则跳过）
           → 前端骨架占位阶段（router 全量 lazy 路由表 + FeStub 占位，保证中途任意时刻可构建可起；
             含 e2e 基线脚手架：Playwright globalSetup 按注入时序注种子 + admin 登录 storageState；
             含单测基线：vitest include 限定 tests/**/*.test.*——单测一律 frontend/tests/ 镜像 src/，
@@ -8,12 +8,16 @@ export const meta = {
   name: 'erp-coding',
   description: 'Run the entire ERP coding phase autonomously and silently: per-module backend+frontend feature loops, test gate, milestone tag.',
   phases: [
-    { title: 'Router' }, { title: 'Schedule' }, { title: 'Backend' }, { title: 'Frontend' },
+    { title: 'Router' }, { title: 'Schedule' }, { title: 'Backend' }, { title: 'Preview' }, { title: 'Frontend' },
     { title: 'Behavior' }, { title: 'Gate' }, { title: 'Seed' }, { title: 'Milestone' },
   ],
   // 注：'Behavior' = 阶段级行为验收门（v3）——整个前端阶段在 featureLoop 全部 FE 完成后只跑**一次**
   // 行为验收（含 fix 循环），不再在每个 FE 的 review 循环内做 approve 子门（v2 per-FE 形态已撤销）。
   // 时序：featureLoop(frontend) → Behavior（行为门+fix）→ Gate（testGate 全量回归，兜底行为 fix 引入的回归）。
+  // 注：'Preview' = 静态原型渲染门——前端段开头一次性渲染 prototype/**/*.html 本身（Playwright headless
+  // 截图归档 + 原型自带交互点击冒烟）。与 Behavior 正交：Preview 测**静态原型**、Behavior 测**实现**。
+  // 硬门：原型渲染失败 / 脚本未捕获异常(jsErrors) → halt（原型属上游 plan 权威，coding 不改原型源码，
+  // 应回 plan/add-req 修后重跑）；console.error advisory；环境未就绪 retry→仲裁。时序：Preview → Frontend（骨架+featureLoop）。
 }
  
 const ROUTER_SCHEMA = { type:'object', additionalProperties:false,
@@ -154,6 +158,38 @@ const BEHAVIOR_GATE_SCHEMA = { type:&#39;object&#39;, additionalProperties:false,
         confidence:{type:'string', enum:['high','medium','low']} } } },
     artifactPath:{type:'string'} } }
  
+// PROTOTYPE_PREVIEW_SCHEMA：静态原型渲染门（phase('Preview')）返回。与 BEHAVIOR_GATE 正交——
+// 后者测「实现」（冷起全栈 + Playwright 驱动真前端），本门只渲染 *静态* prototype/**/*.html 本身：
+// 逐页 headless 渲染→截图归档（可视化基线）→跑原型自带交互点击冒烟→捕获 JS/console 错误。
+// status：ok=渲染门正常跑完（含 advisory 问题）；blocked=仅限环境未就绪（Playwright/浏览器缺失/超时）需仲裁。
+// 原型属上游 plan 权威、coding 绝不改原型源码——故渲染/JS 问题是 advisory（记 decisions+证据，绝不硬 halt）。
+const PROTOTYPE_PREVIEW_SCHEMA = { type:'object', additionalProperties:false,
+  required:['status','pagesFound','pagesRendered'], properties:{
+    status:{type:'string', enum:['ok','blocked']},
+    pagesFound:{type:'integer'},      // Glob 到的 prototype/**/*.html 总数
+    pagesRendered:{type:'integer'},   // 成功渲染并截图的页数
+    pages:{ type:'array', items:{ type:'object', additionalProperties:false,
+      required:['file','rendered'],
+      properties:{
+        file:{type:'string'},                                 // prototype 相对路径
+        rendered:{type:'boolean'},
+        screenshot:{type:'string'},                           // assets 相对路径（已归档，纳入版本管理）
+        controlsExercised:{type:'integer'},                   // 实际驱动（点击/切换）过的控件数
+        jsErrors:{type:'array', items:{type:'string'}},       // pageerror 文本（原型自身脚本质量信号）
+        consoleErrors:{type:'array', items:{type:'string'}},  // console.error 文本
+        notes:{type:'string'} } } },
+    // envError：仅环境未就绪（与「原型自身有问题」严格区分——后者是 advisory，不进 envError）。
+    envError:{ type:'object', additionalProperties:false,
+      required:['kind'], properties:{
+        kind:{type:'string', enum:['playwright-missing','browser-missing','timeout','none']},
+        detail:{type:'string'} } },
+    decisions:{ type:'array', items:{ type:'object', additionalProperties:false,
+      required:['question','choice','rationale'],
+      properties:{
+        question:{type:'string'}, choice:{type:'string'}, rationale:{type:'string'},
+        confidence:{type:'string', enum:['high','medium','low']} } } },
+    artifactPath:{type:'string'} } }
+
 // ── 微步骤 schemas（runBranchSetup / runMilestone / runCrossModule 用）─────────
 const WT_SCHEMA = { type:'object', additionalProperties:false,
   required:['clean'], properties:{
@@ -838,6 +874,72 @@ function seedGenPrompt(module, c) {
   ].filter(Boolean).join('\n')
 }
  
+// ---- 静态原型渲染门（Preview）prompt ----
+// 与下方「前端行为验收」正交：行为门测**实现**（冷起全栈 + Playwright 驱动真前端），本门只渲染
+// **静态** prototype/**/*.html 本身——逐页 headless 渲染→截图归档（可视化基线）→跑原型自带交互点击
+// 冒烟→捕获 JS/console 错误。原型是 plan/add-req 的上游权威产物：本门**只渲染不修改**，原型自身问题
+// 走 advisory（记证据，不硬 halt）。不起后端/前端 app、不跑 setup-test-db/seed。
+
+// prototypePreviewContract：渲染门硬约束（只读、不起全栈、唯一可写区 = .tmp + assets + 证据报告）。
+function prototypePreviewContract(c) {
+  return [
+    '## 硬约束（非交互原型渲染子代理）',
+    '- 你是 Workflow 派生的**非交互子代理**，物理上无法弹 AskUserQuestion / 等人输入。**绝不要尝试问人**。',
+    '- 你是**静态原型只读渲染门**：用 Playwright headless 渲染 `prototype/**/*.html` 本身、截图、跑原型自带交互——**不是**实现功能、**不是**起后端/前端 app、**不是**改任何源码。',
+    `- **作用域（唯一可写区）**：\`${c.root}/.tmp/prototype-preview/\`（一次性 runner，跑完即弃）+ 截图归档到 \`${c.root}/docs/superpowers/module-reports/assets/prototype/\` + 证据报告 \`${c.root}/docs/superpowers/module-reports/prototype-preview.md\`。`,
+    '- **越界硬停**：**绝不**编辑 `prototype/` / `frontend/` / `backend/` / `sql/` / `scripts/` 下任何文件——原型是上游 plan 的权威产物，本门只渲染不修改。命中越界即以 `status:blocked` 或写清阻塞点结束。',
+    '- **不起全栈**：本门只渲染静态 HTML（`file://` 或仅服务 `prototype/` 的临时静态服务器），**绝不**冷起后端 / 前端 dev server、**绝不**跑 setup-test-db / seed。',
+    '- 证据报告**使用中文**；文件名 / 选择器标识符可用英文。',
+    '- **运行时确定性**：视口尺寸 / 临时目录名 / 截图文件名 / 临时端口一律确定性派生（按页面相对路径 / attempt 序号），**绝不**依赖时间戳 / 随机数。',
+  ].join('\n')
+}
+
+// prototypePreviewPrompt：静态原型渲染门子代理完整流水线（step0-3 + schema）。
+// feItems：本前端阶段全部 FE-NN（仅作分组参考，不强制与原型页一一对应）；attempt：环境 race 重试序号（1..）。
+function prototypePreviewPrompt(feItems, attempt, c) {
+  const feList = (feItems || []).map(x => `\`${x}\``).join(', ') || '（无 FE 清单）'
+  const tmpDir = `${c.root}/.tmp/prototype-preview`
+  const assets = 'docs/superpowers/module-reports/assets/prototype'
+  const evidence = 'docs/superpowers/module-reports/prototype-preview.md'
+  return [
+    `# preview — 静态原型渲染门（headless，attempt=${attempt}）`,
+    '',
+    prototypePreviewContract(c),
+    '',
+    '## 目标',
+    '渲染**全部静态原型** `prototype/**/*.html` 本身，产出两类产物：① 每页**截图**（可视化基线，供人工 / 行为门比对）；② 原型**自带交互**的点击冒烟（按钮 / 链接 / 表单切换是否触发 JS 错误）。这是对静态设计原型的「查看界面 + 模拟操作」，与实现无关。',
+    `- 关联前端功能（仅作分组参考，不强制一一对应）：${feList}。`,
+    attempt > 1 ? `- 本次 = attempt ${attempt}（上次 \`status:blocked\` 环境未就绪后重试）。` : '',
+    '',
+    '## step0 发现原型 + 探测环境',
+    `- Glob \`${c.root}/prototype/**/*.html\`，得页面清单 = \`pagesFound\`。**空**（项目无原型）→ 直接返回 \`{ "status":"ok", "pagesFound":0, "pagesRendered":0, "pages":[] }\`，不报错、不写任何文件。`,
+    '- 探测 Playwright 是否可用（`frontend/node_modules` 内或全局）+ 浏览器内核是否已装。不可用 → `status:"blocked"` + `envError.kind="playwright-missing"|"browser-missing"`（**不要**尝试 `npm install` / `playwright install`——环境就绪由上层处理）。',
+    '',
+    '## step1 渲染 + 截图（确定性）',
+    `- 入口清目录：删除并重建 \`${tmpDir}/\`（确定性、跨平台：\`fs.rmSync(p,{recursive:true,force:true})\` 后 \`fs.mkdirSync(p,{recursive:true})\`；**仅限**此路径）。`,
+    `- 在 \`${tmpDir}/\` 写一次性 runner（如 \`run.mjs\`）：用 Playwright headless 逐页加载。优先 \`file://\` 直开；若原型用了相对 fetch / 根绝对路径资源导致 file:// 加载不全 → 起一个**仅服务 \`${c.root}/prototype/\` 静态目录**的临时本地服务器（端口确定性派生，\`finally\` 中 teardown）。`,
+    '- 视口确定性（默认 1440×900；某原型在 `<meta viewport>` / 注释里声明了特定尺寸则用之并记 `decisions[]`）。每页 `waitForLoadState` 稳定后整页截图。',
+    `- 截图归档到**已纳入版本管理**的 \`${assets}/<安全文件名>.png\`（文件名按原型相对路径确定性派生，如 \`prototype/order/list.html\` → \`order__list.png\`；**不要**引用 \`.tmp\` 防断链）。\`pagesRendered\` = 成功截图页数。`,
+    '',
+    '## step2 原型自带交互冒烟（模拟操作）',
+    '- 每页注册 `page.on("pageerror")`（收 JS 异常）与 `page.on("console")`（收 `error` 级）；注册 `page.on("dialog")` 自动 dismiss，防原生 `confirm/alert` 阻塞。',
+    '- 枚举页面可见可点控件（`button` / `a[href]` / `[role=button]` / `input` / `select` / 带 `onclick` 的元素），逐个**点击 / 切换一次**。`target=_blank` / 会 `window.open` 的只记不点（防新窗暴增）。`controlsExercised` 计实际驱动的控件数。',
+    '- 收集每页 `jsErrors`（pageerror 文本）/ `consoleErrors`（console.error 文本）——**原型自身**的脚本质量信号，仅作记录（advisory）。',
+    '- `finally` 中 kill 临时静态服务器（若起过）。',
+    '',
+    '## step3 证据落盘 + commit',
+    `- 写 \`${evidence}\`：按页一小节（原型相对路径 / 截图链接 / controlsExercised / jsErrors / consoleErrors / 视口决策），头部写 pagesFound-Rendered 汇总。渲染失败 / JS 错用**红字**标注为**阻断项**（上层据此 halt——回 /erp-workflow:plan-start 或 /add-req 修原型后重跑，**不在 coding 改**）；console.error 标注为 advisory。`,
+    commitBlock(`${evidence} ${assets}`, 'docs(preview:prototype): 静态原型渲染基线 + 交互冒烟证据', undefined, c),
+    '',
+    '## 输出（必须符合下发的 PROTOTYPE_PREVIEW JSON schema）',
+    '- `status`: `ok`（渲染门正常跑完——即使某页渲染失败/有 JS 错也填 ok，硬/软由上层 JS 据 `pages[]` 分流）| `blocked`（**仅限**环境未就绪：Playwright / 浏览器缺失 / 超时）。',
+    '- `pages[]` **据实填**（上层据此判硬门）：`rendered=false` 或 `jsErrors` 非空 = 硬缺陷（上层会 halt 等人工修原型）；`consoleErrors` = 软信号（advisory）。`pagesFound` / `pagesRendered` 整数据实填；每页 file / rendered / screenshot / controlsExercised / jsErrors / consoleErrors / notes。',
+    '- `envError`: 无环境问题填 `{ "kind":"none" }`；环境未就绪填对应 kind + detail。',
+    '- 做过自主默认（视口 / 服务方式等）→ `decisions[]` 逐条登记。`artifactPath` = 证据报告项目根相对路径。',
+    '- schema 是 `additionalProperties:false`，不要返回额外字段。**不要自动重试**——重试由上层 Workflow 控制。',
+  ].filter(Boolean).join('\n')
+}
+
 // ---- 前端行为验收（阶段级行为门，v3）----
 // 设计权威：docs/design/2026-06-05-frontend-behavior-stage-gate.md。
 // 时机：featureLoop(frontend) 全部 FE 通过静态 review（req-done tag 已打）之后、testGate 之前，
@@ -1099,6 +1201,8 @@ const ADJUDICATE_MAX = 3                       // 单个 site 的仲裁轮上限
 //  - BEHAVIOR_ATTEMPT_MAX = 单个 behaviorRound 内的环境 race 重起上限（沿用 testGate attempt 1→2 思路）。
 const BEHAVIOR_STAGE_MAX = 3
 const BEHAVIOR_ATTEMPT_MAX = 2
+// 静态原型渲染门（Preview）的环境 race 重起上限（Playwright/浏览器缺失/超时时自动重起，沿用 behavior attempt 思路）。
+const PROTOTYPE_PREVIEW_ATTEMPT_MAX = 2
 const NULL_AGENT_PROBLEM = 'agent() 返回 null（子代理终端 API 错误 / 被用户跳过）——典型为断网或机器休眠；可重试'
 const adjGuidance = (g) => g ? `\n\n## 仲裁返回的纠正指令（本次重跑必须遵守）\n${g}` : ''
  
@@ -2747,6 +2851,85 @@ const isBuildFailed = (r) =&gt; !!(r.envError &amp;&amp; r.envError.kind === &#39;build-failed&#39;
 // runBehaviorGateOnce：跑一次阶段级行为验收（含内部 envError attempt 重试 + 空覆盖兜底）。
 // 返回最终 bg（BEHAVIOR_GATE_SCHEMA）；不在内部收敛交互/文字（交给外层 runBehaviorGate 推进）。
 // behaviorRound：阶段门内的行为 fix 轮；内部 attempt 1..BEHAVIOR_ATTEMPT_MAX（环境 race 重起）+ 仲裁兜底。
+// runPrototypePreview：静态原型渲染门主驱动（被前端段开头调用，phase('Preview') 下）。
+// 与 runBehaviorGate 正交——本门只渲染静态 prototype/。两类边界严格分流：
+//  - **硬门（halt）**：原型**渲染失败**（rendered=false）或**原型脚本未捕获异常**（jsErrors=pageerror）——
+//    经仲裁 allowContinue:false（只许 retry/halt）。原型属上游 plan 权威、coding 不改原型源码——故 halt =
+//    「停下等人工回 /erp-workflow:plan-start 或 /add-req 修原型后重跑」，不是在 coding 里改原型。
+//  - **advisory**：console.error（弱信号，缺图标/CDN 警告等噪声多）——只记 decisions 不阻断。
+//  - **环境未就绪**（Playwright/浏览器缺失/超时）：retry→仲裁 allowContinue:true（不让「机器没装浏览器」卡死 coding）。
+// 终波恒宽 1、主根执行（c.lane==null）；静态渲染无 DB、无需 ERP_TEST_DB_SCHEMA 注入。
+async function runPrototypePreview(feItems, c) {
+  const lbl = (a) => `preview:proto:a${a}`
+  let attempt = 1
+  let pv = await agentR(prototypePreviewPrompt(feItems, attempt, c),
+    {label: lbl(attempt), phase: 'Preview', schema: PROTOTYPE_PREVIEW_SCHEMA})
+  recordDecisions('preview:prototype', pv.decisions, c.decisions)
+  // 环境未就绪 → 自动重起 attempt 1→PROTOTYPE_PREVIEW_ATTEMPT_MAX；仍 blocked → 进仲裁循环。
+  while (pv.status === 'blocked' && attempt < PROTOTYPE_PREVIEW_ATTEMPT_MAX) {
+    attempt += 1
+    pv = await agentR(prototypePreviewPrompt(feItems, attempt, c),
+      {label: lbl(attempt), phase: 'Preview', schema: PROTOTYPE_PREVIEW_SCHEMA})
+    recordDecisions('preview:prototype', pv.decisions, c.decisions)
+  }
+  for (let adj = 1; pv.status === 'blocked' && adj <= ADJUDICATE_MAX; adj++) {
+    const ev = pv.envError || { kind: '?', detail: '' }
+    // allowContinue:true——渲染门只产可视化基线（非硬正确性边界）；环境长期缺 Playwright 时仲裁可降级跳过，
+    // 不让「机器没装浏览器」卡死整个 coding（与行为门的 allowContinue:false 严格区分）。
+    const verdict = await adjudicate('preview-env:prototype',
+      { problem: `原型渲染门环境未就绪 envError=${ev.kind}: ${ev.detail || ''}`, envError: pv.envError || null, allowContinue: true },
+      'Preview', adj, c.root)
+    if (verdict.action === 'continue') {
+      log(`原型渲染门：环境未就绪经仲裁降级为口头建议继续（${ev.kind}）——本次跳过原型可视化基线`)
+      recordDecisions('preview:prototype',
+        [{ question: '原型渲染门环境未就绪', choice: '降级继续（跳过可视化基线）', rationale: ev.detail || ev.kind, confidence: 'low' }], c.decisions)
+      return pv
+    }
+    if (verdict.action !== 'retry') throw new Error(`HALT preview-env prototype: ${verdict.rationale || ev.kind}`)
+    attempt += 1
+    pv = await agentR(prototypePreviewPrompt(feItems, attempt, c),
+      {label: lbl(attempt), phase: 'Preview', schema: PROTOTYPE_PREVIEW_SCHEMA})
+    recordDecisions('preview:prototype', pv.decisions, c.decisions)
+  }
+  if (pv.status === 'blocked') throw new Error(`HALT preview-env prototype: ${ADJUDICATE_MAX} 轮仲裁后原型渲染门仍环境未就绪`)
+  // 至此 env 就绪（status:ok）。硬门评估（含仲裁 retry 重跑——疑似一次性渲染抖动/超时被误判时重跑一次门）：
+  //  硬缺陷 = 渲染失败(rendered=false) 或 原型脚本未捕获异常(jsErrors)；console.error 仅 advisory（弱信号）。
+  for (let adj = 1; adj <= ADJUDICATE_MAX; adj++) {
+    if (pv.pagesFound === 0) {
+      log('原型渲染门：项目无 prototype/**/*.html，跳过（无可视化基线可产）')
+      return pv
+    }
+    const pages = Array.isArray(pv.pages) ? pv.pages : []
+    const hardBroken = pages.filter(p => p && (!p.rendered || (p.jsErrors || []).length))
+    const consoleOnly = pages.filter(p => p && p.rendered && !(p.jsErrors || []).length && (p.consoleErrors || []).length)
+    // advisory：渲染成功但有 console.error 的页只记 decisions，不阻断。
+    if (consoleOnly.length) {
+      recordDecisions('preview:prototype', consoleOnly.map(p => ({
+        question: `原型 ${p.file} 有 console.error`,
+        choice: '记录不阻断（弱信号，回 plan/add-req 酌情修）',
+        rationale: `consoleErrors=${(p.consoleErrors || []).length}`,
+        confidence: 'low' })), c.decisions)
+    }
+    if (!hardBroken.length) {
+      log(`原型渲染门：${pv.pagesRendered}/${pv.pagesFound} 页全部渲染通过（无渲染失败/JS 异常）——可视化基线已归档${consoleOnly.length ? `；${consoleOnly.length} 页有 console.error（advisory）` : ''}`)
+      return pv
+    }
+    const digest = hardBroken.map(p => `${p.file}（rendered=${p.rendered}, jsErrors=${(p.jsErrors || []).length}）`).join('; ')
+    // allowContinue:false——原型渲染失败/脚本异常是硬缺陷，仲裁只许 retry/halt，绝不放行带病原型进前端实现。
+    const verdict = await adjudicate('preview-broken:prototype',
+      { problem: `静态原型渲染门硬缺陷（渲染失败 / 原型脚本未捕获异常）：${digest}。原型属上游 plan 权威，coding 不改原型源码——应回 /erp-workflow:plan-start 或 /add-req 修原型后重跑。`,
+        allowContinue: false }, 'Preview', adj, c.root)
+    if (verdict.action !== 'retry') throw new Error(`HALT preview-broken prototype: ${verdict.rationale || digest}`)
+    // retry：重跑渲染门一次（仲裁判定疑似一次性，如渲染超时被误标 jsError）。
+    attempt += 1
+    pv = await agentR(prototypePreviewPrompt(feItems, attempt, c),
+      {label: lbl(attempt), phase: 'Preview', schema: PROTOTYPE_PREVIEW_SCHEMA})
+    recordDecisions('preview:prototype', pv.decisions, c.decisions)
+    if (pv.status === 'blocked') throw new Error(`HALT preview-env prototype: 硬门 retry 后又遇环境未就绪 envError=${(pv.envError || {}).kind || '?'}`)
+  }
+  throw new Error(`HALT preview-broken prototype: ${ADJUDICATE_MAX} 轮仲裁后原型仍有硬缺陷（渲染失败/JS 异常）`)
+}
+
 async function runBehaviorGateOnce(feItems, behaviorRound, c) {
   const lbl = (a) => `behavior:frontend-phase:r${behaviorRound}:a${a}`
   let attempt = 1
@@ -3180,6 +3363,11 @@ async function runModule(module, c) {
       await runCrossModule(module, c)                   // 替代被删 hook，JS 编排：diff → 分类 → 写日志
     }
     if (module.feItems.length) {                        // 前端段（仅末尾 frontend-phase 聚合模块）
+      // 静态原型渲染门（Preview）：前端段开头先渲染 prototype/**/*.html 本身——Playwright headless
+      // 截图归档为可视化基线 + 跑原型自带交互点击冒烟。与行为门（测实现）正交；advisory（原型属上游
+      // plan 权威，coding 不改原型源码，渲染/JS 问题只记证据不阻断）。静态渲染、不起全栈。终波主根执行。
+      if (c.lane == null) phase('Preview')
+      await runPrototypePreview(module.feItems, c)
       if (c.lane == null) phase('Frontend')
       // 前端骨架占位 stage（设计 § 2，前置依赖 A）：featureLoop 之前一次性建 App 外壳 + router 全量 lazy
       // 路由表（FeStub 占位）+ 无悬空导航——保证逐 FE 实现中途任意时刻 app 可构建可起、每 FE 路由可达，