Skip to content

DSH 插件(三):同一份事件流,实时转发与事后复盘 ​

会话跑完,想复盘时第一反应是去翻 ~/.dsh/sessions/*/session.jsonl.zstd。解压一看,只有 header,没有对话,没有工具调用,也没有报错。

事件不落盘。它们只在运行时通过 session/event 推给订阅者,会话结束就没了。这意味着任何“事后看”的需求,都必须有人提前接住这条流。

log-forwarder 和 session-export 就是两种接法:一个持续往外推,一个按需导出。这篇讲它们共用的事件契约,以及各自踩过的边界。

一、事件信封只有四个字段 ​

所有事件都走同一条总线,结构固定:

js
{ type: "tool/call", seq: 42, time: 1757..., data: { callId, name, arguments } }

type 是事件名,data 的结构随类型变化,真正需要小心的是 seq:

  • 总线按 seq 去重,重复的会被静默丢弃;
  • 补录、重放时 seq 必须单调递增,不能从 0 重新开始;
  • 插件自己的采集器也要维护 lastSeq,否则快照和实时流会叠出重复事件。

session-export 的采集器第一行就是去重:

js
handle(session, event) {
  const seq = Number.isFinite(event?.seq) ? event.seq : -1
  if (seq <= this.lastSeq) return
  this.lastSeq = seq
  // ...按 type 归一化
}

看起来只是一行判断,但少了它,补录的事件和实时事件会在报告里出现两遍。

二、补录:插件加载前发生的事怎么办 ​

插件不是从会话第一秒就在的。用户可能已经聊了三轮,才装上或启用它。这时只订阅实时流,前 20 分钟的内容全丢。

宿主给了 session.snapshotEvents():首次收到某个会话的事件时,先取一份快照补进去,再接实时流。

js
if (!recorders.has(session.id)) {
  const recorder = new SessionRecorder(config)
  recorders.set(session.id, recorder)
  for (const event of session.snapshotEvents()) {
    recorder.handle(session, event)   // 先补历史
  }
}
recorder.handle(session, event)       // 再处理当前这条

两个容易错的地方:

  1. 补录必须发生在处理当前事件之前,否则当前事件先占了 lastSeq,快照会被整段丢掉;
  2. 快照和实时流可能有重叠,仍然要靠 seq 去重,不能假设它们不重叠。

踩坑:不要试图回放 zstd

会话压缩包里只有元信息 header。事件没有落盘,这不是压缩或格式问题,是设计上就没存。任何“读文件重建时间线”的方案都走不通,只能在运行时接。

三、实时转发:三条通道,互不拖累 ​

log-forwarder 把原始事件归一化成统一 JSON,再分发到三个通道:

通道用途关键参数
WebSocket外部页面实时监控端口默认 18765,被占用则 +1,最多试 5 个
本地 JSONL留档、离线分析单文件上限 50 MB
Loki接入日志聚合缓冲 1,000 条,连续失败 10 次熔断

通道基类把“失败隔离”写进了契约:deliver() 不允许抛异常,内部失败只记 failed 并置通道状态,不能影响其他通道。否则 Loki 挂了会把本地文件通道一起拖死。

WebSocket 的端口处理也是为这个场景写的:固定端口最容易被占用,插件从首选端口开始逐个尝试,最多 5 个,全失败才报错。实际端口会回写到状态里,面板和 /status 读的是真实端口,不是配置值。

背压策略是“有界缓冲 + 丢弃最旧”。监控场景里,旧事件的价值低于新事件;如果无限缓冲,一次 Loki 故障就能把内存吃满。

四、事后复盘:导出的是一份能读的报告 ​

session-export 的目标不是“把 JSON 存下来”,而是“第二天能看懂昨天发生了什么”。它把事件归一化成轮次、工具调用、错误和统计,再渲染成 Markdown 或自包含 HTML。

几个有意的取舍:

  • 单会话事件有上限,超过就停止采集并标记 stopped,避免长会话把内存吃穿;
  • 文本按 maxContentLength 截断,导出的是复盘材料,不是完整 transcript;
  • 工具入参可选,默认不保留,避免把命令里的密钥写进报告;
  • 敏感字段掩码,在归一化阶段就处理,导出器拿不到原文。

统计是纯函数,从采集器快照派生:轮次耗时、P50、工具调用次数、最慢的三个工具。HTML 报告里还有一条轮次时间轴,能直接看出哪一轮卡了多久。

js
slowCalls.sort((a, b) => b.durationMs - a.durationMs)
return { ...base, p50TurnMs, slowestTools: slowCalls.slice(0, 3) }

这些数字比“总共用了 18 分钟”有用:18 分钟里可能有 12 分钟卡在一个超时的网络工具上,看最慢工具比看总时长更快定位。

五、两种接法怎么选 ​

维度log-forwardersession-export
时机始终在线按需导出
消费者外部系统人
数据形态标准事件 JSONMarkdown / HTML
失败影响单通道熔断导出失败,不影响会话
适合调试、演示、集中日志复盘、交接、留证

两个插件可以同时装。它们的采集是独立的,互不依赖;共用的是同一条 session/event 和同一套 seq 规则。

六、边界 ​

实时转发能看到“正在发生什么”,但看不到“为什么”:事件里没有模型的完整思维链,只有它最终发出的消息和工具调用。导出报告能给出耗时和错误,但给不出因果关系。

还有一个现实限制:插件只在他加载之后才看得到事件。补录能找回当前会话的历史,但找不回插件安装之前的旧会话。

为什么不做一个统一的“可观测平台”

那会变成一个独立服务,需要存储、查询、权限和前端。现在这两个插件各自只做一件事:一个把流送出去,一个把流变成报告。需要长期存储就接 Loki,需要人读就导出 HTML,边界清楚,卸载也干净。

下一篇从“看”转向“查”:让 Agent 在回答前先检索你的 Obsidian 笔记和真实论文,并且把引用格式交给确定性代码,而不是模型。

本文阅读--次|全站访问--次|访客--人