上下文减负 markelayan/billion-context-relief

billion-context-relief

- npm： billion-context-relief
- GitHub： markelayan/billion-context-relief

由智能体主动请求的上下文减负，面向 DSH（DeepSeek Harness）。它是 billion-context-dsh（ACP）的配套插件。

ACP 让智能体把一段上下文压缩成自己写的摘要。但有时候摘要并不合适：

- 体积大，但以后可能还要原样用到（长日志、抓取的页面、文件转储）。把它移出窗口、写进文件，只留一个指针：context_export。
- 完全没用了（走进死胡同的搜索、已被取代的快照、过期的提醒）。直接丢掉，不写摘要也不留文件：context_delete。

插件加了这两个动作，另外还加了两个：一个用来找出哪些内容值得移动（context_large_blocks），一个用来清理导出的文件（context_exports）。

每次改动都是一次显式的智能体调用。 不会自动压缩、导出、删除或清理任何东西。唯一自动运行的是顾问提示，而且它只做提醒。

目录

- 环境要求与兼容性
- ACP 依赖
- 安装
- 工具
- 替换如何生效
- 它会拒绝什么
- 顾问
- 导出
- 配置
- 安全与数据说明
- 升级与重载
- 疑难排查
- 开发
- 相关插件

环境要求与兼容性

包：npm 上的 billion-context-relief。发布内容：lib/、cordis.patch.yml、README.md、CHANGELOG.md、LICENSE（打包后约 19 kB，无运行时依赖）。

| 组件 | 版本 | 状态 |
| DSH | 0.2.0-rc.2 | ✅ 兼容。已在真实 DSH 会话中实测（导出、删除、拒绝、导出清理）。 |
| DSH | 0.1.x | ❌ 不支持。必须要有 0.2 的压缩接缝和会话接口。 |
| billion-context-dsh（ACP） | github:Tyan66666/billion-context-dsh#2026-09-30_dsh-0.2-seam-port（报告版本 0.2.26） | ✅ 已测试 |
| billion-context-dsh（ACP） | npm billion-context-dsh@0.2.26 | ⚠️ 预期可用（版本和导出相同），未测试 |
| billion-context-dsh (ACP) | DSH 0.1 系列 | ❌ 不支持 |
| Node.js | >= 20 | 必需 |

运行时依赖：无。billion-context-dsh 是 peer 依赖：它必须已经装在同一个 DSH 配置档里，并且作为压缩引擎处于启用状态。

声明的 DSH 兼容性写在 package.json → dsh.compatibility.dshReleases。

ACP 依赖

本插件不自己实现压缩。每次替换都走 ACP 自己的 compress 路径，所以 ACP 必须：

1. 已安装在该配置档里（配置档的 package.json 中有 billion-context-dsh），并且
2. 是当前启用的压缩引擎，也就是列在 dsh.profile.bundles 中。ACP 的 bundle 会替换掉 compaction-basic。

它用到 ACP 的这些部分（都是 billion-context-dsh 的公开导出）：

| 导出 | 用途 |
| AcpCompactionEngine | 识别当前运行的引擎（ctx.compaction），读取它的 env 和上下文窗口 |
| makeTools(env) → compress | 通过 ACP 的 compress 处理器执行每次替换 |
| resolveSurfaceRange | 把请求的区间解析成 ACP 当前生效、且工具对配平的区间 |
| shadowedSeqsOf | 某个区间会隐藏掉的具体消息 |
| AlreadyCompressedRangeError | 拒绝已经落在 ACP 块内部的区间 |

ACP 的定位方式：

- 首先按普通 import 处理（billion-context-dsh 能从本包解析到）。
- 当本插件是从配置档之外的文件夹链接进来（link: 安装）时，从 ~/.dsh/profiles/*/node_modules/billion-context-dsh 解析。只接受 AcpCompactionEngine 就是当前引擎那个类的副本，所以过期副本或第二份副本永远不会被用到。

没有 ACP 时（没装，或者启用了别的压缩引擎），每个工具都会回答需要 ACP，并且不做任何改动。advisor 保持沉默。

ACP 的全局配置永远不会被修改。每次调用的两处差异见 How replacements work。

安装

如果配置档里还没有 ACP，先装 ACP：

dsh plugin --profile web add "billion-context-dsh@github:Tyan66666/billion-context-dsh#2026-09-30_dsh-0.2-seam-port"

然后从 npm 安装本插件（推荐）：

dsh plugin --profile web add billion-context-relief

用 billion-context-relief@0.1.2 锁定版本。以后升级：

dsh plugin --profile web update billion-context-relief

或者从 GitHub 安装（锁定到 release tag）：

dsh plugin --profile web add "billion-context-relief@github:markelayan/billion-context-relief#v0.1.2"

或者用本地链接，方便开发：

dsh plugin --profile web add "billion-context-relief@link:/path/to/billion-context-relief"
dsh plugin add 会把包写进配置档的 package.json 和 dsh.profile.bundles，运行中的 DSH 无需重启即可加载。插件的工具会出现在安装之后打开的会话里：会话的工具列表在会话组装时就已固定，所以要重新打开需要用它的会话。

检查是否加载成功：DSH 日志（dsh web 对应 ~/.dsh/dsh-web.log）会显示

[billion-context-relief] ready — tools: context_large_blocks, context_export, context_delete, context_exports · advisor=true · exports in <tmpdir>/billion-context-relief

卸载：

dsh plugin --profile web remove billion-context-relief

已经创建的块会作为普通 ACP 块留在会话里。导出文件会一直留在磁盘上，直到你删除；见 Exports。

工具

范围边界是 surface seqs（整数）或 ACP mNNNNN 引用，由 context_large_blocks 和 acp_status 显示。范围两端都包含在内。

context_large_blocks

列出保护区域之外的超大条目。只读。

| 参数 | 类型 | 描述 |
| largeMessageTokens | integer | 本次调用覆盖单条消息阈值 |
| largeTurnTokens | integer | 本次调用覆盖每轮阈值 |
| largeBlockTokens | integer | 本次调用覆盖 ACP 摘要块阈值 |
| limit | integer 1–50 | 最多条目数（默认 20） |

输出示例：

Thresholds: message ≥4.0K · turn ≥12.0K · ACP block ≥3.0K tokens.
· seqs 278–394 · turn 6 (38 msgs) · ~50.1K tok · 6 turns ago
· seq 308 · tool web_fetch · ~12.5K tok · 6 turns ago
· seq 355 · tool web_fetch · ~11.4K tok · 6 turns ago usage 45% · oversized messages/blocks ~40.8K tok Turn entries overlap their messages — act on either, not both.

标签显示条目类型（工具名、runtime-context snapshot、plugin:<name>、ACP summary block 等）。标签从不显示内容。

context_export

把一段已完成的上下文写入临时文件，模型不会读到它，并用一行指针替换这段范围。

| 参数 | 类型 | 必填 | 描述 |
| startSeq | seq 或 mNNNNN | ✅ | 第一条消息 |
| endSeq | seq 或 mNNNNN | ✅ | 最后一条消息 |
| name | string | | 文件名提示，例如 pytest-run-3 |
| note | string | | 保留在指针里的一行说明（最多 120 字符） |

留在上下文里的内容：

[CONTEXT EXPORTED (temp file) → /…/billion-context-relief/<session>/2026-10-04_205824_pytest-run-3.md · 2 msgs · seqs 306–308 · ~12.5K tok · note: …]

之后智能体如果需要取回内容，可以用它平时的文件工具读取该文件。

context_delete

用一个标记替换一段范围。没有摘要，也没有文件。

| 参数 | 类型 | 必填 | 描述 |
| startSeq | seq 或 mNNNNN | ✅ | 第一条消息 |
| endSeq | seq 或 mNNNNN | ✅ | 最后一条消息 |
| reason | string | ✅ | 为什么可以安全丢弃；保留在标记里（最多 reasonMaxChars） |
| confirm | boolean | 超过 deleteConfirmTokens 时 | 范围超过 8,000 token（默认值）时必填 |

上下文中保留的内容：

[DELETED REFERENCES · seqs 363–365 · 2 msgs · ~12.8K tok · reason: consumed docs fetch, findings in report]

context_exports

管理本会话的导出文件，只按文件名操作：从不打开或打印文件内容。

| 参数 | 类型 | 是否必填 | 说明 |
| action | "list" 或 "delete" | ✅ | |
| names | string[] | delete 时必填 | 来自 list 的文件名 |
| all | boolean | | 删除本会话的每个导出 |

list 显示文件名、大小、seq 区间、消息数、token 估算值和备注。文件名会经过校验，因此路径逃逸（../）会被拒绝。只有发起调用的会话自己的导出可见。

替换如何工作

每次替换都走 ACP 自己的压缩路径（makeTools(env) → compress → kernel.applyCompression → ACP 状态存储 → 持久化压缩事务），把指针或标记当作「摘要」。结果是普通的 ACP 块：

- acp_status 会列出它，search_context 能在其中找到文本，decompress 仍可从会话日志中读取原文；
- DSH 的用量计量会记入释放的 token（实测：一次 12.5K 导出后，45% → 39%）。

范围处理。 ACP 解析范围之前，插件会先把它拓宽，避免任何工具调用或结果被切成两半：范围从某条工具结果开始时，也会把发起该调用的 assistant 消息纳入；范围在某次调用处结束时，也会把它的结果纳入。ACP 自己会把范围收缩成平衡的剩余部分，否则第一条结果会悄悄留在上下文中。工具的回复始终报告实际处理的范围。

每次调用与模型 compress 的两点差异：

1. 这些调用中 compress.minCompressRange 为 0。否则 ACP 的 5,000 字符下限会阻止单条小记录（比如一条插件提醒）被移除。
2. 缓解工具自身的调用和结果不会从记录中隐藏（ACP 会隐藏自己的 compress 调用）。

ACP 的全局配置从不改动。

拒绝的情况

调用被拒绝时什么都不会改变；回复会说明原因。

| 情况 | 回复 |
| 当前（未结束）轮次 | reach into the current (open) turn — only completed turns can be relieved |
| 内核保护区（最后 5 条消息、最后 5K token、最近的用户消息） | are in the protected zone … — pick older messages |
| 范围已在 ACP 块内 | already inside an ACP block — nothing to relieve; decompress reads the originals |
| context_delete 没有原因 | a reason is required |
| context_delete 超过 deleteConfirmTokens 且没有 confirm: true | 要求 confirm:true，或建议改用 context_export |
| 最新的 AGENTS.md / agent-instructions 副本 | 被 ACP 拒绝（DSH 会立刻重新注入） |
| ACP 未启用 | 说明需要 ACP |
如果 ACP 在导出文件写入后拒绝某个范围，文件会被再次删除。

Advisor

智能体在对话中收到的一条通知。它只做告知：绝不编辑、导出或删除任何内容。

以下条件全部满足时才会发送：

- 会话的上下文用量至少达到 minUsagePct（默认 40%）；
- 保护区域之外至少存在一个超大条目；
- 顶部条目列表自上次通知以来发生了变化；
- 距上次通知至少过去了 advisorCooldownSteps 步（默认 8）。

[billion-context-relief: large context — act on it if no longer needed]
· seq 342 · tool bash · ~9.2K tok · 23 turns ago
· seq 118 · runtime-context snapshot · ~4.2K tok · 30 turns ago usage 61% · oversized messages/blocks ~13.4K tok Tools: context_export (keep a temp copy) · context_delete (drop, no copy). This notice can itself be removed with context_delete.

旧通知永远不会自动删除。智能体可以像删除其他内容一样删除它们。设置 advisorEnabled: false 可关闭通知；工具照常工作。

Exports

- 位置： <os tmpdir>/billion-context-relief/<session-id>/，配置后则为 <exportRoot>/<session-id>/。在 macOS 上，tmpdir 位于 /var/folders/…/T/ 下。
- 权限： 目录 0700，文件 0600。
- 索引： 每个会话目录都有一个 index.json，包含元数据（span、count、tokens、note），因此列目录时永远不会打开导出文件。
- 格式： Markdown，每条消息一节（## seq N · ），包含原始文本、工具调用和工具结果。
- 生命周期： 没有任何东西会自动删除导出文件。 它们会一直保留，直到智能体调用 context_exports 并传入 delete（按名称，或 all: true）。delete all 还会删除会话目录。操作系统可能按自己的计划清理临时目录中的旧文件；如果导出文件必须在那之后仍然存在，请设置 exportRoot。

Configuration

默认值随本包的 cordis.patch.yml 一起提供。在你的配置档的 cordis.patch.yml（~/.dsh/profiles/<profile>/cordis.patch.yml）中用同 id 的行覆盖它们：

- id: billion-context-relief
config:
largeMessageTokens: 4000 # single message
largeTurnTokens: 12000 # one completed turn
largeBlockTokens: 3000 # one ACP summary block
minUsagePct: 0.4 # advisor stays silent below this usage (0–1)
advisorEnabled: true # inform-only notice; never modifies context
advisorCooldownSteps: 8 # min steps between notices per session
maxItems: 5 # items per advisor notice
deleteConfirmTokens: 8000 # context_delete above this needs confirm:true
reasonMaxChars: 120 # max length of the delete reason in the marker
exportRoot: '' # '' → <os tmpdir>/billion-context-relief

未知键会被忽略。类型错误的值会回退到默认值。

Safety and data notes

- 在会话中不可撤销。 ACP 的 decompress 会返回原始内容供阅读，但不会把这段范围解压回来。把 context_delete 当成对会话永久生效的操作，拿不准时就用 context_export。
- 原始内容不会从磁盘上抹掉。 这两种操作都只是把内容从模型视野里移除。会话日志仍保留原始事件（decompress 读的就是它）。本插件从不修改会话日志。
- 导出文件包含原始对话内容，包括工具打印出的任何敏感信息（日志里的密钥、抓取页面里的个人数据）。把 exportRoot 放在任何仓库或同步文件夹之外。
- 不访问网络。 本插件不发起任何出站请求，也不注册任何 HTTP 路由。
- 作用范围。 一次工具调用只能操作发起调用的那个会话自己的上下文和导出。

升级与重新加载

- 从 DSH GUI 重新加载插件，或重启 DSH，都会载入新代码。dsh plugin remove + add 会更新配置档，但已经载入运行进程的模块可能仍保留旧代码，直到重新加载。
- 会话只有在重新打开时，才会拿到新增或变更的工具 schema。
- 早期版本创建的块和标记仍然有效；它们就是普通的 ACP 块。

见 CHANGELOG.md。

故障排查

| 现象 | 原因 / 修复 |
| 工具提示需要 ACP | 该配置档里没装 ACP，或 ACP 不在 dsh.profile.bundles 里，或另一个压缩引擎正在生效 |
| 会话里找不到工具 | 会话是在安装之前打开的。重新打开它。 |
| 日志里缺少 ready 行 | 检查配置档的 package.json 和 dsh.profile.bundles 里是否有 billion-context-relief（dsh plugin --profile web list） |
| 报告的范围和请求的不一致 | 属正常：范围被扩到完整的工具调用/结果对，或被缩到尚未进入 ACP 块的消息。返回结果会给出实际范围。 |
| 导出指针指向的文件不存在 | 该导出被 context_exports 删掉了，或操作系统清理了它的临时目录。decompress 仍能读到原始内容。 |

开发

npm test

Node 内置的测试运行器覆盖了各个辅助模块（test/core.test.mjs：扫描、保护区、标记、导出存储、范围扩缩）以及针对模拟 DSH 宿主和 ACP 模块的工具测试（test/host.test.mjs）。没有外部依赖。

相关插件

- billion-context-dsh：ACP，本插件所依赖的压缩引擎（必需）。
- agents-in-the-loop：为 DSH 智能体提供跨会话消息传递。
- dsh-keyword-injector：由关键词和工具触发的上下文提醒。

本插件取代了旧的本地插件 dsh-ctxdel，后者那套自动删除扫描已经彻底移除。

License

MIT