description: "面向部署方与后端作者的会话遥测捕获 seam 说明，用于选择上报后端、挂载脱敏规则或实现后端约定。" kind: "package-library"

@deepseek-ai/dsh-session-telemetry

English | 中文

概述

会话遥测让部署方发送会话活动的有序副本用于上报，同时保留权威会话日志。部署方选择一个上报后端，并可在投递前脱敏每个外发副本；如果没有脱敏规则，捕获的数据将原样离开进程。交接以非阻塞方式完成，因此上报不会延迟会话处理。投递采用尽力而为方式；如果进程崩溃，队列中的记录可能丢失。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

作为部署方，选择一个后端并挂载它，当记录不能以捕获原样离开进程时添加脱敏规则。作为后端作者，实现三成员约定，并以一种捕获模式组装协调器。

选择并挂载后端

只加载一个后端插件；它把捕获协调器与投递流水线注册为 ctx.sessionTelemetry。重复加载会抛出异常。必需的 sharing 成员 报告部署模式，不代表会话准入或投递。只有在未挂载任何遥测服务时，消费方才可报告「未配置」。/feedback 命令确认记录，不读取此策略。

后端约定

后端实现三个成员：emit(record) 必须是非阻塞入队，因为它会在会话事件路径上同步执行；可选的 flush() 是轮次结束后的即发即忘提示，多数后端为了遵循 SDK 自身的批处理计划而省略它；shutdown() 排空已入队记录，并在 SDK 停止后结束，dispose（资源释放）会等待它。实现 flush() 的后端必须安排并发 flush 与最终 shutdown() 排空的先后顺序。

捕获内容

捕获以两种模式之一运行。live 捕获在追加时跟随会话事件、在挂载时回放已存活会话并记录生命周期标记；on-demand 捕获只在后端通过 captureSession(session, throughSeq?) 请求前缀时读取权威会话日志。协调器选项决定是否包含存储历史。每条权威会话事件都按顺序映射为一条 ledger 记录。assistant/message 或 assistant/attempt 记录会携带完整的嵌入式紧凑流，包括失败和重试输出。每条 ledger 记录还携带 session.id、session.format_version、数值型事件标识、可选 header 事实与预先映射的严重级别（tool/result.isError、turn/end 的错误原因与 agent-error 映射为 error；其余为 info）。

ledger 记录携带 sourceEvent，其中包含所属 Session id 和不含 data 的事件信封副本。脱敏 waterfall 接收的 body 是唯一的载荷副本。后端可从信封和脱敏后的 body 重建完整导出事件，而不绕过脱敏。

共享披露

每个后端通过 sharing 披露部署模式：full、feedback-only 或 disabled。后端还可限制符合条件的会话。该属性不是投递回执；交接是非阻塞入队，批处理、重试与丢失策略属于后端 SDK。

脱敏记录

协调器复制权威事件后，每条外发记录都会立即经过 sessionTelemetry/record waterfall（瀑布式事件）。本包不带任何规则：未挂载监听器时，记录以捕获时的原样到达后端，因此导出数据能干净到什么程度，恰恰取决于部署方挂载了什么规则。监听器通过变换 next() 的返回值来堆叠；抛出异常的监听器以 fail-closed 方式拦下这一条记录。脱敏只作用于外发副本——权威会话日志永不改写。

理解实现

本节解释捕获设计；可观察行为已在使用本包中完整说明。

设计理念

捕获包负责完整事件捕获、脱敏和交接游标。脱敏规则必须保留 sourceEvent 才能通过 OTel 上传；返回不含它的新记录会阻止该事件上传并产生诊断。复制的 envelope 不含 data，数据仅由 body 携带。OTel 后端负责字节/条数调度并使用 SDK 传输和重试。历史恢复遥测决策记录 说明捕获和脱敏依据。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | Service Definition：SessionTelemetryBackend/SessionTelemetrySink 约定、记录词汇、session-telemetry/record waterfall 声明 | | src/coordinator.ts | 捕获：live 监听器、生命周期本地 on-demand 回放、脱敏、handoff 游标、异常隔离 |

捕获流程

实时捕获通过组合 fiber 的 effect 注册 Session 事件、刷新提示、关闭标记与 agent/error 观察器。按需捕获只注册释放 effect，并按历史策略读取请求的权威日志前缀。同步处理器隔离失败，避免影响 agent loop（智能体循环）或其他监听器。

handoff 游标

模块级 WeakMap<Session, seq> 记录已经移交的最高序号，而不是已送达的最高序号。再次接管同一对象时从该游标之后继续。采集从 firstLifecycleSeq 开始：新 fork 包含子会话自有的标记与 fork 结束事件；恢复的 Session 排除已存储前缀，包括先前的子会话轮次。显式 includeHistory: true 会让尚未移交的对象从 seq 0 开始，包括恢复或 fork 历史。Backend 负责采集授权；已有存储历史本身不构成授权，OTel backend 等待新的显式反馈。接收方通过 (session.id, session.format_version, event.seq) 对重复记录去重。

进一步探索

当 seam 约定不够用时阅读以下页面。它们从随附后端逐步进入子系统参考与决策证据。

• OpenTelemetry 遥测后端——部署方加载的随附后端，含模式与导出器配置。
• 会话遥测子系统——能力拆分与类型声明。
• 历史会话遥测复活决策——理由、权衡与被否决的替代方案。
• 会话包映射——相邻的持久化、投影、标题与遥测包。

模型体验

无，因为该 seam 观察会话流并把脱敏后的副本交给外部；它不注册任何面向模型的内容。

KV Cache 影响

无；本包既不组装也不发送提供方请求。

已知限制与延期工作

这些限制定义部署方能得到的投递与数据保护保证。它们是当前包约束。

• 尽力而为的投递——游标标记的是已交接而非已投递；在重载窗口内被拆除的会话无法重新收养，崩溃时留在后端队列中的内容会丢失。持久化 outbox（spool、每 sink 游标、at-least-once）推迟到有部署方提出明确的崩溃丢失要求时再实现。
• 不内置脱敏规则——未挂载 sessionTelemetry/record 监听器时，记录以捕获时的原样离开进程，包括文件内容或命令输出中内嵌的任何凭据；向共享 collector 导出的部署方自行负责其规则集。
• 按需脱敏使用当前状态——未捕获的事件只存在于权威会话日志中；后续的 captureSession() 会使用当时挂载的策略，深拷贝并脱敏其当前值，且不存在捕获时的遥测快照或持久化的捕获前 spool。

开发备注

无。