ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话遥测:捕获策略、共享披露与脱敏 waterfall 的顺序到底怎么排

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话遥测脱敏OTel
接好 OTel 后才发现记了不该记的内容,或脱敏顺序不对漏字段。本文讲 SessionTelemetryRecord 的五个字段、ledger 与 ops 两条通道、capture 与 includeHistory 的差别,以及脱敏 waterfall 的短路规则。

遥测最容易出问题的不是接不上,而是接上之后才发现把不该导出的内容导出了。 DSH plugin 把捕获、脱敏与交接拆成三段:捕获服务规范化记录,waterfall 负责脱敏,后端只拿到处理后的副本。三段里任何一段理解错,都会在导出侧留下痕迹。 DSH插件 接 OTel 之前,最好先想清楚哪些字段允许出门,脱敏顺序错了事后很难补。

一条逻辑记录只有五个字段,但分工很硬

SessionTelemetryRecord 的字段少,是因为每个字段都只承担一种职责。(来源)

  • sourceEvent — 规范化信封但不含 data,正文由另行脱敏的 body 承载;操作记录没有这个字段。
  • channel — ledger(镜像会话日志)或 ops(操作信号),后端把两者放在不同的 instrumentation scope 下。
  • time — Unix 毫秒。ledger 用源事件的追加时间,ops 用发出时间。
  • severity — 预映射的告警级别,在捕获时就定好。
  • attributes — 刻意最小的身份属性。
  • body — 完整载荷,交接后不可再改。

severity 的映射规则值得记住:事件自身的结果标志说它是错,就映射成 error——例如工具消息的 isError、turn/end 的错误原因,以及 agent-error 操作记录;其余捕获事件默认 info;warn 留给 session-telemetry/record 策略与后端使用。

attributes 也有明确边界:ledger 记录带 session.id、session.format_version、event.type、event.seq,可选 session.cwd 与 session.parent_id;seeded 会话还会带 session.seed_length。ops 记录带 telemetry.op、session.id,agent-error 额外带 agent.id、turn、step、error.name。凡是能从 body 里恢复的,都刻意不在 attributes 里重复。

ledger 与 ops 是两条通道,去重规则不同

一条是日志镜像,一条是告警信号,别用同一套假设消费。(来源)

每条权威会话事件都会完整透传为一条有序 ledger 记录,包括每个携带完整紧凑 stream 的 assistant/message 或 assistant/attempt,以及由插件合并进来、该 seam 从未听说过的类型。进程本地的 agent/assistant-stream frame 不进入这条持久 feed。

边界语义同样明确:新 fork 从子会话自有后缀开始,包括继承标记与 fork 结束事件;恢复的 Session 从已存储前缀之后开始,包括恢复的 fork;后端可以选择 includeHistory 来包含完整前缀;重新收养同一对象时从交接游标之后继续。

投递是尽力而为的,这句话要按字面理解:游标标记的是“已交接”而不是“已送达”。记录可能丢失(崩溃、重载窗口),也可能重复(新对象回放、SDK 重试)。因此接收端对 ledger 记录按 (session.id, session.format_version, event.seq) 去重;ops 记录刻意省略这类标识——它们是用于告警的信号,不是用于累加的条目,重复被容忍而非去重。

共享披露说的是部署策略,不是投递回执

sharing 回答“这个部署允许共享到什么程度”,不回答“这条记录送到了没有”。(来源)

每个后端通过 ctx.sessionTelemetry 上必需的抽象 sharing 成员暴露部署级模式:

ts
type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'

官方特别澄清了两点:它既不是逐 Session 的接纳决定,也不是投递回执;/feedback 的确认文本不会去查询它。所以你不要拿 sharing 当“这条已经上报成功”的证据。

反馈侧还有一组归属事实:反馈后端授权 Session 前缀,并负责独立队列、逐请求调度与 4,000,000 字节上限。这条上限属于反馈后端,不是捕获服务。

捕获策略:live 与 on-demand

两种捕获模式的差别不在数据量,而在“什么时候读日志”。(来源)

ts
type SessionTelemetryCapture = 'live' | 'on-demand'

capture 默认 live,即跟随实时事件;on-demand 则等显式捕获再读权威日志。includeHistory 默认 false,它允许捕获已存储与继承的记录,但本身不授权捕获——两个开关各管一件事,不能互相替代。

OTel 后端使用按需捕获,并要求新的自身显式反馈;它只释放截至该反馈的完整前缀,且这条规则适用于所有提供方。这解释了为什么“接上 OTel 后历史会话迟迟不出现”:在拿到显式反馈之前,它不会释放前缀。

后端契约:emit 必须非阻塞

三个方法里只有 emit 是必需的,但它必须是非阻塞入队。(来源)

  • emit(record) — 把记录交给后端流水线。它由协调器从 session/event 热路径同步调用,所以任何比队列推送更慢的动作都会拖累 agent 循环;这里抛出的错误由协调器兜住并记录,永远不会回到循环。
  • flush() — 可选的轮次结束提示,即发即忘。多数后端应当不实现它,让 SDK 自己的批处理节奏决定导出时机;实现了就要自己承担它与 shutdown() 排空之间的并发关系,OTel 后端正是因此不实现。
  • shutdown() — 把 fiber 的销毁转发给 SDK:冲刷队列并达到静止。调用前已发出的内容必须仍被送达,包括在 flush 提示进行中入队的记录;协调器在调用它之前立即发出销毁时的 shutdown 标记。它被 dispose 等待,拒绝只记警告,绝不让应用拆除失败。

还有两条装配约束:一个上下文只允许一个实现,重复加载会抛错;后端要在自己的构造函数里组合 SessionTelemetryCoordinator 来装配捕获侧。按需捕获不创建 ops 记录。

脱敏 waterfall:不挂规则就等于不脱敏

seam 自身不带任何规则,导出数据有多干净完全取决于你挂了什么。(来源)

每条记录在权威事件副本与 emit() 之间都要经过 session-telemetry/record waterfall。四条堆叠规则:

  1. 变换 next() 返回值来堆叠 — 监听器一层层包裹,内层把记录原样传出。
  2. 不调用 next() 就返回,等于替换其下方的全部逻辑 — 这是短路,不是追加。
  3. 抛出异常会扣下这一条记录 — 在协调器的隔离范围内 fail-closed,且永远不会到达 agent 循环。
  4. 只作用于导出副本 — 权威会话日志永不改写。

调度时机也分两种:实时捕获在追加时同步派发;按需捕获在读取权威日志时派发。记录本身已经是协调器的深拷贝,监听器要返回新记录,不得就地修改。

实践上这意味着脱敏顺序是你可以控制的:先挂字段级掩码,再挂整体丢弃,最后挂后端适配。顺序反了,被掩码的字段可能又在下层被重建。

验证:敏感字段与重复投递

验证遥测要同时测“导出内容”和“重复消费”,只测一条不够。(来源) 六步:

  1. 挂一个只改 body 的 waterfall 监听器,断言后端收到的是改后值。
  2. 挂一个不调用 next() 就返回的监听器,断言下层全部逻辑被替换,而非叠加。
  3. 挂一个会抛错的监听器,断言该条记录被扣下,且 agent 循环不受影响。
  4. 用同一份日志回放两次,断言接收端按 (session.id, session.format_version, event.seq) 去重后条数不变。
  5. 检查 sharing 为 feedback-only 时,不要把 /feedback 的确认当作 full 的投递证明。
  6. 在 shutdown() 前制造一条 flush 途中的入队记录,断言它仍被送达。

想先看整体接入,可以对照OTel 可观测性与会话遥测概览;记录来源的完整事件词汇见会话派生消息。

一句话收束: ledger 镜像日志、ops 只发信号,游标只代表交接,sharing 只是部署策略,脱敏靠你挂的 waterfall,且只改导出副本。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 导出的遥测数据,会不会被塞进模型请求里?

不会,DSH plugin 明确说明上报数据不进入模型请求。DSH plugin 的遥测走导出通道,权威会话日志也不会被脱敏改写,脱敏只作用于导出副本。

DSH plugin 的遥测游标代表已经送达,还是只代表交接完成?

不代表,DSH plugin 的游标只标记已交接。DSH plugin 的投递是尽力而为,记录可能因崩溃或重载窗口丢失,也可能因对象回放或 SDK 重试重复,所以接收端要按事件身份去重。

DSH plugin 的 ledger 与 ops 记录怎么去重?

ledger 按会话身份加事件序号去重,ops 不去重。DSH plugin 让 ops 记录刻意省略事件序号,因为它是告警信号而不是累加条目,重复被容忍。

DSH plugin 没挂任何脱敏监听器时,导出数据会被处理吗?

不会,DSH plugin 的 waterfall 本身不带任何规则。DSH plugin 在没有监听器时把记录原样交给后端,导出数据有多干净完全取决于部署方挂了什么规则。

相关术语

SessionTelemetryRecord
SessionTelemetryRecord 是交给后端的逻辑记录,包含 sourceEvent、channel、time、severity、attributes 与 body。— packages/session/session-telemetry/src/index.ts
ledger
ledger 是镜像会话日志的遥测通道,每条权威会话事件对应一条有序记录,可按事件身份去重。— packages/session/session-telemetry/src/index.ts
ops
ops 是操作信号通道,承载没有日志归属的 agent-error 与 shutdown,刻意省略事件序号。— packages/session/session-telemetry/src/index.ts
session-telemetry/record
session-telemetry/record 是每条导出记录必经的 waterfall,先变换 next() 返回值堆叠,不调用 next 即替换下层全部逻辑。— packages/session/session-telemetry/src/index.ts

来源