DSH 插件(三):同一份事件流,实时转发与事后复盘
会话跑完,想复盘时第一反应是去翻 ~/.dsh/sessions/*/session.jsonl.zstd。解压一看,只有 header,没有对话,没有工具调用,也没有报错。
事件不落盘。它们只在运行时通过 session/event 推给订阅者,会话结束就没了。这意味着任何“事后看”的需求,都必须有人提前接住这条流。
log-forwarder 和 session-export 就是两种接法:一个持续往外推,一个按需导出。这篇讲它们共用的事件契约,以及各自踩过的边界。
一、事件信封只有四个字段
所有事件都走同一条总线,结构固定:
{ type: "tool/call", seq: 42, time: 1757..., data: { callId, name, arguments } }type 是事件名,data 的结构随类型变化,真正需要小心的是 seq:
- 总线按
seq去重,重复的会被静默丢弃; - 补录、重放时
seq必须单调递增,不能从 0 重新开始; - 插件自己的采集器也要维护
lastSeq,否则快照和实时流会叠出重复事件。
session-export 的采集器第一行就是去重:
handle(session, event) {
const seq = Number.isFinite(event?.seq) ? event.seq : -1
if (seq <= this.lastSeq) return
this.lastSeq = seq
// ...按 type 归一化
}看起来只是一行判断,但少了它,补录的事件和实时事件会在报告里出现两遍。
二、补录:插件加载前发生的事怎么办
插件不是从会话第一秒就在的。用户可能已经聊了三轮,才装上或启用它。这时只订阅实时流,前 20 分钟的内容全丢。
宿主给了 session.snapshotEvents():首次收到某个会话的事件时,先取一份快照补进去,再接实时流。
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) // 再处理当前这条两个容易错的地方:
- 补录必须发生在处理当前事件之前,否则当前事件先占了
lastSeq,快照会被整段丢掉; - 快照和实时流可能有重叠,仍然要靠
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 报告里还有一条轮次时间轴,能直接看出哪一轮卡了多久。
slowCalls.sort((a, b) => b.durationMs - a.durationMs)
return { ...base, p50TurnMs, slowestTools: slowCalls.slice(0, 3) }这些数字比“总共用了 18 分钟”有用:18 分钟里可能有 12 分钟卡在一个超时的网络工具上,看最慢工具比看总时长更快定位。
五、两种接法怎么选
| 维度 | log-forwarder | session-export |
|---|---|---|
| 时机 | 始终在线 | 按需导出 |
| 消费者 | 外部系统 | 人 |
| 数据形态 | 标准事件 JSON | Markdown / HTML |
| 失败影响 | 单通道熔断 | 导出失败,不影响会话 |
| 适合 | 调试、演示、集中日志 | 复盘、交接、留证 |
两个插件可以同时装。它们的采集是独立的,互不依赖;共用的是同一条 session/event 和同一套 seq 规则。
六、边界
实时转发能看到“正在发生什么”,但看不到“为什么”:事件里没有模型的完整思维链,只有它最终发出的消息和工具调用。导出报告能给出耗时和错误,但给不出因果关系。
还有一个现实限制:插件只在他加载之后才看得到事件。补录能找回当前会话的历史,但找不回插件安装之前的旧会话。
为什么不做一个统一的“可观测平台”
那会变成一个独立服务,需要存储、查询、权限和前端。现在这两个插件各自只做一件事:一个把流送出去,一个把流变成报告。需要长期存储就接 Loki,需要人读就导出 HTML,边界清楚,卸载也干净。
下一篇从“看”转向“查”:让 Agent 在回答前先检索你的 Obsidian 笔记和真实论文,并且把引用格式交给确定性代码,而不是模型。