AdLike2048/docs/方案-预览调试工作台.md

方案：预览调试工作台（零侵入）

日期：2026-10-14
范围：仅 preview-template/，不修改 assets/**，可拷贝到任意 Creator 3.8 项目。

1. 目标

浏览器预览中的运行时分析坞：可调布局、层级/属性（含点选与实时改值）、官方性能浮窗 + 历史曲线、资源缓存与内存估算、控制台。

不做：Prefab 编辑、序列化落盘、编辑器级 Inspector、项目内埋点。

2. 硬约束

• 零侵入：不新增/修改业务 TS；不要求项目调用 mark()。
• 全部代码在 preview-template/index.ejs + preview-template/workbench/**。
• 运行时只访问预览页引擎全局（cc）；在 <%- include(cocosTemplate) %> 之后加载并等待就绪。
• 可选软接口：window.__PreviewWorkbench.mark(label)（项目可不调用）。

3. 业务标记（模板侧）

来源	文案示例	实现
场景启动/改名	scene:Main	Director.EVENT_AFTER_SCENE_LAUNCH + 轮询 scene.name
前后台	game:hide/show	Game.EVENT_HIDE/SHOW
Bundle 新出现	bundle:xxx	轮询 assetManager.bundles diff
资源跳变	assets:+N	计数增幅超阈值（可关）
用户手动	user:…	性能面板按钮

无「大厅/战斗」等玩法语义；自愿 mark('battle') 可显示自定义标签。

4. 架构

preview-template/
  index.ejs
  workbench/
    css/workbench.css
    js/
      host.js                 # 等 cc、挂 __PreviewWorkbench
      bridge.js               # 壳侧 postMessage / 同域直调
      layout-core.js          # 布局生命周期 / 停靠树重建 / 工具栏 / 持久化
      layout-presets.js       # 分析/场景/精简预设树
      layout-render.js        # split/tabs/game 渲染与分割条
      layout-dock.js          # 面板拖拽停靠
      layout-tree.js          # 停靠树查找/清理/拆分
      layout-float.js         # 悬浮窗与面板开关记忆
      markers.js
      perf-sampler.js
      charts/ring-chart.js
      panels/perf.js
      panels/assets.js
      panels/hierarchy.js
      panels/inspector.js
      panels/console.js
      pick.js

游戏侧探针（?pw=game，见「方案-工作台性能隔离」）：

workbench/js/
  agent-util.js               # 节点遍历/序列化/指纹公共函数
  agent-core.js               # 探针构造、RPC、订阅、资源/游戏控制
  agent-serialize.js          # Inspector 属性读写
  agent-pick.js               # 画布点选与高亮
  agent-console.js            # console 钩子与格式化
  agent.js                    # 启动入口（创建 __PW_Agent）
  device.js / idle.js / perf-sampler.js / markers.js

5. 布局

• 隐藏官方预览工具栏，使用自研菜单（设备 / 旋转 / 帧率 / 暂停 / 游戏·检视 / 面板开关）。
• 设备选择后预览区显示手机边框（刘海可选），按逻辑分辨率缩放适配。
• Desktop 停靠树（接近 Creator）：
  • 拖到区域标题栏/中心 = 合并为同一区域页签
  • 拖到区域边沿 = 在该方向新建布局区域（递归拆分）
  • 横排含游戏时，上/下边沿只包住连续非游戏列（例如层级|属性下方），不横跨游戏区；竖排含游戏时左/右同理
  • 分割条拖拽改比例；localStorage 键 preview-workbench-layout-v7
  • 默认分析布局：竖屏 → 左上层级|属性、左下控制台（横跨两列）、中游戏、右性能；横屏 → 上层级|属性|游戏|性能、下控制台通栏
• 设备预览：设备框仅为容器（按可用区域与设备宽高比算出真实布局尺寸，禁止 transform: scale）；游戏画布 100% 铺满容器；setFrameSize = 容器 client 尺寸，触摸坐标与画面一致
• Compact：游戏最大化；面板互斥抽屉；底栏切换。

原型（Desktop 分析）

┌─ 官方 Toolbar ──────────────────────────────────────────┐
├─ WB: [Game|Inspect] [布局] [浮窗] [层级][属性][资源][性能][控制台]
├─ Hierarchy │     GameCanvas      │ Inspector ─┤
├────────────┴─────────────────────┴────────────┤
│ BOTTOM Perf Viz（曲线 + 自动/手动标记纵线）      │
└────────────────────────────────────────────────┘

6. 面板要点

• 性能：profiler.showStats 浮窗 + PerfSampler 环缓冲多曲线；暂停/清空/导出 CSV/打标记。
• 资源：仅 assetManager；按 Bundle/类型筛选排序；估算内存（不能算则 n/a）；GFX 总量对照；预览缩略图。
• 层级/属性：运行时树；可写 transform/active 等；Game/Inspect 切换；Inspect 下画布点选 + 高亮。
• 控制台：钩子 console.* 环缓冲。

7. 分期与验收

阶段	验收
P0	PC 拖拽布局持久化；手机抽屉；横竖屏画布正常；cc 就绪提示
P1	浮窗与曲线同源；自动 scene/bundle 标记；导出 CSV
P2	分类/分包/排序/估算/预览
P3	点选高亮；改属性实时生效
P4	级别过滤控制台

8. 风险

• 全局名以预览注入为准，失败提示「引擎未就绪」。
• 单资源 GPU 内存为估算，与 textureMemory 总量可能不一致，UI 并排标注。
• Inspect 临时高亮须在退出/卸载时销毁。