ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话候选排序规则:cwd 亲和度、排除自身与 limit 上限到底怎么定

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用排序candidateLimit
候选列表把当前会话自己也列出来、顺序每次不同、limit 传了没生效,都是排序契约没对齐。本文讲 self 排除、cwd 亲和度、limit 边界与宿主不该二次排序的原因。

候选排序不是「谁新谁靠前」,而是「谁和当前工作目录更近谁靠前」:DSH plugin(DSH插件) 用 cwd 亲和度排序、排除自身、并用 candidateLimit 封顶。 宿主在这三条之外做的任何排序,都会让结果偏离契约。

DSH plugin 候选里出现当前会话

先怀疑 agent 传错了,而不是排序错了。(来源) 现场:

text
当前会话 A,正在输入 @
候选列表里出现 A

官方对 listCandidates 的说明很明确:self 被排除,其 cwd 参与排序。也就是说,排除是按「请求方 agent」判断的。

如果列表里出现当前会话,常见原因是宿主用了一个通用的 agent 去请求,而不是当前会话对应的那一个。身份错了,排除自然失效。

另一个可能是缓存:上一次用别的 agent 请求的结果没有失效,被复用了。

DSH plugin 的 self 排除在哪一层

在解析器内部,不在前端过滤。(来源) 分工:

层是否负责排除自身
listCandidates(agent, …)是
Remote candidates是,沿用解析器
宿主前端否,不应重复做

前端再过滤一次看似保险,实际会掩盖身份问题:真正的 bug 被遮住,换成另一个入口又会复现。

判断方法:直接调用解析器,看结果里有没有自身。如果没有,说明前端拿到的 agent 不是你以为的那个。

DSH plugin 的 cwd 亲和度排序意味着什么

同目录优先,其次才是其他目录,同级之间不承诺「最近使用」。(来源) 三个要点:

  1. 排序依据是工作目录关系,不是时间;
  2. createdAt 只表示创建时间,不参与亲和度计算;
  3. 没有 cwd 的会话仍会出现,只是排不进「同目录」这一档。

这解释了一个常见疑惑:明明刚用过的会话,为什么排在后面。因为它和当前目录不同,亲和度低。

如果产品需要「最近使用」,那是另一个排序维度,不能靠改候选顺序实现。

DSH plugin 的 limit 边界

limit 是正数上限,不传就用配置值。(来源) 规则:

  • 签名是 listCandidates(agent, query, limit, signal);
  • limit 可选,传入时必须为正;
  • 不传时取配置里的 candidateLimit;
  • Remote 方法沿用配置上限,宿主不要再截断。

实践中容易犯两个错:传 0 想表达「不限」,或传一个极大值想「拿全量」。前者不合法,后者会让按键级请求变重。

按界面能同时展示的条数传值,是最稳的做法。

DSH plugin 为什么宿主不该二次排序

因为排序是契约,不是建议。(来源) 三个后果:

二次排序后果
按时间重排同目录优先失效
按名称重排用户位置记忆失效
按随机权重重排同一 query 结果不稳定

第三种最糟:列表在输入过程中跳动,用户刚要点的那条跑掉了位置。

如果确实需要另一种顺序,正确做法是新增一个排序维度并明确契约,而不是在前端覆盖。

DSH plugin 排序的验证

四个断言覆盖排除、亲和度、上限与稳定性。 步骤:

  1. 用当前会话的 agent 请求,确认自身不在结果里;
  2. 构造同目录与异目录会话,确认同目录在前;
  3. 传 limit=3,确认最多返回 3 条;
  4. 同 query 连续请求两次,确认顺序完全一致。

第 2 步不要只看第一条,要看整组的相对顺序;第 4 步是稳定性断言,失败通常意味着排序里混入了时间或随机因素。

还有一个上限细节:limit 必须是正数。把 0 解释成「不限」会让调用方无意中拉全量,排序也失去意义。

如果宿主需要「最近使用」视图,应该另建索引,而不是复用候选接口的排序规则。

排序之后是展示。读 DSH plugin 会话候选名怎么选;想看 Remote 出口怎么带 mention,读 DSH plugin 的 Remote candidates 怎么用;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的会话候选里为什么会出现当前正在用的这个会话?

正常情况下不应该,DSH plugin 的 listCandidates 会排除自身。DSH plugin 的 listCandidates 会排除自身,并用请求方 agent 的 cwd 参与排序;如果当前会话出现在列表里,先确认请求用的 agent 是不是同一个。

DSH plugin 的会话候选排序是按最近使用时间吗,依据是什么?

不是,DSH plugin 的排序依据是工作目录亲和度。DSH plugin 按工作目录亲和度排序,让同目录的会话更靠前;最近使用时间不在排序依据里,候选上的 createdAt 只表示创建时间。

DSH plugin 的 limit 传多少合适,传 0 会怎样?

limit 是可选的的正数上限,DSH plugin 不接受 0 或负数;不传时使用配置的 candidateLimit。按界面能展示的条数传值,不要为了「多拿一点」传一个很大的数。

DSH plugin 返回的候选顺序,前端还能按自己的规则再排一次吗?

DSH plugin 不建议前端再排一次候选顺序。DSH plugin 的排序是服务端契约,二次排序会破坏同目录优先的顺序,也会让同一 query 在两次请求间出现不同结果。

相关术语

cwd 亲和度
cwd 亲和度是候选排序的依据,与请求方工作目录相同或相近的会话排在更前面。— DeepSeek Harness 官方参考 - 会话引用
self 排除
self 排除是候选发现时把请求方会话自身从结果中移除的规则,避免用户引用当前会话。— session-reference/src/index.ts
candidateLimit
candidateLimit 是候选数量的配置上限,调用时可被 limit 参数覆盖。— session-reference/src/index.ts
二次排序(second sort)
二次排序是宿主在服务端返回后再次改变候选顺序的做法,会破坏服务端的确定性契约。— DeepSeek Harness 官方参考 - 会话引用

来源