缓存感知压缩插件 Zhuchen00123/dsh-compaction-cacheaware

dsh-compaction-cacheaware

面向 DeepSeek Harness（DSH）的 Reasonix 风格缓存感知压缩后端。

这是一个独立、模块化的 DSH 插件。它实现官方 @deepseek-ai/dsh-compaction 接缝（ctx.compaction），设计为在预设的压缩域中替代 @deepseek-ai/dsh-compaction-basic 挂载。它不会修改其他插件、预设或宿主文件。

🐋 收录于 DSH 插件社区目录（1024Store）

本仓库带 dsh-plugin topic，且 package.json 声明了有效的 dsh.bundle.patch（patch 文件随仓库同 revision 提交），可被 awesome-deepseek-harness-plugins 目录的静态校验收录。
在线市场：<https://deepseek1024.com/>

文档

- PROJECT.md — 项目说明与维护入口
- MAINTENANCE.md — 维护手册
- MIGRATION_BRIEF.md — 迁移交接说明
- DESKTOP_MIGRATION.md — DSH Desktop 0.2.0-rc.2 安装与迁移（两套依赖锚点、包安装 ≠ preset realm 替换、宿主 API 变化、待执行验收清单）
- reasonix_compact_design.md — Reasonix 原始设计

从 Reasonix 移植了什么

对照上游 main-v2 同步，提交记录在 src/generated/reasonix-constants.ts；每次同步都会写入 docs/UPSTREAM_SYNC_REPORT.md。

- 单一自动触发：compact_ratio（默认 0.8），而不是多个 soft/snip/force 阈值。
- 每个事务一个结构化检查点：稳定前缀 + 一份摘要 + 近期尾部。
- 稳定前缀只保留系统头：上游的 pinnedPrefixLen 保留系统消息，因此较早的用户轮次、失败记录和 [[keep]] 标记现在进入摘要前缀，不再逐字保留。
- 近期尾部预算：window × recent_tail_ratio（16%），不设 min/max 钳制。
- 检查点接受条件：候选必须严格减少 token，且对于自动维护，必须落在物理输入上限（window − protocolReserveTokens）之下。上游移除了 50% 检查点上限和特殊的固定前缀节省路径，因此任何严格更小的候选都会被接受。
- 保留规范转录：DSH 的表面 replace 只在模型可见投影中遮蔽旧范围；原始会话日志仍是事实来源。
- 有界摘要调用：每次候选尝试只调用一次，对 invalid_prompt 网关使用与服务商无关的转录回退，没有无界重试循环。
- Reasonix 摘要标题：Standing facts & constraints、Goal、 Decisions & rationale、Files & code、Commands & outcomes、 Errors & fixes、Pending & next step。

0.2.0 范围与上游差距

本版本移植了单一压力阈值、系统头保留、一个结构化检查点加近期尾部、有界摘要路由、持久的 compaction/start → summary → replace → end 事务，以及通过 DSH 0.2.0-rc.2 会话 API 保留规范日志（较早的 0.1.6-alpha.2 一代已成历史——见 DESKTOP_MIGRATION.md §1）。手动 /compact、压力压缩、服务商确认的溢出，三者走同一套后端事务。恢复的检查点若低于压力阈值，恢复时不会再次摘要；后续请求仍按正常阈值处理。

以下上游机制本包未实现：在活跃轮溢出折叠中保留最近两个已完成轮次、按触发条件区分的摘要预算、二分查找安全摘要前缀、分块摘要、溢出驱动的 slim/transcript 重试、有损的工具结果/历史裁剪、学习式摘要 token 反馈。若挂载了可选的 dsh-compaction-tool-result-pruner，本插件会在尝试摘要前调用它；pruner 本身仍是独立包，默认不启用。其余 vendored 的 context_.go 文件是参考快照，不是对 Reasonix 的上下文胶囊、回执、恢复、报告或用量子系统的移植。

已移除的配置键，以及从 0.1.11 升级的说明，见迁移指南。

Install / build

安装到 DSH profile（推荐）

已发布到 npm registry，直接安装：

cd "$env:USERPROFILE\.dsh\profiles\web"
pnpm add dsh-compaction-cacheaware

注意：npm install 按 registry 上的 tag 解析，装到哪个版本取决于当时的 tag，不能代替选择本轮本地产物——本地 0.2.0 迁移产物尚未发布，也未安装到 Desktop；目标宿主是 DSH 0.2.0-rc.2 一代（见 DESKTOP_MIGRATION.md §1 / §3.3）。

本包自带 DSH profile bundle 声明和 cordis.patch.yml。将 dsh-compaction-cacheaware 加入 profile 的 dsh.profile.bundles 后，DSH 会在 profile 层禁用 compaction-basic 并挂载本后端；agent preset 的 isolated compaction realm 需要各自另行替换（profile 层 patch 到不了那里，见下）。不要再把同一条插入 patch 重复添加到 profile 的 cordis.patch.yml。

也可以从 GitHub 安装：

pnpm add dsh-compaction-cacheaware@github:Zhuchen00123/dsh-compaction-cacheaware

安装到 DSH Desktop

Desktop 走桌面自己的插件管理，不要用 dsh plugin --profile desktop （desktop 这个名字保留给 Electron 持有的 profile，CLI 会拒绝它的插件管理请求）。
Desktop 有自己的依赖锚点，且「装包」与「在每个 preset 的 isolated compaction realm 里替换引擎」是两步；本节上面的 profile 层自动替换只覆盖 profile 组合，不覆盖 preset realm。

安装载体建议用 npm pack 打出的 tarball 经桌面插件管理安装：这样 @deepseek-ai/dsh- 与 @deepseek-ai/cordis 都由 Desktop 自己的锚点解析，与运行时是同一份。不要把带完整 dev node_modules 的开发目录直接 file:// 挂给 Desktop——宿主类依赖会从该目录解析，可能与 Desktop 运行时不是同一实例（peer 不一致 / 双实例风险），只适合临时调试。
完整步骤、0.2.0-rc.2 宿主 API 变化与桌面验收清单见 DESKTOP_MIGRATION.md。

本地开发 / 构建

pnpm install
pnpm build

本地验证状态：npm run typecheck 与 npm run build 通过，node --test 24/24 通过 （6 config + 2 selection + 16 engine，含选区准备与摘要期间重定价、变更拒绝和手动错误分类）；这是源码侧 fixture 验证， 不是真实模型或 Desktop 验收，后者仍是 未执行（见 DESKTOP_MIGRATION.md 的 §10 / §11）。

如果不使用 profile bundle，也可以在 preset 的 compaction realm 里手动替换：

- id: compaction-basic
name: '@deepseek-ai/dsh-compaction-basic'
- id: compaction-cacheaware
name: 'dsh-compaction-cacheaware'
config:
compactRatio: 0.8
recentTailRatio: 0.16
summaryMaxTokens: 8192

如果从源码本地调试，也可以直接用编译产物路径：

- id: compaction-cacheaware
name: 'file:///absolute/path/to/dsh-compaction-cacheaware/lib/index.js'
config:
compactRatio: 0.8
recentTailRatio: 0.16
summaryMaxTokens: 8192

注意：挂载到智能体预设的隔离压缩域内，会直接替换那里的 compaction-basic；配置档级别的 bundle 补丁到不了这个域，所以每个在自己的压缩组里带 compaction-basic 的预设，都得逐个迁移到这个包。

把 @deepseek-ai/dsh-command-compact 留在同一个域里，/compact 才会用这个后端。可选的 @deepseek-ai/dsh-compaction-tool-result-pruner 仍可作为同级挂载；本插件通过 ctx.get() 读取它。

配置

| 键 | 默认值 | 含义 |
| compactRatio | 0.8 | 唯一的自动触发比例。 |
| recentTailRatio | 0.16 | 窗口内保留原文的近期尾部比例。 |
| summaryMaxTokens | 8192 | 摘要器输出上限。 |
| minRecentKeep | 2 | 至少保留的近期消息条数。 |
| minCompactMessages | 2 | 最少可压缩消息条数。 |
| protocolReserveTokens | 256 | 协议框架预留；同时决定物理输入上限（window − this）。 |
| summarizationProvider / summarizationModel | '' | 可选的摘要路由；默认走对话路由。 |
| auto | true | 注册自动压力/溢出监听器。 |

原先的 checkpointCeilingRatio、recentTailMinTokens、recentTailMaxTokens、exceptionalMinSavingsRatio、maxPinnedFirstUserTokens、pinnedFirstUserWindowFrac 这几个键已移除：上游删掉了它们对应的概念，留着只会变成悄悄不再跟踪任何东西的配置。minRecentKeep 保留下来作为安全边界——上游的 planCompaction 目前传的是常量 0 作为尾部下限，这跟它自己的注释矛盾，所以本次移植没有照搬那个行为。

模块化

- 插件只注册 ctx.compaction 和自己的自动监听器。
- 域自检（自 0.1.11 起）：挂载时如果同一域里已有别的压缩引擎占着 ctx.compaction，会打一条警告；如果之后挂载的实例取代了本实例，它的自动监听器会主动退场（只警告一次，支持热重载），而不是跟新主人抢。注意配置档级别的 bundle 补丁到不了智能体预设的隔离压缩域——每个预设都得单独迁移。
- 它不改 dsh-wsl-bash、dsh-team-dashboard、router-opencode-wsl，也不改任何其他插件。
- 要用它，就在自己的预设或配置档补丁里挂载；参见本包里的 cordis.patch.example.yml。

与 Reasonix 保持同步

scripts/sync-reasonix-compact.mjs 和 .github/workflows/sync-reasonix-compact.yml 里的 GitHub Action 会检查 esengine/DeepSeek-Reasonix 每周（周日 03:00 UTC）、手动触发，以及推送到本仓库的 main 时运行；一旦发现变更，就新建或更新 PR。同步任务：

1. 拉取最新的 main-v2 Reasonix 源码（也可以用 --from <dir> 指定预先拉取的目录树，适用于没有 git 网络访问的沙箱和 CI）。
2. 在上游 agent 目录中发现匹配的 compact.go / context.go 文件，不再依赖固定文件列表。
3. 刷新 vendor/reasonix/compact/，重新生成 src/generated/reasonix-constants.ts，并写入 docs/UPSTREAM_SYNC_REPORT.md。
4. 提交并新建 PR，说明改了什么。

同步以前有兼容性门槛：上游发生结构性重写时只产生一条警告，完全不落任何变更，于是 CI 不会开 PR，vendor 里的快照就悄悄烂掉了。现在同步总会落下快照和报告，并用 REASONIX_UPSTREAM_REMOVED_CONSTANTS 标记上游已删除的移植常量，只保留最后一次的本地值，好让包还能构建。

pnpm sync:reasonix # fetch from git
node scripts/sync-reasonix-compact.mjs --from /path/to/upstream-tree # offline

本包会导入这些生成的常量，调参值因此始终能追溯到上游。

发布到 GitHub / 社区目录

本仓库设计为可发布成独立的公开 GitHub 仓库。1024Store 目录会收录带 dsh-plugin topic 的公开仓库，并静态校验 dsh.bundle.patch 声明（补丁文件必须存在于同一目录树中）。

1. Authenticate GitHub CLI once
gh auth login

2. From this repository root, publish and add catalog topics
./scripts/publish.sh dsh-compaction-cacheaware

scripts/publish.sh 会：

1. 创建公开 GitHub 仓库并推送本仓库。
2. 添加 dsh-plugin、deepseek-harness 和 reasonix 三个 topic。

之后，deepseek1024.com 就会列出这个条目。要发布到 npm，先提交并推送完整的发布目录树，再推送对应的 vX.Y.Z 标签，然后运行 ./scripts/publish-npm.sh X.Y.Z。npm 脚本在发布前会检查本地与远端的分支/标签是否指向同一个干净的提交；它不会改版本号，也不会创建 Git 引用。

许可证

MIT