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

> 日期：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 临时高亮须在退出/卸载时销毁。