第6讲 · 会话日志与三级事件体系

《DeepSeek Harness 从上手到精通》系列 · 第二阶 核心概念篇

🎯 目标：理解"模型可见即已记录"这条运行时不变量 难度 ★★☆ ⏱ 约 25 分钟 前置：第 5 讲 Agent Loop

dsh 有一条贯穿全局的不变量：模型看到的，一定已经被记录下来了。理解这句话，你就理解了 dsh 的"可复现、可审计、可分支"从何而来。本讲基于 0.1.0-rc.5。

一、仅追加的 SessionEvent 日志

dsh 的会话日志是一串仅追加（append-only）的 SessionEvent。它只增不删，像一个不可篡改的流水账。常见事件按前缀分三类：

前缀含义例子
turn/*一轮对话的开始/结束turn/start、turn/end
step/*一轮内的单步推理step/start、step/llm
tool/*工具调用与结果tool/call、tool/result

二、deriveMessages()：一切都是"派生"

模型每一轮看到的"消息历史"，不是另存了一份，而是用 deriveMessages() 从事件流投影（project）出来的。这是关键洞察：

  • fork：从某个事件节点"分叉"出新会话，本质是换一个投影起点；
  • resume：从历史事件继续，投影接着往后走；
  • transcript：把事件流导出成人类可读记录，仍是同一份数据的另一种投影。

一句话：事件流是"真相源"，fork/resume/transcript 都是它的不同视角。所以你第 2 讲玩的 fork 分支实验，底层就是这么来的。

三、三级事件体系

dsh 的事件按"生命周期与作用域"分三级，理解它，你就看懂了第 2 讲 UI 上那些"影子"。

三级事件体系
图 1 三级事件：持久会话事件 / 实时 Agent 事件 / 能力事件，各司其职。
级别事件前缀特点
持久会话事件turn/* step/* tool/*落盘、可 fork/resume
实时 Agent 事件agent/*飞行中进度，UI 进度提示
能力事件fs/* tools/*文件/工具底层记录

四、四种派发模式

事件在插件之间如何传递，由派发模式决定。记住前两种最常用：

  • emit：发出就完事，不等任何人（通知类）；
  • waterfall：像瀑布一样依次经过监听器，任一处可短路（中间件拦截的精髓）；
  • parallel：多个监听器并发触发；
  • serial：严格串行，一个接一个。

审批弹窗、日志落盘，背后就是 waterfall + emit 的组合。

五、JSONL 与 SQLite 双后端

事件流可以落盘成两种后端，按需选择：

JSONL 与 SQLite 双持久化后端
图 2 同一份事件流，可投影为 JSONL（便于阅读/传输）或 SQLite（便于检索）。
后端适合特点
JSONL人工阅读、版本管理、传输一行一事件，纯文本
SQLite检索、查询、规模化结构化，可 SQL 查询

六、动手练习：导出 JSONL 并找 5 类事件

本讲产出是实操 + 标注：跑完一次真实任务后，导出该会话的 JSONL 日志，人工找出并标注以下 5 类事件各一条：

# 示意：导出会话事件（具体子命令以官方 CLI 为准） npx @deepseek-ai/dsh sessions export --format jsonl --out session.jsonl
  • turn/start · step/llm · tool/call · tool/result · turn/end

七、常见坑

  • 以为消息历史是单独存的：它是事件流的投影，改了事件流，历史随之变；
  • 混淆 agent/* 与持久事件：实时事件不落盘，刷新后消失，别拿它当记录；
  • waterfall 被短路找不到原因：某插件 return 了，后续监听器就不执行了，排查时看顺序；
  • 导出命令随版本变：子命令名以你安装的 dsh 实际为准，先 dsh sessions --help 确认。

八、官方文档对应章节

  • docs/ 中 SessionEvent / session 持久化相关章节
  • 事件派发（emit/waterfall/parallel/serial）机制文档
  • 建议阅读顺序：先本讲建立三级框架，再读官方 JSONL/SQLite 后端细节

本讲内容基于 DeepSeek Harness 官方文档与项目源码整理，仅供学习参考，具体命令与配置请以官方最新版本为准。系列文章配合源码仓库食用效果更佳：https://github.com/deepseek-ai/deepseek-harness

咨询 DeepSeek Harness 相关问题，请加微信：A0qingfengyuan_01

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由 AI 协助完成！