DSH plugin 怎么接会话遥测？TelemetryBackend、脱敏与 OTLP 队列

会话遥测不是“把日志再抄一份”，而是一条独立的导出链路：捕获服务负责把会话事件变成逻辑记录，脱敏 waterfall 负责裁剪敏感信息，后端负责非阻塞入队与批量导出。 它不会进入模型请求，也不保证不丢不重。写后端插件前，先接受这三条边界，否则实现会不自觉地阻塞智能体循环或承诺做不到的可靠性。

DeepSeek Harness：一条记录长什么样

每条遥测记录只有两种通道：ledger 与 ops；前者可去重，后者是告警信号。 对照：（来源）

attributes 刻意保持最小：ledger 带会话与事件身份，ops 带操作名与必要的 agent/turn/step；能从 body 恢复的内容不会重复塞进属性。

body 是完整载荷：ledger 是会话事件 data 的深拷贝，ops 是操作载荷。交给后端后不应再修改。

DeepSeek Harness：捕获与交接游标

捕获有两种模式：跟随实时事件，或按需读取规范日志；两者都受交接游标约束。 关键点：（来源）

1. live 捕获 — 在事件追加时同步分发。预期：适合实时监控，但 emit 必须足够快。
2. on-demand 捕获 — 只在显式请求时读取规范日志。预期：适合反馈型后端；OTel 后端就使用这种模式。
3. includeHistory — 可选包含继承的 fork 历史与更早生命周期。预期：默认不包含，避免重复导出旧前缀。
4. 重新收养 — 同一对象重新交给后端时，从交接游标之后继续。预期：不会从头重放。

新 fork 从子会话自有后缀开始，包含继承标记与 fork 结束事件；恢复的 Session 从已存储前缀之后开始。游标表示“已交接”，不是“已送达”。

DeepSeek Harness：脱敏 waterfall

脱敏规则不在 seam 里，而在 session-telemetry/record 的监听器里；不挂监听器就等于不脱敏。 要点：（来源）

• waterfall 自身无规则 — 最内层 next() 原样放行。预期：记录以捕获时原样到达后端。
• 监听器叠加 — 通过变换 next() 的返回值堆叠规则。预期：多个规则可以组合。
• 不调用 next() 即替换 — 返回自己的记录会替换下面所有逻辑。预期：适合整条丢弃或强制改写。
• 抛异常即扣下 — 监听器异常会让该条记录 fail-closed，不会进入循环。预期：敏感数据不会因为规则写错而漏出。
• 只改导出副本 — 权威会话日志永不改写。预期：本地审计记录保持原样。

脱敏发生在捕获热路径上，监听器要同步、快速、无阻塞；不要在这里做网络请求或大文件读写。

DeepSeek Harness：后端契约

后端只有三个动作：emit、可选 flush、shutdown；其中 emit 必须非阻塞。 逐项：（来源）

1. emit(record) — 同步调用，只做入队。预期：慢操作放到自己的队列里，异常被协调器隔离。
2. flush?() — 可选的轮次结束提示，fire-and-forget。预期：不要在这里阻塞，也不要有意义地抛错。
3. shutdown() — 冲刷队列并等待静止。预期：调用前已 emit 的记录仍要交付，包括 flush 在途时入队的记录。

SessionTelemetryBackend 每个上下文只允许一个实现，重复加载会抛异常。后端在构造函数里组合 SessionTelemetryCoordinator 来装配捕获侧。

DeepSeek Harness：三种后端策略

OTel、自定义 sink、完全关闭，选哪种取决于你要“观测”还是“合规”。 三种：（来源）

1. OTel 后端 — 用按需捕获，要求新的显式反馈，释放截至反馈的完整前缀。预期：适合标准可观测平台，队列与 4,000,000 字节上限由后端负责。
2. 自定义 sink — 实现 emit/flush/shutdown，把记录写到内部系统。预期：适合已有日志平台，但要自己处理去重与重试。
3. 关闭遥测 — 设 DSH_TELEMETRY_MODE=DISABLED。预期：完全不导出；OTLP 走 Node 自带 HTTP 客户端，本来也不经过代理。

如果环境禁止直连出网，OTLP 导出会失败；DSH 不依赖它，关掉不影响主流程。

DeepSeek Harness：隐私与可靠性边界

遥测的“最小身份”不等于“最小内容”；body 仍可能含对话与工具结果。 三点：（来源）

• 默认不脱敏 — 没有监听器就没有规则，敏感数据会按原样导出。
• 尽力投递 — 崩溃窗口可能丢，重放可能重；ledger 去重，ops 容忍重复。
• 不进模型请求 — 这条是确定的；不要把遥测当成“给模型看的上下文”。

上线前再检查三件事：脱敏监听器是否真的挂载、emit 是否只做入队、shutdown 是否能等到队列静止。三项都过，再谈导出效果。

还有一条容易被忽略：OTLP 导出器使用 Node 自带 HTTP 客户端，不走代理。如果环境禁止直连出网，导出会失败，但不影响 DSH 主流程；需要隔离时直接关闭遥测。

一个最小后端骨架

后端只做三件事：入队、可选 flush、shutdown 等静止。 骨架：

class MyTelemetryBackend {
  private queue: SessionTelemetryRecord[] = []

  emit(record: SessionTelemetryRecord) {
    this.queue.push(record) // 只入队，不做网络 IO
  }

  async shutdown() {
    // 冲刷队列，等待发送完成
    await this.drain(this.queue.splice(0))
  }
}

emit 在热路径同步调用，不能 await；需要网络请求时交给自己的 worker。shutdown 必须把调用前已 emit 的记录都交付，包括 flush 在途时入队的记录。

DeepSeek Harness 常见问题

Q：能不能在 emit 里直接写数据库？ 不建议。emit 在热路径同步调用，写库会拖慢循环；应先入队，再由自己的 worker 落盘。

Q：fork 会话会重复导出父会话历史吗？ 默认不会。新 fork 从子会话自有后缀开始；需要历史时显式开 includeHistory。

Q：脱敏规则写错会怎样？ 监听器抛异常会让该条记录被扣下，fail-closed；不会把未脱敏的数据放过去，但会丢这一条。

一句话收束： 遥测后端只要守住“emit 非阻塞、脱敏靠 waterfall、投递尽力而为”三条，就不会拖垮主循环，也不会给出虚假的可靠性承诺。