ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话标题的持久状态:辅助请求记录、提供方输入与输出到底如何对齐与校验

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话标题session/titleSessionTitleService
标题生成一次后不再更新,或重启后标题消失,往往不是模型问题。本文讲 session/title 的持久折叠、三种来源的差别、辅助请求记录的内容,以及 rename 与 refresh 的边界。

标题只生成一次就再也不动,先别怀疑模型;先确认标题的来源是不是被钉住了。 DSH plugin 的标题不是会话对象上的一个可变字段,而是一串 session/title 事件折叠出来的持久状态。来源决定了它还会不会更新,事件决定了它重启后还在不在。 DSH插件 想自定义标题来源时,先弄清这条状态链,再谈换 provider。

标题是日志状态,不是会话字段

ctx.sessionTitle.get() 读的是日志折叠结果,最新事件覆盖旧值。(来源) session/title 是仅记录日志的事件,它的载荷包含三样东西:

  1. title — 规范化后的非空标题文本;
  2. messageSeqs — 生成该标题所用的精确人类消息 seq,显式改名时为空数组;
  3. source — 内建回退、已注册提供方,还是用户手动指定。

折叠结果比事件多两个封装事实:eventSeq 与 updatedAt,分别是最近一条 session/title 的序号与时间戳。所以要判断“标题是什么时候变的”,看 updatedAt,不要看会话的创建时间。

还有一层兼容性细节:title 投影的版本 1 状态与客户端视图都只保留标题字符串或 null。这意味着旧的持久化缓存行仍然可读,你不需要为历史会话写迁移,但也不要指望从投影里读出 source 或 messageSeqs。

为什么是“后写覆盖”而不是“首个标题固定”? 因为标题是一条修订记录,每次接纳都会追加新事件,折叠永远取最新一条。这个语义对用户改名很友好——改名不需要删旧事件,只要追加即可;对排查也友好——历史标题全在日志里,你能清楚看到它是怎么一步步变的。

需要完整来源时读 get() 的快照,需要给列表页快速出文本时读投影。两条路径拿到的信息量不同,不要用投影的 null 去断言“这个会话没有标题”,它只表示“投影版本 1 没有可显示的字符串”。

三种来源决定标题还能不能更新

标题能不能继续自动变,取决于 source.kind,而不是取决于有没有提供方。(来源)

  • fallback — 内建回退生成,没有模型参与;
  • provider — 已注册的标题提供方生成,附带 SessionTitleProviderId,如果走了模型还会带 model 的 provider 与 model;
  • user — 显式改名,会钉住标题。

user 这一类的注释写得很直白:显式用户改名会钉住标题,自动生成停止调度。这解释了两类现场:改名后标题“冻结”是预期行为;改名生成中再收到自动结果,则要检查是不是在钉住之后还有旧请求在跑。按官方描述,进行中的自动生成会被取代。

辅助请求记录为什么单独存在

它记录的是“这次标题请求到底发了什么”,而不是“标题最终是什么”。(来源)

共享执行模块会在调用模型前,记录每一项已经过验证且可分发的标题请求。这份记录的口径很硬:即使后续生成失败,载荷仍会复现模型可见的系统输入与消息输入、路由、输出上限、解析后的推理强度、提供方归属和源消息归因。

字段逐项对应:titleProvider、messageSeqs、route、system、messages、maxTokens、reasoningEffort。注意 reasoningEffort 只在记录时存在,较早的请求可以省略,所以读旧记录时不要假定它一定存在。

这份记录的价值在两个场景最明显:一是排查“标题为什么这么起”,你能看到当时模型实际读到的消息;二是审计“谁发起了这次辅助调用”,titleProvider 与 messageSeqs 都在。

提供方拿到什么、被接受什么

提供方的输出只是候选,正规化与落盘都由服务负责。(来源)

服务在每次提供方调用前,会创建一份快照:截至某一修订的合格消息、刚刚确保的回退、以及最新已接纳的标题。提供方拿到的 SessionTitleProviderRequest 包含 session、messages(每项是 seq 加拼接后的 text)、可选 route、可选 currentTitle,以及用于取代、销毁、超时组合或调用方取消的 signal。

合格消息的口径只有一条:人类文本消息。SessionTitleUserMessage 由源 user/message 的 seq 与拼接后的 text 组成,太短的会话或只有工具调用的会话拿不到可用文本,因此 get() 会一直返回 undefined,refresh() 也无从生成。这不是故障,而是没有合格输入。

提供方返回的 SessionTitleProviderResult 只有三项:title、messageSeqs、可选 model。关键约束在这里:返回的 seq 只可来自该次请求的 messages。你不能引用更早或更晚的消息,因为服务会验证顺序。

服务负责的接纳流程依次做四件事:验证顺序、规范化标题、强制执行字节上限、追加标题及其来源消息 seq 与来源类型。四步都不在提供方手里,所以提供方不该自己做截断或去重。

automatic 决定新的人类提示词何时触发自动生成,取值只有 first-prompt 与 all-prompts。一个提供方只能声明一种节奏,服务也只允许注册唯一一个可选提供方。

三个方法:get、rename、refresh

读用 get,钉住用 rename,解除钉住用 refresh,三者语义不能互换。(来源)

  • get(session) — 返回最新折叠快照,在还没有合格输入时返回 undefined。它不触发任何生成。
  • rename(session, title) — 追加一条 source: user 的 session/title,钉住标题、取代进行中的自动生成,之后的用户消息不再安排生成。标题规范化后为空会抛 SessionTitleInvalidError;会话不活跃或服务已销毁则抛普通 Error。
  • refresh(session, signal?) — 显式重试已注册提供方,或在没有提供方时物化内建回退。它是唯一的“故意解除钉住”入口,没有合格文本时返回 undefined。

三者的返回都是 SessionTitleSnapshot 或 undefined,没有“半成功”。如果你的插件需要“改名后立刻重新生成”,正确写法是先 rename 再 refresh,而不是改名后等自动生成——按语义它不会再来。

注册与失效:迟到的结果不会落盘

标题提供方是单例资源,卸载时的清理语义决定了会不会写出过期标题。(来源)

register(provider) 注册唯一的可选标题提供方,返回 Cordis 的 effect disposer。销毁会中止该提供方所有待处理与活跃的工作;替换方可以在销毁已开始后注册;而关闭中的提供方,其迟到结果永不提交。

最后一句是设计约束,不是实现巧合。如果你在插件热替换时看到“旧标题又冒出来了”,先检查旧提供方的 generate 是否在 signal 中止后仍然返回结果并试图提交。正确做法是尊重 signal,让服务完成它的接纳判定。

register 返回的 disposer 会等活跃调用停稳才 settle。这个细节影响卸载顺序:先把标题提供方的 disposer 等完,再拆掉它依赖的下游服务,才能避免迟到回调打到已销毁的上下文。

验证:改名、重启、再读取

标题问题必须分三步验证:状态、时序、来源,一次一起看。(来源) 六步:

  1. 新会话调 get(),断言返回 undefined,且没有 session/title 事件。
  2. 触发首次生成,断言快照的 source.kind 是 provider 或 fallback,messageSeqs 非空。
  3. 调 rename(session, " "),断言抛出 SessionTitleInvalidError,且日志没有新增事件。
  4. 调 rename(session, "发布前检查"),断言 source.kind 是 user、messageSeqs 为空、updatedAt 更新。
  5. 重启进程后重新 get(),断言标题与 eventSeq 与重启前一致。
  6. 调 refresh(),断言能重新生成,且新快照的来源不再是 user。

如果第 6 步没有变化,通常是没注册提供方,此时 refresh 走的是内建回退,标题可能恰好与旧文本相同。先看 source,再看字符串。

想理解标题提供方怎么接进模型路由,可以对照标题提供方;想确认标题在引用与展示层的表现,看会话引用标签。

一句话收束: 标题是日志折叠出来的状态,user 来源会钉住它,辅助请求记录保留的是输入而不是结果,替换提供方时迟到结果一律不提交。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的标题存在会话对象的字段里,还是写进日志事件?

不是,DSH plugin 把标题存成日志事件再折叠出来。DSH plugin 的 session/title 是仅记录日志的事件,ctx.sessionTitle.get() 返回的是最新折叠结果,重启后读的仍是同一条日志。

DSH plugin 里用户手动改名之后,还会不会再自动生成标题?

不会,DSH plugin 的 rename 会把来源标成 user,从而钉住标题。DSH plugin 在钉住后会中止进行中的自动生成,后续用户消息也不再安排生成,只有显式调用 refresh 才会解除。

DSH plugin 标题生成失败的时候,辅助请求记录还会留下吗?

在,DSH plugin 在调用模型前就记录已验证且可分发的请求。DSH plugin 的载荷会复现模型可见的系统输入与消息输入、路由、输出上限、推理强度与来源归因,即使后续生成失败也不影响这条记录。

DSH plugin 换标题提供方时旧提供方的结果会写进去吗?

不会,DSH plugin 在卸载开始后旧提供方的迟到结果永不提交。DSH plugin 的 disposer 会等活跃调用停稳,替换方可以在卸载已开始后注册。

相关术语

SessionTitleSource
SessionTitleSource 记录标题的来源类型,分为 fallback、带提供方标识的 provider,以及钉住标题的 user 三种。— packages/session/session-title/src/index.ts
SessionTitleSnapshot
SessionTitleSnapshot 是最新折叠标题加上事件封装事实,包含 title、messageSeqs、source、eventSeq 与 updatedAt。— packages/session/session-title/src/index.ts
SessionTitleAutomaticMode
SessionTitleAutomaticMode 是提供方拥有的自动生成节奏,只有 first-prompt 与 all-prompts 两种。— packages/session/session-title/src/index.ts
辅助请求记录
辅助请求记录是调用模型前写入的可分发标题请求事件,复现系统输入、消息输入、路由、输出上限与来源归因。— DeepSeek Harness 官方参考 - 会话标题

来源