DSH plugin 会话引用的 label 转义:方括号、圆括号与标签安全 JSON 怎么处理
会话标题里只要出现一个 ],手拼的 mention 就会在方括号处提前结束:这不是边界情况,而是 label 放在 @[...] 结构里的必然结果。 DSH plugin(DSH插件) 用标签安全的 JSON 序列化解决它,你的宿主要做的是不插手。
DSH plugin 标题里一个方括号让提及失效
先看一段手拼代码的失败现场。(来源) 假设标题是:
修复 [支付] 回调
手拼得到:
@[修复 [支付] 回调](dsh-session:xxxx)
解析器在第一个 ] 就认为 label 结束,后面变成一段无法识别的文本。引用失效,用户只看到输入框里一段奇怪的字符。
问题不在标题「不合法」,而在拼接方式把标题当成了语法的一部分。
DSH plugin 的标签安全 JSON 是什么
它是一层序列化约定,目标只有一个:让任意 label 文本安全进入标签结构。(来源) 官方把它与字节保留并列,作为会话引用约定的组成部分。
它解决的正是分隔符冲突:
| label 内容 | 手拼风险 | 序列化后 |
|---|---|---|
修复 [支付] 回调 | 在 ] 处截断 | 完整保留 |
review (v2) | 圆括号被当 URI 边界 | 完整保留 |
a"b | 引号破坏结构 | 完整保留 |
注意它不是 URL 编码,也不是 HTML 转义。它服务的是 mention 的语法结构,而不是网络传输。
DSH plugin 三层转义分别负责什么
三层各管一段,别混用。(来源) 分工:
- 标签层 — 处理 label 与方括号的冲突;
- URI 层 — 处理身份部分的编码;
- 内容层 — 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]b | mention 结构完整 |
a(b)c | URI 边界不错位 |
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
常见问题
因为 DSH plugin 的 mention 用 @[...] 承载 label,未转义的 ] 会被当成结束符。DSH plugin 的规范文本由服务序列化,方括号会被安全处理;手拼字符串才会截断。
DSH plugin 的标签安全 JSON 目标是在标签结构里安全携带任意文本,避免分隔符冲突。DSH plugin 由会话引用约定负责序列化,宿主不需要自己实现编码规则。
不建议,DSH plugin 的 mention 是已序列化的结果。DSH plugin 的 mention 是已序列化的结果,任何 trim 或替换都可能改变 label 内容;要展示得更好看,应该在渲染层处理,而不是改要插入的文本。
不需要宿主处理,DSH plugin 的序列化会保留这些字符。DSH plugin 的序列化会保留这些字符;宿主按照字节原样插入即可,额外编码反而会让不同端显示不一致。
相关术语
- 标签安全 JSON
- 标签安全 JSON 是会话引用约定中的序列化方式,用来在标签结构内安全携带任意 label 文本。— DeepSeek Harness 官方参考 - 会话引用
- 分隔符冲突(delimiter collision)
- 分隔符冲突是 label 中出现与语法相同的字符(如方括号)导致解析提前结束的问题。— DeepSeek Harness 官方参考 - 会话引用
- 序列化(serialization)
- 序列化是把候选信息转换为可插入草稿的 mention 文本的过程,由服务端完成。— DeepSeek Harness 官方参考 - 会话引用
- 原样插入(verbatim insertion)
- 原样插入是宿主把服务返回的 mention 不做任何改写直接放入草稿的做法。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/types.ts· deepseek-ai