DSH plugin file reference query: spaces and quotes
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:
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 form | Query starts | Space 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:
- Trigger position —
@or@", used only to classify the form; - Start — the first character after the trigger;
- 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:
| Input | Handling |
|---|---|
@src | Query is src |
@"my notes | Query is my notes |
@src/ | Query is src/, keep descending |
A stray @ in prose | Parse 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:
- Type
@my notes.mdand confirm the query ismy— the expected failure that proves you understand the space boundary. - Type
@"my notes.mdand confirm the query ismy notes.md. - Move the cursor into the middle of
@src/and confirm the query shortens with it. - Type an email address in normal prose and confirm no candidate request fires.
- 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
FAQ
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.
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.
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.
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
- DeepSeek Harness reference - Session references· deepseek-ai
- file-reference/src/index.ts· deepseek-ai