fix(pbl_scense_ext): 生成产物入库声明与仓库事实一致（QC #9）

wwwroot/pbl_overlay/*.ui 是构建产物，此前未列入 .gitignore 却已被 12 个 .ui 跟踪入库，与 gen_overlay_pages.py docstring「不入库、已在 .gitignore 排除」的自述矛盾。采用方案(a)消除矛盾： - .gitignore 追加 wwwroot/pbl_overlay/ - git rm --cached wwwroot/pbl_overlay/*.ui（仅解除跟踪，磁盘文件保留，由 apps/pbls/build.sh 第9步重跑生成） - docstring 写明具体排除条目并附 git check-ignore / git ls-files 自检命令 - README 新增「生成产物与入库边界」章节，与仓库事实一致验证：git check-ignore -v 命中 .gitignore:15；git ls-files wwwroot/pbl_overlay 为空； python3 scripts/gen_overlay_pages.py --check rc=0。
2026-09-21 12:50:40 +08:00 · 2026-09-21 12:50:40 +08:00 · a451b1d413
commit a451b1d413
parent 3742c65c32
15 changed files with 28 additions and 951 deletions
--- a/.gitignore
+++ b/.gitignore
@ -10,3 +10,6 @@ dist/
 build/
 .venv/
 venv/
+
+# M9 覆盖层页面壳：构建产物，由 apps/pbls/build.sh 第9步 scripts/gen_overlay_pages.py 重新生成，不入库
+wwwroot/pbl_overlay/
--- a/README.md
+++ b/README.md
@ -1,2 +1,21 @@
 # pbl_scense_ext

+PBL 覆盖层前端扩展模块（scense / scense_game 之上的 pbl_scense_ext 覆盖层与页面注册，M9）。
+
+## 生成产物与入库边界
+
+- `wwwroot/pbl_overlay/*.ui`（12 个覆盖层页面壳）是**构建产物，不入库**：仓库根
+  `.gitignore` 以条目 `wwwroot/pbl_overlay/` 排除该目录，由 `apps/pbls/build.sh`
+  第 9 步调用 `python3 scripts/gen_overlay_pages.py` 重新生成
+  （module-development-spec「CRUD-Generated wwwroot Directories Must Not Be Git-Tracked」）。
+- 入库的交付物是**生成器与事实源**：`scripts/gen_overlay_pages.py`（生成器）、
+  `wwwroot/i18n/{zh,en}/msg.txt`（界面文案事实源）、`wwwroot/overlay/*.js|*.css`
+  （覆盖层实现）、`scripts/load_path.py`（RBAC 路径登记）。
+- 一致性自检（两条都必须成立）：
+  ```bash
+  git check-ignore -v wwwroot/pbl_overlay/home.ui   # 命中 .gitignore 的 wwwroot/pbl_overlay/
+  git ls-files wwwroot/pbl_overlay                  # 空输出（无任何跟踪文件）
+  ```
+- 新增/删除页面壳：改 `gen_overlay_pages.py` 的 `PAGES` 注册表 + `wwwroot/overlay/pbl_overlay_core.js`
+  的 `PAGES` + `scripts/load_path.py` 的 `OVERLAY_PAGES` 三处同源，再跑
+  `python3 scripts/gen_overlay_pages.py --check`（rc=0 才算通过）。
--- a/scripts/gen_overlay_pages.py
+++ b/scripts/gen_overlay_pages.py
@ -3,9 +3,12 @@
 """生成 M9 覆盖层 12 个页面壳 wwwroot/pbl_overlay/<key>.ui（bricks 纯 JSON）。

 【产物定位：构建产物，不入库】
-wwwroot/pbl_overlay/*.ui 属生成目录，已在 .gitignore 中排除，由
-apps/pbls/build.sh 第 9 步调用本脚本重跑生成（module-development-spec
-「CRUD-Generated wwwroot Directories Must Not Be Git-Tracked」/ QC 退回意见 #3 方案 (b)）。
+wwwroot/pbl_overlay/*.ui 属生成目录，仓库根 .gitignore 以条目
+`wwwroot/pbl_overlay/` 将其排除，由 apps/pbls/build.sh 第 9 步调用本脚本重跑生成
+（module-development-spec「CRUD-Generated wwwroot Directories Must Not Be Git-Tracked」/
+QC 退回意见 #3 方案 (b)）。可核验：
+    git check-ignore -v wwwroot/pbl_overlay/home.ui   # 命中 .gitignore 中的该条目
+    git ls-files wwwroot/pbl_overlay                  # 输出为空（无跟踪文件）
 本脚本（生成器）与 wwwroot/i18n/*/msg.txt（文案事实源）才是入库的交付物。

 为什么需要页面壳：wwwroot/overlay/pbl_overlay_core.js 的 PAGES 注册表 route 指向
--- a/wwwroot/pbl_overlay/agent_console.ui
+++ b/wwwroot/pbl_overlay/agent_console.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · Agent 控制台",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_agent_console",
-      "options": {
-        "html": "<div data-pbl-page=\"agent_console\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">Agent 控制台（agent_console）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为教师/学生侧页面（首屏预算 ≤1.5s）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'agent_console'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'agent_console'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/approval_center.ui
+++ b/wwwroot/pbl_overlay/approval_center.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 人工审批中心",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_approval_center",
-      "options": {
-        "html": "<div data-pbl-page=\"approval_center\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">人工审批中心（approval_center）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为教师/学生侧页面（首屏预算 ≤1.5s）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'approval_center'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'approval_center'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/artifact_studio.ui
+++ b/wwwroot/pbl_overlay/artifact_studio.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 产出物工坊",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_artifact_studio",
-      "options": {
-        "html": "<div data-pbl-page=\"artifact_studio\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">产出物工坊（artifact_studio）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为世界内覆盖层（广播渲染预算 ≤500ms）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'artifact_studio'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'artifact_studio'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/assessment_report.ui
+++ b/wwwroot/pbl_overlay/assessment_report.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 评估报告",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_assessment_report",
-      "options": {
-        "html": "<div data-pbl-page=\"assessment_report\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">评估报告（assessment_report）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为教师/学生侧页面（首屏预算 ≤1.5s）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'assessment_report'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'assessment_report'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/blueprint_editor.ui
+++ b/wwwroot/pbl_overlay/blueprint_editor.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 蓝图结构视图",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_blueprint_editor",
-      "options": {
-        "html": "<div data-pbl-page=\"blueprint_editor\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">蓝图结构视图（blueprint_editor）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为教师/学生侧页面（首屏预算 ≤1.5s）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'blueprint_editor'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'blueprint_editor'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/blueprint_list.ui
+++ b/wwwroot/pbl_overlay/blueprint_list.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 蓝图列表",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_blueprint_list",
-      "options": {
-        "html": "<div data-pbl-page=\"blueprint_list\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">蓝图列表（blueprint_list）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为教师/学生侧页面（首屏预算 ≤1.5s）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'blueprint_list'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'blueprint_list'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/evidence_wall.ui
+++ b/wwwroot/pbl_overlay/evidence_wall.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 证据墙",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_evidence_wall",
-      "options": {
-        "html": "<div data-pbl-page=\"evidence_wall\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">证据墙（evidence_wall）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为世界内覆盖层（广播渲染预算 ≤500ms）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'evidence_wall'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'evidence_wall'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/home.ui
+++ b/wwwroot/pbl_overlay/home.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · PBL 首页",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_home",
-      "options": {
-        "html": "<div data-pbl-page=\"home\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">PBL 首页（home）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为教师/学生侧页面（首屏预算 ≤1.5s）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'home'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'home'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/mission_board.ui
+++ b/wwwroot/pbl_overlay/mission_board.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 驱动问题板",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_mission_board",
-      "options": {
-        "html": "<div data-pbl-page=\"mission_board\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">驱动问题板（mission_board）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为世界内覆盖层（广播渲染预算 ≤500ms）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'mission_board'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'mission_board'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/play_preview.ui
+++ b/wwwroot/pbl_overlay/play_preview.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · Play 预览",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_play_preview",
-      "options": {
-        "html": "<div data-pbl-page=\"play_preview\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">Play 预览（play_preview）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为世界内覆盖层（广播渲染预算 ≤500ms）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'play_preview'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'play_preview'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/role_panel.ui
+++ b/wwwroot/pbl_overlay/role_panel.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 角色面板",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_role_panel",
-      "options": {
-        "html": "<div data-pbl-page=\"role_panel\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">角色面板（role_panel）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为世界内覆盖层（广播渲染预算 ≤500ms）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'role_panel'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'role_panel'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}
--- a/wwwroot/pbl_overlay/validation_report.ui
+++ b/wwwroot/pbl_overlay/validation_report.ui
@ -1,79 +0,0 @@
-{
-  "widgettype": "VBox",
-  "options": {
-    "width": "100%",
-    "height": "100%",
-    "padding": "12px",
-    "backgroundColor": "#0B1020"
-  },
-  "subwidgets": [
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "PBL 覆盖层 · 校验报告(14维)",
-        "fontSize": "18px",
-        "fontWeight": "bold",
-        "color": "#E5E7EB"
-      }
-    },
-    {
-      "widgettype": "Html",
-      "id": "pbl_overlay_shell_validation_report",
-      "options": {
-        "html": "<div data-pbl-page=\"validation_report\" data-pbl-overlay-root=\"1\" class=\"pbl-shell\"><div class=\"pbl-shell-hint\">校验报告(14维)（validation_report）· 覆盖层未启用：点击下方「启用 PBL 覆盖层」装配 PBL 组件；本页为教师/学生侧页面（首屏预算 ≤1.5s）。</div></div>"
-      }
-    },
-    {
-      "widgettype": "HBox",
-      "options": {
-        "width": "100%",
-        "gap": "8px",
-        "marginTop": "10px"
-      },
-      "subwidgets": [
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "启用 PBL 覆盖层",
-            "type": "primary"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "script",
-              "options": {
-                "script": "window.PblOverlayLoader?PblOverlayLoader.start({page:'validation_report'}):(function(){var b=String(window.__PBL_API_BASE__||'').replace(/\\/$/,'');var s=document.createElement('script');s.src=b+'/pbl_scense_ext/overlay/pbl_overlay_loader.js';s.async=false;s.onload=function(){window.PblOverlayLoader.start({page:'validation_report'})};s.onerror=function(){window.__pblOverlayFail&&window.__pblOverlayFail('PBL_E_NETWORK','覆盖层引导脚本加载失败')};document.head.appendChild(s);})()"
-              }
-            }
-          ]
-        },
-        {
-          "widgettype": "Button",
-          "options": {
-            "label": "PBL 首页"
-          },
-          "binds": [
-            {
-              "wid": "self",
-              "event": "click",
-              "actiontype": "url",
-              "options": {
-                "url": "{{entire_url('/pbl_scense_ext/pbl_overlay/home.ui')}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "widgettype": "Text",
-      "options": {
-        "label": "上下文：URL 携带 session_id / blueprint_id / world_id；覆盖层仅渲染服务端权威状态，不本地预测（Q4）。",
-        "fontSize": "12px",
-        "color": "#6B7280",
-        "marginTop": "10px"
-      }
-    }
-  ]
-}