ChatGPTClaudeGrok / X / CursorGemini

DSH plugin file reference query: spaces and quotes

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessfile referencequerycompletion
Paths with spaces fail for a simple reason: the query is only the text after @ or @". Where it starts, where the cursor ends it, and five test cases.

Most failed file completions are not missing files but a misbuilt query: DSH plugin's list(agent, query, signal) accepts only the path text after @ or @", so the trigger itself, characters after the cursor, and anything past a space must not leak in. Parse the input correctly and most completion complaints disappear.

A DSH plugin completion that never appears

The same file, typed two ways, produces two different outcomes. (source) Scenario:

text
Input A: @my notes.md
Input B: @"my notes.md

Input A is cut at the space, so the query becomes my and my notes.md never matches. Input B starts with @", the whole string enters the query, and the candidate appears.

This is not an implementation quirk; it is the interface definition. The quoted form exists precisely so a space is not a boundary.

What @ and @" actually change in DSH plugin

Only the query start and its termination, never the candidate source. (source) Comparison:

Input formQuery startsSpace handling
@First character after @A space ends the query
@"First character after @"Spaces belong to the query until closing quote or submit

Both forms call the same list, and the candidate shape is identical. The host's only job is to detect which form is active and cut the right substring.

If a host maintains a separate candidate pipeline for the quoted form, the query cut is probably wrong; the form changes the start, not the source.

A detail worth stating: when the user has typed @" but not a closing quote, send everything before the cursor anyway. Waiting for a closing quote means no candidates while typing.

Where a DSH plugin query starts and ends

From just after the trigger to the cursor — no trigger character, no text after the cursor. (source) Three positions matter:

  1. Trigger position — @ or @", used only to classify the form;
  2. Start — the first character after the trigger;
  3. End — the current cursor, not the end of the line.

The cursor is the end because users insert references mid-sentence; text after the cursor is unrelated prose. Treat the whole line as a query and candidates get polluted by that prose.

In practice a host must track selection state continuously instead of parsing at submit time. Completion requests happen during typing, so parsing must happen at the same moment.

Caching parsed queries is risky: moving the cursor produces no text input, so a cache keyed only on text returns the previous query.

Why an empty DSH plugin query is not "all files"

If the page never promises a full listing for an empty query, do not write logic that assumes one. (source) The common mistake: the user types @, the host sends an empty string, and the UI expects a complete file tree.

Three safer rules:

  • Treat the empty-query response as the provider's decision and do not pad it;
  • Cap what you render so a large result cannot freeze the list;
  • If the product wants "recent files", build it as its own capability rather than simulating it with an empty query.

These rules avoid the "typing @ hangs the editor" failure and keep provider details out of the frontend.

A very short debounce is fine for large empty-query results. Substituting a locally cached list is not: it makes the visible scope disagree with the provider.

DeepSeek Harness: Four input shapes, four handling rules

Four kinds of input need four rules; a single regex will not cover them. (source) Comparison:

InputHandling
@srcQuery is src
@"my notesQuery is my notes
@src/Query is src/, keep descending
A stray @ in proseParse only inside a completion context

The last row is the one most often missed: email addresses, decorators in code, and casual mentions all contain @. Decide using cursor position and the preceding character, not by firing a request on every @.

Five test cases for DSH plugin query parsing

Five cases cover spaces, cursor, empty input, false triggers, and cancellation. (source) Steps:

  1. Type @my notes.md and confirm the query is my — the expected failure that proves you understand the space boundary.
  2. Type @"my notes.md and confirm the query is my notes.md.
  3. Move the cursor into the middle of @src/ and confirm the query shortens with it.
  4. Type an email address in normal prose and confirm no candidate request fires.
  5. Type @, delete it immediately, and confirm the old request is cancelled or its result discarded.

Case four guards against a parser that gradually widens over time.

Case five checks the cancellation path; without it, fast typing lets an old response overwrite newer candidates.

Once parsing is right, the next question is scope. To see how cwd bounds completion, read the DSH plugin file reference cwd boundary; to see directory and file transitions, read the two kinds in DSH plugin completion; for the wider picture, read how DSH plugin implements session references.

Sources: DeepSeek Harness reference - Session references, file-reference/src/index.ts

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why can't DSH plugin complete a path that contains a space?

DSH plugin cannot complete it because the query only covers text after @ or @". With the plain @ form, a space ends the query, so the provider only sees the first word. Start with @" to keep the whole path together.

Should a host pass the @ symbol into the DSH plugin query?

A host should not pass the @ symbol into the DSH plugin query. The list interface defines query as the text after @ or @"; the trigger character is not part of the path, and passing it makes the provider treat the symbol as a path segment.

Does an empty DSH plugin query return every file?

An empty DSH plugin query is not a request for every file. Treat an empty query result as the provider's decision, cap what you render, and do not build features on the assumption of a full listing.

Where should the DSH plugin query stop when the cursor sits mid-path?

The DSH plugin query stops at the cursor. The query describes the path text being typed right now; including characters after the cursor shifts candidate scope away from user intent and the completion stops matching.

Related Terms

query
query is the path text parameter of the file reference interface, covering content after the @ or @" trigger and before the cursor.— DeepSeek Harness reference - Session references
quoted form
The quoted form starts with @" so a path containing spaces enters the query as one value instead of being cut at the space.— DeepSeek Harness reference - Session references
trigger character
The trigger character is the @ that opens file completion; it marks the start and is not part of the query.— DeepSeek Harness reference - Session references
truncation boundary
The truncation boundary is where a host cuts the query out of the input text, determined by trigger, cursor, and quote state.— DeepSeek Harness reference - Session references

Sources