轮次记忆压缩vilicvane/dsh-plugin-turn-memory

dsh-plugin-turn-memory

目标为 DSH 0.1.5-rc.2，使用 Session.snapshotEvents() 读取历史记录，
并使用经过验证的 SessionSeq 值作为压缩范围。

当前活跃的实现正在根据 design.md 中研究得出的约定进行重建。
先前的实现保留在 obsolete/ 下，仅供调查之用。

该插件现在有两个协同工作的层：

- 已完成轮次的压缩使用父级 fork，并落地一次 N→M 的转录重写；
- 可选的长思考预处理会在每个完整的长推理块到达时立即启动异步小模型回忆提示，然后将成功的提示交给正常的主模型轮次工作器，而不替换其原始父级上下文；
- 长根轮次会收到一条模型可见的交接提醒，并可在其已完成轮次压缩落地后于新轮次中继续；
- 可选的根会话压缩提供 ctx.compaction，通过顺序的主模型工作器处理选定的已完成历史范围，并且仅在宿主拥有的工作草稿完成后才提交一个标准的持久检查点。
- 压缩后的图像块可以变为持久的  文本引用；read_memory_image 会按需重新加载原始像素，而不是将它们放入之后的每一次模型请求中。
- 当压缩记忆遗漏了某个代价高昂的细节时，read_session_history 可以恢复某个已完成轮次原始的仅追加用户、助手、推理和工具结果节点。

主插件默认保持禁用状态。当插件启用时，已完成轮次压缩默认开启，除非设置 turnCompression: false。会话压缩则通过 sessionCompaction.enabled: true 单独选择启用。

观察到的已完成用户对话轮次会收到一个持久的待处理标记，并在代理冷恢复后一直保留，直到其最终落地存在为止。该插件不会仅仅因为安装后打开了旧会话就回填无标记的历史记录。UI 创建的谱系分叉属于用户对话，会正常参与；内部子代理则不会。一个遗留的 turn-memory 空操作，若其当前表面仍包含原始推理，也会被迁移一次。

安装

从 GitHub 将包添加到 DSH 配置文件：

dsh plugin --profile web add github:vilicvane/dsh-plugin-turn-memory

对于本地开发，改为链接工作树：

dsh plugin --profile web add link:/path/to/dsh-plugin-turn-memory

然后在配置文件的 cordis.patch.yml 中注册该插件。对于 web 配置文件，这通常是 $DSH_HOME/profiles/web/cordis.patch.yml。在安装包或更改配置文件配置后，重启 dsh web。

配置

仅已完成轮次压缩

此模式不触碰配置文件现有的整会话压缩后端：

- insert:
- id: turn-memory
name: dsh-plugin-turn-memory
config:
enabled: true
turnCompression: true
turnContinuation:
enabled: true
reminderIntervalNodes: 30
thoughtHints:
enabled: true
provider: ollama
model: your-small-model-id
minimumChars: 16000
maxTokens: 1024
timeoutMs: 120000
sessionHistory:
enabled: true
maxReadChars: 160000
catalogTurns: 40

已完成轮次和整个会话的压缩

只有一个插件可以提供 ctx.compaction。在启用此层之前，请禁用 compaction-basic，并移除或禁用任何其他会话压缩提供程序。当 Web 配置文件已禁用 command-compact 时，请重新启用它；其 /compact 命令将调用 turn-memory 的引擎。
yaml
- id: compaction-basic
disabled: true

- id: command-compact
disabled: false

- insert:
- id: turn-memory
name: dsh-plugin-turn-memory
config:
enabled: true
turnCompression: true
sessionCompaction:
enabled: true
auto: true
thresholdRatio: 0.8
retainRatio: 0.16
segmentTokens: 32000
workerAttempts: 2

在同一配置中设置 turnCompression: false 以仅使用整个会话层。设置 sessionCompaction.auto: false 以禁用压力触发，同时保持手动 /compact 可用。

主要调优选项如下：

| 键 | 默认值 | 含义 |
| --- | ---: | --- |
| enabled | false | 启用该插件。 |
| turnCompression | true | 使用主模型 fork 压缩每个已完成的根会话轮次，然后在需要时使用全新的同模型恢复工作程序。 |
| turnWorkerAttempts | 3 | 在没有被接受的替代项的情况下，允许连续失败的工作程序数量。每次成功替换都会重置此预算。 |
| turnContinuation.enabled | true | 允许一个较长的根轮次显式交接、结束、压缩，并作为新轮次恢复。 |
| turnContinuation.reminderIntervalNodes | 30 | 用于一次性继续提醒的开放轮次表面节点间隔：30、60、90，依此类推。 |
| thoughtHints.enabled | false | 在正常轮次压缩之前，使用配置的辅助模型预处理完整的长推理块。 |
| thoughtHints.provider | 启用时必需 | 辅助一次性请求的提供程序路由。 |
| thoughtHints.model | 启用时必需 | 辅助一次性请求的模型 ID。 |
| thoughtHints.minimumChars | 16000 | 启动提示请求所需的最小原始推理块字符数。 |
| thoughtHints.maxTokens | 1024 | 一个紧凑召回索引响应的最大输出 token 数。 |
| thoughtHints.timeoutMs | 120000 | 每个块的辅助请求超时；超时会降级为无提示。 |
| sessionHistory.enabled | true | 在调用会话的仅追加已完成轮次上公开只读的 read_session_history 回退。 |
| sessionHistory.maxReadChars | 160000 | 每次读取返回的原始轮次字符数上限；更大的轮次通过 offset 分页。 |
| sessionHistory.catalogTurns | 40 | 当省略 turn 时，默认列出的最近已完成轮次数量。 |
| previewChars | 120 | 轮次目录中每个节点显示的字符数。 |
| maxReadChars | 30000 | 一次轮次节点读取返回的最大文本量。 |
| surfaceDumpDir | 插件 .tmp/ | 接收每个会话最新折叠表面快照的目录。 |
| sessionCompaction.enabled | false | 将轮次记忆注册为配置文件的 ctx.compaction 提供程序。 |
| sessionCompaction.auto | true | 在令牌压力下启用自动压缩。 |
| sessionCompaction.thresholdRatio | 0.8 | 自动压缩启动时的上下文窗口比率。 |
| sessionCompaction.retainRatio | 0.16 | 保留在所选压缩范围之外的最新历史的大致份额。 |
| sessionCompaction.retainTokens | 未设置 | retainRatio 的绝对替代项；不要同时设置两者。 |
| sessionCompaction.segmentTokens | 32000 | 分配给每个顺序工作线程的大致源令牌预算。 |
| sessionCompaction.workerAttempts | 2 | 每个分段允许的连续失败工作线程数，且未产生被接受的修订。每次成功替换都会重置此预算。 |
| sessionCompaction.workerMaxTokens | 8192 | 每个会话工作线程的输出令牌限制。 |
| sessionCompaction.workerTimeoutMs | 300000 | 每次工作线程尝试的超时时间。 |
| sessionCompaction.compactionRetries | 1 | 当成功的检查点仍使表面高于 thresholdRatio 时，允许的额外压力压缩遍数。 |

每个会话分段首先通过 fork 使用父级的提供程序/模型。如果它在没有权威完成的情况下停止，继续工作线程会通过全新的 spawn 使用相同的主模型，并将分配的规范源和被接受的宿主拥有的修订嵌入提示中。提供程序错误、超时、达到最大令牌停止或缺少完成，仅当该工作线程未产生被接受的修订时才消耗预算。轮次、会话和思维提示提示文件会为每个新请求读取，因此编辑提示不需要重启 Web。

当启用思维提示时，每个根会话 assistant/chunk 推理 block-end 在达到或超过 minimumChars 时，会立即启动独立的 ctx.llm.stream() 调用。模型只看到固定的 prompts/thought-hints.md 系统提示，后跟一条包含原始推理块的用户消息。多个块可能并发运行。在持久 turn/end 时，压缩会等待属于该轮次当前表面上实际存在的助手消息的调用；冷恢复会从那些持久推理块重新生成缺失的调用。失败或空的提示会被省略，并且永远不会阻塞压缩，因为父级 fork 仍然继承完整的原始推理。提示仅作为建议性回忆索引，永远不会作为转录节点持久化，并且每个携带推理的原始助手节点在落地前仍必须被重写。
在根轮次每达到 turnContinuation.reminderIntervalNodes 的整数倍时，其动态运行时上下文会向模型给出一条简短直接的动作通知，要求其停止、准备交接，并调用 continue_after_turn_compression。该通知和自动后续使用普通文本，不带 XML 包装标签；结构化标签仅保留在压缩协议需要显式数据边界或持久引用之处。该通知保持为插件上下文，而不是伪造的持久助手消息。只有当整个任务将在接下来几个动作内完成时，模型才可以继续当前轮次；进行中的原子变更会在交接前完成。计数器包括开放轮次中追加来源的模型可见消息，并排除可替换的运行时快照。该通知包括当前节点数、整个规范上下文的估计 token 大小，以及下一个提醒里程碑。持久运行时快照会记住已经显示过哪些里程碑，包括跨重启，并且恢复解析器仍能识别较旧的带标签快照。成功的持久原生工具对或 Code Mode 子分派会记录已完成的工作、当前状态、未解决的依赖项以及确切的下一步工作，然后结束该轮次。插件首先落地并刷新正常完成轮次的压缩，然后作为单独的普通轮次提交一个直接自动的插件来源后续。如果压缩尚未成功，则不会开始继续；冷恢复恢复可以完成缺失的压缩，并分派仍然待处理的请求，而不会重复已插入的后续。

当配置文件具有附件存储时，插件会向主对话和两种压缩工作器类型公开 read_memory_image。压缩保留内容寻址的附件 id，而不是本地路径，并且该工具只接受确实出现在当前会话或其活动根父级中的 id。原始像素仅在工具请求时加载，并且仅在活动模型声明支持图像输入时加载。

主工具目录还默认公开 read_session_history。不带 turn 时，它会列出最近完成的轮次及其可见/推理大小；带 turn= 时，它会读取该轮次原始的仅追加消息节点，包括后来被表面替换所遮蔽的推理。读取仅限于调用代理自己的会话，并按字符偏移分页。这是一条按需恢复路径：它不会将原始历史恢复到常驻表面，也不会使其成为每个请求的一部分。
提供商确认的上下文溢出具有固定的一次性恢复策略：仅压缩一次，并且只有在持久化表面替换提交后，才重放失败的主模型请求。如果该重放也溢出，则保留提供商错误，而不是启动另一个压缩循环。这与 sessionCompaction.compactionRetries 无关，后者控制当一个检查点仍使会话高于配置阈值时，额外的成功压力压缩。

验证工作流

每次编辑后运行快速确定性检查：
bash
pnpm check

当更改涉及插件接线、提示词、工具、表面落地或持久化时，运行真实的端到端冒烟测试：
bash
pnpm e2e

在更改压力选择、分段、会话工具、工作器编排、检查点渲染或压缩事务后，运行专用的会话压缩 E2E：
bash
pnpm e2e:session

它在测试覆盖层中禁用原装后端，创建三个已完成的轮次，注入由 turn-memory 生成的相同轮次后助手替换，并首先证明上游 token-meter 拒绝该生命周期形态。然后它强制前两个轮次进入独立分段，并通过其规范表面定价回退手动调用自定义引擎。在单次失败预算下，第一个分段的分叉在已接受的变更后被故意停止；测试要求新生成的延续来完成它，然后要求下一个分段以分叉开始。最后，它验证标准事件邻接、检查点来源、未触碰的保留尾部、持久化，以及确切会话的冷恢复。

当生产提示词行为发生变化时，还要运行定性引导回归：
bash
pnpm e2e:prompt

重复相同的独立真实模型场景以测量观察到的稳定性：
bash
TURN_MEMORY_PROMPT_EVAL_RUNS=3 pnpm e2e:prompt:repeat

重复包装器保留每个会话和表面路径，然后在 .tmp/ 下报告通过率和 Wilson 95% 置信区间。

运行更广泛的生产提示词矩阵，以覆盖拼写错误合并、真正的证据驱动目标变更以及实现细节保留：
bash
TURN_MEMORY_PROMPT_EVAL_RUNS=2 pnpm e2e:prompt:matrix

每个场景都执行真实的父级工作、自动轮次压缩、冷恢复、完整表面重放和 sessionQuery 比较。该矩阵接受可变的有效节点计数，但要求因果用户/助手边界和场景特定的延续细节。它在每个会话前后对生产提示词、渲染器、编辑器和插件入口进行指纹识别，因此并发编辑会使运行失败，而不是混合提示词版本。使用 TURN_MEMORY_PROMPT_EVAL_SCENARIOS=goal_change 来隔离单个场景。

这会创建一个真实的多步骤轮次，其第一次 /repo 尝试失败，并且其后续用户引导说 playground。与确定性冒烟协议不同，它
使用生产压缩提示，并要求两条用户消息合并为一个修正后的意图，其来源包含这两个来源。助手的工作可以保留在多个语义节点中，但它们合在一起必须同时保留失败的绕行和最终的 6 类型/9 设备结论。它检查实时折叠、持久化、冷加载和会话查询投影，然后写入 .tmp/prompt-eval-surface-.json 以供检查。

e2e 工作流使用专用的 ~/.dsh/profiles/test-turn-memory 配置文件以及配置的真实模型。它创建一个全新的父会话，强制进行多节点工具轮次，有意让其实时 turn/end 保持未压缩，刷新持久化，销毁代理，并冷恢复同一会话。然后恢复扫描必须启动错过的压缩。运行器在接受 n* -> r 变更后中断其第一个工作进程，并验证新生成的恢复工作进程会继续处理那些 r 节点直至最终重写。它检查实时 foldSurface() 和 deriveMessages()，刷新，第二次冷恢复，并验证持久恢复检测既不重复也不改变替换标识。成功以 E2E_RESULT=PASS 结束，打印保留的测试会话 ID，并将精确的 sessionQuery.readSurface() 快照写入 .tmp/e2e-surface-.json。E2E_SURFACE_PATH 输出包含其绝对路径，以便直接检查。

运行器通过 DSH 的有界 appExit 服务请求关闭，而不是调用 process.exit()，因此持久化和插件拆卸会被排空。

每个启用的 turn-memory 实例在成功替换后也会刷新并写入其完整的折叠表面。默认情况下，每个会话的最新快照会写入此插件旁边的 .tmp/e2e-surface-.json；surfaceDumpDir 会更改目标位置，但不设置它并不会禁用该转储。