DSH plugin 的 Remote candidates:每个候选为什么自带规范 mention
在 DSH plugin(DSH插件) 里,浏览器端拿不到本地 agent,所以候选必须走 Remote 出口;这个出口返回的每条候选都多带一个 mention,你的前端只负责插入,不负责拼接。 自己拼 mention,是这类接入最常见的返工点。
DSH plugin 浏览器端要插入 @ 提及,mention 从哪来
从候选响应里来,不从会话标题拼。(来源) 一个典型的错误实现:
// 错误:自己拼
const mention = `@[${candidate.label}](dsh-session:${candidate.sessionId})`
这段代码在标题含 ]、(、空格或 emoji 时会坏。正确做法是直接取服务返回的字段:
const mention = candidate.mention
差别不在代码长短,而在「谁负责序列化」。序列化属于会话引用约定,不属于 UI。
DSH plugin 的 candidates 方法返回什么
在候选基础上加一个 mention,其他字段不变。(来源) 结构:
| 字段 | 说明 |
|---|---|
sessionId | 不透明身份 |
label | 标题或 id 回退 |
displayTitle | subagent 创建标签,可选 |
cwd | 工作目录,可选 |
sameWorkspace | 是否与请求方同目录 |
createdAt | 创建时间 |
mention | 规范提及文本,Remote 独有 |
Remote 方法名为 sessionReferenceResolver/candidates,服务的是浏览器这类无法持有本地 agent 的消费方。
注意 mention 在有 displayTitle 时会用 displayTitle 作为标签,所以它不一定等于 label。
DSH plugin 的 mention 为什么必须由服务生成
三个原因:转义、编码、一致性。(来源) 拆开看:
- 转义 — label 位于
@[...]内,方括号与括号都要处理; - 编码 — URI 部分需要按约定编码,手拼容易漏;
- 一致性 — 同一候选在网页、桌面、终端应得到同一段文本。
第三条最容易被低估:不同端各自拼,用户从一端复制到另一端时,解析结果可能不同。
服务端生成把这三件事收在一处,前端只做插入,责任边界清晰。
DSH plugin 的 limit 归谁管
归服务端,前端不要再截断。(来源) 规则:
- Remote 方法应用配置的 candidate limit;
- 返回条数已经受限,前端按原样渲染;
- 需要更少条目时,用 UI 折叠或分页,不要丢弃数据。
重复截断会让两个数字对不上:配置说 20,界面只显示 5,排查时很难判断是谁截的。
如果产品希望「只显示 5 条」,那属于展示策略,应该在渲染层做,并保留完整数据用于「展开更多」。
DSH plugin 从候选到草稿的四步
四步,任何一步都不要改写 mention。(来源) 步骤:
- 用户输入
@,前端调用 Remote candidates; - 渲染候选列表,展示
displayTitle或label; - 用户选中,把
mention原样插入草稿; - 提交时把选中的
sessionId一并作为引用输入传出。
第 3 步的「原样」很重要:不要 trim、不要替换空格、不要重新编码。
第 4 步说明 mention 只是草稿文本,真正的引用身份仍是 sessionId。两者分开,才能既让用户看懂,又让 prepare 准确。
DSH plugin Remote 候选的端到端验证
四个断言,覆盖字段、转义、上限与解析。 步骤:
- 调用 Remote 方法,确认每条候选都有
mention; - 选一个标题含
]的会话,确认 mention 插入后不破坏语法; - 确认返回条数不超过配置上限;
- 把 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
常见问题
不完全一样,DSH plugin 的 Remote 候选多一个 mention 字段。多出的 mention 携带可直接插入提示词草稿的规范文本,其余元数据字段保持一致。
不一样,DSH plugin 的 mention 需要服务端处理转义与编码。DSH plugin 的 mention 需要处理 label 转义、URI 编码与 displayTitle 选择,前端拼容易在特殊字符上出错;服务端生成能保证同一候选在各端得到相同文本。
会,DSH plugin 的 Remote 方法会应用配置的 candidate limit。前端不需要再截断,重复截断反而会让「配置的上限」和「实际显示」对不上。
不建议把原始 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 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/index.ts· deepseek-ai