DSH plugin 文件引用候选为什么只有路径:cwd 边界、provider 排序与不读内容的取舍
DSH plugin(DSH插件) 的文件引用候选只有 path 与 kind 两个字段,这不是设计遗漏,而是把「发现」和「读取」拆成了两步:发现只回答有哪些路径,读取发生在用户选中之后。 一旦你试图在候选里塞内容,就会同时破坏按键性能、权限边界和确定性。
DSH plugin 文件引用的候选长什么样
候选是一条约定的补全记录,不是文件对象。(来源) 官方类型只有两个字段:
| 字段 | 类型 | 含义 |
|---|---|---|
path | string | 面向用户的路径,普通提示词与文件系统工具都接受 |
kind | 'file' | 'directory' | 目录让补全保持打开,文件让这次提及收尾 |
path 的注释写得很清楚:它是「用户可见、且能被正常提示词与文件系统工具接受」的路径。也就是说,它是一个可被再次消费的字符串,而不是已经打开的文件句柄。
kind 决定的是交互状态,不是文件类型判断。目录候选被选中后补全不关闭,用户可以继续往里走;文件候选被选中后这次提及结束。把目录当文件插入,用户会立刻发现「怎么补全没了」。
一个典型路径是这样的:用户输入 @src,候选里出现 src/(directory)与 src.ts(file)。选中前者,输入框保留 @src/ 并继续请求候选项;选中后者,输入框收尾为一次完整提及。宿主不需要判断「这个字符串是不是目录」,只认 kind 就够了。
还有一个细节:kind 由目录项直接得出,不需要打开文件确认。这意味着即使文件内容损坏或读取超时,补全仍然能正常工作。
DSH plugin 候选为什么不带文件内容
因为发现运行在按键频率上,而读内容是重操作。(来源) 候选会在用户每输入一个字符时重新生成;如果每次生成都读文件,输入延迟会随目录规模线性上升。
具体代价有三层:
- 性能 — 一个几千文件的工作区,每次按键都读一遍内容,延迟不可控。
- 权限 — 候选可能来自用户没有读权限的路径,发现阶段读内容会让补全直接失败。
- 确定性 — 读内容会引入文件变化,同一 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 负责排序与命名空间访问,但不读文件内容。
这条分工解决三个常见问题:
- 顺序稳定 — provider 给出确定性顺序,宿主二次排序会破坏它。
- 命名空间冲突 — 多个来源有同名文件时,由 provider 决定如何呈现,而不是前端去重。
- 多来源合并 — 组合 provider 之上的 Remote 适配器统一出口,宿主不需要知道有几个来源。
一个实用判断:如果宿主代码里出现「按修改时间重排候选」或「过滤掉重复路径」,说明这层逻辑放错了位置。
DSH plugin 里想拿文件内容该在哪一步做
在用户选中候选之后,用文件系统工具读取,而不是改候选结构。(来源) 推荐顺序:
- 候选返回
path,用户点选或回车确认; - 宿主把路径插入草稿,或作为工具参数;
- 需要预览时,单独发起一次读取,并处理权限与大小;
- 读取失败不影响补全,只影响预览。
这个顺序的好处是:发现始终轻量,读取只在真正需要时发生,失败也不会把补全列表打空。
如果确实需要「候选里带摘要」,那属于另一个能力,应该新开一个接口,而不是往 FileReferenceCandidate 上加字段。改公共类型会同时影响所有宿主。
DSH plugin 候选契约的自检清单
五条能立刻验证你的实现有没有越界。 清单:
- 打印一次候选,确认只有
path与kind,没有额外内容字段; - 连续输入五个字符,确认同一 query 的结果顺序一致;
- 在子目录会话里输入
@,确认上层文件不出现; - 选中目录后确认补全不关闭,选中文件后确认关闭;
- 在没有读权限的目录里输入
@,确认候选仍能列出文件名。
第 5 条是权限边界的反证:候选不依赖文件内容,所以列目录不需要读权限。
五条都过,说明你守住的是「发现」这一层。下一步想接文件读取,读 DSH plugin 文件引用的 query 怎么传;想接宿主适配器,读 两个文件引用服务怎么选;想先看整体链路,读 DSH plugin 怎么完整实现会话引用。
常见问题
DSH plugin 不在候选里带文件内容,原因不是不方便,而是代价太高。DSH plugin 的候选在按键频率下反复生成,带上内容意味着每次输入都要读文件;官方把候选限定为仅含路径,读取交给后续步骤。
这些信息不属于候选契约,DSH plugin 不会在发现阶段提供。需要展示时,应该在用户选中候选之后,用文件系统工具单独读取,而不是修改候选结构。
因为发现范围由被寻址 agent 的 cwd 约束,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 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- file-reference types.ts· deepseek-ai