@blueking/open-telemetry 0.0.22-beta.1 → 0.0.23

package/skills/bk-rum-otele/references/api.md

@@ -2,338 +2,371 @@
 
 # API 参考
 
-本页只描述 `src/index.ts` 公开导出的 API。深层路径文件属于实现细节，接入方不应直接 import。
+本文只描述 `src/index.ts` 当前公开导出的 API。日常接入优先使用 `BkOpenTelemetry` 的生命周期、上下文和手动上报方法；运行时底层方法主要服务自定义插件。
 
 ## 创建实例
 
 ```ts
-import { BkOpenTelemetry, type BkOTOptions } from '@blueking/open-telemetry';
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
-const options: BkOTOptions = {
-  application: { name: 'bk-rum-demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-};
+const rum = new BkOpenTelemetry({
+  application: { name: 'order-center' },
+  transport: { endpoint: 'https://rum.example.com' },
+});
+```
+
+构造函数会同步完成：
+
+1. 校验并解析配置；
+2. 创建 Resource、`WebTracerProvider`、Session sampler、过滤处理器和 exporter；
+3. 获得 instrumentation name 为 `bk-rum` 的 Tracer；
+4. 如果 `autoStart !== false`，异步调用 `start()`。
+
+构造函数不会创建 MeterProvider 或 LoggerProvider。`autoStart` 的异步失败只会在控制台输出 `[bk-ot] auto start failed` 警告；如果业务必须感知启动结果，应设置 `autoStart: false` 并显式 `await rum.start()`。
 
-const bkOT = new BkOpenTelemetry(options);
+CDN bundle 的默认导出会挂到：
+
+```js
+window.BkOpenTelemetry
 ```
 
-构造函数同步解析配置并创建三个 OpenTelemetry Provider；`autoStart: true` 时随后异步启动采集。完整配置见[配置参考](./configuration.md)。
+## 生命周期 API
 
-## 生命周期方法
+### `start(): Promise<void>`
 
-### start()
+安装内置/自定义插件、全局 OTel context/propagator，并启用 extensions 中的 instrumentation。
 
 ```ts
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'bk-rum-demo' },
+const rum = new BkOpenTelemetry({
+  application: { name: 'order-center' },
+  transport: { endpoint: 'https://rum.example.com' },
   autoStart: false,
-  transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
-bkOT.use(myPlugin);
-await bkOT.start();
+await rum.start();
 ```
 
-启动 Session、View、内置插件、接入方插件和 instrumentations，并安装页面隐藏时的 flush 监听。重复调用 `start()` 不会重复启动。
+行为：
+
+- 已启动或正在启动时重复调用会直接返回；
+- `enabled: false` 时把实例标记为已启动，但不安装采集；
+- Consent 为 `not-granted` 时不安装采集，之后可授权启动；
+- 单个插件初始化失败不会阻断其余插件，`debug: true` 时打印警告；
+- 整体启动异常会清理已安装内容并恢复到可再次启动的 idle 状态；
+- `shutdown()` 后再次调用会抛错，必须创建新实例。
 
-### flush()
+### `flush(): Promise<void>`
+
+并行调用已启动插件的 `flush()`，然后 `forceFlush()` Trace Provider。
 
 ```ts
-await bkOT.flush();
+await rum.flush();
 ```
 
-先并行调用已启动插件的 `flush()`，再 force flush Trace Provider。SDK 已在 `pagehide` 和页面变为 hidden 时触发 flush；业务只需在关键流程完成后按需主动调用。
+适用于测试、关键跳转前尽力发送和联调。它不是服务端持久化确认，也无法突破浏览器退出时的网络限制。
+
+### `shutdown(): Promise<void>`
 
-### shutdown()
+按插件启动顺序的逆序执行 shutdown，关闭 instrumentations，flush Provider，移除页面生命周期监听并销毁 Provider。
 
 ```ts
-await bkOT.shutdown();
+await rum.shutdown();
 ```
 
-反向关闭插件、结束待处理事件、刷新 Provider 并清理浏览器 patch/监听。该方法幂等；关闭后不能重新启动同一实例，再调用 `start()` 会抛错。
+重复调用安全。关闭后实例不可重启，也不应继续上报。
 
-## Consent
-
-### setTrackingConsent(consent)
+### `setTrackingConsent(consent): Promise<void>`
 
 ```ts
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'consent-demo' },
-  privacy: { trackingConsent: 'not-granted' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-});
-
-await bkOT.setTrackingConsent('granted');
-await bkOT.setTrackingConsent('not-granted');
+await rum.setTrackingConsent('granted');
+await rum.setTrackingConsent('not-granted');
 ```
 
-- 未授权：不创建 Session/View，不启动插件，不 patch 浏览器 API。
-- 授权：启动采集并建立新的 Session/View。
-- 撤销：关闭采集副作用并 flush 已允许的数据。
-- 再授权：插件会再次执行 `init()`。
+参数类型：`'granted' | 'not-granted'`。
+
+- 实例已启动后授权：安装插件并开始新/共享 Session；
+- 实例已启动后撤销：关闭插件/instrumentation、清理运行时 Session 关联并 flush；
+- 实例尚未启动时：只更新配置中的授权状态，等待 `start()`；
+- 重复设置相同值不执行操作。
 
-该方法在 `autoStart: false` 且尚未 `start()` 时只更新状态；随后 `start()` 使用最新 Consent。
+Consent 只控制 SDK 采集生命周期，不负责展示弹窗、记录法律依据或删除已被 Collector 接收的数据。
 
-## User 与 View
+## 用户与 View API
 
-### setUser(user)
+### `setUser(user): void`
 
 ```ts
-bkOT.setUser({ id: 'user-12345' });
-bkOT.setUser({ id: undefined });
+rum.setUser({ id: 'user-001' });
+rum.setUser({ id: undefined }); // 清除 user.id
 ```
 
-更新后续事件的 `user.id`。SDK 不 hash、不脱敏、不改写该值。
+`BkOTUserContext` 当前只有可选 `id`。更新影响后续创建的 Span，不回写已结束 Span。SDK 对 ID 原样透传，不 hash、不脱敏。
 
-### startView(options?)
-
-结束当前 View 并创建新 View，`view.id` 始终由 SDK 生成。
+### `startView(options?): void`
 
 ```ts
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'manual-view-demo' },
-  autoStart: false,
-  tracking: { view: { tracking: 'manual' } },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-});
-
-await bkOT.start();
-bkOT.startView({
+rum.startView({
   name: '订单详情',
   url: location.href,
-  attributes: { 'biz.owner': 'order-team' },
+  attributes: { 'biz.page_kind': 'detail' },
 });
 ```
 
-`BkOTStartViewOptions` 包含 `name?`、`url?`、`attributes?`。调用时必须已有采样有效的 Session；例如 `autoStart: false` 且尚未 `await start()`、未授权或未采样时，调用会被忽略。自动启动过程中、Page View 插件尚未初始化时发出的有效命令会由运行时队列交给插件消费，但接入代码仍推荐显式等待 `start()`。`attributes` 不能覆盖 SDK 的 Session/View 保留字段。
+`BkOTStartViewOptions`：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `name` | `string` | View 展示名；缺省时使用低基数 path group |
+| `url` | `string` | View URL；缺省时使用当前 `location.href` |
+| `attributes` | `Attributes` | 该 View 生命周期内附加到后续 Span 的自定义属性 |
 
-### setViewName(name)
+只有当前 Session 命中采样时才派发命令。推荐 `tracking.view.tracking: 'manual'` 时使用。View 自定义属性不能覆盖 SDK 保护的 RUM 语义字段和采样字段；在新 View 开始时旧 View 属性会被清除。
 
 ```ts
-bkOT.setViewName('订单详情-只读');
+const rum = new BkOpenTelemetry({
+  application: { name: 'manual-view-app' },
+  transport: { endpoint: 'https://rum.example.com' },
+  autoStart: false,
+  tracking: { view: { tracking: 'manual' } },
+});
+
+await rum.start();
+rum.startView({ name: '订单详情' });
 ```
 
-更新当前 View 名称，不创建新 View。后续子事件使用新名称，View Snapshot 产生 update。
+### `setViewName(name): void`
 
-### setViewLoadingTime()
+更新当前 View 名称并产生 View update 生命周期 Span：
 
 ```ts
-await renderAsyncPage();
-bkOT.setViewLoadingTime();
+rum.setViewName('订单详情');
 ```
 
-用“当前时刻 - View 开始时刻”覆盖自动 `view.loading_time`。每次调用替换前一次值；没有有效 View 时忽略。
+没有采样 Session 时调用被忽略。
 
-## 手动事件
+### `setViewLoadingTime(): void`
 
-### reportAction(payload)
+以调用时刻减 View 开始时刻作为手动 `view.loading_time`，并产生 View update：
 
 ```ts
-bkOT.reportAction({
-  name: '保存',
-  attributes: { 'biz.form': 'alarm-strategy' },
-});
+requestAnimationFrame(() => rum.setViewLoadingTime());
 ```
 
-创建并立即结束 `action.custom` Span，写入新的 `action.id`、`action.name` 和 `action.type=custom`。它不会触发自动点击的活动耗时、关联计数或挫败信号计算。
+适用于业务明确知道页面“可用”时刻的场景。它不接受数值参数，时间点就是调用当下；没有采样 Session 时被忽略。
 
-### reportCustomEvent(payload)
+## 手动事件 API
 
-```ts
-bkOT.reportCustomEvent({
-  name: 'strategy_saved',
-  attributes: { 'biz.strategy_id': '10001' },
-});
+两个手动 API 都不维护启动前队列。默认构造函数触发的 autoStart 是异步的；构造后立即同步调用可能发生在 View 插件建立上下文之前。需要可靠接收首个业务事件时，设置 `autoStart: false`，先 `await start()`；manual View 再调用 `startView()`，最后才调用手动事件 API。
+
+### `reportAction(payload): void`
 
-bkOT.reportCustomEvent({
-  name: 'strategy_save_failed',
-  error: new Error('validation failed'),
+```ts
+rum.reportAction({
+  name: '立即购买',
+  attributes: {
+    'biz.product_type': 'subscription',
+  },
 });
 ```
 
-创建 `custom.<name>` Span，并合并 `context.attributes.page`、`context.attributes.custom` 与 payload attributes。传入 `error` 时记录 exception、设置 Span Status/`result=error`，但 `span_type` 仍为 `custom`。
-
-两类方法均受 Session 采样控制；未采样时直接返回。`debug: true` 仅对被丢弃的 Custom Event 输出 warning。
-
-## 自定义信号
-
-### startSpan(name, attributes?, options?)
+参数：
 
 ```ts
-const startedAt = Date.now();
-const span = bkOT.startSpan(
-  'custom.cache_warmup',
-  { 'biz.cache': 'homepage' },
-  { startTime: startedAt, contextTime: startedAt },
-);
-
-span.end();
+interface BkOTActionEventPayload {
+  name: string;
+  attributes?: Attributes;
+}
 ```
 
-自动合并事件发生时的运行时上下文，并应用 `privacy.redactAttributes`。第三个参数的内部形状名为 `BkOTStartSpanOptions`，但该类型没有从包根导出，接入方直接按下表传对象即可，不要生成对它的 import：
+立即创建并结束 `action.custom` Span，写入新的 `action.id`、`action.type=custom`、`span_type=action` 和 `outcome.type=success`。事件标识和时间直接使用 OTLP Span ID 与开始时间。它不是一个持续的自动 Action 窗口，不会等待或关联调用之后的请求。
 
-| 字段 | 说明 |
-| --- | --- |
-| `startTime` | OpenTelemetry `TimeInput`；常用 epoch ms |
-| `contextTime` | 用该 epoch ms 从历史快照解析 Session/View/Action；数字型 `startTime` 默认同时作为该值 |
-| `kind` | OpenTelemetry `SpanKind`，默认 `INTERNAL` |
-
-只有已采样且同时带有效 `session.id`、`view.id` 的 Span 会导出。
-
-### tracer
-
-实例公开 SDK 私有 Provider 对应的 OpenTelemetry `Tracer`。SDK 不创建或公开 `Meter`、`Logger`，自定义 RUM 事件使用 `startSpan()`。
+未命中 Session 采样时静默丢弃。
 
-## 扩展注册
-
-### use(plugin)
+### `reportCustomEvent(payload): void`
 
 ```ts
-bkOT.use(
-  createPlugin({
-    name: 'biz-plugin',
-    init(context) {
-      context.startSpan('custom.biz_plugin_ready').end();
-    },
-  }),
-);
+rum.reportCustomEvent({
+  name: 'order.checkout',
+  attributes: { 'biz.payment_method': 'card' },
+});
+
+rum.reportCustomEvent({
+  name: 'order.checkout_failed',
+  error: new Error('payment rejected'),
+});
 ```
 
-### useInstrumentation(instrumentation)
+参数：
 
 ```ts
-bkOT.useInstrumentation(new SomeWebInstrumentation());
+interface BkOTCustomEventPayload {
+  name: string;
+  attributes?: Attributes;
+  error?: Error;
+}
 ```
 
-两者都必须在 `start()` 前调用；使用默认自动启动时没有可靠的动态注册窗口，推荐配置 `autoStart: false`。完整插件契约见[自定义插件](./custom-plugin.md)。
-
-额外 instrumentation 的稳定扩展边界是 Trace；SDK 不注册 Metric Provider。
+产出 Span 名为 `custom.<name>`，同时写 `rum.custom.name=<name>` 和 `span_type=custom`。有 `error` 时记录 exception Event，将 `outcome.type` 和 Span Status 设为 error；没有 error 时 `outcome.type=success`。
 
-## 运行时与诊断成员
+`name` 会进入 Span name 和字段，必须使用非空的有限枚举，不要拼订单号、URL、用户输入等高基数内容。运行时没有非空校验：空字符串会生成 `custom.` Span 和空的 `rum.custom.name`，不会仅因 name 为空抛错或自动丢弃，但这类数据没有可用语义。未采样时静默丢弃；`debug: true` 会额外打印 dropped warning。
 
-| 成员 | 返回/作用 |
-| --- | --- |
-| `config` | `resolveConfig()` 解析后的 `ResolvedBkOTConfig` |
-| `applyRedact(attributes)` | 执行 `privacy.redactAttributes` |
-| `getRuntimeAttributes()` | 当前公共属性快照 |
-| `getRuntimeAttributesAt(timestamp)` | 指定 epoch ms 的历史公共属性快照 |
-| `setRuntimeAttributes(attributes, changedAt?)` | 写入公共属性；高级扩展 API，谨慎避免覆盖 SDK 字段 |
-| `isSampled()` | 当前 Session 是否命中采样 |
-| `isSessionActive()` | 是否存在有效 Session |
-| `isViewActive()` | 是否存在有效 View |
-| `onSessionLifecycle(listener)` | 订阅 Session renewed/expired，返回取消函数 |
-| `notifySessionLifecycle(event)` | 向运行时分发生命周期事件；主要供高级插件使用 |
+## 扩展注册 API
 
-## createPlugin(plugin)
+### `use(plugin): BkOpenTelemetry`
 
-`createPlugin()` 是保留完整类型推导的恒等构造器。
+链式注册 `BkOTPlugin`：
 
 ```ts
-import { createPlugin } from '@blueking/open-telemetry';
-
-const plugin = createPlugin({
-  name: 'page-visible',
-  enabled: config => config.enabled,
-  init(context) {},
-  flush() {},
-  shutdown() {},
+const rum = new BkOpenTelemetry({
+  application: { name: 'demo' },
+  transport: { endpoint: 'https://rum.example.com' },
+  autoStart: false,
 });
-```
 
-`BkOTPlugin` 的 `enabled` 可为布尔值或接收 `ResolvedBkOTConfig` 的函数。Plugin Manager 顺序启动、并行 flush、反向 shutdown，并隔离单个插件的初始化错误。
+rum.use(myPlugin).use(otherPlugin);
+await rum.start();
+```
 
-## Schema 辅助 API
+只能在第一次 `start()` 前调用；否则抛错。也可以通过 `extensions.plugins` 在构造配置中注册。
 
-### RUM_ATTRIBUTES
+### `useInstrumentation(instrumentation): BkOpenTelemetry`
 
-归一字段 key 常量。
+把标准 OTel instrumentation 绑定到 SDK 私有 WebTracerProvider：
 
 ```ts
-const spanTypeKey = RUM_ATTRIBUTES.spanType; // 'span_type'
+rum.useInstrumentation(instrumentation);
 ```
 
-### RUM_SPAN_TYPE / RUM_SPAN_RESULT
+同样只能在第一次 `start()` 前调用。如果 `enabled: false`，该方法不会加入配置。Instrumentation 创建的 Span 仍必须具有有效的 Session/View/采样运行时上下文，才会通过 SDK 的过滤处理器。
 
-分别提供标准 `span_type` 与 `result` 值。
+## 自定义插件运行时 API
 
-### buildRumSpanAttributes(classification)
+以下方法在实例上公开，但主要面向 `BkOTPlugin.init(context)`：
 
-```ts
-const span = bkOT.startSpan('custom.cache_hit', {
-  ...buildRumSpanAttributes({
-    spanType: RUM_SPAN_TYPE.custom,
-    spanSubtype: 'cache',
-  }),
-});
-span.end();
-```
-
-### buildRumSpanAttributes 相关类型
+| API | 作用 |
+| --- | --- |
+| `startSpan(name, attributes?, options?)` | 按 Session 采样和历史时间上下文创建 Span |
+| `getRuntimeAttributes()` | 复制当前 Session/View/User/Device/Action 属性 |
+| `getRuntimeAttributesAt(timestamp)` | 按 epoch ms 回查该时刻的关联上下文 |
+| `setRuntimeAttributes(attributes, changedAt?)` | 修改后续公共运行时属性 |
+| `applyRedact(attributes)` | 调用配置的 `redactAttributes` |
+| `isSampled()` | 当前 Session 是否命中采样 |
+| `isSessionActive()` / `isViewActive()` | 是否存在有效关联 ID |
+| `onSessionLifecycle(listener)` | 监听 renewed/expired，返回取消函数 |
+| `notifySessionLifecycle(event)` | 发布 Session 生命周期事件，一般仅 Session 扩展使用 |
+| `tracer` | SDK 私有 OTel Tracer |
+| `config` | 已解析的 `ResolvedBkOTConfig` |
 
-公开 `RumSpanClassification`、`RumSpanType`、`RumSpanResult`，用于扩展插件保持同一归一模型。
+`BkOpenTelemetry` 类实现上还公开了 `registerInstrumentations()`，但 `BkOTInstance` 接口有意不把它作为普通实例契约；自定义扩展应通过 Plugin Context 的同名方法调用，常规接入应使用启动前的 `useInstrumentation()`。
 
-## resolveConfig(options)
+### `startSpan()`
 
 ```ts
-import { resolveConfig } from '@blueking/open-telemetry';
-
-const config = resolveConfig({
-  application: { name: 'bk-rum-demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-});
+const span = context.startSpan(
+  'custom.operation',
+  { 'biz.operation': 'calculate' },
+  {
+    startTime: occurredAt,
+    contextTime: occurredAt,
+    kind: SpanKind.INTERNAL,
+  },
+);
 
-console.log(config.transport.endpoint);
+span.end(endedAt);
 ```
 
-用于预览核心解析结果和测试配置。插件自己的参数默认值在插件工厂执行时解析，不会全部展开到 `ResolvedBkOTConfig`。
-
-## 内置插件工厂
+`BkOTStartSpanOptions`：
 
-公共入口导出以下工厂，便于自定义组合或测试：
-
-| 工厂 | 选项类型 |
+| 字段 | 说明 |
 | --- | --- |
-| `createSessionPlugin` | `BkOTSessionConfig` |
-| `createDevicePlugin` | `BkOTDevicePluginOptions` |
-| `createCommonInstrumentationsPlugin` | `BkOTRequestConfig \| boolean` |
-| `createResourcePlugin` | 直接传 `boolean`，控制是否为静态资源创建 Span；默认 `true` |
-| `createErrorPlugin` | 无 |
-| `createWebVitalsPlugin` | 无 |
-| `createBlankScreenPlugin` | `BkOTBlankScreenPluginOptions` |
-| `createActionPlugin` | `BkOTActionPluginOptions` |
-| `createLongTaskPlugin` | `BkOTLongTaskPluginOptions` |
-| `createWebSocketPlugin` | 无 |
-| `createCspViolationPlugin` | 无 |
+| `startTime` | OTel `TimeInput`；浏览器场景常用 epoch milliseconds |
+| `contextTime` | 用哪个 epoch ms 回查 Session/View/Action；缺省时复用数字型 `startTime` |
+| `kind` | SpanKind，默认 `INTERNAL` |
 
-`createCommonInstrumentationsPlugin` 名称保留，但当前实现是 SDK 自有 Fetch/XHR patch，不注册官方 Fetch/XHR instrumentation。
+运行时属性先合并，显式 `attributes` 后合并，因此显式同名字段优先；整体再经过 `redactAttributes`。未采样时返回 OTel non-recording Span，调用方仍可安全 `end()`。
 
-## 其他公共导出
+延迟到达的 PerformanceEntry 应同时设置真实 `startTime` 和 `contextTime`，避免把旧事件错误关联到新的 View。
 
-`src/index.ts` 还导出以下高级能力：
+### `setRuntimeAttributes()` 的边界
 
-- `RumRuntimeContext` 及 Session/View/User 相关类型。
-- `PluginManager`。
-- `FilteringSpanProcessor`。
-- `EXCLUDED_ACTIVITY_MUTATIONS_ATTRIBUTE`，用于标记不应延长 View Loading/Action 的 DOM 子树。
-- 配置输入、解析结果、Transport、Hook、请求上下文等 TypeScript 类型。
+它是扩展底层能力，不是常规业务标签 API。传入 `session.id` 会触发采样决定重算；错误修改 `view.*` 或 `action.id` 会破坏关联历史。普通业务字段更适合通过 context Hook、View attributes 或事件 payload 添加。
 
-这些主要服务 SDK 维护和高级扩展；常规接入只需 `BkOpenTelemetry`、`BkOTOptions` 和手动事件类型。
+## 配置解析函数
+
+```ts
+import { resolveConfig } from '@blueking/open-telemetry';
+```
 
-`BkOpenTelemetry` 具体类上还能看到 `registerInstrumentations()`，它用于 SDK 向插件运行时提供批量注册能力，但被刻意排除在 `BkOTInstance` 契约之外，也会绕过 `useInstrumentation()` 的启动阶段检查。接入方不要直接调用；使用 `extensions.instrumentations` 或 `useInstrumentation()`。
+`resolveConfig(options)` 校验必填项、补默认值、构造最终 `/v1/rum` URL、合并鉴权头，并生成 Resource attributes。它主要用于测试和高级集成，不会启动 SDK。
 
-## 公共类型索引
+## 根入口的运行时导出
 
-以下名称都可以从包根路径执行 `import type`：
+以下值可以从 `@blueking/open-telemetry` 在运行时 import：
 
-| 分类 | 类型 |
+| 导出 | 用途 |
 | --- | --- |
-| 顶层配置 | `BkOTOptions`、`BkOTApplicationConfig`、`BkOTTransportConfig`、`BkOTTrackingConfig`、`BkOTTrackingConsent`、`BkOTContextConfig`、`BkOTPrivacyConfig`、`BkOTExtensionsConfig` |
-| Transport | `BkOTBatchConfig`、`SignalExporterConfig` |
-| View/Session/User | `BkOTViewConfig`、`BkOTSessionConfig`、`BkOTStartViewOptions`、`BkOTViewContext`、`BkOTSessionLifecycleEvent`、`BkOTUserContext` |
-| Request | `BkOTRequestConfig`、`BkOTRequestEvent`、`BkOTRequestContext`、`BkOTUrlMatcher` |
-| 事件与 Hook | `BkOTActionEventPayload`、`BkOTCustomEventPayload`、`BkOTBeforeSendEvent`、`BkOTAttributesConfig`、`BkOTAttributeValue` |
-| 插件 | `BkOTPlugin`、`BkOTRuntimeContext`、`BkOTActionPluginOptions`、`BkOTBlankScreenPluginOptions`、`BkOTDevicePluginOptions`、`BkOTLongTaskPluginOptions` |
-| 实例与解析结果 | `BkOTInstance`、`PluginManager`、`ResolvedBkOTConfig`、`ResolvedApplicationConfig`、`ResolvedTransportConfig`、`ResolvedViewConfig`、`ResolvedConfigHooks` |
-| Schema | `RumAttributeKey`、`RumSpanClassification`、`RumSpanType`、`RumSpanResult` |
-
-如某个源码类型没有出现在本表，也没有从 `src/index.ts` 导出，则它不是包的公共契约。
+| `BkOpenTelemetry` | SDK 主类 |
+| `resolveConfig` | 解析并校验 `BkOTOptions`，不启动 SDK |
+| `createPlugin` | 保留传入 Plugin 对象及其类型推断 |
+| `FilteringSpanProcessor` | SDK 的 RUM 上下文与导出过滤 Processor |
+| `RumRuntimeContext` | User/Session/View/Action 运行时快照和历史关联实现 |
+| `createActionPlugin` | 内置自动 Action 插件工厂 |
+| `createBlankScreenPlugin` | 内置白屏插件工厂 |
+| `createCommonInstrumentationsPlugin` | 内置 Fetch/XHR 插件工厂；名称保留，但当前不是标准 instrumentation 集合 |
+| `createCspViolationPlugin` | 内置 CSP 插件工厂 |
+| `createDevicePlugin` | 内置 Device 运行时插件工厂 |
+| `createErrorPlugin` | 内置 Error 插件工厂 |
+| `createLongTaskPlugin` | 内置 Long Task 插件工厂 |
+| `createResourcePlugin` | 内置 Resource Timing 插件工厂 |
+| `createSessionPlugin` | 内置 Session 插件工厂 |
+| `createWebVitalsPlugin` | 内置 Web Vitals 插件工厂 |
+| `createWebSocketPlugin` | 内置 WebSocket 插件工厂 |
+| `EXCLUDED_ACTIVITY_MUTATIONS_ATTRIBUTE` | 值为 `data-bk-excluded-activity-mutations`，标记不延长页面活动的 DOM 子树 |
+| `RUM_ATTRIBUTES` | SDK 公共字段 key 常量表 |
+| `RUM_SPAN_TYPE` | RUM Span 大类常量表 |
+| `RUM_SPAN_OUTCOME` | success/warning/error/timeout/abort 常量表 |
+| `buildRumSpanAttributes` | 根据 spanType/outcome/outcomeReason 生成分类属性 |
+
+内置插件工厂适合 SDK 定制或组合插件。普通接入使用 `tracking` 开关即可；不要把同一个内置工厂再放进 `extensions.plugins`，否则可能重复监听和上报。
+
+## 根入口的 TypeScript 类型导出
+
+配置：
+
+- `BkOTOptions`
+- `BkOTApplicationConfig`
+- `BkOTTransportConfig`、`BkOTBatchConfig`
+- `BkOTTrackingConfig`、`BkOTViewConfig`、`BkOTRequestConfig`
+- `BkOTPrivacyConfig`、`BkOTTrackingConsent`
+- `BkOTContextConfig`、`BkOTAttributesConfig`
+- `BkOTExtensionsConfig`
+- `BkOTUrlMatcher`、`BkOTAttributeValue`
+- `BkOTBeforeSendEvent`、`BkOTRequestEvent`、`BkOTRequestContext`、`BkOTRequestOutcome`
+- `BkOTActionEventPayload`、`BkOTCustomEventPayload`
+- `ResolvedApplicationConfig`、`ResolvedBkOTConfig`、`ResolvedConfigHooks`、`ResolvedTransportConfig`、`ResolvedViewConfig`
+
+实例与运行时：
+
+- `BkOTInstance`
+- `BkOTUserContext`
+- `BkOTStartViewOptions`、`BkOTViewContext`
+- `BkOTSessionLifecycleEvent`
+- `BkOTPlugin`、`BkOTRuntimeContext`
+- `PluginManager`：当前是 type-only 导出，不能从根入口 `new PluginManager()`
+
+插件参数：
+
+- `BkOTActionPluginOptions`
+- `BkOTBlankScreenPluginOptions`
+- `BkOTDevicePluginOptions`
+- `BkOTLongTaskPluginOptions`
+- `BkOTSessionConfig`
+
+模型：
+
+- `RumAttributeKey`
+- `RumSpanClassification`
+- `RumSpanOutcome`
+- `RumSpanType`
+
+`BkOTStartSpanOptions` 当前用于方法签名，但没有从 package 根入口单独导出；调用方通常由 `context.startSpan()` 的参数类型自动推导。