DSH plugin 会话引用归一化:prepare 之前宿主该做什么、哪些内容一定不能动
「引用内容被改写了」这件事,通常发生在调用 prepare 之前:你的宿主把归一化和内容清洗混成一步,把本该保留的字节也处理掉了。 DSH plugin(DSH插件) 的边界很清楚:宿主整理输入,prepare 只删标记,快照按字节保留。
DSH plugin 引用内容跟原文对不上
差异先从宿主的预处理里找,而不是先怀疑服务。(来源) 典型现场:
原会话: const x = 1 // 两个空格
引用后: const x = 1 // 一个空格
如果宿主在提交前做了「合并连续空格」,引用内容就会和原文不同。服务没有改写它,是上游先改了。
判断方法:把同一段内容不经宿主处理直接交给 prepare,比较结果。如果一致,问题在宿主;如果仍不一致,才需要查服务。
DSH plugin 里三个处理阶段
三个阶段各做各的,混在一起就会互相抵消。(来源) 对照:
| 阶段 | 执行者 | 做什么 |
|---|---|---|
| 输入归一化 | 宿主 | 把编辑器内容转成可读内容块 |
| token 移除 | prepare | 删除正文里的 mention 标记 |
| 快照保留 | prepare | 按字节携带被引用内容 |
第一阶段的产出是 content,第二、三阶段发生在 prepare 内部。
很多人把「删标记」也放在第一阶段,结果 prepare 找不到标记,反而无法正确区分正文与引用。
DSH plugin 宿主该归一化的三件事
只处理输入形态,不处理语义。(来源) 三件:
- 编辑器结构 — 把富文本、列表、代码块转成内容块;
- 私有标记 — 去掉仅用于界面展示的占位符,但保留 mention 标记;
- 无效控制字符 — 清理会导致解析失败的控制字符。
第三件要谨慎:只清理确实非法的字符,不要把制表符、换行当成「脏数据」。
一个判断标准:归一化后的内容,应该和用户肉眼看到的意思一致,而不是和排版引擎的内部表示一致。
DSH plugin 宿主不该碰的三件事
三件事都属于「展示优化」,不该进入提交流程。(来源) 对照:
| 动作 | 看似合理 | 实际问题 |
|---|---|---|
| 合并连续空格 | 让内容更整齐 | 改写了代码与排版 |
| 全角转半角 | 统一标点 | 改变了用户原文 |
| 自动补句号 | 让句子完整 | 凭空增加内容 |
这三件事的共同点是「服务端无法区分原文与优化结果」。一旦写进快照,回溯时无法还原。
如果产品需要更整洁的展示,应该在渲染层做,而不是改提交内容。
DSH plugin 归一化与字节保留的边界表
一条边界,三种角色,照表执行即可。(来源) 边界:
| 内容 | 宿主 | prepare |
|---|---|---|
| mention 标记 | 保留 | 移除 |
| 用户正文 | 归一化为内容块 | 原样携带 |
| 被引用会话内容 | 不接触 | 按字节保留 |
这张表能解决绝大多数争议:宿主只碰「自己的输入」,服务只碰「标记与快照」。
越界的典型信号是:宿主代码里出现了对被引用内容的字符串替换。
DSH plugin 归一化差异的范围测试
四个用例,把差异限制在预期范围内。 步骤:
- 含连续空格的消息,确认引用前后空格数一致;
- 含 CRLF 的消息,确认换行未被统一;
- 含全角标点的消息,确认标点未被转换;
- 含 mention 的消息,确认标记被移除而正文完整。
第 1、2 个用例针对最常见的「清理型改写」,第 4 个用例确认 token 移除没有误删正文。
四个都过,说明归一化只作用在输入形态上。
归一化失败时应该拒绝提交,而不是把原始字符串硬塞进 content,让 prepare 去解析一个它无法识别的引用。
边界清楚之后,下一步是预算。读 DSH plugin 会话引用的预算与 64 KiB 回退;想看哪些处理会改写内容,读 DSH plugin 会话引用的字节保留;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/index.ts
常见问题
先查宿主自己的归一化,DSH plugin 只负责移除 mention token。DSH plugin 只负责移除 mention token,其余内容按字节保留;如果宿主提前做了 trim 或全半角转换,差异来自这一层。
因为输入形态因宿主而异,DSH plugin 只接受可读内容块。DSH plugin 只接受可读内容块,富文本、快捷键、粘贴格式需要宿主先整理;服务端不猜测各端编辑器结构。
不能,DSH plugin 的字节保留要求不改写被引用内容。DSH plugin 的字节保留要求不改写被引用内容,连续空格可能属于代码或排版;合并会让引用与原文不一致,也会影响用户对内容的信任。
DSH plugin 允许宿主按产品规则处理用户输入,但不要对引用快照做同样处理。DSH plugin 的边界是:宿主整理自己的输入,服务保持被引用内容原样。
相关术语
- 宿主归一化(host normalization)
- 宿主归一化是宿主把编辑器内容整理成可读内容块的过程,发生在调用 prepare 之前。— session-reference/src/index.ts
- token 移除
- token 移除是 prepare 删除正文中宿主 mention 标记的步骤,只删标记,不改其余文本。— DeepSeek Harness 官方参考 - 会话引用
- 字节保留(byte preservation)
- 字节保留是会话引用约定对被引用内容的约束,除标记外不按展示需要改写原文。— DeepSeek Harness 官方参考 - 会话引用
- 可读内容块(readable content block)
- 可读内容块是去掉编辑器私有标记后、模型与用户都能理解的 ContentBlock 序列。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/index.ts· deepseek-ai