ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 文件引用的 query:@ 与 @" 两种输入形态、空格路径与截断边界

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness文件引用query补全
文件为空格的路径补不出来,问题常在 query 的截取方式。本文讲 @ 与 @" 两种输入形态、query 从哪里开始、空 query 为什么不能假设返回全部,以及五个可复现的测试用例。

文件补全补不出来,很多不是路径不存在,而是 query 传错了:DSH plugin(DSH插件) 的 list(agent, query, signal) 只接受 @ 或 @" 之后的路径文本,@ 本身、光标后的字符、空格后的内容都不该混进去。 把输入解析对了,补全问题会少一大半。

DSH plugin 从一次补不出来的输入说起

同一个文件,用两种输入方式,结果完全不同。(来源) 场景:

text
输入 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 该从哪里截到哪里

从触发符之后截到光标,不包含触发符,也不包含光标后的内容。(来源) 三个位置要分清:

  1. 触发符位置 — @ 或 @",只用来判断形态;
  2. 起点 — 触发符结束后的第一个字符;
  3. 终点 — 当前光标位置,而不是整行结尾。

为什么终点是光标:用户可能在句子中间插入引用,光标后面还有正文。如果把整行都当 query,候选会被后面的正文污染。

实现上,宿主通常需要保存输入框的选区状态,而不是等提交时再解析。补全请求发生在输入过程中,解析也必须发生在同一时刻。

缓存解析结果要小心:移动光标不会产生字符输入,只按文本内容缓存会返回上一次的 query。

DSH plugin 空 query 为什么不能想当然

页面没有承诺「空 query 返回全部」,宿主就不该按这个假设写逻辑。(来源) 常见误区是:用户刚输入 @,宿主传空字符串,然后期待一个完整文件列表。

更稳妥的做法有三条:

  • 把空 query 的返回当作 provider 的决定,不额外补全;
  • 对返回数量做展示层限制,避免一次渲染成百上千条;
  • 如果产品需要「最近文件」,那是一个独立能力,不要靠空 query 模拟。

这三条能避免「一输入 @ 就卡住」的性能问题,也不会把 provider 的实现细节写死在前端。

空 query 的返回可能很大,宿主可以加一个很短的防抖窗口,但不要用「本地缓存冒充候选」,那会让范围与 provider 不一致。

DSH plugin 输入解析的边界表

四类输入,四套处理,别用一套正则硬套。(来源) 对照:

输入处理
@srcquery 为 src
@"my notesquery 为 my notes
@src/query 为 src/,继续下钻
正文中的 @只有处于补全触发上下文时才解析

最后一行最容易被忽略:邮箱、代码里的装饰器、普通文本里的 @ 都可能误触发补全。宿主需要结合光标位置与前置字符判断,而不是见到 @ 就请求候选。

DSH plugin query 的五个测试用例

五个用例覆盖空格、光标、空值与误触发。 步骤:

  1. 输入 @my notes.md,确认 query 为 my(用于验证空格截断);
  2. 输入 @"my notes.md,确认 query 为 my notes.md;
  3. 在 @src/ 中间移动光标,确认 query 随光标缩短;
  4. 在正文里输入邮箱地址,确认不触发候选请求;
  5. 输入 @ 后立刻删除,确认旧请求被取消或结果被丢弃。

第 1 个用例是「预期失败」,用来确认你理解了空格边界;第 4 个用例是回归保护,避免解析器越改越宽。

第 5 个用例验证取消路径:没有它,快速输入时旧结果会覆盖新候选。

query 解析对了,下一步是候选范围。想看 cwd 如何限制补全,读 DSH plugin 文件引用的 cwd 边界;想看目录与文件的切换,读 DSH plugin 文件补全的两种 kind;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里输入 @ 之后带空格的路径补不出来,是文件不存在吗?

不一定是文件不存在,问题可能出在 DSH plugin 的 query 截取上。DSH plugin 的 query 是 @ 或 @" 之后的路径文本,空格路径需要用引号形态 @" 开始,否则解析器会在空格处把 query 截断,看起来就像文件不存在。

DSH plugin 的 query 要把 @ 符号一起传进去吗,还是只传后面的文字?

只传后面的路径文字,不要带 @ 符号;这是 DSH plugin 对 query 的定义。DSH plugin 的 list 接口把 query 定义为 @ 或 @" 之后的文本,@ 本身属于触发符,传进去会让 provider 把符号当成路径的一部分。

DSH plugin 在 query 为空时会返回全部文件吗?

页面没有规定空 query 必须返回全部,DSH plugin 也没有承诺这一点。宿主不要把空 query 当成「列出一切」,应按 provider 的实际返回处理,并避免一次渲染过多候选。

DSH plugin 里光标停在路径中间时,query 应该截到哪里?

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 官方参考 - 会话引用

来源