DSH plugin 会话候选名:label、displayTitle 与 subagent 标签怎么选
在 DSH plugin(DSH插件) 里,会话候选里的名字不是随便取的:label 走「标题 → id」的回退链,displayTitle 在 subagent 场景优先用持久创建标签,规范 mention 又优先用 displayTitle。 搞清这三条来源,才不会把「显示 id」当成故障。
DSH plugin 里同一会话为什么会有三个名字
三个名字对应三种来源,不是三份数据。(来源) 拆开看:
sessionId 不透明身份,永远存在
label 最新标题,缺失时等于 sessionId
displayTitle subagent 持久创建 label,可选
用户看到的可能是其中任意一个,取决于会话有没有标题、是不是 subagent、你的宿主选择了哪个字段。
三个名字的优先级不是随意的:身份永远用 id,展示尽量用可读文本,mention 则选最稳定的可读文本。
DSH plugin 的 label 从哪来
先找最新 log-backed 标题,找不到就用 id。(来源) 这条回退链只有两级:
- 会话有标题 —
label等于标题; - 会话无标题 —
label等于不透明 session id。
官方注释把第二级写得很明确:回退到 opaque session id。这意味着「看到一串 id」是设计内的兜底,不是投影坏了。
回退链的好处是候选永远有可显示文本,宿主不需要处理「名字为空」的分支。
DSH plugin 的 displayTitle 优先给谁
优先给 subagent,因为它的创建标签比会话标题更能说明角色。(来源) 规则是:存在 subagent 持久创建 label 时,displayTitle 用它,否则缺省。
举个对比例子:
| 会话 | label | displayTitle |
|---|---|---|
| 普通会话有标题 | 修复登录超时 | 无 |
| subagent 有创建标签 | 修复登录超时 | reviewer |
| 无标题普通会话 | 8f3c…(id) | 无 |
第二行说明为什么需要两个字段:标题描述「在做什么」,创建标签描述「以什么角色做」。候选列表里后者往往更好认。
DSH plugin 显示名与 mention 分别用哪个
列表展示可以自由选,mention 按服务返回的来。(来源) 分工:
- 列表主标题:优先
displayTitle,没有则label; - 副标题或来源说明:可以用
label或 cwd; - mention:直接用候选自带的规范文本,不要自己拼。
官方说明 Remote 候选在 displayTitle 存在时用它标记规范 mention。也就是说,用户插入草稿的那段文本,可能和列表里显示的 label 不同。
这不算不一致:mention 需要的是稳定、可读、可解析的文本,而列表可以按 UI 需要组合字段。
DSH plugin 为什么名称都来自投影读取
因为发现运行在按键频率上,不能每次都扫日志。(来源) 官方注释写明:标题与 subagent label 只来自投影读取,两者都没有时回退 id。
投影读取带来两个可观察后果:
- 标题刚改完,候选里可能还是旧名字;
- 投影尚未生成的会话,直接显示 id。
这两个都是预期行为。判断是否异常的方法不是看名字新旧,而是看「等投影刷新后是否更新」。
如果长时间不更新,才需要查投影本身,而不是查候选接口。
DSH plugin 名称字段的验证矩阵
三种会话,三种预期,一次跑完。 矩阵:
| 会话类型 | label 预期 | displayTitle 预期 |
|---|---|---|
| 有标题普通会话 | 标题 | 无 |
| 有创建标签的 subagent | 标题或 id | 创建标签 |
| 无标题普通会话 | id | 无 |
再补一条动态验证:改标题后等待投影刷新,确认 label 更新而 displayTitle 不变。
三条静态加一条动态,就能确认自己没有把字段用反。
选择顺序要写成固定分支:有 displayTitle 就用它,否则用 label,而 label 本身已经回退到 id。不要在 UI 里按「哪个非空用哪个」临时决定,否则同一个会话在列表和引用卡片上会出现两个名字。
如果投影长时间不刷新,先查投影生成任务,而不是改候选接口的回退逻辑;把回退改成扫日志,会引入新的性能问题。
名称解决的是「看得懂」,下一步是「找得到」。读 DSH plugin 会话候选为什么只搜元数据;想看排序规则,读 DSH plugin 会话候选的排序与 self 排除;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/types.ts
常见问题
因为该会话在 DSH plugin 里还没有可用的标题。DSH plugin 的 label 优先取最新 log-backed 标题,没有标题时才回退到 session id;显示 id 说明回退生效,不是数据损坏。
两者的来源不同,这是 DSH plugin 两个字段的设计分工。DSH plugin 的 label 取会话标题,displayTitle 在存在 subagent 持久创建 label 时优先用它;一个描述会话内容,一个描述创建时的角色。
DSH plugin 在有 displayTitle 时用它标记规范 mention。DSH plugin 的 Remote 候选会以 displayTitle 作为规范提及文本,label 仍保留在候选里供其他展示使用。
因为 DSH plugin 的名称来自投影读取,不是每次都扫日志。DSH plugin 在按键频率下只读投影,标题更新需要等投影刷新后才会反映到候选里。
相关术语
- label
- label 是会话候选的显示名,优先取最新 log-backed 标题,缺失时回退到不透明的 session id。— DeepSeek Harness 官方参考 - 会话引用
- displayTitle
- displayTitle 是优先使用 subagent 持久创建 label 的显示文本,存在时也用于标记规范 mention。— DeepSeek Harness 官方参考 - 会话引用
- 投影读取(projection read)
- 投影读取是从会话投影中获取标题与标签的方式,不扫描完整日志,适合按键频率下的发现。— DeepSeek Harness 官方参考 - 会话引用
- subagent 创建 label
- subagent 创建 label 是子智能体创建时写入并持久保存的角色标签,用于在候选中区分同类子会话。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/types.ts· deepseek-ai