athif23/dsh-context-rollover

dsh-context-rollover

一个 DeepSeek Harness 捆绑包，用于
模型驱动的上下文自我管理：模型可以刻意结束一个工作上下文窗口，并在一个全新的窗口中继续，同时保留持久状态——且无需摘要。

fresh working context + durable model-managed notes + small recent raw tail + recoverable full history

灵感来自 openai/codex 中的上下文管理架构（new_context 工具、无需摘要器的 token 预算压缩、历史/笔记分离）以及 pi-posthorse。Codex 是架构参考；DSH 是实现权威——一切都通过 DSH 自身的 surface-replace 协议和压缩事务运行。

Web 配置：rollover 仅在 standard-rollover 预设中运行。

仅安装此捆绑包本身是不够的。Web 配置从会话的 agent 预设中组合压缩，而默认预设（standard）保持与发布时完全一致：它保留内置摘要器，并且没有 rollover 工具，也没有 rollover 指导——没有 new_context，没有 get_context_remaining，没有 notes，没有 history。standard 会话完全无法进行 rollover。

要使用它，请打开一个新会话，并在发送第一条消息之前在预设选择器中选择 "Standard + rollover (experimental)"——会话的预设一旦其第一轮运行就会被冻结。

Headless 和其他无 roster 的配置是例外：它们没有预设 roster，因此宿主引擎为每个会话提供服务，无需选择。

工作原理

该插件提供活动的 ctx.compaction 引擎（它在捆绑包补丁中禁用 dsh-compaction-basic）。在 Web 配置中，该引擎还必须存在于会话的 agent 预设中——请参阅下方的 Web 配置。一次 rollover 是一次真正的 DSH 压缩：compaction/start → compaction/summary → 一条带有完整来源溯源的替换 user/message → compaction/end——但“摘要”是一个确定性检查点（持久笔记加上可选的交接），绝不是一次 LLM 调用。原始会话事件保持持久化；经过 token 预算的近期尾部在表面上保持逐字不变；deriveMessages() 会自动重建。

职责保持分离（Codex 的教训）：

| 关注点 | 负责方 |
|---|---|
| 请求边界 | new_context 工具（仅记录待处理请求） |
| 跨越边界 | agent/pre-step（在下一个模型请求之前）和 agent/turn-stopping |
| 跟踪窗口 | 从持久日志中读取的 rollover 计数 + 摘要序列号 |
| 测量压力 | ctx.tokenMeter + 所路由模型的上下文窗口 |
| 替换表面 | DSH 压缩事务内的 commitRollover |
| 保留选定状态 | notes 工具（每个会话的 markdown 文件） |
| 恢复旧细节 | history 工具（对已被遮蔽的表面事件进行搜索/读取） |

面向模型的工具
- new_context({ handoff? }) — 在下一个安全点请求上下文边界。交接内容（有界）会成为新窗口检查点的一部分。边界会在安全的生命周期点跨越，绝不会在工具批次中途跨越。
- get_context_remaining() — 诚实的余量：在硬窗口和自动滚动之前剩余的 token 数，或“尚未测量”。
- notes — 对 /notes// 下按会话划分的 markdown 文件执行 list | read | write | append | search。不会自动写入任何内容；由模型决定哪些内容得以保留。
- history — 对已离开活动表面的对话执行 search | read。定向恢复，而非整体重建。

滚动路径

1. 模型驱动（首选）：模型保存笔记，在阶段边界（研究 → 实现等）调用 new_context 并附上简短交接。
2. 压力（安全网）：当超过窗口的 thresholdRatio 时，引擎会自动滚动，并保留持久笔记和最近的逐字尾部。低于该阈值时，每个窗口一次的检查点提醒会建议保存笔记并滚动。
3. 溢出：提供商确认的 CONTEXT_WINDOW_EXCEEDED 会强制滚动，使用相同的笔记 + 尾部检查点，并重试请求。
4. 手动：/compact 继续可用——它在空闲 agent 上执行相同的独立笔记 + 尾部滚动。

只有模型驱动路径会携带交接。引擎绝不会为压力、溢出或手动滚动写入交接：生成交接本身要么意味着一次 LLM 摘要调用，要么意味着将较早的用户消息复制到新窗口中，而第二种选项会复活过时的请求。这些路径改为通过笔记和最近的逐字尾部来保留意图。

此插件涉及的内容

- 注册四个面向模型的工具（new_context、get_context_remaining、notes、history）以及一个系统提示部分——在无头配置文件中每个会话都如此；在 Web 配置文件中仅在 standard-rollover 会话内如此（其他预设保持与发布时完全一致）。
- 仅在一个位置写入文件：/notes// 下的 markdown 笔记。磁盘上不会写入其他任何内容；没有网络调用，没有遥测。
- 替换活动的压缩后端（compaction-basic 被 bundle 补丁禁用）。会话日志在两个方向上保持完全兼容。
- 无凭据、无云服务、无数据离开本机。

宿主版本兼容性

该插件针对两条宿主线进行类型检查：开发检出及其已安装的配置文件（0.1.6-alpha.1，通过生成的 tsconfig 路径），以及发布到公共 npm 的最新包（0.0.1-rc.1，即针对 compat/node_modules 的 pnpm typecheck:compat 探测）。运行时差异在 src/compat.ts 中桥接：

- 会话日志作为 snapshotEvents()（较新线）或 events（已发布）；
- eventAt(seq) 与该数组的索引访问；
- 按节点计费，表示为 heuristicTokens（较新的行）或 tokens；
- 替换操作表示为 { startSeq, endSeq }（较新的行）或
{ start, end }，每个进程只探测一次，因为每一行都会拒绝另一行的字段名。

请注意，已发布的 @deepseek-ai/dsh- 包是一个部分镜像：其中一些对等依赖引用了从未公开发布的包，因此无法组装出仅依赖 npm 的独立宿主图。这是预期之中的——插件的对等依赖会从正在运行的 dsh 宿主的安装闭包中解析，而将插件本身安装到某个 profile 中只会获取此包。

安装

从 npm 安装（推荐）：

dsh plugin --profile  add dsh-context-rollover
或者，不使用 dsh CLI：
pnpm --dir "$DSH_HOME/profiles/" add dsh-context-rollover

自定义 profile 初始化时仅包含 dsh-base；由于该包声明了 dsh.bundle.patch，bundle 的补丁会自动应用。首次安装后（bundle 成员变更属于启动时组合），启动该 profile 一次——插件的对等依赖包会从正在运行的宿主的安装闭包中解析，而绝不会从 npm 解析。

从 GitHub 而非 npm 安装：

dsh plugin --profile  add github:athif23/dsh-context-rollover

从本地检出安装（开发用途，参见下文 HMR 部分）：

dsh plugin --profile  add D:/path/to/dsh-context-rollover

Windows 注意事项：如果从 Git Bash 安装后插件能加载，但其 @deepseek-ai/ 导入在运行时失败，则 pnpm 可能生成了损坏的 link: 联结（Git Bash/Windows 路径处理 bug）。请按下文 HMR 部分所述，使用 cmd /c mklink /J 重新创建它们——同样的修复方法适用于 profile 中任何被链接的同级包。

bundle 的 cordis.patch.yml 会禁用 dsh-compaction-basic，并挂载 context-rollover 引擎本身。command-compact、token 计量器以及压缩不变式配套组件无需更改——它们仅依赖 ctx.compaction。

Web profile（预设会话）

无头及其他仅含 base 的 profile 在完成上述安装后即可使用：宿主引擎就是会话的引擎，不存在名册，也没有任何东西需要让位。Web profile 则不同——其会话从agent 预设而非宿主组合压缩——因此该 bundle 还会在部署自身的预设集旁边注册一个随附的 standard-rollover 预设（选择器中显示为“Standard + rollover (experimental)”）。安装后重启宿主一次，然后在其上打开新会话以试用该实验；standard 仍为默认值。请在会话仍为空白时选择该预设：创建头部被深度冻结，且会话只能在其第一轮运行之前更改预设，因此已经启动的 standard 会话无法迁移到 rollover。

无需命令，无需编辑 profile。有两点行为使这一点成立：

- 宿主引擎会让位于任何预设拥有的后端：在 standard 上
会话中，随附的摘要器单独运行（此前两个后端会针对每个压力信号竞争）；在 standard-rollover 上，预设的 rollover 引擎单独运行；无头会话保留宿主引擎。
- 预设的引擎行设置了 modelSurface: 'always'，因此它是其会话中 rollover 工具和指导的唯一来源。在预设部署中，宿主行（modelSurface: 'auto'）两者都不注册，因此 standard 和 minimal 会话永远不会看到 rollover 框架化的指令。

自定义阈值属于你自己的预设副本（受支持的定制流程：在选取器中复制 standard-rollover 并编辑 context-rollover 行）——随附的预设带有以下默认值。如果某个部署在后续补丁层中重新声明了整个 agent-presets 配置，则该层胜出并隐藏随附的预设；在那里重新添加该 bundle 的根节点即可恢复它。卸载该 bundle 会移除预设：已经使用它的会话会继续运行，新会话必须选择另一个预设。

维护者：presets/standard-rollover/ 是生成的，而非手工编写的——在 harness 更新后重新运行 pnpm preset:sync 并提交刷新结果。同步会保持其他所有内容逐字节一致，并在随附的 standard 形态发生漂移时大声失败。

配置（插件行上的 cordis.yml config）：

- insert:
- id: context-rollover
name: dsh-context-rollover
config:
thresholdRatio: 0.9          # automatic rollover point (fraction of window)
reminderThresholdRatio: 0.75 # one-time checkpoint reminder point
retainRatio: 0.1             # recent verbatim tail (fraction of window)
retainTokens: null           # absolute tail budget; overrides retainRatio
handoffMaxChars: 20000
notesEnabled: true
historyEnabled: true
notesDir: null               # base dir override; default /notes
modelSurface: auto           # auto (host rows) | always (preset rows)

使用 HMR 进行本地开发

快速循环从你的检出目录运行 DSH，插件从此目录链接，并由 Cordis HMR 监视源代码：

1. 创建专用 profile 并链接此包

dsh plugin --profile rollover-dev add D:/path/to/dsh-context-rollover

（自定义 profile 初始化时仅包含 dsh-base；该 bundle 的补丁会自动应用，因为该包声明了 dsh.bundle.patch。）

2. 在 $DSH_HOME/profiles/rollover-dev/cordis.patch.yml 中启用 hmr 行
（补丁行会替换整个配置，因此需重新声明 root）：

- id: hmr
config:
root: ['.', 'D:/path/to/dsh-context-rollover/src']
debounce: 100

基础 bundle 默认以禁用状态挂载 hmr；它所需的 timer 行已经处于活动状态。

3. 从源代码运行 DSH

cd /path/to/deepseek-harness
pnpm run build          # once; Typert host artifacts are required
pnpm dsh --profile rollover-dev

源启动通过 tsx（node --import tsx/esm）运行，这正是 TypeScript 插件源码热重载能够生效的原因。

4. 编辑此包中的 src/.ts —— 受影响的插件会就地重载；注册项（工具、系统提示词片段、事件监听器）会通过 Cordis effects 撤销并重新应用。Profile 补丁编辑也会实时重组（patchReload: live 是自定义 profile 的默认值）。

5. 以下情况仍需要重启：初始 bundle 安装、bundle 成员变更（dsh.plugin add/remove）、框架级依赖变更（Cordis 会回退到 loader.exit()），以及任何 HMR 无法安全替换的内容。

Windows：link: 联接点与 Git Bash

在 Git Bash 中运行 profile 的 pnpm install 时，会把 link:D:/... 说明符错误处理成目标无效的联接点（驱动器冒号被当作相对路径）。如果某个 profile 的链接插件在安装后无法加载，请用真实目标重新创建联接点：

cmd /c mklink /J "%DSH_HOME%\profiles\web\node_modules\dsh-context-rollover" "D:\path\to\dsh-context-rollover"

（或者从 PowerShell/cmd 运行安装。）此包自身的运行时 peer 是指向共享安装闭包 $DSH_HOME/profiles/node_modules/@deepseek-ai/ 的联接点。这正是让引擎共享宿主模块实例的关键：扩展 CompactionEngine 的服务插件必须导入宿主所加载的确切类，因此通过宿主相同的闭包来解析其 @deepseek-ai/ 导入是至关重要的，而非一种优化。

测试与类型检查（无需 DSH 构建）

同级的 DSH 检出是事实来源：tsconfig.base.json 的路径会被生成到 tsconfig.dsh-paths.json 中，vitest 别名会从 TypeScript 源码执行一切 —— 与 DSH 自身测试套件使用相同的源码平面。Vendored 包针对其构建后的声明进行类型检查，因此 skipLibCheck 会吸收它们放宽的严格性。

pnpm install
pnpm test        # surface、notes、history、engine 集成、工具渲染
pnpm typecheck

测试会挂载真实的会话存储、token 计量器、工具运行时、agent 循环，以及压缩不变式伴随组件，因此每一次提交的 rollover 都会依据 DSH 自身的不变式进行验证。集成测试端到端地证明了该语义实验：模型进行研究，在回合中途调用 new_context，而新的窗口在回合继续的同时携带 notes + handoff + 近期尾部。

范围与限制

- 一次 rollover 检查点包含持久化 notes、模型在提供 handoff 时的 handoff，以及位于检查点之外保留的逐字尾部。不会将更早的用户提示词复制到其中。
- Notes 在会话内的上下文 rollover 中得以保留；没有跨会话同步、嵌入或云存储。
- Notes 是文件，而非会话事件：Session.append 无法将插件的自定义事件类型标记为 ignorable，因此会话日志上的未知插件事件
会使该日志在任何没有该插件的 DSH 构建中都无法读取。只写入已知的事件类型（compaction/、user/message）。
- 复用了通用的  检查点来源信息，因此转录 UI 能像识别任何压缩一样识别滚动检查点。
- 没有分叉或修补任何 DSH 核心；该插件只使用公开接缝。

许可证

MIT