DSH plugin 多 provider 组合:文件候选的排序、命名空间与去重到底谁说了算
在 DSH plugin(DSH插件) 里,当工作区、插件、远端各有一套文件来源时,候选列表的问题不再是「有没有」,而是「谁排前面、同名怎么区分、重复算谁的」:这三件事都归 composed provider,不归你的宿主。 前端越早接管合并,列表就越容易随分页和并发漂移。
DSH plugin 里两个同名 README 同时出现
同名路径并存不是错误数据,而是组合层还没决定命名空间。(来源) 现场通常长这样:
README.md <- 工作区来源
docs/README.md <- 文档来源
plugin/README.md <- 插件来源
三个来源都能提供 README.md 这个相对路径,但它们在用户眼里代表不同东西。如果组合层只是简单拼接,用户会看到三个一模一样的条目,选中哪一个全靠运气。
这里的关键不是「去重」,而是「先区分再合并」:命名空间负责区分,去重只在同一命名空间内发生。
一个反例:如果用户先看到三个一样的 README,选完才发现引用的是插件目录里那份,说明区分信息出现得太晚,界面上的「选中」已经变成一次猜谜。
DSH plugin 的 composed provider 是什么
它是 Remote 适配器背后的组合实现,不是又一个对外接口。(来源) 分层关系:
| 层 | 职责 |
|---|---|
ctx.sessionFileReferences | Remote 出口,从 Session 身份解析 agent |
| composed provider | 合并多个来源,排序、命名空间、去重 |
| 各来源 provider | 各自列出自己范围内的路径 |
对外只有一个 list(agent, query, signal),组合发生在内部。宿主看不到来源数量,也不应该看到。
这层设计的好处是:新增一个来源时,宿主代码不用改;来源出问题时,也只影响自己那部分候选。
组合层最好把来源失败隔离开:某个来源读取失败时,返回其余来源的候选并记录错误,而不是让整个列表变空。
DSH plugin 排序为什么必须归 provider
因为只有组合层同时看得到所有来源。(来源) 三条理由:
- 跨来源可比 — 前端只拿到合并后的列表,无法知道某条来自哪个来源,也就无法按来源优先级排序;
- 稳定性 — 组合层可以固定来源顺序,前端二次排序会把它打乱;
- 一致性 — 同一 query 在不同宿主、不同端上应该得到相同顺序,排序逻辑必须只有一份。
一个可操作的判断:如果排序代码里出现了「当前时间」「随机」「Map 遍历顺序」,那它不该在候选链路里。
DSH plugin 命名空间与去重怎么分工
命名空间先于去重,去重只在同域内生效。(来源) 分工建议:
- 命名空间负责让不同来源的同名路径可区分,例如带来源前缀或分组;
- 去重只在同一命名空间内做,避免把不同来源的
README.md误判为重复; - 展示层不参与合并,只按 provider 给出的顺序渲染。
如果反过来先去重再区分,就会丢掉来源信息;用户选中后也不知道自己引用的是哪一份。
这条规则对插件作者尤其重要:插件新增来源时,应该先声明命名空间,再考虑是否与既有来源合并。
DSH plugin 组合场景下的确定性更难
来源越多,不稳定因素越多。(来源) 常见三类:
| 不稳定因素 | 表现 | 处理 |
|---|---|---|
| 并发返回顺序 | 每次合并顺序不同 | 固定来源顺序,按来源归并 |
| 文件系统遍历顺序 | 同目录候选乱序 | 排序后再合并 |
| 分页或截断 | 去重结果随批次变化 | 在合并后统一截断 |
第三类最隐蔽:如果先去重再截断,第一批和第二批的重复判断可能不一致,用户往下翻会看到重复项。
正确顺序是「各来源取全量 → 合并 → 去重 → 排序 → 截断」。截断放最后,才能保证前缀稳定。
去重键也要统一:用原始路径还是规范化路径,必须由组合层决定一次,不能让不同来源各用一套。
DSH plugin 组合层的自测步骤
四个断言覆盖合并、区分、稳定与截断。 步骤:
- 构造两个来源各含
README.md,确认候选能区分来源; - 同一 query 连续请求两次,确认顺序与内容完全一致;
- 把来源返回顺序反转,确认合并结果不变;
- 把 limit 调小,确认截断发生在合并之后且前缀稳定。
第 3 步最能暴露实现问题:如果反转来源顺序后结果变了,说明组合层依赖了到达顺序。
第 2 步和第 3 步要一起看:单次调用稳定,不代表结果与来源顺序无关。
组合层稳定后,再处理宿主接线。读 DSH plugin 两个文件引用服务怎么选;想看范围边界,读 DSH plugin 文件引用的 cwd 边界;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
常见问题
DSH plugin 由 composed provider 的命名空间规则决定显示哪一个,而不是前端随便挑。DSH plugin 把排序和命名空间访问交给 provider,宿主只展示它给出的路径,重复项应该在组合层处理。
不是一回事,DSH plugin 把它们分成了出口与组合实现两层。DSH plugin 的 Remote 适配器是会话文件引用的对外出口,composed provider 是它背后的组合实现;前者负责解析 agent 身份,后者负责把多个来源合成一份确定性候选。
在 DSH plugin 里,前端去重看似更快,但只能看到当前页的候选。DSH plugin 的候选需要跨来源、跨批次保持一致,只有组合层能同时看到全部来源,去重才不会随分页或截断变化。
DSH plugin 的候选顺序变化,常见原因是组合层依赖了不稳定因素,例如并发返回顺序、修改时间或哈希遍历。DSH plugin 要求确定性候选,组合实现必须给每个来源固定优先级,并在合并时保持稳定顺序。
相关术语
- composed provider
- composed provider 是把多个文件引用来源合成为一个候选列表的组合实现,负责排序与命名空间访问。— DeepSeek Harness 官方参考 - 会话引用
- 命名空间(namespace)
- 命名空间是 provider 为不同来源划分的路径作用域,用来区分同名路径并决定展示形式。— DeepSeek Harness 官方参考 - 会话引用
- 来源优先级(source priority)
- 来源优先级是组合层为每个 provider 设定的固定顺序,用来保证合并结果可预测。— DeepSeek Harness 官方参考 - 会话引用
- 确定性候选(deterministic candidates)
- 确定性候选是同一 query 在同一环境下返回相同集合与顺序的结果,是缓存与测试的前提。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- file-reference/src/index.ts· deepseek-ai