DeepSeek Harness 会话标题子系统设计解析

给一段 AI 会话自动起名字，听起来是件小事，真要做对却不容易：标题要能随对话演进而更新，要能说清每一次修订来自谁，要让用户的命名拥有最高优先级，还要在模型调用失败时依然有像样的兜底。开源智能体框架 DeepSeek Harness（GitHub 仓库 deepseek-ai/deepseek-harness，MIT 协议）把这件事做成了独立子系统，对应 npm 包 @deepseek-ai/dsh-session-title：一个持久、后写覆盖的标题状态，加上可选的异步标题提供方。本文基于该项目的中文文档，梳理这个子系统的设计思路。

标题是折叠出来的，不是存出来的

子系统不维护一个可变的「当前标题」字段，而是把每次标题修订作为 session/title 事件追加进会话日志，再用 foldSessionTitle() 从事件流折叠出最新快照。这种做法和整个框架的日志优先哲学一脉相承：标题只是日志重放的一个视图，任何时刻都能从事件序列确定性地推导出来。

快照类型 SessionTitleSnapshot 在标题数据之外，还附带 eventSeq 与 updatedAt，能回答「这个标题来自哪条日志事件、什么时候写入」。每条标题事件的载荷 SessionTitleEventData 则包含三样东西：规范化后的非空标题文本；messageSeqs，即本次标题所依据的精确人类消息序号列表；以及 source，标明标题来自内置回退、注册提供方还是用户显式命名。生成修订时还会记录 SessionTitleProviderId，标识是哪一个提供方注册项产出了这条标题。

三种来源里，用户显式改名的语义最特殊：一旦 rename() 写入 user 来源的标题事件，标题即被固定，进行中的自动生成会被作废，后续用户消息也不再调度新的生成。唯一的解锁方式是显式调用 refresh()，文档称之为刻意的解除固定。

可插拔的生成策略

自动生成由注册的标题提供方承担。每个提供方声明一个稳定 id 和一个生成节奏 automatic，取值为 first-prompt（只在第一条人类提示后生成一次）或 all-prompts（每条人类提示后都可能修订）。提供方接口 generate(request) 收到的是不可变输入：活动会话对象、截至本次修订的全部合格人类消息快照（每条带事件序号与拼接后的文本）、当前已记录的主请求模型路由，以及用于取消的 AbortSignal。返回值是提议的标题、所用消息序号，以及可选的模型路由。

没有注册提供方时，框架内置的回退逻辑负责给出标题，保证开箱即用也有像样的名字。

每次模型调用都先留痕

这个子系统对可审计性的执着体现在辅助请求记录上：共享的 LLM 辅助组件在真正调用模型之前，先把每一项已通过验证、可分发的标题请求写进日志。载荷 SessionTitleLlmRequestEventData 复现了模型能看到的一切：负责本次请求的提供方身份、消息序号列表、精确的模型路由（provider 加 model）、系统提示词、完整消息列表和输出 token 上限。即使随后的生成失败，这条日志也已经落盘，事后可以完整重现模型当时的可见输入。

接纳流程守住最后一道关

提供方返回的结果并不会直接生效。服务会对截至某一修订的合格消息创建快照，提供方返回的消息序号只允许来自这份快照；随后由服务负责的接纳流程依次校验序号顺序、规范化标题文本、强制执行字节上限，全部通过后才把标题连同来源消息序号和来源类型追加为日志事件。任何一步不合格，这条修订就不会污染标题状态。

四个方法组成完整表面

子系统以 Cordis 插件形式挂载，通过 ctx.sessionTitle 暴露四个方法：get(session) 读取最新折叠快照，合格输入出现之前返回 undefined；rename(session, title) 接受用户显式命名，规范化后为空会抛出 SessionTitleInvalidError；refresh(session, signal) 显式重试已注册的提供方，没有提供方时物化内置回退；register(provider) 注册唯一的标题提供方，返回的清理函数会等活跃调用平息后才完成，期间再注册新的提供方会被拒绝。

为什么值得借鉴

会话标题是许多 AI 产品的标配，但多数实现是一个可变字段加一次模型调用，既说不清标题从哪来，也无法在换模型、重放会话时保持一致。DeepSeek Harness 的做法把三个工程问题一次解决：事件溯源让标题可回放；来源与消息序号的完整记录让每次修订可归因；先落日志再调模型让失败调用同样可审计。给会话起名这件小事，在这里被做成了一堂状态设计课。