笔记式上下文压缩 sqzw-x/dsh-notes-context

dsh-notes-context

给 DeepSeek Harness 带来 omp（Oh My Pi）的笔记式上下文压缩：用模型维护的持久笔记本取代 LLM 摘要式压缩，窗口边界零模型调用。

DSH 内置压缩机制

上下文接近窗口上限时，调用模型总结旧历史，并用总结替换原文。三个问题：

- 慢：总结需等待模型返回。
- 不可靠：总结质量取决于模型当次发挥。
- 原文丢失：被替换的历史默认不再对模型可见。

本插件采用笔记本机制：不总结，改记笔记。

| | 内置压缩 | 本插件 |
| 边界处调用模型 | 是 | 否（写入静态模板） |
| 边界可预测 | 否 | 是（本地、确定性） |
| 原文可回读 | 否 | 是，按 seq |
| 什么信息重要 | 摘要模型决定 | 干活的模型自己决定 |

机制

笔记本 context_notes

模型在会话中维护一本笔记，记录任务状态、已定决策、改动过的文件、阻塞项、下一步。笔记跨窗口保留。

context_notes → 读取
context_notes { text: "..." } → 整本替换（非追加）
context_notes { text: "" } → 清空

上限 16 KiB（UTF-8 字节）。超出直接拒绝，不部分写入。

提醒（每窗口一次）

已使用的上下文接近压缩阈值时（距阈值不足 32,000 token），向模型注入一条提醒，要求更新笔记本。

提醒可忽略：模型不响应时压缩照常发生。它的作用是减少细节丢失。

窗口滚动（零模型调用）

到达压缩阈值时，复用 DSH 内置压缩的保留策略，仅替换总结步骤：写入固定过渡文本 + 当前笔记全文，不调用模型。

原文回读 context_history

滚动仅将被替换的历史移出模型可见范围，不删除（日志 append-only）。模型可按 seq 回读原文：

context_history → 索引
context_history { from: 120, to: 200 } → 指定区间
context_history { from: 0, to: 50, raw: true } → 原文

配置

常用配置项如下。完整字段见设置页，推导过程见 内部机制。

| 字段 | 默认 | 说明 |
| thresholdTokens | -1 | 压缩阈值。绝对值优先：450000 即 450K，不随模型改变。-1 改用比例 thresholdRatio |
| keepRecentTokens | 20000 | 滚动后保留的原文上限，绝对值。实际保留量更大（裁剪以整条消息为单位） |
| reserveTokens | 留空 | 压缩阈值下方保留的余量。留空取窗口的 15%，不低于 16384。目标离窗口上限不足该值时，实际触发点会提前，最多提前该值 |

触发点取两道上限里低的那道：min(目标, 窗口 − 输出预留 − 余量)。声明了 maxTokens 的供应商（pi-ai 系列）会占掉窗口的四成左右，目标设高时会被这道上限截住。这是窗口的物理限制，不是配置错误；想让目标精确命中，就把 reserveTokens 设小。
| reminderEnabled | true | 是否注入提醒 |

提醒位置无配置项，由压缩阈值推导：

lead = min(32000, max(8192, floor(压缩阈值 × 0.125)))

压缩阈值 450,000 时提醒落在 418,000。调整提醒位置需调整压缩阈值。

生效时机：改完立即生效。rolloverText、notebookSummaryMaxChars 与两个 static 标记例外——仅在写入边界时读取，故下次滚动才生效。

- id: notes-context
config:
thresholdTokens: 450000
keepRecentTokens: 20000

安装

从 npm 安装（发布后；预构建，无需本地构建）
dsh plugin --profile <profile> add dsh-notes-context
dsh --profile <profile> --dump-config # 确认两层都生效

从 GitHub 源码安装也可以，但 pnpm 会要求允许本包运行构建脚本（prepack 生成 lib/）；把 pnpm 提示的 allowBuilds 条目写进 profile 的 pnpm-workspace.yaml 后重试：

dsh plugin --profile <profile> add github:sqzw-x/dsh-notes-context

组合包含两行 patch：停用 compaction-basic，挂载本包。

限制

- 笔记本质量由模型决定。 插件不自动补写、不代为总结。模型未记录的信息需从原文回读。
- 每次写入都是一条留在上下文里的消息。 频繁重写会增大上下文。
- 边界零开销 ≠ 全程零开销。 写笔记本本身是一次工具调用，成本前移而非消除。
- DSH 自身的压缩配置不可见、不可改，只能改配置文件并重启 dsh（原因见 内部机制）。
- 受限工具集的会话（如子代理）若无法调用 context_notes，退化为无笔记本的滚动。

开发

npm ci
npm run typecheck
npm run build
npm test

发布

发布走 npm Trusted Publishing（OIDC），CI 不需要长期 NPM_TOKEN。
1. 首次发布：npm 上还没有 dsh-notes-context，先在本地 npm login，再执行 npm publish --access public（或在 CI 里临时用一次性 token 发布），创建包并确定归属。
2. 在 npmjs.com 打开该包 → Settings → Trusted publishing，添加 GitHub Actions：
- Organization or user: sqzw-x
- Repository: dsh-notes-context
- Workflow filename: publish.yml
- Allowed actions: 勾选 npm publish（npm stage publish 默认允许）
3. 之后打 v 标签，.github/workflows/publish.yml 就会经 OIDC 发布；标签版本须与 package.json 一致。新配置要在 2 天内完成一次成功发布，否则过期；若 0.2.0 已手动发过，先 npm version patch 到 0.2.1 再打标签。
4. 验证通过后删掉 NPM_TOKEN，并在包的 Publishing access 里选 “Require two-factor authentication and disallow tokens”。

首版已手动发布过时：升到下一个版本并用 CI 验证 trusted publisher
npm version patch && git push --follow-tags

之后的版本
git tag "v$(node -pe 'require("./package.json").version')" && git push origin --tags

许可

MIT