dsh-context-window：复刻 Codex 的上下文窗口管理

前言¶

智能体开发中，上下文窗口填满后的处理是一个常见痛点。传统的摘要压缩往往是有损的，会导致模型遗忘细节，且质量会随压缩次数衰减。Codex 在 0.153.0 版本后引入了新的上下文窗口管理模型：不再频繁压缩，而是在接近阈值时，通过“换窗”丢弃整个旧窗口，只装回一份全新的初始上下文，依靠 notes 和 searchable history 保留细节。

dsh-context-window 是一个 DSH 插件，由 CooperZhuang 维护，旨在复刻这套机制。它包含三个核心组件：token 预算提示、模型可调用的 new_context 工具，以及预算记账与阈值节流。

核心功能¶

该插件提供两种换窗模式（resetMode）：

1. resetMode: handoff（推荐）：无摘要换窗。换窗时直接写入交接检查点（包含目标、待办、笔记、最后请求），不产生 compaction 事件，模型知道旧内容在哪。
2. resetMode: seam-region：委托 ctx.compaction.compactRegion 执行整面替换。这会走传统的摘要压缩路径，需要将行挂进 agent preset 的 compaction realm。

安装与启用¶

安装时使用官方命令，插件默认 enabled: false，装上不会改变当前行为。

dsh plugin --profile web add dsh-context-window

配置时在 profile 的 cordis.patch.yml 或挂载行写入以下内容：

- id: context-window
  name: 'dsh-context-window'
  config:
    enabled: true
    resetMode: handoff
    noticeThresholds: [25, 50, 75]
    effectiveContextWindowPercent: 95
    autoCompactTokenLimitRatio: 0.9
    fallbackBufferTokens: 8000
    reminderThresholdTokens: 16000
    bodyAfterPrefix: true
    toolEnabled: true
    toolName: new_context
    notesToolEnabled: true
    notesToolName: notes

模型交互¶

模型会接收到窗口提示和换窗工具。

1. 窗口提示
开窗时注入提示，包含当前窗口 ID 和剩余 token 数。

2. 换窗工具
模型调用 new_context 工具时，返回如下文本：

A new context window will start without summarizing conversation history.

3. 笔记工具
模型调用 notes 工具时，返回如下文本：

Noted (1/8 notes retained for the next window).

4. 交接检查点
在 resetMode: handoff 模式下，换窗后新窗口的第一条消息是 context_handoff：

<context_handoff>
Context window 1 (id 0199…) ended; this is context window 2 (id 0199…).
The messages of the previous window are gone. The state below was carried over verbatim.

<objective phase="active">
修复换窗后没有任务状态的问题
</objective>

<remaining_work>
- [~] 补 history 工具
- [ ] 真机挂载冒烟
</remaining_work>

<notes>
- seam 禁止不平衡切点，换窗只能落在 step 边界
</notes>

<last_human_request>
继续之前的工作
</last_human_request>
</context_handoff>

已知限制¶

使用时需注意以下几点：

• 挂载约束：ctx.compaction 是按 realm 隔离的。seam-region 模式需要将行挂进 agent preset 的 compaction realm；handoff 模式不需要后端，在 host 平面即可工作。
• 边界限制：换窗只能落在 step 边界。DSH 的压缩 seam 强制 tool-pairing 平衡，不允许切穿还在飞的工具调用。
• 计量启发式：token meter 是启发式的（4 字符/token），CJK 与 JSON schema 会被低估，阈值会偏晚触发。
• UI 不可见：handoff 模式不产生 compaction/* 事件，在 UI 的压缩统计中不可见，只在日志中记录。
• 基线不持久：baselinePrefillTokens 只在内存中，进程重启后 body_after_prefix 会退化为 total。

总结¶

dsh-context-window 提供了一种显式重启的上下文管理方式，通过 handoff 模式将交接内容显式写入新窗口，避免了隐式摘要压缩的信息丢失。这是一个 MIT 许可证的开源项目，适合需要在复杂长对话场景中保持上下文连续性的开发者。

GitHub 仓库