ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 文件引用候选为什么只有路径:cwd 边界、provider 排序与不读内容的取舍

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness文件引用FileReferenceCandidate插件开发
FileReferenceCandidate 只有 path 与 kind 两个字段。本文解释这条契约的边界:cwd 决定发现范围,provider 负责排序与命名空间,发现阶段不读文件内容,以及想拿内容应该放在哪一步。

DSH plugin(DSH插件) 的文件引用候选只有 path 与 kind 两个字段,这不是设计遗漏,而是把「发现」和「读取」拆成了两步:发现只回答有哪些路径,读取发生在用户选中之后。 一旦你试图在候选里塞内容,就会同时破坏按键性能、权限边界和确定性。

DSH plugin 文件引用的候选长什么样

候选是一条约定的补全记录,不是文件对象。(来源) 官方类型只有两个字段:

字段类型含义
pathstring面向用户的路径,普通提示词与文件系统工具都接受
kind'file' | 'directory'目录让补全保持打开,文件让这次提及收尾

path 的注释写得很清楚:它是「用户可见、且能被正常提示词与文件系统工具接受」的路径。也就是说,它是一个可被再次消费的字符串,而不是已经打开的文件句柄。

kind 决定的是交互状态,不是文件类型判断。目录候选被选中后补全不关闭,用户可以继续往里走;文件候选被选中后这次提及结束。把目录当文件插入,用户会立刻发现「怎么补全没了」。

一个典型路径是这样的:用户输入 @src,候选里出现 src/(directory)与 src.ts(file)。选中前者,输入框保留 @src/ 并继续请求候选项;选中后者,输入框收尾为一次完整提及。宿主不需要判断「这个字符串是不是目录」,只认 kind 就够了。

还有一个细节:kind 由目录项直接得出,不需要打开文件确认。这意味着即使文件内容损坏或读取超时,补全仍然能正常工作。

DSH plugin 候选为什么不带文件内容

因为发现运行在按键频率上,而读内容是重操作。(来源) 候选会在用户每输入一个字符时重新生成;如果每次生成都读文件,输入延迟会随目录规模线性上升。

具体代价有三层:

  1. 性能 — 一个几千文件的工作区,每次按键都读一遍内容,延迟不可控。
  2. 权限 — 候选可能来自用户没有读权限的路径,发现阶段读内容会让补全直接失败。
  3. 确定性 — 读内容会引入文件变化,同一 query 两次结果不同,宿主无法缓存。

所以契约把候选压到最小:只给路径和类型。任何「顺手加个大小、加个摘要」的想法,都会把这条链路从轻量发现变成重型扫描。

可以用一个简单标准判断某个字段该不该进候选:它是否只需要目录项就能得到。文件名、是否为目录属于目录项;内容、行数、摘要都需要打开文件,因此都不属于候选。

反过来也能验证:如果候选真的依赖内容,那么在无读权限的目录里,补全应该整体失败。实际实现里补全照常工作,说明它只看了目录项。

DSH plugin 里 cwd 如何决定候选范围

范围来自被寻址的 agent,不是来自前端当前打开的文件夹。(来源) list(agent, query, signal) 的第一个参数就是 agent,官方注释写明「目标 agent 的 session cwd 约束发现范围」。

这意味着两件事:

  • 前端切了目录树,但 agent 的 cwd 没变,候选范围不会跟着变;
  • 想让候选进入子目录,靠的是选中 kind: 'directory' 的候选继续补全,而不是让服务端递归扫描。

如果用户在子目录里启动会话,却想引用上层文件,正确做法是换工作目录或换会话,而不是在前端拼 ../。拼出来的路径即使能显示,也不在发现范围内,后续工具调用同样会失败。

这类问题在单仓多包的项目里最常见:会话开在 packages/web,用户想引用根目录的 pnpm-workspace.yaml,补全里始终没有。不是插件漏了,而是发现范围就只有 packages/web。把会话切到仓库根目录,候选自然出现。

DSH plugin 候选的排序与命名空间归谁管

排序和命名空间都归 provider,宿主只负责展示。(来源) 官方对 FileReferenceService 的描述是:provider 负责排序与命名空间访问,但不读文件内容。

这条分工解决三个常见问题:

  1. 顺序稳定 — provider 给出确定性顺序,宿主二次排序会破坏它。
  2. 命名空间冲突 — 多个来源有同名文件时,由 provider 决定如何呈现,而不是前端去重。
  3. 多来源合并 — 组合 provider 之上的 Remote 适配器统一出口,宿主不需要知道有几个来源。

一个实用判断:如果宿主代码里出现「按修改时间重排候选」或「过滤掉重复路径」,说明这层逻辑放错了位置。

DSH plugin 里想拿文件内容该在哪一步做

在用户选中候选之后,用文件系统工具读取,而不是改候选结构。(来源) 推荐顺序:

  1. 候选返回 path,用户点选或回车确认;
  2. 宿主把路径插入草稿,或作为工具参数;
  3. 需要预览时,单独发起一次读取,并处理权限与大小;
  4. 读取失败不影响补全,只影响预览。

这个顺序的好处是:发现始终轻量,读取只在真正需要时发生,失败也不会把补全列表打空。

如果确实需要「候选里带摘要」,那属于另一个能力,应该新开一个接口,而不是往 FileReferenceCandidate 上加字段。改公共类型会同时影响所有宿主。

DSH plugin 候选契约的自检清单

五条能立刻验证你的实现有没有越界。 清单:

  1. 打印一次候选,确认只有 path 与 kind,没有额外内容字段;
  2. 连续输入五个字符,确认同一 query 的结果顺序一致;
  3. 在子目录会话里输入 @,确认上层文件不出现;
  4. 选中目录后确认补全不关闭,选中文件后确认关闭;
  5. 在没有读权限的目录里输入 @,确认候选仍能列出文件名。

第 5 条是权限边界的反证:候选不依赖文件内容,所以列目录不需要读权限。

五条都过,说明你守住的是「发现」这一层。下一步想接文件读取,读 DSH plugin 文件引用的 query 怎么传;想接宿主适配器,读 两个文件引用服务怎么选;想先看整体链路,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的文件引用候选为什么不直接带上文件内容,难道不是更方便吗?

DSH plugin 不在候选里带文件内容,原因不是不方便,而是代价太高。DSH plugin 的候选在按键频率下反复生成,带上内容意味着每次输入都要读文件;官方把候选限定为仅含路径,读取交给后续步骤。

DSH plugin 的 FileReferenceCandidate 只有两个字段,那文件大小和修改时间从哪里拿?

这些信息不属于候选契约,DSH plugin 不会在发现阶段提供。需要展示时,应该在用户选中候选之后,用文件系统工具单独读取,而不是修改候选结构。

为什么 DSH plugin 的文件候选只在当前 cwd 里找,上层目录的文件怎么补全?

因为发现范围由被寻址 agent 的 cwd 约束,DSH plugin 不会越界扫描。想补全上层文件,应该切换会话或工作目录,再重新触发候选。

DSH plugin 的文件候选顺序可以自己再排一次吗,比如按修改时间?

DSH plugin 不建议宿主再排一次候选顺序。DSH plugin 要求候选是确定性的,排序由 provider 负责;宿主二次排序会让同一 query 的结果在不同时刻不一致,也会破坏目录优先的补全体验。

相关术语

FileReferenceCandidate
FileReferenceCandidate 是文件引用发现阶段的结果,只含 path 与 kind,用于补全列表,不携带文件内容。— DeepSeek Harness 官方参考 - 会话引用
cwd
cwd 是被寻址 agent 的工作目录,也是文件引用发现的范围边界,候选只在这个目录内产生。— DeepSeek Harness 官方参考 - 会话引用
provider
provider 是文件引用候选的提供方,负责排序与命名空间访问,但不读取文件内容。— DeepSeek Harness 官方参考 - 会话引用
确定性候选(deterministic candidates)
确定性候选是同一 query 在同一环境下返回相同路径集合与相同顺序的结果,便于宿主缓存与测试。— DeepSeek Harness 官方参考 - 会话引用

来源