ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 会话引用的 label 转义:方括号、圆括号与标签安全 JSON 怎么处理

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用转义label
会话标题里出现方括号、圆括号、引号或 emoji 时,mention 很容易被截断。本文讲标签安全 JSON 负责什么、三层转义怎么分工,以及宿主最常犯的两个改写动作。

会话标题里只要出现一个 ],手拼的 mention 就会在方括号处提前结束:这不是边界情况,而是 label 放在 @[...] 结构里的必然结果。 DSH plugin(DSH插件) 用标签安全的 JSON 序列化解决它,你的宿主要做的是不插手。

DSH plugin 标题里一个方括号让提及失效

先看一段手拼代码的失败现场。(来源) 假设标题是:

text
修复 [支付] 回调

手拼得到:

text
@[修复 [支付] 回调](dsh-session:xxxx)

解析器在第一个 ] 就认为 label 结束,后面变成一段无法识别的文本。引用失效,用户只看到输入框里一段奇怪的字符。

问题不在标题「不合法」,而在拼接方式把标题当成了语法的一部分。

DSH plugin 的标签安全 JSON 是什么

它是一层序列化约定,目标只有一个:让任意 label 文本安全进入标签结构。(来源) 官方把它与字节保留并列,作为会话引用约定的组成部分。

它解决的正是分隔符冲突:

label 内容手拼风险序列化后
修复 [支付] 回调在 ] 处截断完整保留
review (v2)圆括号被当 URI 边界完整保留
a"b引号破坏结构完整保留

注意它不是 URL 编码,也不是 HTML 转义。它服务的是 mention 的语法结构,而不是网络传输。

DSH plugin 三层转义分别负责什么

三层各管一段,别混用。(来源) 分工:

  1. 标签层 — 处理 label 与方括号的冲突;
  2. URI 层 — 处理身份部分的编码;
  3. 内容层 — prepare 移除 token,不改写其余字节。

宿主通常只接触第 1 层的结果,也就是候选里那段现成的 mention。第 2、3 层都在服务内部完成。

理解这三层的好处是:出问题时能判断该找谁。label 显示错,找序列化;引用定位错,找 URI;正文被改写,找内容层。

DSH plugin 宿主最常犯的两个改写

trim 与替换,两个看起来无害的动作。(来源) 对照:

动作目的后果
mention.trim()去掉首尾空白label 内容变化,跨端显示不一致
把 ] 替换成全角让显示更好看与解析器期望的字符不一致

这两个动作的共同点是「以展示为目的改数据」。展示应该发生在渲染层:把 label 单独取出来显示,而不是改 mention。

如果确实需要更短的显示,用 displayTitle 或 label 渲染列表,mention 只在插入时使用。

DSH plugin 转义与字节保留的关系

一个管结构,一个管内容,目标都是「不改原意」。(来源) 关系:

  • 标签安全 JSON 保证 label 不破坏 mention 结构;
  • 字节保留保证 prepare 不改写被引用内容的其余部分;
  • 两者都不允许宿主插入自己的编码规则。

所以「先 normalize 再插入」这类做法是双重违规:既可能破坏结构,也可能改变字节。

正确的边界是:服务负责序列化与读取,宿主负责原样搬运与展示。

DSH plugin 特殊字符的测试矩阵

六类字符,一次跑完。 矩阵:

标题内容预期
a]bmention 结构完整
a(b)cURI 边界不错位
a"b'c引号不影响解析
中文标题原样保留
emoji 标题原样保留
前后带空格空格保留,不被 trim

最后一行最容易被忽略:空格属于 label 的一部分,去掉它等于改了用户的标题。

测试时不要只断言「能解析」,还要断言「解析出的 sessionId 与候选一致」。

转义搞定后,下一步是手打 mention 的边界。读 DSH plugin 手打的 mention 算不算引用;想看 URI 结构,读 DSH plugin 的 dsh-session URI 怎么解析;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的会话标题里有方括号,为什么引用会直接失效?

因为 DSH plugin 的 mention 用 @[...] 承载 label,未转义的 ] 会被当成结束符。DSH plugin 的规范文本由服务序列化,方括号会被安全处理;手拼字符串才会截断。

DSH plugin 的标签安全 JSON 是把 label 整个编码成 JSON 字符串吗?

DSH plugin 的标签安全 JSON 目标是在标签结构里安全携带任意文本,避免分隔符冲突。DSH plugin 由会话引用约定负责序列化,宿主不需要自己实现编码规则。

DSH plugin 里宿主插入 mention 前能先去掉首尾空格吗?

不建议,DSH plugin 的 mention 是已序列化的结果。DSH plugin 的 mention 是已序列化的结果,任何 trim 或替换都可能改变 label 内容;要展示得更好看,应该在渲染层处理,而不是改要插入的文本。

DSH plugin 的 label 里有 emoji 或中文,需要额外转义吗?

不需要宿主处理,DSH plugin 的序列化会保留这些字符。DSH plugin 的序列化会保留这些字符;宿主按照字节原样插入即可,额外编码反而会让不同端显示不一致。

相关术语

标签安全 JSON
标签安全 JSON 是会话引用约定中的序列化方式,用来在标签结构内安全携带任意 label 文本。— DeepSeek Harness 官方参考 - 会话引用
分隔符冲突(delimiter collision)
分隔符冲突是 label 中出现与语法相同的字符(如方括号)导致解析提前结束的问题。— DeepSeek Harness 官方参考 - 会话引用
序列化(serialization)
序列化是把候选信息转换为可插入草稿的 mention 文本的过程,由服务端完成。— DeepSeek Harness 官方参考 - 会话引用
原样插入(verbatim insertion)
原样插入是宿主把服务返回的 mention 不做任何改写直接放入草稿的做法。— DeepSeek Harness 官方参考 - 会话引用

来源