ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 文件引用的 cwd 边界:为什么补全只在当前工作目录里找,怎么换范围

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness文件引用cwd工作目录
文件引用只在一个工作目录里发现候选,cwd 来自被寻址的 agent,而不是前端目录树。本文讲 cwd 的来源、三种越界做法为什么不成立、换范围的三条正路,以及可复现的边界测试。

文件引用补全看不到某个文件,先确认它在不在会话的 cwd 里,而不是先怀疑插件。 DSH plugin(DSH插件) 的发现范围由被寻址 agent 的工作目录决定,前端目录树、编辑器当前文件、上一次浏览记录都不参与。

DSH plugin 子目录会话看不到根目录文件

这是边界生效的正常结果,不是缺功能。(来源) 一个常见现场:

text
仓库根目录/
├── pnpm-workspace.yaml
└── packages/web/        <- 会话在这里启动

会话开在 packages/web,用户输入 @pnpm,候选为空。不是文件不存在,也不是 provider 漏扫,而是发现范围只有 packages/web。

判断方法很直接:把会话切到仓库根目录,再输入同样的前缀。如果候选出现,说明是 cwd 边界;如果仍然为空,才需要查 provider。

还有一个快速判断:先输入当前目录里确实存在的文件名。它能出现,就说明链路正常,问题只在范围,而不是插件没装好。

DSH plugin 的 cwd 从哪里来

cwd 属于会话上下文,来自被寻址的 agent,不是前端的当前目录。(来源) 两个入口都能看到这一点:

  1. ctx.fileReferences.list(agent, query, signal) — 抽象缝直接接收 agent;
  2. ctx.sessionFileReferences.list(...) — Remote 适配器从线上 Session 身份解析出 agent。

第二点解释了为什么「界面切了目录,补全没变」:线上身份没变,解析出的 agent 没变,cwd 自然没变。

这也意味着 cwd 不是安全边界之外的附加信息,而是发现逻辑的输入。任何绕过 agent 直接读文件系统的实现,都已经离开了这条链路。

多包仓库里,每个包可能各自开着会话;同一个文件名在不同会话里各自可见,跨包引用就会表现为「另一个包里明明有,却补不出来」。这仍然是边界,不是缓存。

DSH plugin 里三种越界做法为什么不成立

拼路径、递归扫描、前端过滤,都解决不了范围问题。(来源) 对照:

做法表面效果实际问题
前端拼 ../列表里出现上层路径不在发现范围,工具调用失败
让 provider 递归扫全盘候选变多越界、变慢、权限报错
前端过滤隐藏无关文件列表变干净没扩大范围,只是遮住问题

三种做法的共同点是:把「范围」当成展示问题。范围是接口契约,只能通过改变 cwd 来改变。

还有一个隐性代价:越界拿到的路径可能指向用户无权访问的位置,补全时看起来可用,执行时才失败,排查成本更高。

DSH plugin 想换范围的三条正路

换会话、换工作目录、换入口,都是契约内的做法。(来源) 三条:

  1. 切换工作目录 — 把会话 cwd 改到目标目录,重新请求候选;
  2. 新开一个会话 — 在目标目录启动,原会话保持不变;
  3. 使用另一个入口 — 终端与网页各自维护自己的会话上下文,互不替代。

三条路的共同前提是「让 agent 的 cwd 变成你想要的目录」。除此之外没有第四条。

切换之后要重新请求候选,而不是复用切换前的列表;旧列表属于上一个 cwd。

如果产品确实需要跨目录引用,正确设计是提供「切换工作目录」的操作,而不是在补全列表里伪造跨目录路径。

DSH plugin 的 cwd 与 sameWorkspace 怎么配合

一个给范围,一个给判断,别混用。(来源) 分工:

  • cwd 决定「能找到什么」;
  • sameWorkspace 回答「源会话与请求方是否同一目录」,且只在 cwd 已记录且相等时为真。

会话引用场景里,宿主常想标「同项目」。如果拿不到对方的 cwd,就不该自己比较;sameWorkspace 就是为这种「只想要一个区分位」的宿主准备的。

注意它不是权限判断,也不是路径等价判断。两个路径字符串看起来相同,规范化后也可能不同,这类比较不该由前端做。

DSH plugin cwd 边界的自测矩阵

三组对照,能把范围问题与 provider 问题分开。 矩阵:

场景预期
子目录会话搜上层文件无候选
切到上层后同一前缀有候选
同一目录内搜存在的文件有候选,顺序稳定

第一组失败说明边界没生效,第二组失败说明切换没传到 agent,第三组失败才是 provider 或 query 的问题。

测试时不要只看「有没有结果」,还要记录会话启动目录。很多误判来自测试环境本身就在仓库根目录,边界看起来「没生效」。

范围确认之后,下一步是输入解析。读 DSH plugin 文件引用的 query 怎么传;想看多个来源如何合并,读 DSH plugin 多 provider 怎么组合;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的会话开在子目录,为什么补全看不到仓库根目录的文件?

因为发现范围由被寻址 agent 的 cwd 决定,DSH plugin 只在当前工作目录内产生候选。补全看不到根目录文件属于边界内行为,切换会话或工作目录后才会出现。

DSH plugin 里在前端拼 ../ 能不能让补全进入上层目录?

不能,DSH plugin 的候选路径只来自 provider 的发现结果。前端拼出来的路径不在发现范围内,即使显示出来,后续文件系统工具调用也不会接受。

DSH plugin 的 cwd 是前端传的还是服务端记录的,为什么两个目录树不一致?

DSH plugin 的 cwd 属于会话与 agent 的上下文,不是前端目录树的当前选中项。DSH plugin 在 Remote 适配器里从线上 Session 身份解析 agent,因此界面切目录不会改变补全范围。

DSH plugin 的 sameWorkspace 能替代 cwd 比较吗?

DSH plugin 的 sameWorkspace 只回答目录是否相同,不能替代完整路径比较。DSH plugin 的候选允许 cwd 缺失,宿主不该用自己没收到的路径做比较,sameWorkspace 就是为这种场景准备的布尔值。

相关术语

cwd 边界
cwd 边界是文件引用发现的范围上限,由被寻址 agent 的工作目录决定,候选不会越出这个目录。— DeepSeek Harness 官方参考 - 会话引用
agent
agent 是文件引用接口的第一个参数,提供工作目录范围,并决定候选排序的亲和度。— DeepSeek Harness 官方参考 - 会话引用
Session 身份
Session 身份是线上请求携带的会话标识,Remote 适配器据此解析出目标 agent。— session-controller file-references.ts
工作目录切换(working directory switch)
工作目录切换是改变会话 cwd 的操作,切换后文件引用的发现范围随之改变。— DeepSeek Harness 官方参考 - 会话引用

来源