DSH plugin 文件补全的 file 与 directory:两种 kind 何时保持补全、何时收尾
DSH plugin(DSH插件) 的文件补全其实是一个两态状态机:选中 directory 进入「继续展开」,选中 file 进入「提及收尾」。 你的宿主如果只用字符串判断,就会在目录、尾斜杠和同名文件上反复出错。
DSH plugin 补全状态机只有两态
把候选选择看成状态迁移,比看成「插入一段文本」更准确。(来源) 迁移表:
| 当前状态 | 用户选择 | 下一状态 | 输入框 |
|---|---|---|---|
| 展开 | directory | 展开 | 保留前缀,继续请求候选 |
| 展开 | file | 收尾 | 形成一次完整提及 |
| 收尾 | 任意 | 收尾 | 等待提交或继续输入正文 |
官方对 kind 的注释只有一句:目录保持补全打开,文件结束提及。这句话就是整个状态机的定义,不需要额外规则。
状态机的好处是宿主不必知道文件系统细节。它只回答一个问题:这次选择之后,还要不要继续请求候选。
反过来说,收尾态并不禁止用户继续输入;它只表示这次提及已经完整。用户可以在后面接正文,也可以删掉重来。
DSH plugin 目录候选为什么不能当文件插入
因为目录插入会提前结束提及,用户失去继续下钻的入口。(来源) 典型症状是:输入 @packages 后选中目录,输入框变成 @packages 并关闭列表,用户想找 packages/web 却要重新输入。
正确行为是保留一个可继续的形态,例如 @packages/,然后立刻用新的 query 再请求一次候选。注意这里的分隔符由候选路径提供,宿主不要自己拼。
还有一个容易忽略的点:目录候选的数量通常远少于文件候选。如果列表里目录被文件淹没,用户很难下钻,这属于 provider 排序问题,不该由前端过滤解决。
显示层可以做区分,例如给目录加图标或后缀,但不要改变 path 与 kind 的语义。用户看到的样式和实际插入的字符串是两件事。
DSH plugin 里路径拼接权归谁
路径由候选给出,拼接权在 provider,不在宿主。(来源) 这条规则能避免三类错误:
- 宿主自己补
/,在 Windows 或带空格路径上产生不存在的路径; - 宿主把相对路径改写成绝对路径,导致后续工具调用与候选范围不一致;
- 宿主对路径做 URL 编码,显示正常但解析失败。
path 的定义是「面向用户、且能被正常提示词与文件系统工具接受」,这句话意味着它已经是最终形态。宿主把它原样放进输入框即可。
如果确实需要展示更短的相对路径,那属于纯展示层,应该保留原值作为提交值,不要用展示值替换。
软链接是另一个边界:同一个路径可能指向目录,也可能指向文件。宿主不要自己探测,按候选给出的 kind 处理即可,探测结果未必与发现阶段一致。
DSH plugin 候选的确定性对补全意味着什么
同一 query 必须得到同一顺序,否则列表会在输入过程中抖动。(来源) 确定性的直接收益有三个:
- 用户可以靠位置记忆选中目标,不必每次重新扫列表;
- 宿主可以安全缓存上一次结果,减少重复请求;
- 测试可以断言完整输出,而不是只断言「包含某个路径」。
破坏确定性的常见做法是前端按修改时间、按文件大小或按随机权重重排。这些排序看起来更「智能」,实际会让同一个 query 在两次输入间产生不同顺序。
排序如果需要调整,正确位置是 provider,并且要保证结果仍然确定。
缓存也要有边界:键里必须包含 query 与 agent 的 cwd。少了 cwd,切换工作目录后会命中上一层的旧结果,看起来像「候选不刷新」。
DSH plugin 文件补全的三个坏实现
三个能稳定复现的错误,分别对应状态、路径和排序。(来源) 对照:
| 坏实现 | 现象 | 根因 |
|---|---|---|
只用 path.endsWith('/') 判断目录 | 无斜杠目录被当文件 | 忽略 kind |
选中后自行补 / | 双斜杠或错误分隔符 | 夺走拼接权 |
| 按修改时间重排候选 | 列表顺序每次不同 | 破坏确定性 |
这三个错误都不需要读源码就能复现:连续输入同一前缀两次,比较结果即可。
修复顺序也简单:先认 kind,再停止拼路径,最后去掉二次排序。
DSH plugin 补全的自测步骤
五次操作覆盖状态机的主要分支。 步骤:
- 输入一个存在的目录名,选中后确认列表仍在;
- 在展开态继续输入子目录名,确认候选范围收窄;
- 选中一个文件,确认列表关闭且提及完整;
- 对同一前缀连续请求两次,确认顺序完全一致;
- 切换工作目录后重新输入同一前缀,确认候选范围跟着变。
如果第 1 步就失败,先查 kind 是否被丢弃;如果第 4 步失败,先查有没有二次排序。
第 5 步验的是缓存键,很多「候选不刷新」的投诉都出在这里。
补全只是入口。想看候选为什么只有路径,读 DSH plugin 文件引用候选为什么只有路径;想处理带空格的输入,读 DSH plugin 文件引用的 query 怎么传;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
常见问题
这不是 bug,而是 DSH plugin 的补全契约。DSH plugin 用 kind 区分补全状态:directory 的作用就是保持补全打开,方便继续进入下一层;只有 file 才会让这次提及结束。
DSH plugin 不建议宿主自行探测目录类型。DSH plugin 的候选已经给出 kind,宿主再自行探测会多一次文件系统调用,还可能因为权限或软链接得到相反结论,导致补全状态与候选不一致。
宿主不需要自己补斜杠,DSH plugin 返回的 path 已经是最终形态。DSH plugin 返回的 path 是面向用户、可被普通提示词与文件系统工具接受的路径;宿主只负责插入,不要自行拼接分隔符或改写层级。
这是 DSH plugin 确定性候选的正常表现。DSH plugin 要求同一 query 在同一环境下返回相同集合与顺序,避免列表在用户输入过程中抖动;内容变化会通过新的 query 体现。
相关术语
- kind
- kind 是文件引用候选的类型字段,取值为 file 或 directory,用来决定补全是否继续。— DeepSeek Harness 官方参考 - 会话引用
- 补全状态机(completion state machine)
- 补全状态机是宿主根据用户选择在展开与收尾之间切换的交互模型,directory 进入展开态,file 进入收尾态。— DeepSeek Harness 官方参考 - 会话引用
- 命名空间(namespace)
- 命名空间是 provider 为多个文件来源划分的路径作用域,用来避免同名路径互相覆盖。— DeepSeek Harness 官方参考 - 会话引用
- 确定性(determinism)
- 确定性是同一输入在同一环境下产生相同输出集合与顺序的性质,是文件候选可缓存、可测试的前提。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- file-reference types.ts· deepseek-ai