用 playground + DevTools 联调管线
DevTools 扩展的「事件流」Tab 只能看见真正发到网络的事件——被采样 / Schema / killSwitch / Consent 在 SDK 内部丢弃的事件，事件流抓不到。要看每条事件在 SDK 管线里的逐阶段去向（被谁丢、被谁改写），需要打开「管线」Tab，它由 SDK 内置的 Debug 桥提供数据。
本页是一条联调路径：在 playground 或任意接入页启用 Debug 桥 → 在「管线」Tab 观察 ingress / queue / stage 阶段事件。
仅本地 / 测试启用，生产禁用
Debug 桥会把采样 / PII 清洗之前的原始事件（含潜在 PII）经 window.postMessage 广播到同源页面。生产环境绝不能开启——SDK 默认关闭，需手动开关；启用后请在收工时关回。
前置条件
- DevTools 扩展已加载到 Chrome，并能在目标页打开 Tripo Lens 面板。
- 目标页是 http / https（playground 本地启动即可，
file://不行）。 - 目标页接入了
@tripo3d/lens且init()已执行——Debug 桥只在装配时解析一次，故启用后需刷新页面。
步骤 1：启用 Debug 桥（三选一）
Debug 桥默认关闭。SDK 提供三种等价的启用方式（来自 @tripo3d/lens 构造参数 debug 与运行期 flag）：
方式 A：DevTools 面板按钮（推荐用于已部署的页面）
- F12 → Tripo Lens 面板 → 切到「管线」Tab。
- 点顶部「开启内部观测」按钮。
- 按钮右侧出现黄色提示「已通知页面 → 请刷新被检页面使 lens 装配生效」——按提示刷新当前页。
面板按钮的本质是替你在被检页面写下 localStorage['__tripo_lens_debug']='1'，因此刷新后即生效；不想再开就清掉该键。
方式 B：localStorage flag（推荐用于本地 playground）
在被检页面的 DevTools Console 执行：
localStorage.setItem('__tripo_lens_debug', '1');
location.reload();关闭：localStorage.removeItem('__tripo_lens_debug')。
方式 C：构造参数 debug: true（仅本地代码调试）
仅在本地代码中临时改一下，不要提交：
const trace = new TripoLens({
app: 'shop',
configUrl: '…',
endpoint: '…',
debug: true, // 仅本地 / 测试
});三种方式互相等价，但显式 debug: false 一票否决
构造参数 debug 缺省时，三种方式只要任一为真，SDK 就会动态加载 Debug 桥（@tripo3d/lens/debug 异步 chunk），不会进入主包初始 bundle。但构造时显式传 debug: false 是硬关：该实例拒绝页面级 flag（方式 A / B 对它无效）——跑分、高吞吐等静默实例用它防 postMessage 洪泛。SSR / 非浏览器环境一律不装配。
步骤 2：打开「管线」Tab
启用并刷新后：
- F12 → Tripo Lens 面板 → 顶部切到「管线」Tab。
- 顶部按钮区域下方会出现队列快照栏（
队列 size … · P0/P1/P2 … · 淘汰 …），证明 Debug 桥已成功广播queue事件。 - 下面的「管线 N」列表此时多半还是空的——管线条目由事件原始数据触发（
ingress事件），需要先在页面上触发一次上报。
队列快照栏什么时候出现？
SDK 在事件入队 / 出队 / 背压淘汰时都会经 Debug 桥广播 QueueDebugSnapshot。打开管线 Tab 后没有快照栏，多半是页面还没产生过任何事件——做一次操作或刷新页面即可。
步骤 3：触发一次上报
在被检页面上做一次会上报的操作，例如：
- playground 任意 flow 页（快速开始 / 行为埋点 等）点击 demo 上的「track」「click」按钮。
- 真实接入页 点击带
data-trace的元素，或手动trace.track('coord', { … })。 - 刷新页面：会触发
landing/ 归因等 P0 事件。
回到「管线」Tab：
- 列表里最新在最上多出一条「管线条目」，左侧是事件原始
type（如click、pageview、landing），右侧是一串阶段标识小色块。 - 队列快照栏的
size/P0/P1/P2数字会随入队 / 出队跳动。
步骤 4：观察 ingress / queue / stage
每条管线条目对应一条事件的完整生命周期，Debug 桥广播三类消息：
| 桥消息 | 触发时机 | 在面板上的体现 |
|---|---|---|
ingress | 原始事件进入管线（采样前） | 列表新增一条「管线条目」，展开后顶部「原始 raw（采样前）」块就是这条 |
stage | 每个管线阶段产出 | 折叠态的色块序列；展开态的每个 <stage> · <outcome> 块 |
queue | 队列 / 批次状态变化 | 顶部的队列快照栏 |
点条目左侧 ▸ 展开，能看到事件流经的每个阶段及其产物。常见阶段名（顺序属内部约定）：enrich / sample / schema / pii / beforeEmit / serialize。
字段细节（outcome 颜色、阶段意义、队列快照各字段）请直接看 DevTools 面板字段参考 · 管线 Tab，本页不重复。
常见现象解读
| 现象 | 解读 | 跳转 |
|---|---|---|
列表里事件类型字变红、末尾有 ✕ <stage> 丢弃 | 该事件在某个管线阶段被丢弃；展开后那一阶段是红色 dropped 色块 | 阶段含义 → 面板字段参考 |
阶段是橙色 mutated | 该阶段改写了事件（典型：pii 清洗）；产物 JSON 是改写后的版本 | 面板字段参考 |
队列快照栏 淘汰 P1 / P2 数字不停涨 | 队列背压淘汰，与「管线丢弃 N」不是一回事：前者是入队后在出队前丢的，后者是任一管线阶段丢的 | 面板字段参考 |
| 管线列表里有事件、事件流 Tab 却没有 | 这条事件在管线里被丢弃了，根本没发到网络——这正是「事件流看不见、管线看得见」的场景 | 排查：没有上报 |
| 启用并刷新后管线 Tab 仍然全空 | ① flag 没生效（重开 DevTools / 重启 SDK 都不够，必须刷新被检页面）；② 页面是 SSR / 非浏览器环境 | DevTools 扩展 · 使用 |
队列快照栏的 淘汰 与事件流底部条对不上 | 二者同源，差值只是面板打开时机不同（事件流从打开后的首个批次算累计，管线从 Debug 桥广播首个快照算累计） | 面板字段参考 |
收工：关闭 Debug 桥
调试完务必关回，避免页面继续向所有同源监听者广播事件：
- 方式 A / B：被检页面 Console 执行
localStorage.removeItem('__tripo_lens_debug')，刷新页面。 - 方式 C：把
debug: true从代码里去掉，重新构建部署。 window.__TRIPO_LENS_DEBUG__历史 flag 同理delete window.__TRIPO_LENS_DEBUG__后刷新。
下一步
- DevTools 扩展：面板的工作原理、构建加载、典型调试场景。
- DevTools 面板字段参考：管线 Tab 每个字段、阶段标识颜色、队列快照各字段的精确含义。
- 排查：没有上报：自上而下分清「没埋上 / 被过滤 / 发出了没到后端」。