@blueking/open-telemetry 0.0.34 → 0.0.35-beta.1

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

@@ -2,25 +2,25 @@
 
 # 用户 Action 与挫败信号
 
-Action 表示一次用户操作以及操作后引发的页面活动。SDK 默认自动监听 click，也提供 `reportAction()` 上报业务命名动作。自动 Action 才计算 Loading Time、页面活动和挫败信号。
+Action 表示一次用户操作及其页面活动观察窗口。SDK 默认自动监听 click，也提供 `reportAction()` 上报瞬时业务动作。自动 Action 才计算 Loading Time、页面活动和挫败信号；时间窗口关联是推断，不保证每个请求或 DOM 变化都由点击直接触发。
 
 ## 自动 Action 生命周期
 
-插件在 `window` 上以 capture + passive 监听 `click`，**只处理主键点击**（`event.button === 0`）。右键、中键和辅助键点击不创建 Action。
+插件在 `window` 上以 capture + passive 监听 `click`，只接收可见页面中的可信事件（`isTrusted=true`），且要求 `event.button === 0`。保留浏览器由键盘激活控件产生的可信 click；右键、中键、脚本派发和隐藏页面中的 click 不创建自动 Action。本实现不使用 pointerdown/pointerup 生命周期。
 
 一次 click 的处理过程：
 
-1. 从 Event 取得真实发生时间和 composed target（`composedPath()[0]`，因此能穿透 Shadow DOM 拿到真实内部元素）。
-2. 生成 `action.id`，保存当时的 Session/View 上下文。
-3. 把当前活动的 `action.id` 字符串写入运行时上下文，后续请求、资源、错误和 Long Task 自动关联。多个点击窗口重叠时取最近一次。
-4. 观察请求、DOM Mutation、Resource、Long Task、Error 和部分用户行为。
-5. 发生过页面活动后，等待所有请求完成并连续 100ms 无活动。
-6. 最长等待 `maxDuration`，默认 10 秒。
-7. 从运行时上下文移除 Action ID。
+1. 从 Event 取得真实发生时间和浏览器暴露的 composed target；关闭的 Shadow Root 不保证暴露内部目标。
+2. 生成单个 `action.id`，保存当时的 Session/View 上下文和目标快照，包括名称、selector、path、尺寸、位置及命名来源。
+3. 注册该 Action 的有效时间区间。Resource、Error、Long Task 按事件发生时间和所属 Session/View 查询全部匹配的 Action，使用 `action.ids` 数组关联。
+4. 观察请求、DOM Mutation、Resource 和 `window.open`；错误、长任务和用户行为另用于关联或挫败判断。
+5. 点击后 100ms 内出现页面活动时，等待所有跟踪中的请求完成并连续 100ms 无活动；否则以 `no_activity` 结束观察。
+6. 最长等待 `maxDuration`，默认 10 秒；View 切换、Session 过期、页面隐藏/退出及 shutdown 也会结束观察。
+7. 关闭 Action 的有效区间，停止吸收新区间的事件。已开始请求晚到结束仍保留开始时的关联。
 8. 最多再等待到 click 后 1 秒完成 Rage Click 判断。
 9. 使用 `action.name` 创建并结束 Action Span。
 
-上报等待期不会延长 Action 关联窗口；后续无关事件不会因为等待 Rage Click 判断而关联旧 Action。
+上报等待期不会延长 Action 关联窗口。Action 自身的 `action.id` 始终是字符串；子事件仅使用 `action.ids: string[]`，不双写旧 `action.id`。多个窗口重叠时允许多关联。未声明 `span_type` 的通用 OpenTelemetry Span 不自动推测 Action 归属。
 
 ## Action 活动
 
@@ -29,13 +29,22 @@ Action 表示一次用户操作以及操作后引发的页面活动。SDK 默认
 - Fetch/XHR 开始和结束；
 - 静态资源完成；
 - DOM Mutation；
-- Long Task；
-- Error；
 - `window.open`。
 
-Error 会把 Action 标记为发生过活动、更新结束时间并标记 `error_click`；Long Task 也只影响 Action Activity。View Loading Time 的稳定判断会忽略 Error 和 Long Task。`view.excludedActivityUrls` 命中的请求/资源不参与 Action 活动。
+Error 和 Long Task 不延长 Loading Time。通过过滤且关联到 Action 的 Error 可标记 `error_click`。`view.excludedActivityUrls` 命中的请求/资源不参与 Action 活动；带 `data-bk-excluded-activity-mutations` 的节点及后代 Mutation 也被排除。
 
-点击后 100ms 内没有任何页面活动时，Action 以零持续时间结束（Span 起止时间相同）；它仍可能被识别为 Dead Click。持续时间用 OTLP 起止时间表达，不写 `action.loading_time` Attribute。
+Span 起止时间记录已观察区间；`action.loading_time` 单独表达已确认的页面稳定耗时，单位为**毫秒**，与 `view.loading_time` 一致。只有正常观察到页面稳定（`action.end_reason=activity_end`）时才写入，正常稳定时不含尾部 100ms 安静等待。没有活动、达到上限或生命周期中断时不写该字段，缺失不能解释为 `0`。
+
+| `action.end_reason` | 含义                 | `action.loading_time` |
+| ------------------- | -------------------- | --------------------- |
+| `activity_end`      | 已出现活动并正常稳定 | 写入毫秒数            |
+| `no_activity`       | 验证窗口内无页面活动 | 不写                  |
+| `timeout`           | 达到 `maxDuration`   | 不写                  |
+| `view_change`       | 所属 View 结束或切换 | 不写                  |
+| `session_expired`   | 所属 Session 结束    | 不写                  |
+| `page_hidden`       | 页面切到后台         | 不写                  |
+| `page_exit`         | 页面退出             | 不写                  |
+| `shutdown`          | 插件停止             | 不写                  |
 
 ## 自动命名
 
@@ -57,25 +66,28 @@ tracking: {
 <button data-bk-action-name="提交订单">提交</button>
 ```
 
-遥测中的名称为 `Click on 提交订单`，同时写入：
+Action Span 名和 `action.name` 均为 `click 提交订单`，同时写入：
 
 - `action.target.name=提交订单`
 - `action.target.tag=button`
+- `action.name_source=explicit`
 
 名称会合并连续空白、截断到 100 字符。
 
 ## 文本命名模式
 
-`nameCollection='text'` 才会继续读取：
+`nameCollection='text'` 才会继续尝试可访问名称及 DOM 文本：先向上查找安全的 `aria-labelledby`、`aria-label`、关联 label、`alt`、`title`，再读取目标的安全文本，最后回退到标签名。SDK 不读取输入值，也不采集 textarea、select、contenteditable 的正文或可编辑内容。
+
+`data-bk-privacy="mask"` 阻止文本及可访问名称采集，仍允许显式业务标签。目标或跨 Shadow 祖先为 `data-bk-privacy="hidden"`、`hidden`，或由 CSS 隐藏时，跳过整个自动 Action。`aria-hidden="true"` 仅限制文本采集，不丢弃可见装饰图标上的点击。mask 子树中的 selector/path 只保留显式业务标签和结构，不携带 ID/test data 属性。键盘激活的 click 不上报鼠标位置。
+
+`action.name_source` 区分 `explicit`、`accessible_name`、`text` 和 `fallback`。文本模式仍可能读取页面展示的业务信息，因此默认保持 `explicit`；名称、selector 和 path 都受目标隐私规则约束。
 
-1. 关联 label；
-2. button/reset/submit input value；
-3. button、label、`role=button` 文本；
-4. `aria-label`、`alt`、`name`、`title`、`placeholder`；
-5. DOM textContent；
-6. 从目标开始，最多继续检查 10 层父级；遇到 form/body/html/head 停止。
+## 目标定位与坐标
 
-该模式可能采集用户输入、订单内容或个人信息。生产环境优先使用 `explicit`，只有完成隐私评估后才启用文本模式。
+- `action.target.selector` 优先使用稳定属性、非动态 ID，再回退到结构定位，并验证唯一性；最长 512 字符，单个 DOM/Shadow 根内最多回溯 20 层。无法在上限内定位时省略，不截断成无效 selector。它描述采集时的 DOM，不保证跨版本稳定。Shadow DOM 边界使用 `::shadow` 标记，该标记不是标准 CSS，不能把完整字符串直接传给 `querySelector`。
+- `action.target.path` 为事件 `composedPath()` 中 Element 的 selector 数组，顺序从目标到祖先，最多 10 项、总长度最多 2048 字符。它不是 HTML、完整属性或文本内容的快照，不读取任意 dataset 或 href。
+- `action.target.width` / `height` 是目标尺寸，`action.position.x` / `y` 是相对目标的点击坐标，单位均为 CSS px，不是屏幕物理像素。
+- 这些字段在 click 捕获时读取；目标不可定位或隐私策略不允许时，相应字段可以缺失。关闭的 Shadow Root 内部结构以浏览器实际暴露范围为限。
 
 ## Rage Click
 
@@ -102,17 +114,17 @@ button、checkbox、radio、range、reset、submit input 仍可判断。
 
 ## Error Click
 
-Action 活动窗口内发生由 Activity Bus 通知的前端错误时，标记 `error_click`。Error 不要求是 Action Span 的子 Span，只要事件时间落在活动窗口并带同一 `action.id` 即可在服务端关联。
+Error 通过采样和 `beforeSend` 等过滤进入 SDK 发送流后，按其 `action.ids` 标记对应 Action 的 `error_click`。被过滤的 Error 不参与判断，也不延长页面活动窗口。关联与挫败判断使用同一组 ID；Error 不要求是 Action Span 的 Trace 子 Span。进入发送流不代表服务端已经成功入库。
 
 ## Outcome 与字段
 
 自动 Action Span：
 
-| 条件 | `outcome.type` | 具体语义 |
-| --- | --- | --- |
-| 无错误、无挫败 | `success` | 无 |
-| 有前端错误 | `warning` | `action.frustration.type=error_click` |
-| 只有 Rage/Dead Click | `warning` | `action.frustration.type` 对应值 |
+| 条件                 | `outcome.type` | 具体语义                              |
+| -------------------- | -------------- | ------------------------------------- |
+| 无错误、无挫败       | `success`      | 无                                    |
+| 有前端错误           | `warning`      | `action.frustration.type=error_click` |
+| 只有 Rage/Dead Click | `warning`      | `action.frustration.type` 对应值      |
 
 关键字段：
 
@@ -120,11 +132,16 @@ Action 活动窗口内发生由 Activity Bus 通知的前端错误时，标记 `
 - `action.type=click`
 - `action.target.name`
 - `action.target.tag`
+- `action.target.selector`、`action.target.path`
+- `action.target.width` / `height`、`action.position.x` / `y`
+- `action.name_source`
+- `action.end_reason`
+- `action.loading_time`：仅正常稳定时有，单位 ms
 - `action.frustration.type`，按 `rage_click`、`dead_click`、`error_click` 固定顺序的数组
 
-有页面活动时，持续时间体现在 Span 起止时间上，不写 `action.loading_time` Attribute。完整字段见[遥测字段字典](./telemetry-reference.md#action-字段)。
+未命中挫败信号时不写 `action.frustration.type`。`outcome.type=success` 只表示未观察到错误或挫败，不代表业务成功；是否超时或中断应查看 `action.end_reason`。完整字段见[遥测字段字典](./telemetry-reference.md#action-字段)。
 
-SDK 不在 Action Span 中写请求数、资源数、错误数或 Long Task 数；服务端通过 `action.id` 关联原始事件后派生。
+SDK 不在 Action Span 中写请求数、资源数、错误数或 Long Task 数；服务端通过子事件 `action.ids` 关联 Action 自身的 `action.id` 后派生。
 
 ## 手动 Action
 
@@ -141,17 +158,17 @@ bkOT.reportAction({
 
 - 新生成独立 `action.id`；
 - `action.type=custom`；
-- Span 名为 `action.<传入 name>`；
+- Span 名为传入的 `name`，不添加 `action.` 前缀；
 - `span_type=action`、`outcome.type=success`；
 - 不建立活动窗口；
 - 不计算 Loading Time 或挫败信号；
-- 不把该 ID挂到后续请求/错误。
+- 不把该 ID 挂到后续请求/错误。
 
-未采样、未授权或没有有效 View 时不会导出。`reportAction()` 未采样时静默返回。
+未采样、未授权或没有有效 View 时不会导出。`reportAction()` 未采样时静默返回。当前没有持续型 `startAction` / `stopAction` API，也没有 Rage 分组协议。
 
 ## Flush 与页面退出
 
-页面隐藏、pagehide、Session 过期、插件 flush 或 shutdown 时，SDK会结束仍活动的 Action，并立即落数等待中的 Rage Click Action，避免正常生命周期中积压。
+普通 `flush()` 只发送已经准备好的 Span，不强制终结仍在观察或等待 Rage 判断的 Action。View 切换、页面隐藏、pagehide、Session 过期或 shutdown 按对应原因结束自动 Action；只有正常稳定的动作才有 Loading Time。Session 共享结束快照不可用等无法恢复旧边界的情况，遵循 [Session 上下文](./session-context.md) 的保守清理规则。
 
 ## 常见问题
 
@@ -163,9 +180,9 @@ bkOT.reportAction({
 
 预期行为，只有 `event.button === 0` 的主键点击会创建 Action。需要记录其他交互时用 `reportAction()`。
 
-### 点击有请求但 Span 持续时间为 0
+### 点击有请求但没有 action.loading_time
 
-检查请求是否命中 `view.excludedActivityUrls`，click 是否在请求开始前被其他监听逻辑延迟，以及 Action 是否在未采样/无 View 状态发生。持续时间看 Span 起止时间，不要查 `action.loading_time` Attribute。
+先检查 `action.end_reason`：无活动、超时和中断不会生成 Loading Time。再检查请求是否命中 `view.excludedActivityUrls`、是否在 click 之前已经开始，以及 Action 是否在有效 Session/View 内发生。Span 起止记录观察时间（正常结束包含尾部 100ms 确认等待），不能代替页面稳定结果。
 
 ### Dead Click 过多
 

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

@@ -27,7 +27,7 @@ const rum = new BkOpenTelemetry({
 CDN bundle 的默认导出会挂到：
 
 ```js
-window.BkOpenTelemetry
+window.BkOpenTelemetry;
 ```
 
 它只提供这个构造函数，不挂载 ESM 入口里的插件工厂、schema 常量或 TypeScript 类型。
@@ -59,7 +59,7 @@ await rum.start();
 
 ### `flush(): Promise<void>`
 
-并行调用已启动插件的 `flush()`，然后 `forceFlush()` Trace Provider。
+先同步 drain 浏览器队列，再按启动顺序调用插件 `flush()`，最后 `forceFlush()` Trace Provider。单个插件异常不会阻止其余插件清理。
 
 ```ts
 await rum.flush();
@@ -116,13 +116,14 @@ rum.startView({
 
 `BkOTStartViewOptions`：
 
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| `name` | `string` | View 展示名；缺省时使用低基数 path group |
-| `url` | `string` | View URL；缺省时使用当前 `location.href` |
-| `attributes` | `Attributes` | 该 View 生命周期内附加到后续 Span 的自定义属性 |
+| 字段          | 类型         | 说明                                           |
+| ------------- | ------------ | ---------------------------------------------- |
+| `name`        | `string`     | View 展示名；缺省时使用低基数 path group       |
+| `url`         | `string`     | View URL；缺省时使用当前 `location.href`       |
+| `urlTemplate` | `string`     | Router 匹配的低基数模板，优先于 URL 推断       |
+| `attributes`  | `Attributes` | 该 View 生命周期内附加到后续 Span 的自定义属性 |
 
-只有当前 Session 命中采样时才派发命令。推荐 `tracking.view.tracking: 'manual'` 时使用。View 自定义属性不能覆盖 SDK 保护的 RUM 语义字段和采样字段；在新 View 开始时旧 View 属性会被清除。
+保存最新路由意图，在允许采集且有有效 Session 后建立 View；首次 hidden/未授权时不导出，也不丢失意图。已 shutdown 后忽略。推荐 `tracking.view.tracking: 'manual'` 时使用。View 自定义属性不能覆盖 SDK 保留字段；新 View 清除旧业务属性。
 
 ```ts
 const rum = new BkOpenTelemetry({
@@ -156,6 +157,23 @@ requestAnimationFrame(() => rum.setViewLoadingTime());
 
 适用于业务明确知道页面“可用”时刻的场景。它不接受数值参数，时间点就是调用当下；没有采样 Session 时被忽略。
 
+### View 上下文与业务时间点
+
+```ts
+rum.setViewContext({ 'biz.page_kind': 'detail' });
+rum.setViewContextProperty('biz.order_id', '42');
+rum.setViewContextProperty('biz.order_id', undefined);
+const context = rum.getViewContext();
+rum.addTiming('content.ready');
+rum.addTiming('data.ready', 240);
+```
+
+`setViewContext` 替换当前 View 的业务属性，`setViewContextProperty` 更新或删除一个字段；均经过脱敏与字段保护，从调用时刻影响后续事件并发出 View update。`getViewContext` 返回副本。没有有效 View 时修改命令不产生遥测。
+
+`addTiming(name, elapsed?)` 上报 `view.custom_timings.<name>`，单位是相对 View 起点的 ms；省略 elapsed 使用调用时刻，显式数值不是 epoch。无效/负数/未来值忽略，同名覆盖，最多 100 个名称。
+
+`trackVueRouterViews(rum, router)` 提供无 Vue 打包依赖的标准接入，必须配置 manual，返回幂等卸载函数。详见 [Vue Router 接入](./views-routing.md#vue-router-标准接入)。
+
 ## 手动事件 API
 
 两个手动 API 都不维护启动前队列。默认构造函数触发的 autoStart 是异步的；构造后立即同步调用可能发生在 View 插件建立上下文之前。需要可靠接收首个业务事件时，设置 `autoStart: false`，先 `await start()`；manual View 再调用 `startView()`，最后才调用手动事件 API。
@@ -245,19 +263,19 @@ rum.useInstrumentation(instrumentation);
 
 以下方法在实例上公开，但主要面向 `BkOTPlugin.init(context)`：
 
-| 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` |
+| 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`                      |
 
 `BkOpenTelemetry` 类实现上还公开了 `registerInstrumentations()`，但 `BkOTInstance` 接口有意不把它作为普通实例契约；自定义扩展应通过 Plugin Context 的同名方法调用，常规接入应使用启动前的 `useInstrumentation()`。
 
@@ -279,20 +297,23 @@ span.end(endedAt);
 
 `BkOTStartSpanOptions`：
 
-| 字段 | 说明 |
-| --- | --- |
-| `startTime` | OTel `TimeInput`；浏览器场景常用 epoch milliseconds |
-| `contextTime` | 用哪个 epoch ms 回查 Session/View/Action；缺省时复用数字型 `startTime` |
-| `kind` | SpanKind，默认 `INTERNAL` |
-| `links` | `Link[]`，关联其他 Trace。OpenTelemetry 只允许在创建时传入，Span 结束前无法追加；内置请求插件用它把后端 Trace 关联回 Resource Span |
+| 字段          | 说明                                                                                                                               |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `startTime`   | OTel `TimeInput`；浏览器场景常用 epoch milliseconds                                                                                |
+| `contextTime` | 用哪个 epoch ms 回查 Session/View/Action；缺省时复用数字型 `startTime`                                                             |
+| `contextAttributes` | 完整运行时属性快照。提供时替代自动上下文读取，缺失字段不会由 Processor 补回；仍执行脱敏与 Session 采样。用于已冻结归属的迟到指标。 |
+| `kind`        | SpanKind，默认 `INTERNAL`                                                                                                          |
+| `links`       | `Link[]`，关联其他 Trace。OpenTelemetry 只允许在创建时传入，Span 结束前无法追加；内置请求插件用它把后端 Trace 关联回 Resource Span |
 
 运行时属性先合并，显式 `attributes` 后合并，因此显式同名字段优先；整体再经过 `redactAttributes`。未采样时返回 OTel non-recording Span，调用方仍可安全 `end()`。
 
+插件 Context 还提供 `collectionStart` 和 `getViewHistory()`：前者标识本次采集区间及物理文档首次采集资格；后者返回最多 100 个 View 的最后上下文、相对起止时间与原生交互计数边界的隔离副本。这些是内部关联数据，不会作为 `relativeStartedAt` 等字段上报。
+
 延迟到达的 PerformanceEntry 应同时设置真实 `startTime` 和 `contextTime`，避免把旧事件错误关联到新的 View。
 
 ### `setRuntimeAttributes()` 的边界
 
-它是扩展底层能力，不是常规业务标签 API。传入 `session.id` 会触发采样决定重算；错误修改 `view.*` 或 `action.id` 会破坏关联历史。普通业务字段更适合通过 context Hook、View attributes 或事件 payload 添加。
+它是扩展底层能力，不是常规业务标签 API。传入 `session.id` 会触发采样决定重算；错误修改 `view.*` 会破坏关联历史。`action.id`/`action.ids` 不接受全局改写，由 SDK 按独立 Action 区间维护。普通业务字段更适合通过 context Hook、View attributes 或事件 payload 添加。
 
 ## 配置解析函数
 
@@ -306,29 +327,29 @@ import { resolveConfig } from '@blueking/open-telemetry';
 
 以下值可以从 `@blueking/open-telemetry` 在运行时 import：
 
-| 导出 | 用途 |
-| --- | --- |
-| `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 生成 `span_type` 与 `outcome.type`；当前不写 `outcome.reason` |
+| 导出                                    | 用途                                                                                |
+| --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `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 生成 `span_type` 与 `outcome.type`；当前不写 `outcome.reason` |
 
 内置插件工厂适合 SDK 定制或组合插件。普通接入使用 `tracking` 开关即可；不要把同一个内置工厂再放进 `extensions.plugins`，否则可能重复监听和上报。
 

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

@@ -25,18 +25,18 @@ SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、
 
 ## 模块职责
 
-| 模块 | 主要职责 |
-| --- | --- |
-| `core/config.ts` | 输入校验、默认值、Endpoint、Resource 属性与 Hook |
-| `core/sdk.ts` | Provider、Exporter、Processor、公开 API 和 SDK 生命周期 |
-| `core/runtime-context.ts` | User、Session、View、Action 当前快照与历史归属 |
-| `core/plugin.ts` | 插件契约、顺序启动、并行 flush、反向 shutdown |
-| `core/processor.ts` | 上下文补齐、自上报过滤、有效性过滤和 `beforeSend` |
-| `core/sampling.ts` | Session 级确定性采样 |
-| `core/page-activity.ts` | View Loading Time 共用的页面活动稳定判断 |
-| `core/action-activity.ts` | 请求、资源、DOM、错误、Long Task 等活动总线 |
-| `plugins/*.ts` | 浏览器 API 监听、事件归一和单项体验语义 |
-| `schema/*.ts` | RUM 公共字段、Span 类型和结果分类 |
+| 模块                      | 主要职责                                                |
+| ------------------------- | ------------------------------------------------------- |
+| `core/config.ts`          | 输入校验、默认值、Endpoint、Resource 属性与 Hook        |
+| `core/sdk.ts`             | Provider、Exporter、Processor、公开 API 和 SDK 生命周期 |
+| `core/runtime-context.ts` | User、Session、View、Action 当前快照与历史归属          |
+| `core/plugin.ts`          | 插件契约、顺序启动、同步 drain、顺序 flush、反向 shutdown           |
+| `core/processor.ts`       | 上下文补齐、自上报过滤、有效性过滤和 `beforeSend`       |
+| `core/sampling.ts`        | Session 级确定性采样                                    |
+| `core/page-activity.ts`   | View Loading Time 共用的页面活动稳定判断                |
+| `core/action-activity.ts` | 请求、资源、DOM、错误、Long Task 等活动总线             |
+| `plugins/*.ts`            | 浏览器 API 监听、事件归一和单项体验语义                 |
+| `schema/*.ts`             | RUM 公共字段、Span 类型和结果分类                       |
 
 ## 构造阶段
 
@@ -109,13 +109,13 @@ SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、
 - `user.id`
 - `session.id`、`session.type`、`session.has_replay`
 - `view.id`、`view.url`、`view.url_template`、`view.loading_type` 和 `view.name`；`view.name` 优先使用显式名称，否则取 URL 模板
-- 活动窗口内的 `action.id`
+- 逐 Action 区间内的 `action.ids` 数组，仅 Resource/Error/Long Task 自动关联
 - Device 插件产生的视口、屏幕、网络和设备 ID
 - View 自定义属性
 
 `context.attributes.page` 不是持久运行时快照；内置插件在创建具体 Span 时读取，Instrumentation 则由 Processor 的补齐函数在 onStart 时读取。
 
-上下文不仅保存当前值，还保留最多 100 个 Session、View、Action 生效区间。PerformanceObserver 可能在事件结束后才回调，插件可以按事件真实时间回查历史上下文，避免把旧页面的 Resource、Vital 或 Long Task 归到新 View。
+上下文不仅保存当前值，还保留最多 100 个 Session、View 生效区间和 100 个已关闭 Action 区间，尚未结束的 Action 另行保留。PerformanceObserver 可能在事件结束后才回调，插件可以按事件真实时间回查历史上下文，避免把旧页面的 Resource、Vital 或 Long Task 归到新 View。
 
 ## Span 导出条件
 
@@ -139,7 +139,7 @@ SDK 使用 `ZoneContextManager` 和 `W3CTraceContextPropagator`。它们是页
 
 ## Flush 时机
 
-`flush()` 先并行调用已启动插件的 `flush()`，再调用 Trace Provider `forceFlush()`。SDK 自动在以下时机尽力刷新：
+`flush()` 先同步读取所有插件的待交付队列，再按顺序执行检查点，最后调用 Trace Provider `forceFlush()`。SDK 自动在以下时机尽力刷新：
 
 - `window.pagehide`
 - `document.visibilityState` 变为 `hidden`
@@ -154,7 +154,7 @@ SDK 使用 `ZoneContextManager` 和 `W3CTraceContextPropagator`。它们是页
 服务端至少需要：
 
 - 以 `traceId + spanId` 去重；
-- 以 `session.id`、`view.id`、`action.id` 关联事件；
+- 以 `session.id`、`view.id`、子事件 `action.ids` 关联事件；
 - 以 `view.id + view.version` 幂等合并 View start/update/end；
 - 容忍网络批处理导致的乱序和迟到；
 - 使用 `session.sample_rate` 修正聚合；