DevTools 扩展（@tripo3d/lens-devtools）
@tripo3d/lens 的 Chrome DevTools 调试扩展。装好后按 F12 多出一个 Tripo Lens 面板，能实时看每条实际上报的事件、扫描页面的声明式埋点元素，并双向高亮联动。
它是 纯外部观测——不改 SDK、不改业务接入代码、不发布到 npm、也不需要 import。装上扩展、打开面板，就能看到任何接入了 @tripo3d/lens 的页面真实发出去的事件。
它只能看见「真正上了网络」的事件
被采样 / Schema 校验 / killSwitch 在 SDK 内部丢弃的事件从不发出网络请求，外部观测的扩展也就看不到。要看「SDK 内部到底在哪一阶段丢的」，叠加打开 SDK 内置 Debug 桥的「管线」Tab——详见 用 playground + DevTools 联调管线 与 为什么这么设计。
下载与加载
它不发布到 npm、也无需自己构建——直接下载打包好的扩展，解压后加载到浏览器即可。
1. 下载
从 CDN 下载最新版扩展包（始终指向最近一次发布）：
- Chrome：https://assets.cdn.tripo3d.com/fe-tripo-tools/lens-devtools/latest/lens-devtools-chrome.zip
- Firefox：https://assets.cdn.tripo3d.com/fe-tripo-tools/lens-devtools/latest/lens-devtools-firefox.zip
历史版本在 https://assets.cdn.tripo3d.com/fe-tripo-tools/lens-devtools/<版本>/ 下按版本归档；也可以到仓库的 最新 Release 页下载。
下载后解压到任意目录，解压出来的那一层直接含 manifest.json（不再嵌套一层文件夹）。
2. 加载到 Chrome
- 打开
chrome://extensions，右上角开启「开发者模式」。 - 点「加载已解压的扩展程序」→ 选择上一步解压出来的目录（含
manifest.json的那层）。
- 目录在隐藏路径下时，文件选择框里按
Cmd+Shift+.显示隐藏文件夹。
- 升级新版：下载新版 zip → 覆盖解压 → 在扩展卡片点刷新图标重载。
要改扩展源码？
本地开发 / 自行构建产物的方式见 packages/lens-devtools/README.md（pnpm dev 热重载、pnpm build:ext 出 .output/chrome-mv3/）。普通使用者无需关心。
使用
适用于任何接入了 @tripo3d/lens 的页面（你的真实 app 等），无需改 SDK、无需 debug 开关。
- 打开目标页面（必须 http / https，content script 不注入
file://）。 - 先按 F12 打开 DevTools，切到顶部 Tripo Lens 面板。
- 让面板开着再刷新页面——之后所有上报才会被捕获。
面板只在打开期间抓网络
网络监听是在面板打开时才挂上的。如果先刷新页面、后开面板，刷新期间的上报抓不到——开着面板重新刷新即可。
典型调试工作流
下面两个场景覆盖日常埋点自查的绝大多数情况。
场景 A：确认某个埋点是否生效
- 点工具栏「扫描元素」→ 在右侧「追踪元素」找你的坐标；标黄 = 坐标非法（见 坐标规则）。
- 点该项 → 页面对应元素滚动到视口并闪烁，确认埋在了正确的元素上。
- 开着面板点击该元素 → 左侧「事件流」出现对应
click/expose。
场景 B：看某次操作实际报了什么
- 操作页面 → 「事件流」出现事件（最新在上，颜色=优先级，
×N=折叠计数）。 - 点该事件 → 中栏「详情」展示完整信封
{ context, payload, event_format, timestamp }。 - 点详情里的
event_format→ 页面高亮事件来源元素，反向定位。
怀疑「没上报」时——先用「扫描元素」分清是没埋上还是没发出；后者再走 排查：没有上报。
面板一览
顶部工具栏 + 三列主体 + 底部条。
| 区域 | 内容 | 交互 |
|---|---|---|
| 工具栏 | 扫描元素 / 暂停 / 清空；类型 下拉过滤 | — |
| 事件流（左） | 每条实际上报：颜色 = 优先级（P0 红 / P1 橙 / P2 默认色）、×N = 折叠计数、右侧时间，最新在上 | 点一行 → 看详情 |
| 详情（中） | 选中事件的完整信封 { context, payload, event_format, timestamp } JSON（全程 textContent 渲染，不执行内容） | 点 event_format → 页面高亮对应元素 |
| 追踪元素（右） | 点「扫描元素」后列出页面所有 data-trace* 元素及坐标（非法坐标标黄） | 点一项 → 页面滚动 + 闪烁 |
| 底部条 | 设备 / 会话 id（截短）；背压淘汰计数（来自批量壳 dropped） | — |
优先级由 event_type 推断（与 SDK priorityOf 一致）：P0 = landing / identity；P1 = 行为七类；P2 = error / performance 及未知。事件流上限 2000 条，超限丢最旧。
每列字段、阶段标识颜色、队列快照各字段的精确含义见 DevTools 面板字段参考。
故障排查
事件流空、坐标标黄、file:// 页面无反应等常见问题，统一收在 排查：没有上报。
下一步
- 用 playground + DevTools 联调管线：启用 SDK Debug 桥后，在「管线」Tab 看每条事件在 SDK 内部的逐阶段去向。
- DevTools 面板字段参考：事件流 / 管线 / 元素三个 Tab 每个字段、阶段颜色、队列字段的精确含义。
- 为什么这么设计：纯外部观测与 Debug 桥的取舍：默认零侵入的理由，以及何时该升级到启用 Debug 桥。
- 排查：没有上报：埋了没上报、看到一半、后端没数据的自上而下排查路径。
- 行为埋点：声明式
data-trace坐标规则与命令式 API。 - 远程配置：采样 / killSwitch 如何决定哪些事件会上报（即扩展能否看到）。