DSH plugin 的 dsh-session URI:规范 mention 的组成、解析与常见拼错
在 DSH plugin(DSH插件) 里,一段规范 mention 可以拆成三段:唤起符 @、方括号里的显示 label、圆括号里的 dsh-session: URI。 只有第三段携带身份,前两段都是给人看的;把 label 当身份,是解析失败的头号原因。
DSH plugin 一段 mention 由哪几部分组成
三段结构,缺一不可。(来源) 拆开看:
@[修复登录超时](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 中的身份 | 是 | 决定读取哪个会话 |
这个分工带来两个实践结论:
- 改标题不需要迁移引用,label 只是显示;
- 复制 mention 到别处时,不要为了「看得懂」而改 URI。
第二条尤其重要:手工把 id 换成标题,看起来更像人话,实际引用的目标已经丢了。
DSH plugin mention 的四种常见拼错
四种错误,对应四类症状。(来源) 对照:
| 拼错 | 症状 |
|---|---|
少一个 ] | 整段不被识别为提及 |
label 含 ] 未转义 | 在第一个 ] 处截断 |
| 把 id 当 label | 显示成乱码,引用仍可能成功 |
URI 少了 dsh-session: | 解析为普通链接 |
第一、二种会直接失败;第三、四种更隐蔽,可能「看起来能用」,直到跨端复制才暴露。
判断方法很简单:把 mention 放进草稿提交,看解析出的 sessionId 是否等于候选 id。
DSH plugin 解析顺序与失败点
先认结构,再取身份,最后才是移除 token。(来源) 顺序:
- 识别唤起符与方括号范围;
- 从圆括号中取出 URI;
- 校验 scheme 是否为
dsh-session:; - 取身份并构造
SessionReferenceInput; - prepare 时从可读内容中移除 token。
失败点集中在第 3、4 步:scheme 不对会当普通链接,身份不合法会拒绝引用。
第 5 步说明 token 不会进入模型正文。用户看到的 mention 与模型收到的内容,是两件事。
DSH plugin 手工解析的测试
四个用例,专挑边界字符。 步骤:
- 标题含
],确认序列化后仍能解析; - 标题含
(与),确认不会被当成 URI 边界; - 标题为中文与 emoji,确认编码前后一致;
- 把 URI 的 scheme 改掉,确认解析失败而不是静默通过。
第 1、2 个用例是「括号地狱」,也是手拼实现最容易翻车的地方。
第 4 个用例验证失败可见性:宁可报错,也不要把它当普通链接悄悄放过去。
语法清楚之后,下一步是手打 mention 的边界。读 DSH plugin 手打的 mention 算不算引用;想看 Remote 候选怎么带 mention,读 DSH plugin 的 Remote candidates 怎么用;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/types.ts
常见问题
DSH plugin 的 mention 里,只有 URI 中的 sessionId 才是身份。DSH plugin 把 label 定义为显示元数据,解析与读取都以 sessionId 为准,改 label 不会改变引用目标。
手拼会坏,DSH plugin 服务生成的 mention 不会。DSH plugin 的规范 mention 由会话引用约定序列化,label 里的方括号会被安全处理;自己拼字符串才会在第一个 ] 处截断。
不是一回事,DSH plugin 在 prepare 时会移除 mention token。mention 是草稿里的可读文本,真正的引用是结构化的 SessionReferenceInput;DSH plugin 在 prepare 时会移除 mention token,只按 references 读取会话。
可以手工写出 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 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/types.ts· deepseek-ai