DSH plugin 怎么完整实现会话引用？URI 类型、候选发现、字节保留与提示词安全边界

会话引用不是“把另一个会话的聊天记录复制过来”，而是一套结构化的跨会话读取：输入用 sessionId 定位，label 只负责显示；候选发现只搜元数据，不读 transcript；prepare 再把被引用会话的日志按预算整理成可读内容与一个聚合的不可信上下文。 这条链路里最容易出错的是“把 label 当身份”和“把引用内容当可信指令”。

DeepSeek Harness：输入与候选

输入的身份与显示要分开：sessionId 权威，label 只是元数据。 两端：（来源）

1. SessionReferenceInput — 宿主选择一个源会话，包含 sessionId 与可选 label。预期：后续读取只认 id。
2. SessionReferenceCandidate — 发现结果，含 sessionId、label、可选 displayTitle、cwd、sameWorkspace 与创建时间。预期：候选本身不含聊天内容。

label 优先使用最新会话标题，没有标题时回退到不透明 id；displayTitle 在存在 subagent 持久创建 label 时优先用它。筛选会同时搜索 label、displayTitle、session id 与 cwd，绝不搜索 transcript。

sameWorkspace 只在 cwd 存在且等于请求方 agent 的 cwd 时为真。它让宿主不必比较自己从未收到的路径。

DeepSeek Harness：mention 格式

规范 mention 是 @[label](dsh-session:…)，由 Remote 候选方法随候选一起返回。 要点：（来源）

• mention 由服务生成 — 宿主不要自己拼接。预期：label 与 URI 编码一致。
• 插入提示词草稿 — 宿主把 mention 放进输入框。预期：用户看到可读 label，解析时拿到 id。
• prepare 时移除 token — 可读内容会去掉 mention token，再单独生成附加上下文。预期：模型不会把 token 当正文。

如果宿主自己拼 dsh-session: 字符串，很容易在 label 含括号或特殊字符时解析失败；用服务返回的 mention 最稳。

DeepSeek Harness：prepare 之后得到什么

prepare 返回两部分：可读内容与最多一个聚合的不可信上下文。 结构：（来源）

持久 source 记录会保存每个引用：sessionId、label、来源格式版本、capturedThroughSeq、是否压缩、原始/保留/省略消息数、省略字节、是否截断与输入顺序。

capturedThroughSeq 是“被引用会话原始 generation 中的坐标”，不会被重新解释为当前会话的 seq。跨会话拼接时，这一点决定你能不能正确回溯。

DeepSeek Harness：预算与截断

引用不是无限量读取；预算与截断是契约的一部分。 规则：（来源）

1. 自动预算 — 使用最后组装的 route；尚未组装时使用 agent options。预期：与会话实际模型能力匹配。
2. 缺少容量或 adapter — 按 64 KiB 处理。预期：不会因为元数据缺失而无限读取。
3. 截断 — 返回省略事实与完整快照的 spill 定位符，或明确不可用提示。预期：调用方知道内容不完整。
4. 取消 — 取消后不再发布上下文，即使存储随后完成。预期：不会出现“取消了但又写进上下文”。

其他元数据查询失败与取消会拒绝 prepare；不要把失败当成空引用继续。

DeepSeek Harness：七个错误码

错误码是稳定契约，宿主应按码分支，而不是解析提示词。 七个：（来源）

• SESSION_REFERENCE_INVALID_CONFIG — 配置无效。
• SESSION_REFERENCE_INVALID_REFERENCE — 引用格式或内容无效。
• SESSION_REFERENCE_SELF_REFERENCE — 引用了自己。
• SESSION_REFERENCE_TOO_MANY — 超过数量限制。
• SESSION_REFERENCE_READ_FAILED — 源会话读取失败。
• SESSION_REFERENCE_BUDGET_EXCEEDED — 超出预算。
• SESSION_REFERENCE_CANCELLED — 调用被取消。

宿主协议会把这些 code 映射到自己的错误封装，不需要检查提示词字节。

错误码之外，还要看 prepare 是否发布了 additionalContext；上下文不存在不等于失败，可能只是这次没有引用内容。

DeepSeek Harness：三种使用方式

宿主提及、resolver API、直接构造输入，三种方式覆盖不同层。 三种：（来源）

1. 宿主 mention — 用候选返回的 mention 插入草稿。预期：用户体验最好，解析交给 prepare。
2. resolver.listCandidates — 自己做搜索与排序，按 cwd 亲和度取候选。预期：适合自定义 UI。
3. 直接构造 SessionReferenceInput — 已知 sessionId 时直接引用。预期：适合自动化与测试。

无论哪种，最终都要走 prepare，才能得到可读内容与附加上下文。

mention 与 prepare 的字段对照

把“选择输入”和“准备结果”分开看，能避免把 label 当身份。 对照：

持久 source 还会记录 capturedThroughSeq、格式版本、省略消息数与字节。它不是当前会话的 seq，跨会话回溯时不要混用。

DeepSeek Harness 常见问题

Q：会话引用会把被引用会话的全部历史都带进来吗？ 不会。prepare 受预算约束，可能压缩、截断或省略；返回值会带省略事实与定位符。

Q：能不能引用正在运行的会话？ 可以，但读取的是快照坐标；运行中的后续消息不会自动追加到这次引用。

Q：引用内容为什么标为不可信？ 它来自另一个会话的日志，可能包含用户输入或工具输出；作为附加上下文时必须按不可信数据处理，不能当系统指令。

一句话收束： 会话引用的关键是“id 定位、元数据发现、预算读取、不可信上下文”；把 label 当身份或把内容当指令，都会越界。