「新建了会话,列表里的标题一直是空的。」「我明明手动改过名字,怎么又变回去了?」这两个问题对应的是两条不同路径;它们的共同误区是:把「标题存在」和「某个模块成功运行」当成一回事。
实际排查中最常见的六类误判是:
- 把会话已有活动当成已经有符合条件的标题输入;
- 刚建会话看到列表里没标题,就断定生成失败;
- 看到备用标题出现了,就以为提供方已经运行过;
- 把「没有自动更新」和「刷新已成功」混为一谈;
- 以为手动改名之后,后续消息还可能自动覆盖;
- 以为标题进了列表就等于进了主模型会话。
要理清这些问题,先记住一点:标题是一组仅写日志的修订,最新修订会折叠为当前标题;后续是否覆盖,则取决于「谁写入了这条修订」。 站内基础版可参考会话标题是怎么生成的。
一、第一个标题从哪来
会话标题参考定义的是可持久化的标题修订;服务说明解释生成时机。前提是部署挂载了标题服务。
服务会从第一条符合条件的人类消息中截取开头的词语,并根据配置的词数和 UTF-8 字节上限生成备用标题。
这里有个关键限定:只有人类 user/message 事件中的文本块符合条件。如果消息为空,或只包含非文本内容,服务会等到后续出现有效输入。
由此可以推出一条很容易被忽略的结论:会话中已有活动,不等于已经有符合条件的标题输入。 注入消息、工具结果、只有图片的提示,都不能直接证明备用标题应该出现。
备用标题的三个性质
- 不依赖模型:没有模型调用,也就没有可等的模型返回;
- 无需注册可选提供方:它是服务自身的行为;
- 可能异步出现:所以刚创建会话时列表里暂时没有标题,不一定说明生成失败。
这三条也解释了开头的问题:会话刚创建时,备用标题可能还未出现,因此空标题不一定表示生成失败。
二、标题什么时候会变
部署最多注册一个标题提供方,其 automatic 模式为 first-prompt 或 all-prompts。
所以,标题会不会随新消息更新,取决于部署选择了哪个提供方;不能把一种安装的行为推广到其他安装。
提供方拿到的输入是什么
服务会截取当前修订之前符合条件的人类消息,并在调用时提供最新接受的 currentTitle;提供方自己决定是否使用这个标题。
返回结果要指明使用了哪些消息序号,服务随后会检查序号、规范化文本,并判断是否接受。
这条链路很重要:提供方的输出不是直接生效的,它要过服务的检查。
自动生成何时才真正启动
服务说明还给出了一个明确前提:带标记的循环请求必须与日志中的 request/header 路由匹配,自动提供方才会启动。
排查时可以据此确认:如果没有匹配的路由记录,就不应期待自动修订。
新旧修订的竞争关系
- 较新的修订会取代并中止旧工作;
- 过时结果不能追加。
还有一个时序细节:自动生成不会延迟主 Agent 的回复,因此备用标题和提供方标题可能先后出现。先后看到两个标题,并不表示发生了重复写入。
至于失败:自动生成失败会产生警告,并保留最近一次已接受的标题。 也就是说,一次失败不会把标题清空。
first-prompt 模式的额外边界
首次提示提供方的排除项值得单独记住:
- 种子会话被排除;
- 子智能体来源的会话被排除;
- 独立 fork 也不会仅因为缺少来源关系而变得符合条件。
而 fork 会在种子中继承已有标题事件。所以「这是一个 fork,它应该自然获得标题」这个想法,只在继承这条路上成立,不能推广成「fork 都能自动生成」。
不要把一个提供方的调度规则推广给所有实现。
三、重命名和刷新各做什么
这两个操作经常被当成同一件事,其实方向相反。
rename(session, title):主动固定
显式 rename(session, title) 会:
- 记录用户来源的标题;
- 使正在执行的自动生成失效;
- 停止为后续人类消息调度自动修订。
它保护的是用户自己选定的名称。所以你手动命名之后,再发多少条消息都不会让自动修订回来。
refresh(session):有意解除固定
文档中的 refresh(session) 才是主动解除固定并重新生成的路径:必要时先确保已有备用标题,再针对当前符合条件的消息显式调用已注册的提供方。
这里有一条必须讲清的边界:描述的是服务 API,引用资料没有保证每个客户端都提供刷新按钮。 所以在界面上找不到「刷新标题」,不代表服务层没有这个能力;反过来,也不要把文档里的能力当成界面里必然存在的按钮。
两种失败的后果不一样
- 自动失败:保留最近标题并警告;
- 显式刷新遇到提供方错误或调用者取消:会拒绝。
还有一条容易被误解的:取消不会撤销此前已经接受的备用标题。 也就是说,刷新被取消 ≠ 标题没了。
一个容易被忽略的前置条件
模型执行模块说明:在尚无已记录路由时显式刷新,需要同时提供 provider 与 model 覆盖。
所以刷新失败时,先看是不是路由还没建立——这跟提供方本身报错是两回事。
排查时应区分「没有自动更新」和「刷新已成功」,不要只凭列表文字推断调用结果。
四、标题不对时怎么查
1. 五步排查顺序
- 确认部署挂载了标题服务,并检查会话是否已有符合条件的人类文本。空消息或非文本输入,需要等待有效文本才具备输入。
- 确定最新标题来自哪一层:备用逻辑、提供方,还是用户。集成方可以用
ctx.sessionTitle.get()查看折叠后的快照;客户端标题投影本身只提供字符串或null——也就是说,光看列表拿不到来源信息。 - 期望自动生成时,逐项检查:提供方是否注册、采用哪种自动模式、会话是否符合条件、带标记的请求是否已有匹配的日志路由。
- 如果最新来源是用户重命名,后续消息不会自动覆盖;只有确实希望重新生成,且集成确实提供该操作时,才用显式刷新。
- 失败时对照警告与日志:已接受的
session/title修订和已派发的session/title-llm-request是不同的记录。分享前移除不必要的消息内容与路由信息。
2. 一个典型时序
用户先提交一个文本问题,备用标题出现后立刻手动命名。
即便之前那次异步生成稍后返回,用户标题也不应被这次过时结果覆盖。再发一条消息,也不会恢复自动调度——因为重命名已经停掉了后续调度。
反过来:如果部署使用 all-prompts 模式、且没有用户固定标题,新的人类文本可能触发新修订;具体是否接受仍取决于提供方结果与服务的检查。
3. 怎么区分「已接受的修订」和「一次没成功的尝试」
标题事件包含规范化文本、source 和 messageSeqs:
- 用户重命名的序号列表为空;
- 提供方来源还可能包含提供方和模型身份。
而快照附带事件序号及更新时间。这两样合起来,才能把此前已接受的修订和一次没有成功的新尝试分开。
五、标题存在哪里
每个被接受的修订,是一条仅写日志的 session/title 事件,折叠时最新事件生效;客户端看到的 title 投影只有字符串或 null。
会话参考提供了更广的会话事件上下文,事件类型的完整清单见会话事件类型目录。
标题会跟着重放走,但不进主请求
服务说明指出:标题会通过重放、恢复和分页保留,但不会进入主模型会话、系统提示或工具 schema。
这句话的两层意思都要看到:标题会被保留,但不会进入主上下文。前者说明重连时不会丢失标题;后者说明模型本身看不到标题。
辅助调用是单独计费的
模型提供方使用的是单独的辅助请求。派发前会把其输入和准确路由记录到 session/title-llm-request,即便后续生成失败,记录仍可能存在。
两条推论:
- 这条记录可能包含人类消息,应像其他会话数据一样管理;
- 辅助调用单独消耗模型 token——标题未进入主请求,不表示辅助生成没有成本。
会话成本的整体口径可参考会话 token 用量怎么看。
六、限制与安全边界
- 标题是简短标签,不是完整摘要,不能代替对会话内容本身的判断。
- 不保证不包含敏感词:向他人展示会话列表前,应检查实际标题。
- 服务不提供标题的删除、搜索或列表索引——不要指望靠标题去找回会话。
fallbackMaxWords、fallbackMaxBytes、maxTitleBytes是部署必须设置的限制,不能当成所有安装都相同的默认值。- 截断发生在 UTF-8 字符边界,且服务会清理控制字符、规范化空白;所以看到的标题与原始文本不会逐字相同。
session/title-llm-request可能保留人类消息内容:分享日志前必须脱敏。- 辅助标题生成消耗 token:它与主请求是两笔账。
- 客户端投影只提供字符串或
null:标题存在并不能说明它来自哪里;要确认来源,需要查看事件。 - 不要把一个提供方的调度规则推广给所有实现:模式、资格与排除项都随部署而变。
七、术语速查
- 备用标题:从第一条有效人类文本中确定性截取的开头词语。
- 提供方:提出异步标题修订的可选实现。
- 固定:最新标题来自用户重命名后,对自动调度产生的限制。
- 投影:客户端读取的折叠视图,标题部分是字符串或
null。 - 刷新:可解除固定并重新生成标题的显式服务操作。
相关阅读
本文依据 DeepSeek Harness 官方会话标题参考、标题服务说明与模型执行模块说明整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/session-title-generation
插件与文档收录于:https://dsh-plugin.com/zh/blog