DSH plugin 文件引用的 query:@ 与 @" 两种输入形态、空格路径与截断边界
文件补全补不出来,很多不是路径不存在,而是 query 传错了:DSH plugin(DSH插件) 的 list(agent, query, signal) 只接受 @ 或 @" 之后的路径文本,@ 本身、光标后的字符、空格后的内容都不该混进去。 把输入解析对了,补全问题会少一大半。
DSH plugin 从一次补不出来的输入说起
同一个文件,用两种输入方式,结果完全不同。(来源) 场景:
输入 A:@my notes.md
输入 B:@"my notes.md
输入 A 在空格处被切开,query 变成 my,候选里自然找不到 my notes.md。输入 B 用 @" 开头,整个 my notes.md 进入 query,候选才能命中。
这不是实现差异,而是接口定义:query 是「@ 或 @" 之后的路径文本」。引号形态的存在,就是为了让空格不成为边界。
DSH plugin 里 @ 与 @" 的差别在哪
差别只在 query 的起点与结束条件,不在候选本身。(来源) 对照:
| 输入形态 | query 起点 | 空格处理 |
|---|---|---|
@ | @ 之后第一个字符 | 空格视为 query 结束 |
@" | @" 之后第一个字符 | 空格属于 query,直到结束引号或提交 |
两种形态最终都调用同一个 list,候选结构也完全一样。宿主需要做的只是:识别当前处于哪种形态,切出正确的字符串。
如果宿主为引号形态单独写了一套候选逻辑,通常说明 query 切分本身出了问题;形态只影响起点,不影响候选来源。
一个细节:如果用户输入了 @" 但还没输入结束引号,宿主仍应把光标前的全部内容作为 query,而不是等引号闭合才发请求。
DSH plugin 的 query 该从哪里截到哪里
从触发符之后截到光标,不包含触发符,也不包含光标后的内容。(来源) 三个位置要分清:
- 触发符位置 —
@或@",只用来判断形态; - 起点 — 触发符结束后的第一个字符;
- 终点 — 当前光标位置,而不是整行结尾。
为什么终点是光标:用户可能在句子中间插入引用,光标后面还有正文。如果把整行都当 query,候选会被后面的正文污染。
实现上,宿主通常需要保存输入框的选区状态,而不是等提交时再解析。补全请求发生在输入过程中,解析也必须发生在同一时刻。
缓存解析结果要小心:移动光标不会产生字符输入,只按文本内容缓存会返回上一次的 query。
DSH plugin 空 query 为什么不能想当然
页面没有承诺「空 query 返回全部」,宿主就不该按这个假设写逻辑。(来源) 常见误区是:用户刚输入 @,宿主传空字符串,然后期待一个完整文件列表。
更稳妥的做法有三条:
- 把空 query 的返回当作 provider 的决定,不额外补全;
- 对返回数量做展示层限制,避免一次渲染成百上千条;
- 如果产品需要「最近文件」,那是一个独立能力,不要靠空 query 模拟。
这三条能避免「一输入 @ 就卡住」的性能问题,也不会把 provider 的实现细节写死在前端。
空 query 的返回可能很大,宿主可以加一个很短的防抖窗口,但不要用「本地缓存冒充候选」,那会让范围与 provider 不一致。
DSH plugin 输入解析的边界表
四类输入,四套处理,别用一套正则硬套。(来源) 对照:
| 输入 | 处理 |
|---|---|
@src | query 为 src |
@"my notes | query 为 my notes |
@src/ | query 为 src/,继续下钻 |
正文中的 @ | 只有处于补全触发上下文时才解析 |
最后一行最容易被忽略:邮箱、代码里的装饰器、普通文本里的 @ 都可能误触发补全。宿主需要结合光标位置与前置字符判断,而不是见到 @ 就请求候选。
DSH plugin query 的五个测试用例
五个用例覆盖空格、光标、空值与误触发。 步骤:
- 输入
@my notes.md,确认 query 为my(用于验证空格截断); - 输入
@"my notes.md,确认 query 为my notes.md; - 在
@src/中间移动光标,确认 query 随光标缩短; - 在正文里输入邮箱地址,确认不触发候选请求;
- 输入
@后立刻删除,确认旧请求被取消或结果被丢弃。
第 1 个用例是「预期失败」,用来确认你理解了空格边界;第 4 个用例是回归保护,避免解析器越改越宽。
第 5 个用例验证取消路径:没有它,快速输入时旧结果会覆盖新候选。
query 解析对了,下一步是候选范围。想看 cwd 如何限制补全,读 DSH plugin 文件引用的 cwd 边界;想看目录与文件的切换,读 DSH plugin 文件补全的两种 kind;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
常见问题
不一定是文件不存在,问题可能出在 DSH plugin 的 query 截取上。DSH plugin 的 query 是 @ 或 @" 之后的路径文本,空格路径需要用引号形态 @" 开始,否则解析器会在空格处把 query 截断,看起来就像文件不存在。
只传后面的路径文字,不要带 @ 符号;这是 DSH plugin 对 query 的定义。DSH plugin 的 list 接口把 query 定义为 @ 或 @" 之后的文本,@ 本身属于触发符,传进去会让 provider 把符号当成路径的一部分。
页面没有规定空 query 必须返回全部,DSH plugin 也没有承诺这一点。宿主不要把空 query 当成「列出一切」,应按 provider 的实际返回处理,并避免一次渲染过多候选。
query 应该截到光标位置为止,这是 DSH plugin 对输入文本的定义。DSH plugin 的 query 描述的是当前正在输入的路径文本,把光标后的字符也传进去会让候选范围偏离用户意图,补全结果自然对不上。
相关术语
- query
- query 是文件引用接口中的路径文本参数,取触发符 @ 或 @" 之后、光标之前的内容。— DeepSeek Harness 官方参考 - 会话引用
- 引号形态(quoted form)
- 引号形态是以 @" 开始的补全输入,用来让包含空格的路径整体进入 query,而不是在空格处被截断。— DeepSeek Harness 官方参考 - 会话引用
- 触发符(trigger character)
- 触发符是唤起文件补全的 @ 字符,它不属于 query 本身,只用于标记补全开始。— DeepSeek Harness 官方参考 - 会话引用
- 截断边界(truncation boundary)
- 截断边界是宿主从输入框文本中切出 query 的位置,由触发符、光标与引号状态共同决定。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- file-reference/src/index.ts· deepseek-ai