9.5 KiB
Agent Note: 基于日志的会话标题
Status: implemented
English | 中文
问题
会话需要一个面向用户的简短标题，编辑器、终端或查询消费方才能有效呈现它。成本最低的实现可以从第一条提示词派生标题，质量更高的实现则可以让模型处理第一条提示词或整个对话。这些策略在延迟、成本、路由和重试行为上各有不同，但所有消费方都需要一个持久的真源。
会话身份元数据不可变，事件日志是回放和 fork 的边界，而且每个事件都必须包围在轮次内。模型生成的标题往往在主轮次结束后才完成，因此同步写入会延迟 agent（智能体）响应，而作为可变元数据写入则会绕过常规的持久化、回放和沿袭语义。并发提示词、提供方 HMR（热模块替换）、取消以及被忽略的中止信号，还可能让未受版本校验约束的后台结果覆盖更新的标题。
决策
session-title 功能包族负责标题状态和生成策略。@deepseek-ai/dsh-session-title 提供 ctx.sessionTitle、确定性的首消息回退方案，以及一个至多接受单个可选异步提供方的注册表。@deepseek-ai/dsh-session-title-llm 负责通用的辅助模型请求策略；首消息插件和全部用户消息插件分别选择输入调度方式。共享 agent 主干只挂载带显式示例限制的回退服务，两种模型提供方均需按需启用。
事件归属与折叠
每个已接受的修订都是纯日志 session/title 事件。其载荷包含规范化后的非空文本、用于派生标题的所有合格且来源为人类的 user/message 的准确 seq，以及回退来源信息，或已注册的提供方 id 加可选的提供方和模型路由。辅助标题模型发起调用前，共享辅助组件会追加一个纯日志 session/title-llm-request 事件，其载荷包含标题提供方 id、准确的源 seq、路由、系统提示词、消息和输出 token 上限；即使后续生成失败，这次请求仍可审计。未进入调用阶段的验证失败不会创建请求事件。foldSessionTitle() 选择最新的标题事件，并将该事件的 seq 和时间戳加入 SessionTitleSnapshot。这两类事件都不会进入 session.surface 或 deriveMessages()。
核心会话包通过 ctx.sessions.appendOutOfBand() 暴露这一接口，但只允许所属插件同时通过声明合并向 OutOfBandSessionEventMap 添加标记的插件事件类型使用。开放轮次会直接接收纯日志事件，并负责其常规检查点。已关闭的日志会在该插件的触发器下接收 turn/start → event → turn/end，随后等待刷写完成。合成轮次一旦开启，即使目标追加失败，系统仍会尝试将其关闭并刷写；整个序列完成前会延迟 detach。会话标题提供 session-title 零步骤触发器，并让这两类标题事件都使用这一服务边界。
输入与异步时序
只有人类来源的 user/message 事件中的文本块才符合条件。空提示词、仅含控制字符的提示词和非文本提示词会等待下一条合格消息。服务从提示词路径调度首个回退标题而不等待其完成，随后规范化空白和控制序列，应用已配置的单词数和 UTF-8 字节限制且不拆分代码点，并记录第一条消息的 seq。
仅当主循环存在已记录在日志中的当前提供方/模型路由时，自动提供方工作才会启动。request/header 新追加到日志时，会直接启动待执行工作；如果请求头没有变化，则由循环构建且已冻结的 llm/stream 请求会先与折叠所得的路由匹配，再启动该工作。随后，生成工作独立于 agent 响应运行；完成结果在被接受时加入当时开放的轮次，否则使用零步骤追加路径。显式调用 refresh(session, signal?) 会生成尚缺的回退标题并等待已注册的提供方；没有提供方时则返回回退标题。调用方在回退标题刷写期间取消调用不会回滚这次持久化追加，但 refresh() 会重新检查取消信号，并让调用以拒绝结束，而非返回成功。并发刷新会在等待回退标题持久化完成前预留会话本地修订号，因此在任何调用有机会造成提供方完成顺序倒置之前，较新的调用就会取代较早的调用。
首消息提供方仅在新会话首次创建回退标题时调度一次。自动执行失败后，后续提示词不会重新调度；refresh() 是重试路径。全部消息提供方会在每条合格且由人类发出的提示词后调度，并传入截至该修订的所有合格消息，包括预置历史记录。较新的修订会中止并取代更早的待执行或活跃工作。
注册、路由与失败策略
register(provider) 会验证一个带品牌类型的稳定 id、执行时机和生成函数，然后返回一个可等待完成的 effect 资源释放函数。第二个活跃注册会立即抛出错误。提供方执行资源释放时，会将注册标记为正在关闭，中止其待执行和活跃工作，并等待所有调用结束后才移除注册，因此替代提供方不会与忽略取消的旧提供方重叠运行。会话资源释放会中止其活跃工作。服务卸载时，会阻止排队中的回退和提供方微任务启动，中止活跃工作，并且卸载完成前会等待所有已跟踪的 promise 结算。每项会话本地生成都有单调递增的修订号和对应的注册身份；接受结果时会重新检查修订号、注册、会话活跃状态、服务活跃状态和取消状态，因此陈旧输出无法提交。
模型提供方必须显式配置单词数、CJK 字符数、输入字节数、输出 token 数和超时限制。可选的 provider 和 model 覆盖项必须成对提供；两者均未提供时，辅助组件会使用主请求已记录请求头中的准确路由。系统在一条固定且能区分语言的指令下，将选中的消息封装为 JSON。过大输入会被拒绝而不是截断，因为截断会让记录的源消息 seq 错误地表示这些消息已被完整使用。
自动提供方故障只会发出非致命警告，并保留最新标题。显式刷新失败则会向调用方返回拒绝。输出必须是非空文本，并包含来自固定请求、唯一且有序的 seq；服务会在持久接受前对其进行规范化并施加字节限制。
Fork 与消费方
与源日志的其他部分相同，fork 会原样继承作为种子的标题事件。首消息提供方不会自动为 fork 重新生成标题。全部消息提供方可以在子会话出现后续提示词后追加一项归子会话所有的修订，并使用继承的合格消息和新增的合格消息。
ctx.sessionQuery.readTitle() 会折叠一份实时优先或已持久化的日志，而不会在 listSessions() 期间加载标题。ACP（Agent Client Protocol）会在实时流式输出和加载回放期间把该事件映射到 session_info_update，并使用事件时间戳作为 updatedAt。TUI 使用最新标题作为其标题栏副标题，并在完成终端安全渲染后，将终端窗口标题设置为 <session title> — <configured product title>。
考虑过的替代方案
- 可变
SessionHeader或独立元数据：不予采纳，因为这会创建第二套持久化变更协议，削弱不可变身份元数据，让崩溃原子性因后端而异，并使 fork 的复制或引用行为产生歧义。仅追加日志已经负责可回放的后写覆盖状态。 - 返回 agent 响应前等待标题生成：不予采纳，因为辅助提供方的延迟和故障会进入主交互的关键路径。确定性回退方案可以立即提供可用状态，质量更高的标题则可稍后到达。
- 将标题放入派生历史记录或请求前缀：不予采纳，因为 UI 元数据会消耗 token、改变缓存标识，并让主模型观察到自己的标签。纯日志事件既保持可重建，又不会变得对模型可见。
- 允许注册多个提供方，并在完成后解析优先级：不予采纳，因为完成顺序并不等于产品优先级，而且会让重试、HMR 和来源信息变得不确定。需要组合策略的部署可以注册一个自行负责该策略的提供方。
- 静默截断过大的辅助输入：不予采纳，因为提供方结果会声明准确的源消息来源信息，实际却只接收了部分文本。保留原有标题并发出警告，可以保持归因真实。
- 立即在
listSessions()中索引标题：不予采纳，因为现有的轻量元数据列表将需要逐后端同步派生索引。精确的readTitle()建立了读取契约，而没有提前锁定搜索或索引策略。
后果
- 标题可以在 JSONL 和 SQLite 持久化中存续，通过 ACP 回放，并遵循 fork 继承语义，而无需单独的可变记录。
- 回退标题无需辅助调用即可出现；部署方可以自行决定更优标题是否值得模型成本，以及后续提示词是否需要重新生成会话标题。
- 辅助请求记录和延迟接受的标题会占用事件 seq，并可能创建平衡的零步骤轮次，因此持久化会同时呈现尝试发起的调用与已接受的更新，尽管模型历史和 KV 缓存标识保持不变。
- 单个提供方和每会话单调递增的修订号让释放、取代和陈旧结果拒绝行为明确可见，但多策略优先级必须由复合提供方负责。
- 手动重命名、删除、生成标题与用户标题的优先级、搜索和列表索引不在此功能范围内。