前言¶
长会话里，模型往往不知道上下文窗口还剩多少 token，压缩发生后旧轮次在对话里「看不见」，但转录里仍在。OpenAI Codex CLI 用 TokenBudget 做剩余上下文感知、阈值提醒、检查点与历史检索；DSH 侧已有压缩与 shadow 转录，却缺少同一套可调用工具与预算提示的对齐实现。
下面介绍社区插件 dsh-context-budget（维护者 r-ayin，分类：记忆）。它在 2026-09-16 前后按 codex-rs main 分支思路做源码级对标，把预算行注入、剩余查询、历史检索、跨压缩笔记，以及主动换窗与跨会话 handoff 接到 DSH 运行时。
这是什么¶
dsh-context-budget 将 Codex CLI 的 TokenBudget 上下文机制移植到 DeepSeek Harness（DSH）：剩余上下文感知、归档换窗相关行为，以及面向过往会话的 notes / history 检索工具。
- 仓库：github.com/r-ayin/dsh-context-budget
- 社区目录页：skillhub.cn/plugins/r-ayin/dsh-context-budget
- 许可证：MIT（见仓库
package.json） - 当前包版本：0.0.1；运行环境要求 Node.js >= 20
DSH 生态主张「一切皆插件」；SkillHub 为社区目录站点，与 DeepSeek / 幻方无官方从属关系。安装前请自行审阅源码与许可证；插件以当前 dsh 进程权限运行。
与 Codex 机制的对标关系¶
README 用表格说明了实现映射，便于对照 Codex 行为理解本插件在 DSH 里的落点：
| Codex 机制 | 本插件实现 |
|---|---|
| 注入 developer 消息 “You have N tokens left” | systemPrompt.context 预算行（每轮装配渲染进尾部 snapshot，不破坏前缀缓存） |
get_context_remaining 工具 |
*_remaining 工具（tokenMeter.measure + 转录派生双路） |
| 阈值提醒 TokenBudgetReminder | 剩余 ≤30% 时预算行切换为 ⚠ 提醒（早于 DSH 80% 压缩阈值，留出写检查点窗口） |
| 换窗不摘要 + 同 rollout 新窗口 | DSH 压缩为无损 shadow（旧事件留在 session.jsonl.zstd）——无需换窗即可检索 |
history.* 检索旧窗口 |
*_history_search / *_history_read（进程内 snapshotEvents 快路径 + zstd 转录解压兜底） |
notes.* 检查点 |
*_notes（write/read，独立于压缩永久保留；compaction/end 自动落一条 auto 检查点） |
核心功能¶
预算行与阈值提醒¶
开启后，每轮在 systemPrompt.context 尾部注入预算行，数值与转录侧 summarizeBudget 一致；模型在 runtime context 中可直接看到窗口与用量。当剩余比例 ≤ 配置项 reminderRemainingPct（默认 30）时，预算行带 ⚠，早于 DSH 约 80% 的压缩阈值，便于先写检查点再被压缩。
README 记录：注入前后稳态缓存命中率约 100%，因预算行在尾部 snapshot，不改动前缀。
注入工具集¶
工具注入后的名称前缀为 _dsh_external_dsh_context_budget_（下文用 remaining、history_search 等简称指该前缀下的同名工具）。
- remaining：返回窗口、已用、剩余、压缩次数、转录路径等。
- history_search：大小写不敏感子串检索全会话转录，含被压缩 shadow 的旧轮次；进程内 snapshot 快路径，必要时解压 zstd 转录（CLI 优先解多帧）。
- history_read：按 seq 范围读取事件原文。
- notes：
action=write/read，跨压缩保留检查点；默认目录见配置notesDir。 - new_window：模型主动换窗（对标 Codex
new_context）：写检查点并置标志（内存 + 文件），在 pre-step 边界触发compactIfNeeded('context-overflow')强制压缩（可低于常规模压缩阈值）。v1.3 realm 架构下，压缩引擎在 isolate realm 内，通过~/.dsh/context-budget/rollover/<sid>.json跨边界通信；root 侧 90s 未消费会落「未消费」笔记以指引 handoff。 - handoff：跨会话移交：写 handoff 检查点并生成接续 prompt（内嵌旧会话 id 与检索说明），可交给 subagent 或新会话；凭
session_id跨会话检索旧内容。
配置项（loader config）¶
| 字段 | 说明 |
|---|---|
enabled |
默认 true |
injectBudgetLine |
默认 true |
reminderRemainingPct |
默认 30 |
maxSearchHits |
默认 20 |
notesDir |
默认 ~/.dsh/context-budget/notes |
安装与启用¶
已抓取资料中的 README 未给出 dsh plugin add … 一类的一行安装命令；文档描述的是在本机无源码 checkout 时的 install-mode 构建与热重载 流程。若你从 GitHub 获取发布包或本地目录，可按仓库说明构建并注入：
依赖链接自本机已安装的 @deepseek-ai/dsh（scripts/build.sh 从 /usr/lib/node_modules/@deepseek-ai/dsh/node_modules 解析依赖，并用盘上现成 TypeScript 做 tsc）。
bash scripts/build.sh
构建完成后，在 DSH 开发/注入流程中使用（README 原文步骤，将 {dir} 换为插件目录）：
dev_inject_plugin {dir}
dev_reload_package
具体 loader 配置字段见上一节；启用后工具与预算行由插件注册到当前 DSH 进程。
社区目录页可作为发现入口：skillhub.cn/plugins/r-ayin/dsh-context-budget。安装方式以该页与仓库 README 当时公布的命令为准，勿凭插件名拼接未在文档出现的命令。
典型用法¶
README 未提供复制即用的对话脚本，但工具语义清晰，可按会话阶段组合：
- 掌握余量：调用
remaining，确认窗口、已用、剩余与压缩次数，必要时记下转录路径。 - 压缩前留检查点：剩余进入提醒区间（≤30%）时，用
notes的write记下任务状态与未决问题；compaction / 会话 end 时插件也会自动写 auto 检查点。 - 找回 shadow 内容：压缩后对话里看不到的旧轮次，用
history_search搜关键字，再用history_read按 seq 读原文。README 验证过：约 24757 条事件的会话可命中第 1 轮内容；真实压缩会话（如session-0ef7a42c，shadowedRange 8→125873）中被 shadow 的轮次亦可检索。 - 主动换窗：模型判断需要清空当前窗口上下文但保留可追溯性时，调用
new_window；若 realm 隔离导致标志未及时消费，按笔记指引走handoff。 - 跨会话接续：
handoff生成接续 prompt 并写检查点；新会话或 subagent 用返回的session_id与history_*/notes继续读旧会话。
适用场景与注意¶
适合：长时间编码或排障会话、频繁触发 DSH 压缩、需要 Codex 式「还剩多少 token」与检查点习惯、要在压缩后检索全会话转录的开发者。
注意：
- 插件逻辑与转录路径、realm 压缩隔离强相关，DSH 大版本或 preset 变更时需对照 README 与 issue。
new_window走强制压缩路径，勿在未理解后果时频繁调用。- 仅 README 记载的验证日期与用例可作为行为参考；勿外推未列出的性能或兼容性承诺。
- 再次强调：审阅源码与 MIT 许可证，并确认插件权限与数据落盘目录（
notesDir、rollover等均在用户主目录下.dsh/context-budget/）。
结尾¶
dsh-context-budget 把 Codex CLI TokenBudget 的预算感知、提醒、笔记与历史检索接到 DSH 的 shadow 压缩模型上，并补充 new_window / handoff 以覆盖换窗与跨会话接续。若你正在 DSH 里做长会话智能体，可从目录页进入说明与链接，并在 GitHub 查看对标表与构建步骤。
- 目录页：https://www.skillhub.cn/plugins/r-ayin/dsh-context-budget
- GitHub：https://github.com/r-ayin/dsh-context-budget
