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

dsh-compaction-cacheaware

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

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

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

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

文档

- PROJECT.md — 项目说明与维护入口
- MAINTENANCE.md — 维护手册
- MIGRATION_BRIEF.md — 迁移交接说明
- reasonix_compact_design.md — Reasonix 原始设计

从 Reasonix 移植的内容

- 单一自动触发：compact_ratio（默认 0.85），而非多个
soft/snip/force 阈值。
- 单一结构化检查点：稳定前缀 + 一份摘要 + 近期尾部。
- 近期尾部预算：clamp(window×10%, 32K, 96K)。
- 检查点接受条件：普通候选 ≤ 窗口的 50% 且低于
触发阈值；例外固定前缀路径要求 ≥25% 的节省。
- 保留规范转录记录：DSH 的表层 replace 仅在模型可见投影中遮蔽旧
范围；原始会话日志仍是事实来源。
- 每笔事务一次摘要调用：无应用层重试循环。
- Reasonix 摘要标题：Standing facts & constraints、Goal、
Decisions & rationale、Files & code、Commands & outcomes、
Errors & fixes、Pending & next step。

安装 / 构建

安装到 DSH profile（推荐）

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

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

本包自带 DSH profile bundle 声明和 cordis.patch.yml。将
dsh-compaction-cacheaware 加入 profile 的 dsh.profile.bundles 后，DSH
会自动禁用 compaction-basic 并挂载本后端；不要再把同一条插入 patch
重复添加到 profile 的 cordis.patch.yml。

也可以从 GitHub 安装：

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

本地开发 / 构建

pnpm install
pnpm build

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

- id: compaction-basic
name: '@deepseek-ai/dsh-compaction-basic'
- id: compaction-cacheaware
name: 'dsh-compaction-cacheaware'
config:
compactRatio: 0.85
checkpointCeilingRatio: 0.5
recentTailRatio: 0.1
recentTailMinTokens: 8192
recentTailMaxTokens: 16384
summaryMaxTokens: 16384

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

- id: compaction-cacheaware
name: 'file:///absolute/path/to/dsh-compaction-cacheaware/lib/index.js'
config:
compactRatio: 0.85
checkpointCeilingRatio: 0.5
recentTailRatio: 0.1
recentTailMinTokens: 8192
recentTailMaxTokens: 16384
summaryMaxTokens: 16384

注意：挂载在代理预设的隔离压缩领域内的挂载会直接替换那里的
compaction-basic；配置文件级别的捆绑补丁无法触及
该领域，因此每个在其自身压缩组中附带 compaction-basic 的预设都必须迁移到此包。

将 @deepseek-ai/dsh-command-compact 保留在同一领域中，以便 /compact 使用
此后端。可选的 @deepseek-ai/dsh-compaction-tool-result-pruner 仍可作为同级挂载；此插件通过 ctx.get() 读取它。

配置

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| compactRatio | 0.85 | 唯一的自动触发比例。 |
| checkpointCeilingRatio | 0.5 | 正常自动检查点接受上限。 |
| recentTailRatio | 0.1 | 最近逐字尾部比例。 |
| recentTailMinTokens | 8192 | 生产尾部下限（从上游 32K 调低，以便在 token 计量低估时仍能触发压缩）。 |
| recentTailMaxTokens | 16384 | 生产尾部上限（从上游 96K 调低，原因相同）。 |
| summaryMaxTokens | 16384 | 摘要器输出上限。 |
| exceptionalMinSavingsRatio | 0.25 | 当固定前缀超过上限时所需的节省比例。 |
| minRecentKeep | 2 | 保留的最近消息最小值。 |
| minCompactMessages | 2 | 可压缩消息最小值。 |
| maxPinnedFirstUserTokens | 1500 | 若首个用户轮次 ≤ 此值则固定。 |
| pinnedFirstUserWindowFrac | 0.15 | 首个用户固定窗口比例上限。 |
| protocolReserveTokens | 256 | 框架保留量。 |
| summarizationProvider / summarizationModel | '' | 可选的摘要路由；默认为对话路由。 |
| auto | true | 注册自动压力/溢出监听器。 |

模块化

- 该插件仅注册 ctx.compaction 及其自身的自动监听器。
- 领域自检（自 0.1.11 起）：当同一领域中已有另一个压缩引擎拥有 ctx.compaction 时，挂载会记录一条警告；如果后续挂载取代了此实例，其自动监听器会退出（仅警告一次，支持热重载），而不是与新所有者竞争。请注意，配置文件级别的捆绑补丁无法触及代理预设的隔离压缩领域——请逐个迁移每个预设。
- 它不会编辑 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，并在上游 compact
实现发生变化时打开/更新 PR。同步任务：

1. 获取最新的 main-v2 Reasonix 源代码。
2. 用上游 compact 文件和
设计文档更新 vendor/reasonix/compact/。
3. 从 Go 常量重新生成 src/generated/reasonix-constants.ts，并
摘要提示（当它们发生变化时）。
4. 提交并打开一个 PR，附上变更内容的摘要。

生成的常量由本包导入，因此调优值可追溯到上游。

发布到 GitHub / 社区目录

本仓库旨在作为独立的公共 GitHub 仓库发布。
1024Store 目录
会发现带有 dsh-plugin 主题的公共仓库，并静态验证
dsh.bundle.patch 声明（补丁文件必须存在于同一目录树中）。
bash
1. 一次性完成 GitHub CLI 身份验证
gh auth login

2. 从本仓库根目录发布并添加目录主题
./scripts/publish.sh dsh-compaction-cacheaware

scripts/publish.sh 将会：

1. 创建一个公共 GitHub 仓库并推送本仓库。
2. 添加 dsh-plugin、deepseek-harness 和 reasonix 主题。

之后，deepseek1024.com 会列出该条目
（在 npm 包发布之前仅可浏览；安装来自 npm）。

许可证

MIT