ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 手打的 mention 算不算引用:正文文本与结构化输入的分界线到底在哪

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用mention结构化输入
从别处复制一段 @[label](dsh-session:…) 到输入框,发出去却没有带上上下文。本文讲 references 为什么是独立输入、prepare 只移除 token 而不按正文找会话,以及宿主该不该解析手打文本。

正文里出现一段 @[label](dsh-session:…),不等于这次消息引用了那个会话:DSH plugin(DSH插件) 只读 references 数组里的 sessionId,正文中的 mention 只是可读文本。 把「文本正确」当成「引用成立」,是复制粘贴场景最常见的误判。

DSH plugin 复制一段 mention 为什么没生效

因为复制的是显示层文本,不是选择结果。(来源) 现场:

text
用户从文档里复制:@[修复登录超时](dsh-session:abc123)
粘贴进输入框,发送
结果:消息正常发出,但没有带入被引用会话的内容

用户预期「文本里有引用,应该读到了」,实际链路里缺了最关键的一步:这个会话没有进入 references。

文本是给人看的,引用是给程序读的。两者可以同时存在,但不能互相替代。

DSH plugin 的 references 是独立输入

它是 prepare 的入参,不是从正文派生的。(来源) 结构上:

输入形态作用
content可读内容块用户实际说的话
references结构化数组要读取哪些会话
signal取消边界本次 turn 是否还有效

references 的每一项是 SessionReferenceInput,含权威 sessionId 与可选 label。

这三者分开传入,意味着「正文写了什么」和「读了哪些会话」是两件独立的事。

DSH plugin prepare 只移除 token,不反向找会话

它做的是减法,不是解析。(来源) 官方对 content 的描述是「移除宿主 mention token 后的可读内容」。

也就是说:

  • prepare 会把正文里的 mention 标记删掉;
  • 删掉之后不会拿这些字符去查会话;
  • 需要读取的会话全部来自 references。

这条设计避免了「正文即指令」的风险:模型看到的正文干净,读取范围由结构化输入决定。

如果你期待 prepare 兜底解析,会看到「文本被移除了,但上下文没来」的现象。

DSH plugin 宿主处理手打文本的两种选择

要么解析成选择,要么明确不支持,不要含糊。(来源) 两种做法:

  1. 提交前解析 — 识别输入框里的 mention,转成 SessionReferenceInput 放进 references,再调用 prepare;
  2. 不支持 — 把手打 mention 当普通文本,界面提示「请从候选列表选择会话」。

第一种体验好,但要求宿主自己实现解析、校验与去重;第二种简单,但用户会困惑「为什么我粘的不能用」。

无论选哪种,都不要「只在界面上高亮、不放进 references」。那会让用户以为引用生效了。

折中做法也值得考虑:允许粘贴,但粘贴后立即转成可见的引用芯片,同时写入 references。用户的操作习惯没变,结构化输入也保住了。

DSH plugin 这条边界的安全意义

显式选择让「读了什么」可审计。(来源) 三个好处:

  1. 用户知道自己选了哪个会话,而不是被一段文本带着走;
  2. 权限检查可以发生在选择时,而不是解析文本后;
  3. 日志里记录的是 sessionId 列表,不是一段可能被伪造的字符串。

第三点尤其重要:文本可以复制、改写、拼接;结构化输入不会。

所以「手打也能生效」不是便利功能,而是把可信边界从选择动作挪到了任意文本上。

DSH plugin 手打 mention 的验证

三步确认文本与引用确实分离。 步骤:

  1. 正文只放 mention,references 传空,确认没有 additionalContext;
  2. 正文放纯文本,references 传一个会话,确认上下文存在;
  3. 正文放 mention,references 也传同一会话,确认上下文只出现一次。

第 1 步证明文本不触发读取;第 2 步证明读取只看 references;第 3 步确认没有重复聚合。

三步都过,说明你的实现没有把两条链路混在一起。

验证时别只看界面上有没有芯片,要打开请求体确认 references 里有 sessionId;芯片可能只是视觉装饰,真正的引用在结构化字段里。

把 mention 当普通文本保存还有一个副作用:导入导出时它会污染正文,之后若再由宿主解析,等于开了一个后门。

A 清单到这里结束。下一步进入准备与治理:读 DSH plugin 的 prepare 输入输出契约;想先看候选怎么带 mention,读 DSH plugin 的 Remote candidates 怎么用;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 里把别处的 @[label](dsh-session:…) 复制到输入框,为什么引用没生效?

因为正文里的文本不等于引用输入,DSH plugin 不会把它当成引用。DSH plugin 的引用来自 references 数组里的结构化 sessionId,复制进来的只是一段字符,不会自动变成引用。

DSH plugin 的 prepare 会从正文里识别 mention 并读取对应会话吗?

不会,DSH plugin 的 prepare 只按 references 读取。它还会移除正文中的宿主 mention token,但不会反向解析正文里的字符串去找会话。

DSH plugin 里宿主应该主动解析用户手打的 mention 吗?

DSH plugin 不要求宿主解析手打 mention,要支持就得先转成结构化引用。DSH plugin 不要求宿主解析,直接提交纯文本时不会产生上下文;支不支持取决于产品,不应假设核心会兜底。

DSH plugin 里如果手打 mention 也能生效,会不会有安全风险?

会有边界问题,DSH plugin 把引用定义为显式选择。DSH plugin 把引用定义为显式选择;如果任意文本都能触发读取,用户输入或粘贴内容就可能诱导读取未选择的会话。

相关术语

references
references 是 prepare 接收的结构化引用数组,每项含权威 sessionId 与可选 label,决定读取哪些会话。— DeepSeek Harness 官方参考 - 会话引用
正文文本(body text)
正文文本是用户输入框中的可读内容,mention 只是其中一段字符,不构成读取依据。— DeepSeek Harness 官方参考 - 会话引用
token 移除
token 移除是 prepare 从可读内容中删除宿主 mention 标记的步骤,删除后正文不再包含引用语法。— DeepSeek Harness 官方参考 - 会话引用
显式选择(explicit selection)
显式选择是用户通过候选列表明确选中某个会话的动作,产生结构化引用,而不是靠文本推断。— DeepSeek Harness 官方参考 - 会话引用

来源