# 方案：工作台性能隔离（全功能保留）

> 日期：2026-10-14  
> 范围：仅 `preview-template/` + 本文档

## 1. 目标

在保留层级 / 属性 / 点选 / 性能 / 资源 / 控制台 / 设备框等全部能力的前提下，让游戏主线程**默认接近零开销**，并支持一键「纯净测帧」。

同页同线程无法做到严格 0 影响；本方案用三层隔离逼近：

1. **结构**：壳 document ↔ 游戏 iframe（可跨域争取进程隔离）
2. **行为**：游戏内 Agent 默认休眠，按面板订阅激活
3. **测帧**：`纯净测帧` → `hibernate()` 清空全部探针

## 2. 入口模式

| URL | 角色 |
|-----|------|
| `/` 或无 `pw` | **壳**：停靠布局 + 面板 + Bridge；中央 iframe 加载游戏 |
| `?pw=game` | **游戏**：引擎 + 设备框 + Agent（无工作台 DOM） |

跨域策略：壳在 `localhost` 时，iframe 优先 `127.0.0.1`（互为不同 origin）。约 5s 未就绪或 `agent.ready` 失败则写入 `sessionStorage.pw-cross-fail=1` 并**同域降级**。

## 3. 文件

```
preview-template/
  index.ejs                 # data-pw=shell|game 双模式
  workbench/js/
    agent-util.js           # 游戏侧公共：walk / findNodeByUuid / serializeNode / fingerprint
    agent-core.js           # 游戏探针 RPC + 订阅生命周期
    agent-serialize.js      # 属性 Inspector 序列化/写回
    agent-pick.js           # 画布点选
    agent-console.js        # console 钩子与格式化
    agent.js                # 启动入口（先挂 __PW_Agent 再 boot）
    bridge.js               # 壳侧 postMessage / 同域快路径
    idle.js                 # requestIdleCallback 2ms 切片（run 可续跑）
    host.js                 # 仅壳：布局 + 订阅同步
    layout-*.js             # 仅壳：core/presets/render/dock/tree/float
    panels/*                # 仅壳：不直接碰 cc
```

## 4. 订阅与休眠

| 通道 | 激活条件 | 行为 |
|------|----------|------|
| `perf` | 性能面板可见 | 采样（默认 500ms），壳侧 200ms 合并绘曲线 |
| `markers` | 随 perf | scene/bundle 轮询 |
| `hierarchy` | 层级可见 | 指纹变化才推树 |
| `inspector` | 属性可见 | 按需 `node.get/set` |
| `assets` | 资源可见 | idle 切片枚举 |
| `console` | 控制台可见 | hook + 100ms 合批 |
| `pick` | 检视模式 | 点选；选中后 ≤10fps 推 AABB |

默认：无 interval、无 console hook、无 rAF、不 `showStats`。

## 5. 验收

- 默认打开壳、不点面板：游戏 iframe 内 Agent 无定时器；开「纯净测帧」后帧耗时接近裸预览。
- 只开性能 / 层级 / 控制台：仅对应通道有流量；关闭即停。
- 跨域失败自动同域，功能仍可用。

## 6. 风险

- Creator 预览可能只监听单一 host → 跨域失败属预期，走同域降级。
- **壳页禁止执行 `cocosTemplate`**（放入 `<template>`，仅 `?pw=game` 激活）。双引擎会打崩 Electron/Cursor。游戏只在 iframe 内跑；默认同域嵌入。
- 大场景层级序列化仍有成本 → 指纹跳过 + 仅可见时拉取。