架构总览

@tripo3d/lens 把监控、埋点、归因、性能统一到一个采集内核。理解这张分层图，能解释「一条事件从产生到上报经过了什么」，也能帮你判断问题落在哪一层。

六层结构（L1–L6）

L1 公共 API       TripoLens —— 业务唯一接触面，稳定契约
L2 Core 内核      Identity · Session · Consent · Registry · EventBus · RemoteConfig · Breadcrumb
L3 Plugin 业务    Attribution(默认) · Identity(默认) · Tracking/Error/Performance(opt-in)
        │ RawEvent（仅经 ctx.emit）
L4 Pipeline 加工  Enricher → killSwitch → Sampler → Schema → PII → beforeEmit → Serializer
        │ WireItem
L5 Transport 传输 单队列三级优先级 · OfflineStore · fetch keepalive
L6 Platform 适配  storage · url · dom · lifecycle · ssr · performance …（所有平台访问必经此层）
        ▼
     后端网关（单 endpoint，X-DeviceId + 微服务路由头）

• L1 公共 API：业务唯一接触的 TripoLens——构造、init、track / identify / flush 等都在这层，对外是稳定契约。
• L2 Core 内核：身份、会话、Consent、插件注册表、事件总线、远程配置、面包屑等横切能力。
• L3 Plugin 业务：每种采集能力是一个插件。归因与身份默认装；行为 / 错误 / 性能 opt-in。插件只产出 RawEvent，经 ctx.emit 交给管线——装配与解耦见 插件与能力装配。
• L4 Pipeline 加工：原始事件统一加工成可上报的 WireItem。
• L5 Transport 传输：单队列分级上送、离线兜底、fetch keepalive。
• L6 Platform 适配：所有平台访问（window / localStorage / DOM / 生命周期）必经此层，这正是下方 SSR 安全 的基础——非浏览器环境整层短路。

事件如何在 L3→L4→L5 之间流动与变形（Pipeline 六阶段、单队列三级上送、统一信封），独立成篇见 事件的一生。

SSR 安全

所有浏览器副作用都收敛在 L6 平台适配层，并由 isBrowser 判定短路，因此主入口在非浏览器环境全程 no-op：

• 非浏览器环境下 init() 立即 resolve 且 no-op：不解析指纹、不拉配置、不上报。
• deviceId / sessionId 为空串、headers 为 {}，identify() / renewSession() 等也 no-op。
• 即便业务忘加 .client 后缀，库也不会在服务端爆错。

「import 不爆错」≠「采集了 SSR 数据」

主入口在服务端是全程 no-op；要采集 SSR 阶段的错误 / 性能，是另一套机制，见 SSR 采集。

@tripo3d/lens/server 是例外——它是 SSR 服务端原语，依赖 node: 模块，只能在服务端 import。

前后端职责边界

lens 是一个采集端：前端只做「采集 → 丰富上下文 → 本地缓冲 → 发到网关」。归因模型计算、Source Map 符号化、停留时长计算、device ↔ user 的 ID 合并一概归后端——前端只如实上报快照与原始数据。

理解这条边界能避免很多「为什么前端拿不到 XX」的疑问：landing 只带入口快照、看不到「第几次触达」；错误栈是未符号化的原始栈；hide / show / leave 只有时间点、没有 duration。

相关

• 事件的一生：上报数据长什么样、如何加工分级上送
• 插件与能力装配 · 远端配置治理
• API Reference（自动生成）