ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 dsh-session URI:规范 mention 的组成、解析与常见拼错

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用URImention
会话引用靠一段 @[label](dsh-session:…) 文本传递,但 label 只是显示,身份在后面。本文拆开 mention 的三段结构、四种常见拼错,以及解析时该在哪一步失败。

在 DSH plugin(DSH插件) 里,一段规范 mention 可以拆成三段:唤起符 @、方括号里的显示 label、圆括号里的 dsh-session: URI。 只有第三段携带身份,前两段都是给人看的;把 label 当身份,是解析失败的头号原因。

DSH plugin 一段 mention 由哪几部分组成

三段结构,缺一不可。(来源) 拆开看:

text
@[修复登录超时](dsh-session:xxxxx)
│ └──────┬──────┘ └────┬─────┘
│        │              └─ URI:携带身份
│        └─ label:给人看的显示文本
└─ 唤起符:标记这是一次提及

三段各自独立:唤起符由你的宿主识别,label 由服务序列化,URI 由解析器读取。

任何一段被改写,整段就可能失效。尤其是 label 里出现 ],会让「到哪里结束」变得不确定。

DSH plugin 里 dsh-session 后面放什么

放会话身份,不放标题、不放路径。(来源) 约定很明确:

  • URI 的 scheme 是 dsh-session:;
  • 后面承载的是被引用会话的身份信息;
  • 具体编码由会话引用约定负责,宿主不参与。

这条边界解释了一个常见误区:有人以为 URI 里放的是「可读标题」,于是手工替换成别的文本,结果解析不到会话。

身份必须稳定,标题会变。把会变的东西放进身份位置,引用就会随改名失效。

DSH plugin 的 label 与 id 角色分工

label 负责可读,id 负责定位。(来源) 对照:

部分是否权威变化影响
label否只影响显示
URI 中的身份是决定读取哪个会话

这个分工带来两个实践结论:

  1. 改标题不需要迁移引用,label 只是显示;
  2. 复制 mention 到别处时,不要为了「看得懂」而改 URI。

第二条尤其重要:手工把 id 换成标题,看起来更像人话,实际引用的目标已经丢了。

DSH plugin mention 的四种常见拼错

四种错误,对应四类症状。(来源) 对照:

拼错症状
少一个 ]整段不被识别为提及
label 含 ] 未转义在第一个 ] 处截断
把 id 当 label显示成乱码,引用仍可能成功
URI 少了 dsh-session:解析为普通链接

第一、二种会直接失败;第三、四种更隐蔽,可能「看起来能用」,直到跨端复制才暴露。

判断方法很简单:把 mention 放进草稿提交,看解析出的 sessionId 是否等于候选 id。

DSH plugin 解析顺序与失败点

先认结构,再取身份,最后才是移除 token。(来源) 顺序:

  1. 识别唤起符与方括号范围;
  2. 从圆括号中取出 URI;
  3. 校验 scheme 是否为 dsh-session:;
  4. 取身份并构造 SessionReferenceInput;
  5. prepare 时从可读内容中移除 token。

失败点集中在第 3、4 步:scheme 不对会当普通链接,身份不合法会拒绝引用。

第 5 步说明 token 不会进入模型正文。用户看到的 mention 与模型收到的内容,是两件事。

DSH plugin 手工解析的测试

四个用例,专挑边界字符。 步骤:

  1. 标题含 ],确认序列化后仍能解析;
  2. 标题含 ( 与 ),确认不会被当成 URI 边界;
  3. 标题为中文与 emoji,确认编码前后一致;
  4. 把 URI 的 scheme 改掉,确认解析失败而不是静默通过。

第 1、2 个用例是「括号地狱」,也是手拼实现最容易翻车的地方。

第 4 个用例验证失败可见性:宁可报错,也不要把它当普通链接悄悄放过去。

语法清楚之后,下一步是手打 mention 的边界。读 DSH plugin 手打的 mention 算不算引用;想看 Remote 候选怎么带 mention,读 DSH plugin 的 Remote candidates 怎么用;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 @[label](dsh-session:…) 里,label 和后面的 id 哪个才是身份?

DSH plugin 的 mention 里,只有 URI 中的 sessionId 才是身份。DSH plugin 把 label 定义为显示元数据,解析与读取都以 sessionId 为准,改 label 不会改变引用目标。

DSH plugin 的会话标题里有方括号,mention 会不会直接坏掉?

手拼会坏,DSH plugin 服务生成的 mention 不会。DSH plugin 的规范 mention 由会话引用约定序列化,label 里的方括号会被安全处理;自己拼字符串才会在第一个 ] 处截断。

DSH plugin 里 mention 和最后的引用输入是一回事吗?

不是一回事,DSH plugin 在 prepare 时会移除 mention token。mention 是草稿里的可读文本,真正的引用是结构化的 SessionReferenceInput;DSH plugin 在 prepare 时会移除 mention token,只按 references 读取会话。

DSH plugin 的 dsh-session URI 能手工构造给后端用吗?

可以手工写出 DSH plugin 的 dsh-session 文本,但不要把它当成唯一输入。DSH plugin 的读取依赖 references 数组里的 sessionId;只给文本、不给结构化引用,通常不会产生上下文。

相关术语

mention
mention 是形如 @[label](dsh-session:…) 的提及文本,由显示标签与规范 URI 两部分组成。— DeepSeek Harness 官方参考 - 会话引用
dsh-session URI
dsh-session URI 是会话引用的规范定位串,携带被引用会话的身份信息。— DeepSeek Harness 官方参考 - 会话引用
sessionId
sessionId 是会话的不透明权威身份,解析与读取都以它为准,label 不参与定位。— DeepSeek Harness 官方参考 - 会话引用
token 移除
token 移除是 prepare 在生成可读内容时去掉宿主 mention token 的步骤,避免模型把标记当正文。— DeepSeek Harness 官方参考 - 会话引用

来源