DSH plugin mention anatomy: @, label, dsh-session URI
In DSH plugin, a canonical mention splits into three parts: the @ trigger, the display label in brackets, and the dsh-session: URI in parentheses. Only the third carries identity; the first two are for humans — and treating the label as identity is the number one cause of parse failures.
DeepSeek Harness: Three parts of one mention
Three segments, all required. (source) Breaking it down:
@[Fix login timeout](dsh-session:xxxxx)
│ └────────┬────────┘ └────┬─────┘
│ │ └─ URI: carries identity
│ └─ label: readable text for humans
└─ trigger: marks this as a mention
Each part has a distinct owner: the host recognizes the trigger, the service serializes the label, and the resolver reads the URI.
Rewrite any part and the whole can fail. A ] inside the label, in particular, makes "where does it end" ambiguous.
What goes after dsh-session:
Session identity — not a title, not a path. (source) The contract is clear:
- The URI scheme is
dsh-session:; - What follows identifies the referenced session;
- The precise encoding belongs to the session reference contract, not the host.
This boundary explains a common mistake: assuming the URI holds a readable title and replacing it with friendlier text, after which nothing resolves.
Identity must be stable; titles change. Put something mutable in the identity slot and references break on every rename.
DeepSeek Harness: Label vs identity
The label serves readability; the identity serves lookup. (source) Comparison:
| Part | Authoritative | Effect of change |
|---|---|---|
| label | No | Display only |
| identity in URI | Yes | Decides which session is read |
Two practical conclusions follow:
- Renaming a session requires no reference migration, because the label is display only;
- When copying a mention elsewhere, never edit the URI to make it "more readable".
The second matters most: swapping the id for a title looks friendlier while the reference target is already gone.
DeepSeek Harness: Four common miswrites
Four mistakes, four symptom classes. (source) Comparison:
| Miswrite | Symptom |
|---|---|
Missing ] | The whole thing is not recognized as a mention |
Unescaped ] in the label | Truncated at the first ] |
| An id used as the label | Looks like gibberish, may still resolve |
URI missing dsh-session: | Parsed as an ordinary link |
The first two fail loudly; the last two hide, possibly "working" until someone copies across clients.
The quick check: submit a draft containing the mention and compare the resolved sessionId with the candidate id.
DeepSeek Harness: Parse order and failure points
Recognize structure, then take identity, then remove the token. (source) Order:
- Identify the trigger and the bracket range;
- Extract the URI from the parentheses;
- Validate the
dsh-session:scheme; - Take the identity and build
SessionReferenceInput; - During prepare, remove the token from readable content.
Failures cluster at steps 3 and 4: a wrong scheme becomes an ordinary link, and an invalid identity is rejected.
Step 5 explains why the token never reaches model text. What the user sees and what the model receives are different artifacts.
DeepSeek Harness: Testing boundary characters
Four cases aimed at the awkward characters. Steps:
- Put
]in a title and confirm the serialized form still parses; - Put
(and)in a title and confirm they are not treated as URI boundaries; - Use Chinese and emoji titles and confirm encoding round-trips;
- Change the URI scheme and confirm a visible failure instead of silent success.
Cases 1 and 2 are bracket hell, where hand-built mentions fail most often.
Case 4 checks failure visibility: an error is better than quietly passing the text through as a link.
With the syntax clear, the next topic is hand-typed mentions. Read DSH plugin hand-typed mentions; for remote candidates carrying mentions, read DSH plugin remote candidates; for the wider picture, read how DSH plugin implements session references.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
A DSH plugin mention has three parts: the @ trigger, a bracketed display label, and a parenthesized dsh-session URI. Only the URI carries identity; the first two exist for humans.
The DSH plugin URI carries the identity of the referenced session. Titles and paths do not belong there, because identity must be stable while titles change.
Usually because a DSH plugin URI was replaced with readable text or the scheme was dropped. DSH plugin resolves the identity inside the parentheses; a changed URI no longer points at a session.
It can resolve in DSH plugin while looking unreadable. That failure mode is subtle: it works until someone copies it across clients or edits the label, so always verify the resolved sessionId.
Related Terms
- canonical mention
- A canonical mention is the insertable form @[label](dsh-session:…), with a display label and an identity-bearing URI.— DeepSeek Harness reference - Session references
- trigger
- The trigger is the @ that marks a mention; the host recognizes it and it carries no identity.— DeepSeek Harness reference - Session references
- label
- label is the readable text inside the brackets; it affects display only, never which session is read.— DeepSeek Harness reference - Session references
- scheme
- The scheme is the dsh-session: prefix that identifies the URI as a session reference rather than a normal link.— session-reference/src/types.ts
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai