ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话候选筛选:只搜 label、displayTitle、id 与 cwd 四个字段

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用候选筛选搜索
会话候选的筛选只覆盖 label、displayTitle、session id 与 cwd,绝不搜索 transcript。本文解释这条约束的原因、四个字段的匹配方式,以及想按聊天内容找会话时该走哪条路。

在会话引用里搜聊天原话搜不到,不是缺陷:DSH plugin(DSH插件) 的候选筛选只在 label、displayTitle、session id 与 cwd 四个字段上做子串匹配,transcript 被明确排除在外。 想按内容找会话,得换一条链路。

DSH plugin 里为什么搜聊天原话搜不到

因为候选筛选的输入不是消息内容。(来源) 一个常见现场:

text
用户记得某次会话里说过「支付回调超时」
在引用候选里搜「支付回调」
结果:空

用户以为「聊过就应该能搜到」,但引用候选回答的不是「哪次聊过这个」,而是「哪个会话的名字、id 或目录像这个」。

这两个问题的成本差一个数量级:前者要读消息,后者只读元数据。

DSH plugin 候选筛选的四个字段

四个字段,全部来自会话元数据或投影。(来源) 对照:

字段来源说明
label最新标题,缺失回退 id最主要的可读匹配项
displayTitlesubagent 持久创建标签优先用于展示的文本
session id不透明身份知道 id 时可直接搜
cwd会话记录的工作目录按项目路径缩小范围

匹配方式是大小写不敏感的子串匹配,query 可以省略。省略时返回什么由候选上限与排序决定,而不是「返回全部」。

四个字段的共同点是:都能从元数据或投影里直接拿到,不需要打开会话。

DSH plugin 为什么不搜 transcript

三条理由,任何一条都足以否决。(来源) 拆开看:

  1. 成本 — 候选按按键频率触发,扫 transcript 等于每次输入做一次全文检索;
  2. 隐私 — 候选层只需要「选哪个会话」,把消息内容带进来扩大了可见面;
  3. 确定性 — 消息会持续增长,同一 query 的结果会随时间变化,列表不稳定。

第三条常被忽略:即使性能可以接受,候选结果也会因为会话继续对话而变化,用户体验反而更差。

所以「不搜 transcript」不是偷懒,而是把候选限定在稳定、轻量的元数据上。

DSH plugin 想按内容找会话该走哪条路

走会话查询或检索,不要改候选。(来源) 分工:

目标能力结果
选一个会话来引用引用候选元数据匹配的候选列表
找聊过某个话题的会话会话查询/检索命中的消息或会话
看某会话的历史会话历史消息记录

先确定你要的是「引用」还是「查找」。如果是后者,即使用候选接口凑出了结果,也拿不到消息级定位。

这条分工也影响 UI:引用候选的搜索框不应该承诺「搜内容」,否则用户会持续遇到「明明聊过却搜不到」。

DSH plugin 子串匹配的三个细节

大小写、空白、空 query,各有各的行为。(来源) 细节:

  • 大小写 — 不敏感,Review 与 review 等价;
  • 空白 — 不做 trim 之外的归一,query 里的空格属于子串的一部分;
  • 空 query — 合法输入,但返回集合由候选上限与排序决定,不应假设为全量。

第三个细节决定了一个实现选择:不要在空 query 时跳过请求直接渲染本地缓存,否则会和真实候选不一致。

如果产品需要「最近会话」列表,应该用固定排序 + 空 query 的组合,而不是另造一套本地数据。

DSH plugin 筛选行为的验证

四个用例,分别验证命中、不命中、大小写与空值。 步骤:

  1. 用标题片段搜,确认命中;
  2. 用聊天里出现过、但标题里没有的词搜,确认不命中;
  3. 用不同大小写搜同一标题,确认结果一致;
  4. 传空 query,记录返回数量与顺序,确认与下一次调用一致。

第 2 个用例是「预期不命中」,用来确认 transcript 确实没有参与匹配;如果命中了,说明实现越界了。

第 4 个用例验证空 query 的稳定性,避免列表在打开面板时抖动。

还有一点:筛选只影响候选列表,不影响已经选中的引用;清空搜索框不应该顺手清掉 references。

筛选解决「找得到」,下一步是「排得对」。读 DSH plugin 会话候选的排序与 self 排除;想看显示名怎么选,读 DSH plugin 会话候选名怎么选;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/index.ts

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 会话引用里搜聊天原话搜不到,是索引没建好吗?

不是索引问题,而是 DSH plugin 的候选筛选只匹配元数据。DSH plugin 的候选筛选只搜 label、displayTitle、session id 与 cwd,明确不搜 transcript,所以聊天原话本来就不在匹配范围内。

DSH plugin 的候选筛选能搜中文标题吗,大小写和空格有影响吗?

可以搜中文标题,DSH plugin 的匹配不区分大小写。DSH plugin 的匹配是对四个字段做大小写不敏感的子串匹配,中文按原样参与匹配;空格属于子串的一部分,不会自动忽略。

为什么 DSH plugin 不把聊天内容也加进候选筛选,技术上不是做得到吗?

技术上做得到,但 DSH plugin 不采用,因为代价不合适。DSH plugin 的发现按按键频率运行,扫 transcript 会让每次输入都变成全文检索,还会把聊天内容暴露到候选层,收益远小于成本。

DSH plugin 里想按聊天内容找会话,应该用哪个能力?

应该用会话查询或检索能力,而不是 DSH plugin 的引用候选。DSH plugin 的候选只负责「选一个会话来引用」,按内容定位属于另一条链路。

相关术语

候选筛选(candidate filtering)
候选筛选是会话引用发现在用户输入 query 时匹配并排序会话的过程,只覆盖元数据字段。— DeepSeek Harness 官方参考 - 会话引用
transcript
transcript 是会话的完整消息记录,包含用户输入与模型输出,不属于候选筛选的匹配范围。— DeepSeek Harness 官方参考 - 会话引用
子串匹配(substring match)
子串匹配是判断目标字段是否包含 query 文本的匹配方式,DSH plugin 对四个字段做大小写不敏感的子串匹配。— session-reference/src/index.ts
会话检索(session search)
会话检索是按消息内容定位会话的能力,与引用候选的元数据筛选是两条独立链路。— DeepSeek Harness 官方参考 - 会话引用

来源