|
|
|
|
# 方案：工作台性能隔离（全功能保留）
|
|
|
|
|
|
|
|
|
|
> 日期：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 内跑；默认同域嵌入。
|
|
|
|
|
- 大场景层级序列化仍有成本 → 指纹跳过 + 仅可见时拉取。
|
