DSH plugin 文件引用两个服务:ctx.fileReferences 与 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 的抽象缝解决什么问题
它把「发现文件」变成一种可替换的能力,而不是写死在某一个实现里。(来源) 三个收益:
- 可替换 — 工作区、插件、远端可以各自实现,再由组合层合并;
- 可测试 — 测试可以注入一个固定返回的 provider,不依赖真实文件系统;
- 可约束 — 接口只要求路径与 kind,实现方不容易把内容读取混进来。
实现抽象缝时,最需要守住的是「不读内容」和「确定性」这两条。它们不是建议,而是候选能被安全缓存与反复调用的前提。
抽象缝的返回值里没有来源标识,来源区分由组合层完成。实现方如果偷偷加字段,宿主就会被某一个实现绑架。
DSH plugin 的 Remote 适配器多做了什么
它只多做一件事:把线上身份翻译成 agent。(来源) 流程可以拆成三步:
- 请求携带 Session 身份到达;
- 适配器解析出对应 agent;
- 用该 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 走两个入口,比较结果。 步骤:
- 准备一个固定目录与固定 query;
- 直接调用抽象缝,记录路径集合与顺序;
- 通过 Remote 出口调用同一 query,记录结果;
- 比较两者是否一致;
- 取消一次请求,确认两个入口都停止。
第 4 步不一致时,先查 Remote 是否解析到了错误的 agent;第 5 步失败时,先查 signal 是否被适配器丢弃。
第 1 步要固定 cwd,否则两次调用可能落在不同目录,比较就没有意义。
接线完成后,下一步是候选排序与展示。读 DSH plugin 多 provider 怎么组合;想处理输入解析,读 DSH plugin 文件引用的 query 怎么传;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-controller file-references.ts
常见问题
DSH plugin 的两个文件引用服务怎么接,要看你的角色。DSH plugin 里实现 provider 用 ctx.fileReferences,宿主消费补全用 ctx.sessionFileReferences;只接一个不会报错,但要么没有来源,要么没有出口。
DSH plugin 的 Remote 适配器多做了一步身份解析。DSH plugin 的 Remote 出口需要从线上 Session 身份解析出 agent,再用该 agent 的 cwd 约束发现范围,query 只是后续参数。
技术上可以绕过 Remote,但会失去 DSH plugin 的线上身份到 agent 映射。DSH plugin 的浏览器或远端消费方拿不到本地 agent 对象,绕过 Remote 通常意味着自己造一份身份,容易与真实会话不一致。
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
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-controller file-references.ts· deepseek-ai