dvaJi/dsh-codex-context

dsh-codex-context

一个实验性的、无损检索上下文管理器，用于 DeepSeek Harness（dsh），其灵感来自 Codex 0.153（codex-rs/core/src/context_manager/）中引入的实验性 context_management 架构。

它用一个基于 dsh 仅追加会话日志的按 token 预算的滑动窗口替换了 dsh 默认的 LLM 摘要式压缩后端，在模型前方固定持久工作笔记，并暴露冷历史搜索，因此任何离开活动窗口的内容都不会真正消失。

Pi 编码代理的参考实现：Xeron2000/pi-codex-context。

为什么

长时间的代理会话会遭受窗口耗尽、注意力稀释以及有损摘要压缩的困扰，后者会永久破坏精确的错误字符串、命令输出和代码签名。dsh 的会话模型使更好的权衡成为可能：

- 会话日志是仅追加且无损的——压缩仅通过 surfaceOp: { op: 'replace' } 对表层节点进行遮蔽；原始事件永远保留在日志中。
- ctx.compaction 是一个专为第三方后端设计的能力接缝（“固定模板后端是一个实现相同接口的兄弟包”）。
- ctx.tokenMeter 提供一个可感知重放的测量服务；ctx.systemPrompt.context() 固定动态的、持久的、模型可见的上下文。

该插件将这些组合成 3 层架构：

┌────────────────────────────────────────────────────────┐
│                   活动上下文窗口                        │
│   • 系统提示与工具                                      │
│   • [上下文笔记]（固定的动态快照）                      │
│   • 近期工作集（≤ targetActiveTokens，                  │
│     仅在安全边界处截断）                                │
└──────────────────────────┬─────────────────────────────┘
│  以匹配为中心的检索
▼  (search_history)
┌────────────────────────────────────────────────────────┐
│               规范冷存储                                │
│   • 仅追加的会话日志本身                                │
│   • 被遮蔽的节点：完整输出、堆栈跟踪、                  │
│     工具调用——从不被摘要掉，从不被删除                  │
└────────────────────────────────────────────────────────┘

引擎做什么

- 感知 token 的滑动窗口——当计价表层超过有效预算（配置 targetActiveTokens，上限为路由上下文窗口的 emergencyThresholdRatio，该窗口小到永远无法达到配置目标）时，引擎向后遍历累积节点价格，并遮蔽最旧的平衡跨度，直到保留的尾部适合预算，只要预算允许，就将截断点对齐到整个回合边界。
- 零孤儿边界——两条切割边都通过压缩接缝的 toolPairingBalancedBefore/After 进行验证，因此工具调用永远不会与其结果分离（Codex 的 normalize 不变量），并且最小近期尾部始终原样保留。
- 无模型检查点——常规窗口化写入一个极小的模板检查点（[Window Checkpoint] + 检索指引），而不是付出一次 LLM 调用。原始片段仍可查询。
- 紧急降落伞（Codex 行为）——Codex 会常规地进行窗口化，但在接近限制时会进行摘要（使用 SUMMARIZATION_PROMPT 自动压缩）。同样地，当常规步骤压力越过所路由模型上下文窗口的 emergencyThresholdRatio（默认 0.85）时，引擎会通过 ctx.llm.stream() 写入一份真正的结构化模型摘要——复用对话的系统提示、工具和已遮蔽消息作为热前缀——而不是使用模板。降落伞是尽力而为的：失败或被截断的摘要会降级为模板检查点，而提供商确认的溢出（CONTEXT_WINDOW_EXCEEDED）会完全跳过它——进一步接近限制的模型调用极有可能失败，并阻塞唯一能够成功的缩减操作。
- 持久事务——每个窗口化操作都遵循压缩接缝契约：compaction/start … compaction/end 日志记录的锁、全表面或选定跨度的稳定性重新验证、针对令牌计量器的收缩验证，以及每次失败恰好一次关闭尝试。溢出恢复（CONTEXT_WINDOW_EXCEEDED）在持久替换推进表面代际后重试。

模型获得的内容

| 工具 | 用途 |
|---|---|
| update_notes | 更新持久工作笔记（目标、已修改文件、约束、后续步骤）。固定于每个后续请求的顶部；在窗口化、压缩和重启后依然保留。 |
| search_history | 对完整会话日志进行正则/关键词搜索——用户提示、助手消息（包括推理）、工具调用以及完整的工具输出。优先搜索冷（已遮蔽）历史；摘录以匹配位置为中心，而不是从偏移量 0 处切片。查询为不区分大小写的关键词或正则表达式，最多 512 个字符；空查询或仅含空白的查询会被拒绝，而带有嵌套无界量词的模式（一种灾难性回溯风险，例如 (a+)+）会被拒绝并给出指引。 |

笔记持久化不需要自定义会话事件类型：每当渲染文本发生变化时，代理循环已经将动态运行时上下文记录为持久的 user/message 快照（source: @deepseek-ai/dsh-system-prompt，form: 'snapshot'），并在压缩移除快照后重新记录该快照。恢复笔记是对日志进行向后折叠，以查找最新的 codex-context:notes 部分。

安装
该包是一个 dsh bundle（其 package.json 声明了 dsh.bundle 及 cordis.patch.yml）。该补丁禁用了基础 compaction-basic 行，并将此引擎挂载为其自身的 codex-context 行——叶子行的 name 无法就地重写，且两行共享同一 id 会在挂载时被拒绝，因此这是加载器支持的替换摘要后端的方式。command-compact（/compact）和可选的工具结果修剪器针对替换引擎保持不变，继续正常工作。

从 dsh 源码检出（在 @deepseek-ai/ npm 镜像仍持有过期 RC 期间推荐使用）：

dsh plugin --profile demo add /path/to/dsh-codex-context
dsh --profile demo --dump-config   # base compaction-basic row disabled, codex-context row mounted
dsh --profile demo

从 GitHub 安装时，固定一个提交并允许构建（pnpm ≥10 会拒绝 git 依赖的 prepare 脚本，直到被加入允许列表）：

dsh plugin --profile demo add github:dvaJi/dsh-codex-context#
add to the profile's pnpm-workspace.yaml:
allowBuilds:
dsh-codex-context: true

或者发布一个 tarball：pnpm pack → dsh plugin --profile demo add ./dsh-codex-context-0.1.2.tgz。

保留摘要式压缩，仅添加检索层

为希望在随附后端之外使用笔记 + 搜索的组合导出了一个仅工具条目：

- insert:
- id: codex-context-tools
name: dsh-codex-context/tools

切勿在同一上下文中同时挂载两个条目——工具名称会冲突。

配置

一切都是配置字段；所有值均为可选（显示的是 schema 默认值）。在配置文件的 cordis.patch.yml 中为 bundle 行（codex-context）添加一个 config: 块——补丁会替换该行的整个 config，因此请重新声明你关心的每个键。

| 字段 | 默认值 | 含义 |
|---|---|---|
| auto | true | 自动窗口化（agent/pre-step 压力）和溢出恢复（agent/request-error）。 |
| targetActiveTokens | 35000 | 活动窗口的 token 预算；向后遍历会遮蔽较旧的节点，直到尾部能够容纳。当路由模型的上下文窗口小于 targetActiveTokens / emergencyThresholdRatio 时，有效预算会被限制为 emergencyThresholdRatio × contextWindow，以便窗口化提前运行，而不是等待溢出。 |
| minRetainedNodes | 6 | 始终逐字保留的近期表面节点。 |
| maxExcerptLength | 1000 | 每个以匹配为中心的搜索摘录的字符预算。 |
| searchDefaultLimit | 3 | 当模型省略 limit 时，search_history 的结果上限。 |
| searchMaxScanEvents | 20000 | 每次搜索调用扫描日志事件的安全上限。 |
| emergencyThresholdRatio | 0.85 | 上下文窗口的压力比例，超过该比例时引擎会写入真实的模型摘要（降落伞）。 |
| emergencySummarization | true | 降落伞的总开关；false 会使窗口化始终保持无模型。 |
| summarizationProvider / summarizationModel | '' | 紧急摘要器的固定路由；为空时使用路由后的请求目标，然后使用 AgentOptions。必须成对配置（两者都为空或两者都设置），否则插件拒绝加载。 |
| emergencyMaxTokens | 8192 | 紧急摘要请求的输出上限。 |
| maxOverflowRetries | 1 | 在提供方确认上下文溢出后的额外窗口化尝试次数。 |
| notesHint | 提示文本 | 追加在固定笔记快照下方的行；为空则禁用。 |
| retrievalHint | 提示文本 | 嵌入每个窗口检查点的指导语句。 |

无效值（比率超出 (0, 1]、非正预算）会导致插件在加载时失败。

架构说明

- 挂载位置：ctx.compaction（@deepseek-ai/dsh-compaction 中的服务定义）、用于所有计价的 ctx.tokenMeter.measure()、agent/pre-step（瀑布流——压力）、agent/request-error（溢出）、ctx.systemPrompt.context()（固定笔记）、用于两个工具的 ctx.tools.register(defineTool(...))。
- 前缀缓存影响：与用摘要替换任意文本不同，模板检查点很小且稳定；保留的尾部未被改动，因此从窗口边界往后复用仍然有效。紧急摘要器在其指令之前逐字节重放对话自身的前缀，因此只有指令和输出未被缓存。
- 仅日志记录：compaction/start、compaction/summary、compaction/end（以及带有其被遮蔽的 sourceEventSeqs 的替换 user/message）完全按照接缝的持久化目录所记录的方式写入，因此会话查询工具、重放和 Web UI 都能识别它们。

与参考移植版的偏差

- Pi 每轮在内存中重写消息（context 事件）；dsh 的窗口替换是持久的——检查点是会话的一部分，这正是 /compact、重放和冷读取保持一致的原因。
- Pi 从分支条目恢复笔记（pi.appendEntry）；dsh 没有分支——持久运行时上下文快照承担了这一角色。
- dsh 自带面向模型的历史工具（session_search、session_event_search 等）。它们是互补的：search_history 以冷优先、以匹配为中心，作用于当前会话内，并在调用调用之前停止，而会话查询工具则覆盖整个工作区。

已知限制

- 不可分割单元——单个大于窗口的表面节点无法通过表面压缩修复（与已发布后端相同的契约限制）。当路由报告容量时，紧急摘要器仍可防止硬溢出。
- 模板检查点不是摘要——常规窗口化有意不花费模型调用；模型应使用 search_history 检索冷事实，而不是依赖有损摘要。这正是无损检索的意义所在——但只有当模型实际调用该工具时才有效。
- 启发式计量 — token 计量器的每 token 四字符启发式会低估 CJK 文本和 JSON schema 的价格；窗口边界在设计上就是近似的。
- compactRegion 需要开启一个回合（契约限制继承自接缝的事务形态，用于自动调用）。

开发

pnpm install
pnpm test        # vitest over the pure core (window planning, excerpts, extraction)
pnpm build       # tsc → lib/ + lib/types/
pnpm typecheck

纯模块（src/window.ts、src/template.ts、src/extract.ts）没有任何 harness 导入，并且可以独立进行单元测试。与 harness 耦合的模块会针对 types/vendor.d.ts 进行类型检查——这是一个开发回退垫片，镜像了已验证的 dsh 签名，之所以存在，是因为 npm 镜像上存放的是过期的 RC。当针对真实的 dsh 检出进行开发时，请从 tsconfig.json 的 include 中移除 types//.d.ts，以便改为针对权威包进行类型检查。

许可证

MIT — 参见 LICENSE。