ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 Remote candidates:每个候选为什么自带规范 mention

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用Remotemention
浏览器不能直接构造 agent,只能走 Remote 出口。本文讲 sessionReferenceResolver/candidates 返回的候选为什么多一个 mention 字段、它由谁序列化、limit 归谁管,以及从候选到草稿的四步。

在 DSH plugin(DSH插件) 里,浏览器端拿不到本地 agent,所以候选必须走 Remote 出口;这个出口返回的每条候选都多带一个 mention,你的前端只负责插入,不负责拼接。 自己拼 mention,是这类接入最常见的返工点。

DSH plugin 浏览器端要插入 @ 提及,mention 从哪来

从候选响应里来,不从会话标题拼。(来源) 一个典型的错误实现:

ts
// 错误:自己拼
const mention = `@[${candidate.label}](dsh-session:${candidate.sessionId})`

这段代码在标题含 ]、(、空格或 emoji 时会坏。正确做法是直接取服务返回的字段:

ts
const mention = candidate.mention

差别不在代码长短,而在「谁负责序列化」。序列化属于会话引用约定,不属于 UI。

DSH plugin 的 candidates 方法返回什么

在候选基础上加一个 mention,其他字段不变。(来源) 结构:

字段说明
sessionId不透明身份
label标题或 id 回退
displayTitlesubagent 创建标签,可选
cwd工作目录,可选
sameWorkspace是否与请求方同目录
createdAt创建时间
mention规范提及文本,Remote 独有

Remote 方法名为 sessionReferenceResolver/candidates,服务的是浏览器这类无法持有本地 agent 的消费方。

注意 mention 在有 displayTitle 时会用 displayTitle 作为标签,所以它不一定等于 label。

DSH plugin 的 mention 为什么必须由服务生成

三个原因:转义、编码、一致性。(来源) 拆开看:

  1. 转义 — label 位于 @[...] 内,方括号与括号都要处理;
  2. 编码 — URI 部分需要按约定编码,手拼容易漏;
  3. 一致性 — 同一候选在网页、桌面、终端应得到同一段文本。

第三条最容易被低估:不同端各自拼,用户从一端复制到另一端时,解析结果可能不同。

服务端生成把这三件事收在一处,前端只做插入,责任边界清晰。

DSH plugin 的 limit 归谁管

归服务端,前端不要再截断。(来源) 规则:

  • Remote 方法应用配置的 candidate limit;
  • 返回条数已经受限,前端按原样渲染;
  • 需要更少条目时,用 UI 折叠或分页,不要丢弃数据。

重复截断会让两个数字对不上:配置说 20,界面只显示 5,排查时很难判断是谁截的。

如果产品希望「只显示 5 条」,那属于展示策略,应该在渲染层做,并保留完整数据用于「展开更多」。

DSH plugin 从候选到草稿的四步

四步,任何一步都不要改写 mention。(来源) 步骤:

  1. 用户输入 @,前端调用 Remote candidates;
  2. 渲染候选列表,展示 displayTitle 或 label;
  3. 用户选中,把 mention 原样插入草稿;
  4. 提交时把选中的 sessionId 一并作为引用输入传出。

第 3 步的「原样」很重要:不要 trim、不要替换空格、不要重新编码。

第 4 步说明 mention 只是草稿文本,真正的引用身份仍是 sessionId。两者分开,才能既让用户看懂,又让 prepare 准确。

DSH plugin Remote 候选的端到端验证

四个断言,覆盖字段、转义、上限与解析。 步骤:

  1. 调用 Remote 方法,确认每条候选都有 mention;
  2. 选一个标题含 ] 的会话,确认 mention 插入后不破坏语法;
  3. 确认返回条数不超过配置上限;
  4. 把 mention 放进草稿提交,确认 prepare 解析出的 sessionId 与候选一致。

第 4 步是闭环断言:前面三步都通过,但解析出的 id 不对,说明前端在某处改写了文本。

Remote 出口打通后,下一步是理解 mention 的语法细节。读 DSH plugin 的 dsh-session URI 怎么解析;想看 label 特殊字符怎么处理,读 DSH plugin 会话引用的 label 转义;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 Remote candidates 和本地 listCandidates 返回的字段一样吗?

不完全一样,DSH plugin 的 Remote 候选多一个 mention 字段。多出的 mention 携带可直接插入提示词草稿的规范文本,其余元数据字段保持一致。

DSH plugin 的 mention 为什么要服务端生成,前端拼不一样吗?

不一样,DSH plugin 的 mention 需要服务端处理转义与编码。DSH plugin 的 mention 需要处理 label 转义、URI 编码与 displayTitle 选择,前端拼容易在特殊字符上出错;服务端生成能保证同一候选在各端得到相同文本。

DSH plugin 的 Remote candidates 会自己截断吗,前端还需要再限制条数吗?

会,DSH plugin 的 Remote 方法会应用配置的 candidate limit。前端不需要再截断,重复截断反而会让「配置的上限」和「实际显示」对不上。

DSH plugin 候选里的 mention 能直接显示给用户吗?

不建议把原始 mention 当展示文本,DSH plugin 的 mention 是插入用的序列化结果。DSH plugin 的 mention 是插入草稿用的序列化结果,界面应显示 label 或 displayTitle,把 mention 留在输入框内部。

相关术语

SessionReferenceMentionCandidate
SessionReferenceMentionCandidate 是带规范 mention 的会话候选,用于浏览器等 Remote 消费方直接插入提及文本。— DeepSeek Harness 官方参考 - 会话引用
Remote 方法
Remote 方法是暴露给远端消费方的接口,DSH plugin 用 candidates 方法提供带 mention 的候选。— session-reference/src/index.ts
mention
mention 是形如 @[label](dsh-session:…) 的规范提及文本,由服务端序列化后随候选返回。— DeepSeek Harness 官方参考 - 会话引用
草稿(draft)
草稿是用户正在编辑、尚未提交的提示词内容,mention 插入其中,提交后再由 prepare 解析。— DeepSeek Harness 官方参考 - 会话引用

来源