DSH plugin 会话候选排序规则:cwd 亲和度、排除自身与 limit 上限到底怎么定
候选排序不是「谁新谁靠前」,而是「谁和当前工作目录更近谁靠前」:DSH plugin(DSH插件) 用 cwd 亲和度排序、排除自身、并用 candidateLimit 封顶。 宿主在这三条之外做的任何排序,都会让结果偏离契约。
DSH plugin 候选里出现当前会话
先怀疑 agent 传错了,而不是排序错了。(来源) 现场:
当前会话 A,正在输入 @
候选列表里出现 A
官方对 listCandidates 的说明很明确:self 被排除,其 cwd 参与排序。也就是说,排除是按「请求方 agent」判断的。
如果列表里出现当前会话,常见原因是宿主用了一个通用的 agent 去请求,而不是当前会话对应的那一个。身份错了,排除自然失效。
另一个可能是缓存:上一次用别的 agent 请求的结果没有失效,被复用了。
DSH plugin 的 self 排除在哪一层
在解析器内部,不在前端过滤。(来源) 分工:
| 层 | 是否负责排除自身 |
|---|---|
listCandidates(agent, …) | 是 |
Remote candidates | 是,沿用解析器 |
| 宿主前端 | 否,不应重复做 |
前端再过滤一次看似保险,实际会掩盖身份问题:真正的 bug 被遮住,换成另一个入口又会复现。
判断方法:直接调用解析器,看结果里有没有自身。如果没有,说明前端拿到的 agent 不是你以为的那个。
DSH plugin 的 cwd 亲和度排序意味着什么
同目录优先,其次才是其他目录,同级之间不承诺「最近使用」。(来源) 三个要点:
- 排序依据是工作目录关系,不是时间;
createdAt只表示创建时间,不参与亲和度计算;- 没有 cwd 的会话仍会出现,只是排不进「同目录」这一档。
这解释了一个常见疑惑:明明刚用过的会话,为什么排在后面。因为它和当前目录不同,亲和度低。
如果产品需要「最近使用」,那是另一个排序维度,不能靠改候选顺序实现。
DSH plugin 的 limit 边界
limit 是正数上限,不传就用配置值。(来源) 规则:
- 签名是
listCandidates(agent, query, limit, signal); limit可选,传入时必须为正;- 不传时取配置里的
candidateLimit; - Remote 方法沿用配置上限,宿主不要再截断。
实践中容易犯两个错:传 0 想表达「不限」,或传一个极大值想「拿全量」。前者不合法,后者会让按键级请求变重。
按界面能同时展示的条数传值,是最稳的做法。
DSH plugin 为什么宿主不该二次排序
因为排序是契约,不是建议。(来源) 三个后果:
| 二次排序 | 后果 |
|---|---|
| 按时间重排 | 同目录优先失效 |
| 按名称重排 | 用户位置记忆失效 |
| 按随机权重重排 | 同一 query 结果不稳定 |
第三种最糟:列表在输入过程中跳动,用户刚要点的那条跑掉了位置。
如果确实需要另一种顺序,正确做法是新增一个排序维度并明确契约,而不是在前端覆盖。
DSH plugin 排序的验证
四个断言覆盖排除、亲和度、上限与稳定性。 步骤:
- 用当前会话的 agent 请求,确认自身不在结果里;
- 构造同目录与异目录会话,确认同目录在前;
- 传
limit=3,确认最多返回 3 条; - 同 query 连续请求两次,确认顺序完全一致。
第 2 步不要只看第一条,要看整组的相对顺序;第 4 步是稳定性断言,失败通常意味着排序里混入了时间或随机因素。
还有一个上限细节:limit 必须是正数。把 0 解释成「不限」会让调用方无意中拉全量,排序也失去意义。
如果宿主需要「最近使用」视图,应该另建索引,而不是复用候选接口的排序规则。
排序之后是展示。读 DSH plugin 会话候选名怎么选;想看 Remote 出口怎么带 mention,读 DSH plugin 的 Remote candidates 怎么用;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/index.ts
常见问题
正常情况下不应该,DSH plugin 的 listCandidates 会排除自身。DSH plugin 的 listCandidates 会排除自身,并用请求方 agent 的 cwd 参与排序;如果当前会话出现在列表里,先确认请求用的 agent 是不是同一个。
不是,DSH plugin 的排序依据是工作目录亲和度。DSH plugin 按工作目录亲和度排序,让同目录的会话更靠前;最近使用时间不在排序依据里,候选上的 createdAt 只表示创建时间。
limit 是可选的的正数上限,DSH plugin 不接受 0 或负数;不传时使用配置的 candidateLimit。按界面能展示的条数传值,不要为了「多拿一点」传一个很大的数。
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 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/index.ts· deepseek-ai