ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 文件引用两个服务:ctx.fileReferences 与 Remote 适配器怎么选

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness文件引用Remote宿主适配器
两个服务名字接近,职责不同:ctx.fileReferences 是给 provider 实现的抽象缝,ctx.sessionFileReferences 是给宿主消费的 Remote 出口。本文用三问决策表和接线错误说明怎么选。

在 DSH plugin(DSH插件) 里,名字接近不代表职责接近:ctx.fileReferences 是给插件作者实现的抽象缝,ctx.sessionFileReferences 是给宿主消费的 Remote 出口。 选错的典型后果是「有实现但界面拿不到」或「界面能调但背后没有来源」。

DSH plugin 里两个名字很像的服务

先看定义,再看调用方。(来源) 对照:

服务官方描述谁用
ctx.fileReferences可取消的文件引用发现能力,抽象缝provider 实现者
ctx.sessionFileReferences组合 provider 之上的 Host Remote 适配器宿主、远端消费方

两个服务的 list 签名看起来一样:agent、query、signal。区别在 agent 怎么来、背后是谁。

抽象缝的 agent 由调用方直接给出;Remote 适配器的 agent 从线上 Session 身份解析。这一个差别决定了它们不能互换。

一个常见误解是「抽象缝更底层,所以更高级」。实际上两者是不同方向的接口:一个向上提供能力,一个向外暴露能力,没有高低之分。

DSH plugin 的抽象缝解决什么问题

它把「发现文件」变成一种可替换的能力,而不是写死在某一个实现里。(来源) 三个收益:

  1. 可替换 — 工作区、插件、远端可以各自实现,再由组合层合并;
  2. 可测试 — 测试可以注入一个固定返回的 provider,不依赖真实文件系统;
  3. 可约束 — 接口只要求路径与 kind,实现方不容易把内容读取混进来。

实现抽象缝时,最需要守住的是「不读内容」和「确定性」这两条。它们不是建议,而是候选能被安全缓存与反复调用的前提。

抽象缝的返回值里没有来源标识,来源区分由组合层完成。实现方如果偷偷加字段,宿主就会被某一个实现绑架。

DSH plugin 的 Remote 适配器多做了什么

它只多做一件事:把线上身份翻译成 agent。(来源) 流程可以拆成三步:

  1. 请求携带 Session 身份到达;
  2. 适配器解析出对应 agent;
  3. 用该 agent 的 cwd 调用组合 provider 的 list。

除此之外,它不改变 query,也不改变候选结构。返回的仍然是确定性、仅含路径的候选。

这解释了为什么远端消费方不该自己造 agent:一旦身份与真实会话不一致,cwd 范围就会错,候选看起来「少了一些文件」,实际是范围错了。

适配器还负责把取消信号继续往下传。如果它自己吞掉 signal,上游已经停止,provider 仍在扫描。

DSH plugin 三种接法的选择表

按角色选,不按名字像不像选。(来源) 对照:

你的角色接什么原因
插件作者,提供新的文件来源ctx.fileReferences需要实现发现能力
宿主前端,展示补全列表ctx.sessionFileReferences需要从身份解析 agent
测试或本地工具,已有 agent两者皆可,优先抽象缝不经过线上身份

如果同时做两件事,两个都要接:一个实现来源,一个暴露出口。缺一个,链路就是断的。

组织上也有个建议:把两处接线放在同一个模块里,避免实现与出口各自演进后参数对不上。

DSH plugin 为什么不要把 mention 语法写进核心

UI 的提及语法属于宿主,不属于 agent 核心。(来源) 官方在概述里明确:宿主适配器使用这些类型,而不会把各自 UI 的提及语法传入 agent 核心。

原因有三条:

  • 不同宿主的提及语法不同,写进核心会让核心被某个 UI 绑架;
  • 语法会变,核心契约不应该跟着变;
  • 核心只需要路径与 kind,语法解析是宿主自己的事。

所以 list 接收的是路径文本 query,而不是完整的 @[...] 字符串。把整段 mention 传进去,provider 只会把它当路径,结果自然为空。

如果宿主支持多种 mention 语法,解析应发生在提交之前,并且只把路径文本交给 list;语法层不进入核心。

DSH plugin 接线后的验证

用同一 query 走两个入口,比较结果。 步骤:

  1. 准备一个固定目录与固定 query;
  2. 直接调用抽象缝,记录路径集合与顺序;
  3. 通过 Remote 出口调用同一 query,记录结果;
  4. 比较两者是否一致;
  5. 取消一次请求,确认两个入口都停止。

第 4 步不一致时,先查 Remote 是否解析到了错误的 agent;第 5 步失败时,先查 signal 是否被适配器丢弃。

第 1 步要固定 cwd,否则两次调用可能落在不同目录,比较就没有意义。

接线完成后,下一步是候选排序与展示。读 DSH plugin 多 provider 怎么组合;想处理输入解析,读 DSH plugin 文件引用的 query 怎么传;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

来源:DeepSeek Harness 官方参考 - 会话引用、session-controller file-references.ts

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 ctx.fileReferences 能单独接吗?

DSH plugin 的两个文件引用服务怎么接,要看你的角色。DSH plugin 里实现 provider 用 ctx.fileReferences,宿主消费补全用 ctx.sessionFileReferences;只接一个不会报错,但要么没有来源,要么没有出口。

DSH plugin 的 Remote 适配器为什么不直接把 query 传给 provider?

DSH plugin 的 Remote 适配器多做了一步身份解析。DSH plugin 的 Remote 出口需要从线上 Session 身份解析出 agent,再用该 agent 的 cwd 约束发现范围,query 只是后续参数。

DSH plugin 里宿主能不能绕过 Remote,直接调用抽象缝?

技术上可以绕过 Remote,但会失去 DSH plugin 的线上身份到 agent 映射。DSH plugin 的浏览器或远端消费方拿不到本地 agent 对象,绕过 Remote 通常意味着自己造一份身份,容易与真实会话不一致。

DSH plugin 的抽象缝需要返回什么,能不能顺便做缓存?

DSH plugin 的抽象缝应返回确定性的、仅含路径的候选。DSH plugin 不禁止在 provider 内部缓存,但缓存不能改变同一 query 的结果顺序,也不能让取消信号失效。

相关术语

抽象缝(abstraction seam)
抽象缝是只定义能力、不绑定实现的接口,DSH plugin 用它让不同 provider 接入同一套文件发现能力。— DeepSeek Harness 官方参考 - 会话引用
Remote 适配器
Remote 适配器是面向远端消费方的出口,负责把线上 Session 身份解析成 agent 并调用组合 provider。— session-controller file-references.ts
provider
provider 是文件引用的实际提供方,负责在自己范围内产出候选,并保证顺序确定。— DeepSeek Harness 官方参考 - 会话引用
agent 解析
agent 解析是 Remote 层根据请求携带的 Session 身份找到目标 agent 的过程,决定后续 cwd 范围。— session-controller file-references.ts

来源