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

package/dist/plugins/common.d.ts

@@ -8,5 +8,5 @@ interface RequestDetails {
     url?: string;
 }
 export { REQUEST_DISCARD_ATTRIBUTE };
-export declare const decorateRequestSpan: (context: BkOTRuntimeContext, span: Span, subtype: "fetch" | "xhr", domainContext: BkOTRequestContext, details?: RequestDetails, fetchRequest?: Request | RequestInit) => void;
+export declare const decorateRequestSpan: (context: BkOTRuntimeContext, span: Span, subtype: "fetch" | "xhr", domainContext: BkOTRequestContext, details?: RequestDetails) => void;
 export declare const createCommonInstrumentationsPlugin: (option: BkOTRequestConfig | boolean | undefined) => BkOTPlugin;

package/dist/plugins/csp-violation.d.ts

@@ -3,14 +3,6 @@ import type { BkOTPlugin } from '../core/plugin';
  * CSP 违规事件采集插件，通过监听 `securitypolicyviolation` 事件捕获被 CSP 策略拦截的脚本/资源，
  * 以 error span 上报，进入统一错误分析口径。
  *
- * 节流策略：
- * - 同 fingerprint（`violatedDirective + blockedURI + sourceFile + lineNumber`）
- *   在 60s 窗口内最多上报 5 条，避免风暴打爆 collector（如某段被拦截的 inline 脚本被反复渲染）。
- * - `browser.csp_violation.count` counter 在节流前累计所有违规，span 只保留窗口触发序号。
- *
- * 体积优化：
- * - `csp.original_policy`（完整 CSP 策略，可能数 KB）仅在窗口首条上报，后续同 fingerprint 不再重复携带。
- *
  * URL 处理：
  * - `blockedURI` / `sourceFile` 中的 URL 类值会经 `redactUrl` 脱敏。
  * - `blockedURI` 是 'inline' / 'eval' 等 CSP 关键字时直接保留，不调用 redactUrl。

package/dist/plugins/error.d.ts

@@ -1,6 +1,2 @@
 import type { BkOTPlugin } from '../core/plugin';
-export interface BkOTErrorPluginOptions {
-    maxPerWindow?: number;
-    windowMs?: number;
-}
-export declare const createErrorPlugin: (options?: BkOTErrorPluginOptions) => BkOTPlugin;
+export declare const createErrorPlugin: () => BkOTPlugin;

package/dist/plugins/long-task.d.ts

@@ -1,12 +1,10 @@
 import type { BkOTPlugin } from '../core/plugin';
 /**
  * 主线程阻塞优先使用 Long Animation Frame API 获取脚本归因，不支持时回退到 Long Tasks API；
- * span 保留单次诊断详情，metric 只保留低基数维度用于聚合分布。
+ * span 保留单次诊断详情，分布与计数由服务端从原始事件计算。
  */
 export interface BkOTLongTaskPluginOptions {
     /** 采集阈值，默认 50ms。Performance API 本身通常只产生大于 50ms 的条目。 */
     threshold?: number;
-    /** 标记 warning 的阈值，默认 100ms。 */
-    warningThreshold?: number;
 }
 export declare const createLongTaskPlugin: (options?: BkOTLongTaskPluginOptions) => BkOTPlugin;

package/dist/plugins/web-vitals.d.ts

@@ -4,10 +4,7 @@
  * 基于 google/web-vitals 库（attribution 版本）采集 Core Web Vitals：
  *   CLS / FCP / INP / LCP / TTFB
  *
- * 维度分层（关键设计）：
- * - metric (histogram)：仅带低基数维度（`view.url_path_group` / navigation.type / vital.name / vital.rating），
- *   适合做 P50 / P75 / P99 聚合统计，避免维度爆炸
- * - span (browser.web_vital)：带 vital.id（唯一）、vital.value 与 attribution 详情
+ * browser.web_vital span 带 vital.id（唯一）、vital.value 与 attribution 详情
  *   （LCP 元素 url / CLS shift target / INP interaction target 等高基数字段），
  *   方便按个例排查"哪个元素拖累了 LCP"
  *

package/dist/schema/attributes.d.ts

@@ -4,14 +4,10 @@
  * 插件里不要散落硬编码字符串，后续字段命名调整只改这里，避免采集端与字段文档逐步漂移。
  */
 export declare const RUM_ATTRIBUTES: {
-    readonly actionErrorCount: "action.error.count";
-    readonly actionFrustrationCount: "action.frustration.count";
     readonly actionFrustrationType: "action.frustration.type";
     readonly actionId: "action.id";
     readonly actionLoadingTime: "action.loading_time";
-    readonly actionLongTaskCount: "action.long_task.count";
     readonly actionName: "action.name";
-    readonly actionResourceCount: "action.resource.count";
     readonly actionTargetName: "action.target.name";
     readonly actionTargetTag: "action.target.tag";
     readonly actionType: "action.type";
@@ -22,17 +18,15 @@ export declare const RUM_ATTRIBUTES: {
     readonly deviceLogicalProcessorCount: "device.logical_processor_count";
     readonly deviceMemoryGib: "device.memory_gib";
     readonly deviceType: "device.type";
+    readonly eventId: "event.id";
+    readonly eventPhase: "event.phase";
+    readonly eventTimestamp: "event.timestamp";
+    readonly eventType: "event.type";
     readonly errorType: "error_type";
-    readonly exceptionFingerprint: "exception.fingerprint";
-    readonly exceptionMessageShort: "exception.message_short";
-    readonly exceptionStackTopFrame: "exception.stack_top_frame";
     readonly longTaskBlockingDuration: "long_task.blocking_duration";
-    readonly longTaskCulprit: "long_task.culprit";
     readonly longTaskDuration: "long_task.duration";
     readonly longTaskEntryType: "long_task.entry_type";
     readonly longTaskId: "long_task.id";
-    readonly longTaskIsFrozenFrame: "long_task.is_frozen_frame";
-    readonly longTaskScriptCount: "long_task.script.count";
     readonly longTaskStartTime: "long_task.start_time";
     readonly networkEffectiveType: "network.effective_type";
     readonly nextHopProtocol: "resource.protocol";
@@ -43,7 +37,9 @@ export declare const RUM_ATTRIBUTES: {
     readonly osName: "os.name";
     readonly sessionHasReplay: "session.has_replay";
     readonly sessionId: "session.id";
+    readonly sessionSampleRate: "session.sample_rate";
     readonly sessionStartTime: "session.start_time";
+    readonly sessionType: "session.type";
     readonly spanSubtype: "span_subtype";
     readonly spanType: "span_type";
     readonly userId: "user.id";
@@ -59,7 +55,9 @@ export declare const RUM_ATTRIBUTES: {
     readonly viewLoadingTime: "view.loading_time";
     readonly viewLoadingType: "view.loading_type";
     readonly viewName: "view.name";
+    readonly viewStartedAt: "view.started_at";
     readonly viewUrl: "view.url";
     readonly viewUrlPathGroup: "view.url_path_group";
+    readonly viewVersion: "view.version";
 };
 export type RumAttributeKey = (typeof RUM_ATTRIBUTES)[keyof typeof RUM_ATTRIBUTES];

package/dist/schema/span.d.ts

@@ -14,7 +14,9 @@ export declare const RUM_SPAN_TYPE: {
     readonly longtask: "longtask";
     readonly resource: "resource";
     readonly route: "route";
+    readonly session: "session";
     readonly vital: "vital";
+    readonly websocket: "websocket";
 };
 export interface RumResourceSpanInput {
     initiatorType?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.20",
+  "version": "0.0.22-beta.1",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",
@@ -14,6 +14,7 @@
   "scripts": {
     "prepublishOnly": "pnpm build && pnpm dts && pnpm skill:refs",
     "skill:refs": "node scripts/gen-skill-references.mjs",
+    "test:skill-refs": "node --test tests/gen-skill-references.test.mjs",
     "build": "vite build && vite build --mode cdn && pnpm dts",
     "build:cdn": "vite build --mode cdn",
     "build:esm": "vite build",
@@ -26,16 +27,11 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/api-logs": "^0.217.0",
     "@opentelemetry/context-zone": "2.7.1",
     "@opentelemetry/core": "^2.7.1",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.217.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.217.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
     "@opentelemetry/instrumentation": "^0.217.0",
     "@opentelemetry/resources": "^2.7.1",
-    "@opentelemetry/sdk-logs": "^0.217.0",
-    "@opentelemetry/sdk-metrics": "^2.7.1",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/sdk-trace-web": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.38.0",

package/skills/bk-rum-otele/SKILL.md

@@ -27,7 +27,11 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 | 搞懂三类信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文                       | `references/concepts.md`              |
 | 查配置项、默认值、Endpoint、插件参数和 Hook                                                | `references/configuration.md`         |
 | 查 Transport、单信号开关、批量上报、Session 采样和 traceparent 透传                       | `references/transport-sampling.md`    |
-| 开关某个采集能力、看请求配置和各插件参数（request/error/blankScreen/longTask/websocket 等） | `references/plugins.md`               |
+| 了解插件默认组合、启用规则和能力分类                                                       | `references/plugins.md`               |
+| 配置 Session、Device、View、Action                                                         | `references/plugins-basic.md`         |
+| 配置 Resource、Web Vitals、Blank Screen、Long Task、View Loading Time                     | `references/plugins-experience.md`    |
+| 配置 Error、CSP Violation 和错误上报                                                       | `references/plugins-error-security.md` |
+| 配置 Fetch/XHR Request、HTTP Body、Trace Header、WebSocket                                 | `references/plugins-network.md`       |
 | 写自定义插件、接入第三方 OpenTelemetry instrumentation                                      | `references/custom-plugin.md`         |
 | 查公开 API（start/flush/shutdown/setUser/setView/reportAction/reportCustomEvent 等）        | `references/api.md`                   |
 | Vue / React / Vue Router / 微前端 集成                                                      | `references/framework-integration.md` |
@@ -91,7 +95,7 @@ CDN：
 </script>
 ```
 
-`transport.endpoint` 可提供上报根地址（不含路径前缀），SDK 自动拼 `/v1/rum`、`/v1/metrics`、`/v1/logs`；若通过 `transport.signals.{traces|metrics|logs}.endpoint` 自定义某一类地址，则该信号使用完整 URL，不再拼接。当所有已开启信号都有独立地址时，根 endpoint 可省略。三类信号可分别设为 `false` 关闭，但不能全部关闭。`token` 作为 `Authorization: Bearer <token>` 默认头。构造后默认 `autoStart: true` 自动启动，无需手动 `start()`。
+`transport.endpoint` 是必填上报根地址（不含路径前缀），SDK 自动拼 `/v1/rum`。SDK 不创建 Metric/Log Provider，所有原始 RUM 事件统一走 Trace Span。`token` 作为 `Authorization: Bearer <token>` 默认头。构造后默认 `autoStart: true` 自动启动，无需手动 `start()`。
 
 ## 默认采集能力清单
 
@@ -99,16 +103,16 @@ CDN：
 
 - 基础能力：Session、View；内置采集：`request`、`action`、`resource`、`error`、`webVitals`、`blankScreen`、`device`
 
-View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各插件参数见 `references/plugins.md`。
+View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各插件参数按「任务路由」读取对应 `plugins-*.md`。
 
 ## 关键易错点
 
 - **单实例**：`fetch`/`xhr`/`action`/`websocket` 会 patch 或监听全局 API，同页面只应初始化一个 SDK 实例，微前端只在主应用初始化一次。
 - **`use()` / `useInstrumentation()` 必须在 `start()` 之前**：要注册自定义插件或 instrumentation，请设 `autoStart: false` 再手动 `start()`。
 - **采样影响手动上报**：未命中采样时 `reportAction()` / `reportCustomEvent()` 静默丢弃，排查时先确认采样。
-- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性需通过 `privacy` / `request.beforeSend` 显式处理；HTTP body 默认关闭，显式配置 `request.body` 时必须提供 `redact`，默认只采集错误请求；`user.id` 需 hash 的话要在传入前处理。
+- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性需通过 `privacy` / `request.beforeSend` 显式处理；SDK 不采集 HTTP Body；`user.id` 需 hash 的话要在传入前处理。
 - **Consent**：未授权初始化时配置 `privacy.trackingConsent: 'not-granted'`，用户授权后调用 `setTrackingConsent('granted')`；撤销授权会停止采集并解除 patch。
-- **信号开关**：`transport.signals.traces/metrics/logs` 设为 `false` 可关闭对应导出链路；关闭 Trace 后不会注入 `traceparent`。只开 Metric 时没有精确 View 下钻。
+- **单一信号**：只有 `/v1/rum` Trace 通道；计数、直方图、分位数、错误指纹和跨事件聚合由服务端完成。
 - **低基数路由**：用 `tracking.view.getPathGroup` 把 `/user/123` 归类成 `/user/:id`，避免高基数 URL 污染指标维度。
 - **手动 View 的时机**：使用 `autoStart: false`，先 `await start()` 建立 Session，再调用 `startView()`；启动前调用会因没有有效采样 Session 而被忽略。
 - **Action 命名隐私**：默认 `nameCollection: 'explicit'` 只读取 `data-bk-action-name`，否则退回标签名；只有显式设为 `text` 才读取可访问名称和 DOM 文本。

package/skills/bk-rum-otele/evals/evals.json

@@ -13,7 +13,7 @@
       "id": 1,
       "name": "local-no-data-troubleshoot",
       "prompt": "我按文档接了 bk-rum，本地起了 collector 在 4318，但 Network 里没看到 /rum 请求，reportCustomEvent 也没上报，debug 我也开了。可能是什么问题？怎么排查？",
-      "expected_output": "排障应覆盖：session.sampleRate 是会话级确定性采样，未命中时手动事件静默丢弃（建议调试设 sampleRate:1）；enabled/Consent/有效 View 是否正常；建议 transport.signals.traces.processor:'simple'；检查 collector、endpoint 与 Network 中 /v1/rum、/v1/metrics、/v1/logs。",
+      "expected_output": "排障应覆盖：session.sampleRate 是会话级确定性采样，未命中时手动事件静默丢弃（建议调试设 sampleRate:1）；enabled/Consent/有效 View 是否正常；建议 transport.processor:'simple'；检查 collector、endpoint 与 Network 中 /v1/rum。",
       "files": [],
       "assertions": []
     },
@@ -21,7 +21,7 @@
       "id": 2,
       "name": "instrumentation-vs-plugin-httpbody",
       "prompt": "配置里有 instrumentations 和 plugins 两块，fetch、error 这些好像两边都能配？它们到底有什么区别？另外我想采集接口报错时的请求/响应 body 来排查问题，该怎么配、要注意什么？",
-      "expected_output": "正确区分内置 tracking、RUM Plugin 与额外 OTel Instrumentation；指出当前 request 是 SDK 自有 Fetch/XHR patch，生成 browser.resource CLIENT Span，不使用官方 Fetch/XHR instrumentation；说明 excludedUrls、allowedTracingUrls、request.beforeSend；HTTP body 默认关闭，显式配置 tracking.request.body 后默认只采集错误请求，必须配置 redact，并限制 Content-Type 和大小。",
+      "expected_output": "正确区分内置 tracking、RUM Plugin 与额外 OTel Instrumentation；指出当前 request 是 SDK 自有 Fetch/XHR patch，生成 browser.resource CLIENT Span，不使用官方 Fetch/XHR instrumentation；说明 excludedUrls、allowedTracingUrls、request.beforeSend；SDK 不读取或上报 HTTP Body。",
       "files": [],
       "assertions": []
     }

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

@@ -42,7 +42,7 @@ await bkOT.start();
 await bkOT.flush();
 ```
 
-先并行调用已启动插件的 `flush()`，再 force flush Trace、Metric、Log Provider。SDK 已在 `pagehide` 和页面变为 hidden 时触发 flush；业务只需在关键流程完成后按需主动调用。
+先并行调用已启动插件的 `flush()`，再 force flush Trace Provider。SDK 已在 `pagehide` 和页面变为 hidden 时触发 flush；业务只需在关键流程完成后按需主动调用。
 
 ### shutdown()
 
@@ -180,21 +180,9 @@ span.end();
 
 只有已采样且同时带有效 `session.id`、`view.id` 的 Span 会导出。
 
-### emitLog(record)
+### tracer
 
-```ts
-bkOT.emitLog({
-  severityText: 'INFO',
-  body: 'biz.cache_ready',
-  attributes: { 'biz.cache': 'homepage' },
-});
-```
-
-自动合并运行时上下文与脱敏。自定义插件应使用 `emitLog()`，不要直接调用 `logger.emit()`。
-
-### tracer / meter / logger
-
-实例公开 SDK 私有 Provider 对应的原生 OpenTelemetry `Tracer`、`Meter`、`Logger`。优先使用 `startSpan()` 与 `emitLog()`。当前没有公开稳定的自定义 Metric 采样 helper，直接通过 `meter` 创建的数据点默认无法通过过滤器，不应作为接入方稳定能力；详见[架构与数据流](./architecture.md#扩展边界)。
+实例公开 SDK 私有 Provider 对应的 OpenTelemetry `Tracer`。SDK 不创建或公开 `Meter`、`Logger`，自定义 RUM 事件使用 `startSpan()`。
 
 ## 扩展注册
 
@@ -219,7 +207,7 @@ bkOT.useInstrumentation(new SomeWebInstrumentation());
 
 两者都必须在 `start()` 前调用；使用默认自动启动时没有可靠的动态注册窗口，推荐配置 `autoStart: false`。完整插件契约见[自定义插件](./custom-plugin.md)。
 
-额外 instrumentation 的稳定扩展边界是 Trace。第三方 Metric 不会自动获得 SDK 内部采样标记，默认无法通过 Metric 过滤器。
+额外 instrumentation 的稳定扩展边界是 Trace；SDK 不注册 Metric Provider。
 
 ## 运行时与诊断成员
 
@@ -294,7 +282,7 @@ const config = resolveConfig({
   transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
-console.log(config.transport.traces && config.transport.traces.endpoint);
+console.log(config.transport.endpoint);
 ```
 
 用于预览核心解析结果和测试配置。插件自己的参数默认值在插件工厂执行时解析，不会全部展开到 `ResolvedBkOTConfig`。
@@ -309,7 +297,7 @@ console.log(config.transport.traces && config.transport.traces.endpoint);
 | `createDevicePlugin` | `BkOTDevicePluginOptions` |
 | `createCommonInstrumentationsPlugin` | `BkOTRequestConfig \| boolean` |
 | `createResourcePlugin` | 直接传 `boolean`，控制是否为静态资源创建 Span；默认 `true` |
-| `createErrorPlugin` | `BkOTErrorPluginOptions` |
+| `createErrorPlugin` | 无 |
 | `createWebVitalsPlugin` | 无 |
 | `createBlankScreenPlugin` | `BkOTBlankScreenPluginOptions` |
 | `createActionPlugin` | `BkOTActionPluginOptions` |
@@ -325,7 +313,7 @@ console.log(config.transport.traces && config.transport.traces.endpoint);
 
 - `RumRuntimeContext` 及 Session/View/User 相关类型。
 - `PluginManager`。
-- `FilteringSpanProcessor`、`FilteringMetricExporter`、`FilteringLogRecordProcessor`。
+- `FilteringSpanProcessor`。
 - `EXCLUDED_ACTIVITY_MUTATIONS_ATTRIBUTE`，用于标记不应延长 View Loading/Action 的 DOM 子树。
 - 配置输入、解析结果、Transport、Hook、请求上下文等 TypeScript 类型。
 
@@ -340,11 +328,11 @@ console.log(config.transport.traces && config.transport.traces.endpoint);
 | 分类 | 类型 |
 | --- | --- |
 | 顶层配置 | `BkOTOptions`、`BkOTApplicationConfig`、`BkOTTransportConfig`、`BkOTTrackingConfig`、`BkOTTrackingConsent`、`BkOTContextConfig`、`BkOTPrivacyConfig`、`BkOTExtensionsConfig` |
-| Transport | `BkOTBatchConfig`、`SignalExporterConfig`、`SignalExporterInputConfig`、`SignalExportersInputConfig`、`TraceExporterInputConfig`、`MetricExporterInputConfig` |
+| Transport | `BkOTBatchConfig`、`SignalExporterConfig` |
 | View/Session/User | `BkOTViewConfig`、`BkOTSessionConfig`、`BkOTStartViewOptions`、`BkOTViewContext`、`BkOTSessionLifecycleEvent`、`BkOTUserContext` |
-| Request | `BkOTRequestConfig`、`BkOTRequestEvent`、`BkOTRequestContext`、`BkOTRequestBodyConfig`、`BkOTRequestBodyRedactPayload`、`BkOTUrlMatcher` |
+| Request | `BkOTRequestConfig`、`BkOTRequestEvent`、`BkOTRequestContext`、`BkOTUrlMatcher` |
 | 事件与 Hook | `BkOTActionEventPayload`、`BkOTCustomEventPayload`、`BkOTBeforeSendEvent`、`BkOTAttributesConfig`、`BkOTAttributeValue` |
-| 插件 | `BkOTPlugin`、`BkOTRuntimeContext`、`BkOTActionPluginOptions`、`BkOTBlankScreenPluginOptions`、`BkOTDevicePluginOptions`、`BkOTErrorPluginOptions`、`BkOTLongTaskPluginOptions` |
+| 插件 | `BkOTPlugin`、`BkOTRuntimeContext`、`BkOTActionPluginOptions`、`BkOTBlankScreenPluginOptions`、`BkOTDevicePluginOptions`、`BkOTLongTaskPluginOptions` |
 | 实例与解析结果 | `BkOTInstance`、`PluginManager`、`ResolvedBkOTConfig`、`ResolvedApplicationConfig`、`ResolvedTransportConfig`、`ResolvedViewConfig`、`ResolvedConfigHooks` |
 | Schema | `RumAttributeKey`、`RumSpanClassification`、`RumSpanType`、`RumSpanResult` |
 

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

@@ -2,140 +2,60 @@
 
 # 架构与数据流
 
-本页描述当前 `src/` 的实现边界，适合 SDK 维护者、扩展插件作者和需要解释“为什么数据没有被导出”的接入方。
+SDK 只负责采集浏览器事实和必须在浏览器本地完成的体验语义计算，所有数据统一编码为 RUM Span，通过 `<transport.endpoint>/v1/rum` 上报。
 
-## 源码模块
+## 模块边界
 
-| 目录/文件 | 职责 | 稳定入口 |
-| --- | --- | --- |
-| `src/index.ts` | ESM 公共导出边界 | npm import 只能依赖这里导出的符号 |
-| `src/browser.ts` | CDN/IIFE 入口 | 暴露 `window.BkOpenTelemetry` |
-| `src/core/config.ts` | 输入类型、校验、默认值、Endpoint 与 Hook 解析 | `BkOTOptions`、`resolveConfig()` |
-| `src/core/sdk.ts` | Provider、Exporter、生命周期、内置插件组合、公开实例 API | `BkOpenTelemetry` |
-| `src/core/runtime-context.ts` | User/Session/View/Action 属性快照与历史归属 | `RumRuntimeContext` |
-| `src/core/processor.ts` | Span/Metric/Log 的采样、上下文、自上报和 beforeSend 过滤 | 三个 Filtering 类 |
-| `src/core/plugin.ts` | 插件契约、启动、并行 flush、反向 shutdown、错误隔离 | `createPlugin()` |
-| `src/plugins/` | 浏览器采集与 RUM 语义 | 各 `create*Plugin()` |
-| `src/schema/` | 归一字段、Span 类型、结果和耗时分桶 | `RUM_ATTRIBUTES`、`buildRumSpanAttributes()` |
+| 模块 | 职责 |
+| --- | --- |
+| `core/config.ts` | 配置校验、Endpoint、Hook、Resource 属性 |
+| `core/sdk.ts` | TracerProvider、Exporter、生命周期和公开 API |
+| `core/runtime-context.ts` | User/Session/View/Action 当前快照与历史归属 |
+| `core/processor.ts` | 采样、上下文、自上报和 beforeSend 过滤 |
+| `plugins/` | 浏览器原始事件采集与本地体验语义 |
+| `schema/` | RUM 字段和 Span 分类 |
 
-文档描述与源码冲突时，以 `src/index.ts` 的公开导出和对应实现为准。`dist/` 是构建产物，不作为文档事实源。
+SDK 不创建 `MeterProvider`、`LoggerProvider`、Metric Reader 或 Log Processor。
 
-## 构造、启动与关闭
+## 生命周期
 
-### 构造阶段
+构造时只创建 Resource、TracerProvider、OTLP Trace Exporter 和运行时上下文。获得 Consent 后，插件依次建立 Session、View、请求、资源、错误、Vitals、Action 等采集。`flush()` 刷新插件和 Trace Provider；`shutdown()` 反向关闭插件并关闭 Trace Provider。
 
-`new BkOpenTelemetry(options)` 同步完成：
+## 原始事件模型
 
-1. `resolveConfig()` 校验 `application.name`、Transport 和已启用信号的 Endpoint。
-2. 创建 Resource、TracerProvider、MeterProvider、LoggerProvider。
-3. 根据三类信号开关决定是否创建 exporter、processor 或 metric reader。
-4. 创建运行时上下文；初始状态尚无 Session/View，也未命中采样。
-5. `autoStart !== false` 时异步调用 `start()`。
+公共流程：
 
-因此，需要在启动前注册扩展或立即创建手动 View 时，应显式设置 `autoStart: false`。
+1. 插件读取浏览器事件的真实时间。
+2. 按事件时间关联 `session.id`、`view.id`、`action.id`。
+3. 写入唯一 `event.id`、`event.type`、`event.timestamp`。
+4. 创建 RUM Span，应用 URL/属性脱敏。
+5. FilteringSpanProcessor 校验采样和有效上下文，执行 `tracking.beforeSend`。
+6. 通过 `/v1/rum` 批量上报。
 
-### 启动阶段
+Session 和 View 使用显式生命周期事件：
 
-`start()` 幂等。获得 Consent 且 `enabled=true` 时，插件按以下顺序初始化：
+- `browser.session`：`event.phase=start|rotate|end`。
+- `browser.view`：`event.phase=start|update|end`，并携带单调递增的 `view.version`。
+- `browser.websocket`：`event.phase=connect|open|error|close`，通过 `websocket.connection.id` 关联。
 
-1. 上下文：Session → Device → Activity → View → Resource Observer。
-2. 请求：统一 Fetch/XHR patch。
-3. RUM：Error → Web Vitals → Blank Screen → Action → 按需 WebSocket / Long Task / CSP。
-4. 接入方 `extensions.plugins`。
-5. 接入方 OpenTelemetry instrumentations。
+Session 生命周期允许只有 `session.id`；其他普通事件必须同时归属有效 Session 和 View。
 
-单个插件 `init()` 抛错不会阻断其他插件；仅在 `debug: true` 时输出 warning。Consent 撤销后再授权会重新执行插件 `init()`，插件必须在 `shutdown()` 中完整释放监听和 patch。
+## SDK 与服务端分工
 
-### flush 与 shutdown
+SDK 保留浏览器端才可靠的计算：CLS、INP、Action Loading Time、View Loading Time、挫败信号和白屏判断。
 
-- `flush()`：并行刷新插件，再 force flush Trace、Metric、Log provider。
-- `shutdown()`：反向关闭插件，结束/刷新最终数据，移除页面生命周期监听，关闭三个 provider。
-- `shutdown()` 后同一实例不能重新启动；需要重新创建实例。
-- SDK 在 `pagehide` 和页面变为 hidden 时主动调用 `flush()`。
+服务端负责：
 
-## 从浏览器事件到 OTLP
+- View/Session 时长、事件计数、错误率、吞吐量；
+- Counter、Histogram、P50/P75/P95/P99；
+- 错误指纹、分组和风暴控制；
+- 采样率修正、乱序/迟到事件合并；
+- 基于 `event.id` 去重，基于 `view.id + view.version` 幂等更新。
 
-一次事件的公共路径是：
+## 请求采集
 
-1. 插件或公开 API 观察浏览器事件。
-2. 从 `RumRuntimeContext` 读取事件发生时对应的 User、Session、View、Action 属性。
-3. 构造原生 OpenTelemetry Span、Metric datapoint 或 LogRecord。
-4. 应用 URL/属性脱敏和事件级 Hook。
-5. Filtering processor/exporter 校验采样与上下文。
-6. 通过对应 OTLP HTTP exporter 上报。
+Fetch/XHR 由 SDK 单层 patch：创建 `browser.resource` CLIENT Span、可选注入 `traceparent`、关联 Resource Timing，并通过活动总线参与 View/Action Loading Time。`excludedUrls` 完全排除请求，`request.beforeSend` 可修改或丢弃请求 Span。SDK 不读取请求或响应 Body。
 
-不同信号的最终过滤规则不同：
+## 隐私与扩展
 
-| 信号 | 接受条件 | 最终 Hook |
-| --- | --- | --- |
-| Span | 已采样，且同时有有效 `session.id`、`view.id`；排除 SDK 上报请求和请求级丢弃标记 | `tracking.beforeSend` |
-| Log | 同 Span；`session.start/rotate` 允许只有有效 Session | `tracking.beforeSend` |
-| Metric | datapoint 带内部已采样标记；导出前移除该标记 | 无全局 beforeSend |
-
-这意味着手动模式首次 `startView()` 之前，普通 Span/Log 不会导出；只创建原生 meter 数据但没有使用 SDK 采样属性的自定义 Metric 也不会导出。
-
-## 运行时上下文与历史归属
-
-运行时上下文维护当前属性，也保留有限的变更时间线。PerformanceObserver 经常在事件结束后才回调，因此 `startSpan(..., { startTime, contextTime })` 可以按事件真实发生时间解析其所属 Session/View/Action，避免把旧页面资源归到新 View。
-
-### Span 与 Log
-
-Span/Log 可携带唯一关联字段：
-
-- `user.id`
-- `session.id`
-- `view.id`、`view.name`、`view.url`、`view.url_path_group`
-- 活动期间的 `action.id`
-
-### Metric
-
-Metric 只保留 `view.url_path_group` 等低基数属性，不携带 `session.id`、`view.id`、`action.id`。需要从聚合指标下钻到具体访问时，查询同名语义 Span 或 View Snapshot Log，或由后端使用 exemplar/派生数据建立关联。
-
-## Session、采样与 Consent
-
-三者是不同控制层：
-
-| 控制层 | 决定什么 | 运行期变化 |
-| --- | --- | --- |
-| `enabled` | 实例是否启动采集 | 构造后不提供 Setter |
-| Consent | 是否安装采集副作用、创建 Session/View | `setTrackingConsent()` 可授权/撤销 |
-| `session.sampleRate` | 有效 Session 的数据是否进入导出链路 | Session 轮换后用新 ID 重新计算 |
-| Signal 开关 | 是否存在对应 exporter/processor/reader | 构造时固定 |
-
-Session 采样由 `application.name + session.id` 稳定 hash 决定，同一 Session 的三类信号保持一致。插件仍可维护页面生命周期，但未采样数据会在创建或导出路径被丢弃。
-
-## 请求采集设计
-
-Fetch/XHR 由 `createCommonInstrumentationsPlugin()` 的单一生命周期直接 patch，不叠加官方 Fetch/XHR instrumentation：
-
-- `excludedUrls` 在最前面完全排除请求。
-- 开始请求时创建 `browser.resource` CLIENT Span，并登记 View/Action 活动。
-- 只有 `allowedTracingUrls` 命中且 Trace 开启时才调用全局 propagator 注入。SDK 成功注册默认 W3C propagator 时注入 `traceparent`/已有 `tracestate`；宿主已有全局 propagator 时，实际 Header 由宿主决定。
-- Resource Observer 把同一 URL/时间窗的 PerformanceResourceTiming 匹配回请求 Span。
-- `request.beforeSend` 可修改请求事件属性或标记丢弃该 Span。
-- 配置 Body 且 Log 开启时，异步生成关联 `trace.id` / `span.id` 的 `browser.request.body` Log。
-- SDK 自身所有已启用 OTLP Endpoint 始终排除，防止递归上报。
-
-静态资源复用同一个 Resource Observer，但 Fetch/XHR entry 只用于 timing 匹配，不再创建第二条资源 Span。
-
-## 脱敏与 Hook 顺序
-
-| 入口 | 作用范围 | 适合用途 |
-| --- | --- | --- |
-| `privacy.redactUrl` | SDK 写入的 URL 类属性 | 删除 query/hash、模板化路径 |
-| `privacy.redactAttributes` | Resource、通过 SDK `startSpan()`、`emitLog()` 和内置插件显式应用的属性 | 删除敏感业务字段 |
-| `tracking.request.beforeSend` | 单个 Fetch/XHR，带原始 Request/Response/XHR 上下文 | 请求专属补充或丢弃 |
-| Request Body `redact` | 单个请求/响应 Body，必填 | 内容级脱敏；返回 `undefined` 跳过该 Body |
-| `tracking.beforeSend` | Span/Log 进入底层 processor 前 | 最终兜底修改或丢弃；不作用于 Metric |
-
-第三方 instrumentation 自己生成的属性不经过 SDK 的 `redactAttributes` 构造路径。若要统一约束第三方 Span，应在 `tracking.beforeSend` 中做最终清理。
-
-## 扩展边界
-
-- RUM 语义、Session/View 关联、Log 或活动总线：使用 `createPlugin()`。
-- 已有标准 OpenTelemetry instrumentation：通过 `extensions.instrumentations` 或 `useInstrumentation()` 注册。
-- 自定义 Log 使用 `context.emitLog()`，不要直接 `context.logger.emit()`，否则不会自动合并运行时上下文。
-- 自定义 Span 优先使用 `context.startSpan()`，它会应用运行时属性与脱敏。
-- 当前包没有导出稳定的自定义 Metric 采样属性/helper。直接使用 `context.meter` 创建的数据点默认无法通过 `FilteringMetricExporter`；不要依赖内部 `bk.rum.sampled` 字段，也不要把 `getRuntimeAttributes()` 中的唯一 Session/View/Action ID 整体复制到 labels。需要稳定扩展时优先使用 Span/Log，或先在 SDK 内补充公共 Metric API。
-
-完整契约与示例见[自定义插件](./custom-plugin.md)。
+`privacy.redactUrl` 处理 URL，`privacy.redactAttributes` 处理 Resource 和 SDK Span，`tracking.beforeSend` 是导出前最终兜底。自定义 RUM 插件使用 `context.startSpan()`；SDK 不提供 `meter`、`logger` 或 `emitLog()`。

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

@@ -6,43 +6,43 @@
 
 ## 总览
 
-| 能力 | 配置入口 | 默认 | 浏览器入口 | Trace | Metric | Log |
-| --- | --- | --- | --- | --- | --- | --- |
-| Session | `session` | 必选基础能力 | `localStorage`、用户活动、页面可见性 | — | — | `session.start` / `session.rotate` |
-| View | `tracking.view` | 自动模式 | Navigation Timing、History、hash、BFCache、DOM Mutation | `browser.view` | `browser.view.loading_time` | `browser.view` Snapshot |
-| Fetch/XHR | `tracking.request` | 开 | `fetch`、`XMLHttpRequest`、Resource Timing | `browser.resource` | — | 可选 `browser.request.body` |
-| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` | — | — |
-| JS / Promise / 资源错误 | `tracking.error` | 开 | `error`、`unhandledrejection` | 三类 `browser.*error` | — | — |
-| Web Vitals | `tracking.webVitals` | 开 | `web-vitals`、Layout Shift、Event Timing | `browser.web_vital` | 两个 Histogram | — |
-| Action | `tracking.action` | 开 | click、DOM、请求与活动总线 | `action.click` | — | — |
-| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` | — | — |
-| 自定义事件 | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` | — | — |
-| 白屏 | `tracking.blankScreen` | 开 | DOM 命中测试、View 活动 | `browser.blank_screen` | `browser.blank_screen.count` | — |
-| 设备 | `tracking.device` | 开 | UA、UA-CH、Screen、Network Information | Resource 与运行时公共属性 | — | Resource 与运行时公共属性 |
-| Long Task | `tracking.longTask` | 关 | Long Animation Frames / Long Tasks | `browser.long_task` | 三个聚合指标 | — |
-| WebSocket | `tracking.websocket` | 关 | `WebSocket` Proxy | `websocket.connect` | 四个聚合指标 | error / close |
-| CSP | `tracking.cspViolation` | 关 | `securitypolicyviolation` | `csp.violation` | — | — |
-| 自定义插件 | `extensions.plugins` / `use()` | 无 | 由插件决定 | 支持 | 无稳定公共辅助 API | 推荐 `emitLog()` |
-| OTel instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | 由 instrumentation 决定 | 支持 | 无稳定支持 | 取决于实现 |
-
-“默认开”表示获得 Consent 且 SDK 已启动后启用。是否真正导出还受 `enabled`、Session 采样、Session/View 有效性和单信号开关控制。
+| 能力 | 配置入口 | 默认 | 浏览器入口 | 原始 RUM Span |
+| --- | --- | --- | --- | --- |
+| Session | `session` | 必选基础能力 | `localStorage`、用户活动、页面可见性 | `browser.session` start/rotate/end |
+| View | `tracking.view` | 自动模式 | Navigation Timing、History、hash、BFCache、DOM Mutation | `browser.view` start/update/end |
+| Fetch/XHR | `tracking.request` | 开 | `fetch`、`XMLHttpRequest`、Resource Timing | `browser.resource` |
+| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` |
+| JS / Promise / 资源错误 | `tracking.error` | 开 | `error`、`unhandledrejection` | 三类 `browser.*error` |
+| Web Vitals | `tracking.webVitals` | 开 | `web-vitals`、Layout Shift、Event Timing | `browser.web_vital` |
+| Action | `tracking.action` | 开 | click、DOM、请求与活动总线 | `action.click` |
+| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` |
+| 自定义事件 | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` |
+| 白屏 | `tracking.blankScreen` | 开 | DOM 命中测试、View 活动 | `browser.blank_screen` |
+| 设备 | `tracking.device` | 开 | UA、UA-CH、Screen、Network Information | Resource 与运行时公共属性 |
+| Long Task | `tracking.longTask` | 关 | Long Animation Frames / Long Tasks | `browser.long_task` |
+| WebSocket | `tracking.websocket` | 关 | `WebSocket` Proxy | `browser.websocket` connect/open/error/close |
+| CSP | `tracking.cspViolation` | 关 | `securitypolicyviolation` | `csp.violation` |
+| 自定义插件 | `extensions.plugins` / `use()` | 无 | 由插件决定 | `context.startSpan()` |
+| OTel instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | 由 instrumentation 决定 | 支持 |
+
+“默认开”表示获得 Consent 且 SDK 已启动后启用。是否真正导出还受 `enabled`、Session 采样和 Session/View 有效性控制。
 
 ## 能力边界
 
 ### SDK 直接负责
 
 - 创建和轮换 Session，划分初始加载、SPA、BFCache、手动和 Session 续期 View。
-- 统一 patch Fetch/XHR；请求 span、活动计数、Trace Header、Resource Timing 和 Body 采集共用同一生命周期。
+- 统一 patch Fetch/XHR；请求 span、活动追踪、Trace Header 和 Resource Timing 共用同一生命周期。
 - 把浏览器事件归一为 `span_type`、`span_subtype`、`result`、`error_type` 等字段。
-- 自动为 Span/Log 关联 `session.id`、`view.id`，为 Metric 保留低基数 `view.url_path_group`。
+- 自动为 Span 关联 `session.id`、`view.id` 和 `action.id`。
 - 在 exporter 前执行采样、有效上下文、自上报请求和 `tracking.beforeSend` 过滤。
 
 ### SDK 不负责
 
 - 不聚合 `session.duration`、影响用户数、地理信息、Trace 关键路径等后端指标。
 - 不自动判断业务字段是否敏感，也不 hash `user.id`。
-- 不默认采集 HTTP 请求/响应 Body。
-- 不把唯一的 `session.id`、`view.id`、`action.id` 放入 Metric labels。
+- 不采集 HTTP 请求/响应 Body。
+- 不在浏览器生成 Counter、Histogram、分位数、错误指纹或跨事件计数。
 - 不保证浏览器未暴露的数据，例如缺少 `Timing-Allow-Origin` 的跨域资源网络阶段。
 
 ## 默认开启与关闭
@@ -84,13 +84,11 @@ Session 与 View 是导出有效性边界，不提供关闭开关。`tracking.vi
 
 | 能力 | 主要成本/风险 | 建议 |
 | --- | --- | --- |
-| `session.sampleRate` | 决定三类信号总体数据量 | 按应用容量设置；排障临时设为 `1` |
-| Metric 自定义维度 | 高基数会放大时序数量 | 只放应用、租户类别、路由模板等低基数字段 |
-| Request Body | 可能包含凭证、个人数据，且增加网络体积 | 默认关闭；开启时限制类型/大小并强制脱敏 |
+| `session.sampleRate` | 决定 RUM Span 总体数据量 | 按应用容量设置；排障临时设为 `1` |
 | Action 文本命名 | DOM 文本可能包含用户输入 | 保持 `nameCollection: 'explicit'`，关键元素使用 `data-bk-action-name` |
 | Device 持久 ID | 支持跨 Session 关联 | 默认不持久化；需取得合规依据后再开启 |
 | Long Task | 产生 Span 与脚本归因信息 | 仅性能分析场景开启，结合采样控制 |
-| WebSocket | Proxy 全局构造器并统计消息字节 | 同页面单实例；不采集消息内容 |
+| WebSocket | Proxy 全局构造器并监听连接生命周期 | 不包裹 `send()`，不采集消息内容、数量或字节数 |
 
 ## 下一步