ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 多 provider 组合:文件候选的排序、命名空间与去重到底谁说了算

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness文件引用provider命名空间
多个文件来源并存时,候选列表会出现同名路径、顺序漂移和重复项。本文讲 composed provider 的分工:排序与命名空间由谁负责、去重该放在哪一层、以及组合场景下怎么保证确定性。

在 DSH plugin(DSH插件) 里,当工作区、插件、远端各有一套文件来源时,候选列表的问题不再是「有没有」,而是「谁排前面、同名怎么区分、重复算谁的」:这三件事都归 composed provider,不归你的宿主。 前端越早接管合并,列表就越容易随分页和并发漂移。

DSH plugin 里两个同名 README 同时出现

同名路径并存不是错误数据,而是组合层还没决定命名空间。(来源) 现场通常长这样:

text
README.md              <- 工作区来源
docs/README.md         <- 文档来源
plugin/README.md       <- 插件来源

三个来源都能提供 README.md 这个相对路径,但它们在用户眼里代表不同东西。如果组合层只是简单拼接,用户会看到三个一模一样的条目,选中哪一个全靠运气。

这里的关键不是「去重」,而是「先区分再合并」:命名空间负责区分,去重只在同一命名空间内发生。

一个反例:如果用户先看到三个一样的 README,选完才发现引用的是插件目录里那份,说明区分信息出现得太晚,界面上的「选中」已经变成一次猜谜。

DSH plugin 的 composed provider 是什么

它是 Remote 适配器背后的组合实现,不是又一个对外接口。(来源) 分层关系:

层职责
ctx.sessionFileReferencesRemote 出口,从 Session 身份解析 agent
composed provider合并多个来源,排序、命名空间、去重
各来源 provider各自列出自己范围内的路径

对外只有一个 list(agent, query, signal),组合发生在内部。宿主看不到来源数量,也不应该看到。

这层设计的好处是:新增一个来源时,宿主代码不用改;来源出问题时,也只影响自己那部分候选。

组合层最好把来源失败隔离开:某个来源读取失败时,返回其余来源的候选并记录错误,而不是让整个列表变空。

DSH plugin 排序为什么必须归 provider

因为只有组合层同时看得到所有来源。(来源) 三条理由:

  1. 跨来源可比 — 前端只拿到合并后的列表,无法知道某条来自哪个来源,也就无法按来源优先级排序;
  2. 稳定性 — 组合层可以固定来源顺序,前端二次排序会把它打乱;
  3. 一致性 — 同一 query 在不同宿主、不同端上应该得到相同顺序,排序逻辑必须只有一份。

一个可操作的判断:如果排序代码里出现了「当前时间」「随机」「Map 遍历顺序」,那它不该在候选链路里。

DSH plugin 命名空间与去重怎么分工

命名空间先于去重,去重只在同域内生效。(来源) 分工建议:

  • 命名空间负责让不同来源的同名路径可区分,例如带来源前缀或分组;
  • 去重只在同一命名空间内做,避免把不同来源的 README.md 误判为重复;
  • 展示层不参与合并,只按 provider 给出的顺序渲染。

如果反过来先去重再区分,就会丢掉来源信息;用户选中后也不知道自己引用的是哪一份。

这条规则对插件作者尤其重要:插件新增来源时,应该先声明命名空间,再考虑是否与既有来源合并。

DSH plugin 组合场景下的确定性更难

来源越多,不稳定因素越多。(来源) 常见三类:

不稳定因素表现处理
并发返回顺序每次合并顺序不同固定来源顺序,按来源归并
文件系统遍历顺序同目录候选乱序排序后再合并
分页或截断去重结果随批次变化在合并后统一截断

第三类最隐蔽:如果先去重再截断,第一批和第二批的重复判断可能不一致,用户往下翻会看到重复项。

正确顺序是「各来源取全量 → 合并 → 去重 → 排序 → 截断」。截断放最后,才能保证前缀稳定。

去重键也要统一:用原始路径还是规范化路径,必须由组合层决定一次,不能让不同来源各用一套。

DSH plugin 组合层的自测步骤

四个断言覆盖合并、区分、稳定与截断。 步骤:

  1. 构造两个来源各含 README.md,确认候选能区分来源;
  2. 同一 query 连续请求两次,确认顺序与内容完全一致;
  3. 把来源返回顺序反转,确认合并结果不变;
  4. 把 limit 调小,确认截断发生在合并之后且前缀稳定。

第 3 步最能暴露实现问题:如果反转来源顺序后结果变了,说明组合层依赖了到达顺序。

第 2 步和第 3 步要一起看:单次调用稳定,不代表结果与来源顺序无关。

组合层稳定后,再处理宿主接线。读 DSH plugin 两个文件引用服务怎么选;想看范围边界,读 DSH plugin 文件引用的 cwd 边界;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里两个来源都有 README.md,候选应该显示哪一个?

DSH plugin 由 composed provider 的命名空间规则决定显示哪一个,而不是前端随便挑。DSH plugin 把排序和命名空间访问交给 provider,宿主只展示它给出的路径,重复项应该在组合层处理。

DSH plugin 的 composed provider 和 Remote 适配器是一回事吗?

不是一回事,DSH plugin 把它们分成了出口与组合实现两层。DSH plugin 的 Remote 适配器是会话文件引用的对外出口,composed provider 是它背后的组合实现;前者负责解析 agent 身份,后者负责把多个来源合成一份确定性候选。

DSH plugin 前端去重会不会更快,为什么一定要放在 provider 层?

在 DSH plugin 里,前端去重看似更快,但只能看到当前页的候选。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 官方参考 - 会话引用

来源