DeepSeek Harness 会话查询关系追踪:`traceSession` 与 `traceEvent` 的一次性视图设计

原创2026-09-19 14:14:161,907 阅读
文章标签:人工智能AI AgentAgent 框架DeepSeek

DeepSeek Harness 会话查询关系追踪:traceSession 与 traceEvent 的一次性视图设计

本文基于仓库中的设计笔记 .agents/notes/implemented/feature/2026-07-13-session-query-tracing.zh.md 展开,并结合 dsh-session-query 包源码(tracing.ts、types.ts、index.ts)与其单元测试(tracing.spec.ts)进行纵深解读。

导读

在 DeepSeek Harness 中,会话历史(session history)不是一份普通的消息列表,而是一份追加式(append-only)事件日志:会话之间的父子关系编码在不可变 header 的 parentSession 字段中,模型可见的“当前表面”(surface)由位置式替换操作(surfaceOp)决定,事件之间的派生关系则记录在 sourceEventSeqs 引用数组中。消费方若想重建这些关系,就不得不重复实现语料优先级、表面折叠、格式错误日志处理、确定性谱系排序与克隆等整套逻辑——这正是 ctx.sessionQuery 新增的 traceSession(sessionId) 与 traceEvent({ sessionId, seq }) 两个一次性视图要解决的问题。读完本文,你将掌握这两个追踪 API 的语义、校验边界、状态分离原则、源码级实现路径与测试验证方式。

背景:关系分散在三处,消费方无法低成本重建

设计笔记开篇指出了核心痛点:会话关系并非集中存储,而是分散在三种载体上:

  1. 不可变 header:会话之间的父子关系通过 SessionHeader.parentSession 表达,header 一经创建不可变更;
  2. 位置式表面操作:事件通过 surfaceOp: 'append' 或 surfaceOp: { op: 'replace', start, end } 决定自己在模型表面中的位置,替换操作会“遮蔽”(shadow)一段既有表面区间;
  3. 已记录的来源事件 seq 引用:事件通过 sourceEventSeqs 数组显式声明它引用了哪些更早的事件作为构造输入。

如果让每个消费方自己重建这些关系,就必须重复实现四类易错逻辑:语料优先级(live 与持久化数据如何取舍)、表面折叠(如何把日志回放为当前表面)、格式错误日志的处理(损坏的约定如何报错)、确定性的谱系顺序与克隆(父子与后代树如何排序、返回的数据如何与内部状态隔离)。

更关键的是,位置替换关系与来源事件引用关系语义不同:一次位置替换可能遮蔽表面节点,同时引用的来源事件可能根本不在表面上(例如压缩产生的摘要替换了一段用户消息,但摘要还引用了日志中更早的中间产物)。如果把它们合并为一种通用边类型,消费方将无法区分“谁在位置上取代了我”与“我引用了谁作为输入”。这正是后来“合并替换边与来源事件引用边”被否决的原因。

决策:在 ctx.sessionQuery 上公开两个一次性追踪视图

设计决策非常克制:在保留精确读取的基础上,仅为 ctx.sessionQuery 增加两个方法:

  • traceSession(sessionId):追踪会话谱系;
  • traceEvent({ sessionId, seq }):追踪单事件关系。

两个方法都是基于现有「实时数据优先」(live-preferred)语料的一次性视图:

  • 会话追踪读取一次完整语料列表(源码中对应 corpus.ts 的 listSessions,见 index.ts#L300-L304);
  • 事件追踪读取一份逻辑日志并执行一次规范表面折叠(对应 corpus.load 与 tracing.analyzeEventLog)。

服务在调用结束后不保留谱系、反向索引或替换状态——也就是说,每次调用都是独立计算,服务端零缓存、零状态。这保证了“真源”(source of truth)始终是日志本身,任何一次调用得到的都是当时一致时刻的确定性快照。

返回类型:类型级契约

两个方法的返回类型定义在 types.ts:

SessionLineageTrace 由公共字段加一个完整性判别联合组成:

/** Known ancestry and descendants for one logical session. */
type SessionLineageTrace = {
  /** Detached record for the session that was traced. */
  target: SessionRecord
  /** Known parents from the immediate parent outward. */
  ancestors: SessionRecord[]
  /** Complete known descendant trees rooted at the target's direct children. */
  descendants: SessionLineageNode[]
} & (
  | {
    /** The complete parent chain is present in the logical corpus. */
    complete: true
    /** Detached record at the top of the complete lineage. */
    root: SessionRecord
  }
  | {
    /** The parent chain leaves the visible logical corpus. */
    complete: false
    /** First parent id that is not present in the logical corpus. */
    unresolvedParentId: SessionId
  }
)

要点:

  • ancestors 按从直接父级到外层父级的顺序排列;
  • descendants 是递归的后代树,根节点是目标的直接子级;同级节点先按创建时间(createdAt)排序,再按 session id 排序(localeCompare),保证结果确定性(源码见 tracing.ts#L155-L157);
  • 判别联合使“已知根节点”与“第一个无法解析的父级 id”互斥:complete: true 时携带 root,complete: false 时携带 unresolvedParentId;
  • 与目标相连的环(ancestry 死循环)以 SESSION_QUERY_INVALID_LINEAGE 失败(源码见 tracing.ts#L130-L136)。

SessionEventTrace 则把两类关系分开保留:

/** Direct surface replacements and relationships to cited source events for one event. */
interface SessionEventTrace {
  /** Lightweight target record. */
  target: SessionEventRecord
  /** Immediate positional replacement event, when the target was shadowed. */
  replacedBy?: number
  /** Positional replacers from the immediate replacement to the final replacement. */
  replacementChain: number[]
  /** Surface nodes directly removed when the target itself performed a replacement. */
  replacedEventSeqs: number[]
  /** Earlier events cited directly as sources, in their recorded order. */
  sourceEventSeqs: number[]
  /** Later events that directly cite the target as a source, in log order. */
  derivedEventSeqs: number[]
}
  • replacedBy:直接的位置替换者(目标被遮蔽时存在);
  • replacementChain:沿替换者一路追踪至最终节点的完整链条;
  • replacedEventSeqs:目标自身执行替换时直接移除的真实表面节点;
  • sourceEventSeqs:日志中直接来源的顺序(保持记录顺序);
  • derivedEventSeqs:按日志顺序列出后续直接反向引用目标的更晚事件。

需要特别强调的是:查询不会沿被引用的来源事件继续向上追踪——所有 seq 列表(除 replacementChain 外)都只含直接链接。这一刻意选择在“考虑过的替代方案”中解释过:如果返回所有传递引用的来源事件,会掩盖日志中直接记录的证据、无谓增大结果,并让一条遥远的格式错误边改变原本局部的输出。

此外,traceEvent 在服务层返回的是 SessionEventTraceObservation(在 index.ts#L313-L320 中构造),即 SessionEventTrace 附带与事件日志同一观测绑定的克隆 header session,供执行授权检查的消费方验证来源。

校验边界:先验目标,再对整个日志接受或拒绝

事件追踪的校验顺序在源码中有明确体现(tracing.ts#L65-L105):

  1. 先检查目标是否存在:events[seq] 缺失或 seq 不匹配时抛出 SESSION_QUERY_EVENT_NOT_FOUND,不做任何表面或来源事件分析——避免用损坏的日志掩盖“目标不存在”这一更基础的错误;
  2. 随后,事件列表与追踪共用 dsh-session 的单遍表面折叠(foldSurface,来自 @deepseek-ai/dsh-session),对加载的整份日志整体接受或整体拒绝,绝不产出部分结果。

analyzeEventLog(tracing.ts#L175-L214)把折叠结果转成三类事件记录:current(当前表面节点)、shadowed(被替换遮蔽)、log-only(纯日志),并构建 replacedBy 与 replacedEventSeqs 两个反向索引——但这两个索引只存在于单次调用内部,调用结束后即被丢弃。

foldSurface 本身定义在 packages/core/session/src/surface.ts,折叠过程中会对每条事件做局部校验(surfaceOpOf,见该文件 L184 起):非表面事件不能携带 surfaceOp 或 sourceEventSeqs,表面事件必须携带 surfaceOp 标记。事件追踪把折叠抛出的任何错误统一包装为 SESSION_QUERY_INVALID_SURFACE。

设计笔记归纳的校验约定如下,全部违例均以 SESSION_QUERY_INVALID_SURFACE 失败:

约定 要求
seq 连续性 事件 seq 从零开始且连续
表面标记 表面标记符合事件类型的适用范围(仅 user/message、assistant/message、tool/result 三类可入表面)
来源引用权限 只有表面事件类型可以引用来源事件 seq
数组完整性 存在的数组必须非空且没有重复项
来源时序 每个来源必须是更早的 seq
替换完整性 每次位置替换必须指明并引用它移除的全部表面节点(替换与 sourceEventSeqs 联动校验)

测试 tracing.spec.ts#L419-L479 用一个 it.each 表格逐一覆盖了这些违例:非表面来源引用、非法来源数组、空来源、稀疏来源、重复来源、缺失更早来源、未来来源、无来源的替换、替换缺少被遮蔽来源等,全部断言抛 SESSION_QUERY_INVALID_SURFACE。还有一条回归用例(L481-L489)证明 listEvents 应用同一套表面契约——设计笔记特别指出:系统不存在只用于分类、要求更弱的表面标准,追踪与精确读取必须看到同一个模型表面。

状态分离:所有返回记录都与内部状态隔离

这是该功能可靠性的基石,设计笔记明确两条规则:

  1. 已知的实时事件追踪绝不查询持久化:只要目标 session 存在于 ctx.sessions 中,就直接快照,后端故障不会让当前内存历史变得不可读;
  2. 来自持久化数据的事件追踪保留精确读取所要求的列表/加载一致性检查——加载前列表与加载后观察之间的不可变 header 必须兼容,否则以 SESSION_QUERY_SOURCE_CONFLICT 失败。

会话谱系天然属于跨语料操作(需要在全部会话中查找父级与后代),因此保留跨语料的持久化失败语义(SESSION_QUERY_PERSISTENCE_FAILED)。

源码层面有两处直接佐证:

  • SessionCorpus.listSessions(corpus.ts#L58-L77)先列出持久化记录,再用 live 记录覆盖同一 id,并对重叠 id 断言 header 兼容,最后按确定性顺序排序;
  • traceSession 的实现正是「一次 listSessions + 一次确定性遍历」(tracing.ts#L113-L173):ancestors 用循环沿 parentSession 上行并做环检测;后代树用显式栈迭代构建(buildDescendants),而非递归,测试专门验证了 3000 层深度不爆 JavaScript 调用栈(tracing.spec.ts#L261-L280)。

所有返回的 header、事件与记录都是克隆:cloneRecord 对 header 做 structuredClone(tracing.ts#L246-L248),事件记录均为新建对象。测试验证了即使调用方修改返回结果,重复调用仍得到原始值(tracing.spec.ts#L199-L206 与 L327-L344)。

考虑过的替代方案:四个否决及其理由

设计笔记记录了四个被否决的方向,理解它们有助于把握当前 API 的边界:

替代方案 否决理由
公开独立的追踪辅助函数 源优先级与状态分离边界属于 ctx.sessionQuery;公开辅助函数会诱使调用方绕过该边界,自行拼接语料
合并替换边与来源事件引用边为一种通用边 位置替换可以遮蔽表面节点,同时引用不在表面上的构造输入;消费方必须能区分这两种含义
返回所有传递引用的来源事件 会掩盖日志中直接记录的证据、增大结果,并让一条遥远的格式错误边改变原本局部的输出
对格式错误的来源事件列表返回尽力而为的追踪结果 结构上看似合理的局部结果会显得具有权威性;当规范关系约定损坏时,精确检查应明确报错

后果与成本权衡

设计笔记最后总结了该功能的后果:

  • 消费方无需缓存,也无需引入第二份语料,即可获得确定性的关系视图;
  • 成本透明:事件追踪每次调用都会执行全日志校验与分配,谱系追踪每次调用都会列出完整的逻辑语料——这些成本让真源保持明确,并且与承载内容的全文搜索及过滤 API 相互独立(搜索走挂载的 SQLite 后端,追踪是内置具体行为);
  • 测试边界:该功能具备单元测试与服务层测试覆盖(即 tracing.spec.ts),但没有快照或端到端 fixture,因为它没有引入面向模型的消费方、transcript(文本记录)变更或跨进程协议——这与 dsh-session-query 包“无模型体验”的定位一致(见 README.zh.md 的“模型体验”一节)。

从服务层接线看(index.ts#L300-L320),traceSession 与 traceEvent 都接受可选 AbortSignal,在语料解析完成后调用 throwIfAborted() 立即终止——因此在大语料下调用方可以安全地取消慢速追踪,而不必担心返回过期数据。

实战:一个完整的追踪用例

结合测试 appendTraceEvents(tracing.spec.ts#L114-L168)构造的日志(seq 2 为用户消息、seq 3 为引用 seq 2 的用户消息、seq 4 为替换 3 并引用 [3,2] 的助手摘要、seq 8 为替换 4 并引用 [2,4] 的助手摘要),traceEvent 的语义一目了然:

目标 seq replacedBy replacementChain replacedEventSeqs sourceEventSeqs derivedEventSeqs 表面分类
2 — [] [] [] [3, 4, 8] log-only
3 4 [4, 8] [] [2] [4] shadowed
4 8 [8] [3] [3, 2] [8] shadowed
8 — [] [4] [2, 4] [] current

注意 seq 2 是 log-only:它不在当前表面上,也没有被直接替换(被遮蔽的是 seq 3),但它被 3、4、8 三个事件引用,因此 derivedEventSeqs 记录了全部三个后续反向引用;而 seq 3 被 seq 4 直接替换,replacementChain 沿替换链一路到 8。这个例子直观展示了“位置替换”与“来源引用”两条独立的关系维度。

相关文档与进一步探索

总体而言,traceSession 与 traceEvent 是对“会话历史可编程读取”的最小、克制而完备的补充:它们把分散在 header、表面操作与来源引用中的关系收敛为两个一次性的确定性视图,用整日志校验保证“坏日志绝不产生貌似权威的局部结果”,用克隆与状态隔离保证消费方永远看到一致时刻的快照。

登录后查看全文
deepseek-harness