dsh-compaction-cacheaware
Reasonix-style cache-aware compaction backend for DeepSeek Harness (DSH).
This is a standalone, modular DSH plugin. It implements the official
@deepseek-ai/dsh-compaction seam (ctx.compaction) and is designed to be
mounted instead of @deepseek-ai/dsh-compaction-basic inside a preset's
compaction realm. It does not modify other plugins, presets, or host files.
🐋 收录于 DSH 插件社区目录（1024Store）
本仓库带 dsh-plugin topic，且 package.json 声明了有效的
dsh.bundle.patch（patch 文件随仓库同 revision 提交），可被
awesome-deepseek-harness-plugins
目录的静态校验收录。
在线市场：https://deepseek1024.com/
Docs
What it ports from Reasonix
- One automatic trigger:
compact_ratio (default 0.85), not multiple
soft/snip/force thresholds.
- One structured checkpoint: stable prefix + one summary + recent tail.
- Recent tail budget:
clamp(window×10%, 32K, 96K).
- Checkpoint acceptance: normal candidates ≤ 50% of window and below the
trigger; exceptional fixed-prefix path requires ≥25% savings.
- Canonical transcript preserved: DSH's surface
replace shadows the old
range in the model-visible projection only; the raw session log remains the
source of truth.
- One summarizer call per transaction: no application-layer retry loops.
- Reasonix summary headings:
Standing facts & constraints, Goal,
Decisions & rationale, Files & code, Commands & outcomes,
Errors & fixes, Pending & next step.
Install / build
安装到 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
Note: mounts inside an agent preset's isolated compaction realm replace
compaction-basic there directly; the profile-level bundle patch cannot reach
that realm, so every preset that ships compaction-basic in its own compaction
group must be migrated to this package.
Keep @deepseek-ai/dsh-command-compact in the same realm so /compact uses
this backend. The optional @deepseek-ai/dsh-compaction-tool-result-pruner can
still be mounted as a sibling; this plugin reads it through ctx.get().
Configuration
| Key | Default | Meaning |
|---|
compactRatio | 0.85 | Sole automatic trigger fraction. |
checkpointCeilingRatio | 0.5 | Normal auto-checkpoint acceptance ceiling. |
recentTailRatio | 0.1 | Recent verbatim tail fraction. |
recentTailMinTokens | 8192 | Lower bound for production tail (lowered from upstream 32K so compaction still triggers under token-meter underestimation). |
recentTailMaxTokens | 16384 | Upper bound for production tail (lowered from upstream 96K, same reason). |
summaryMaxTokens | 16384 | Summarizer output cap. |
exceptionalMinSavingsRatio | 0.25 | Required savings when fixed prefix exceeds ceiling. |
minRecentKeep | 2 | Minimum recent messages kept. |
minCompactMessages | 2 | Minimum compactable messages. |
maxPinnedFirstUserTokens | 1500 | Pin first user turn if ≤ this. |
pinnedFirstUserWindowFrac | 0.15 | First-user pin window fraction cap. |
protocolReserveTokens | 256 | Framing reserve. |
summarizationProvider / summarizationModel | '' | Optional summary route; defaults to conversation route. |
auto | true | Register automatic pressure/overflow listeners. |
Modularity
- The plugin only registers
ctx.compaction and its own automatic listeners.
- Realm self-check (since 0.1.11): mounting logs a warning when another
compaction engine already owns
ctx.compaction in the same realm, and if a
later mount supersedes this instance, its automatic listeners stand down
(warn-once, hot-reload aware) instead of racing the new owner. Note a
profile-level bundle patch cannot reach an agent preset's isolated
compaction realm — migrate each preset individually.
- It does not edit
dsh-wsl-bash, dsh-team-dashboard, router-opencode-wsl,
or any other plugin.
- To use it, mount it in your own preset or profile patch; see
cordis.patch.example.yml in this package.
Keeping in sync with Reasonix
scripts/sync-reasonix-compact.mjs and the GitHub Action in
.github/workflows/sync-reasonix-compact.yml watch
esengine/DeepSeek-Reasonix and open/update a PR when the upstream compact
implementation changes. The sync job:
- Fetches the latest
main-v2 Reasonix source.
- Updates
vendor/reasonix/compact/ with the upstream compact files and
design docs.
- Regenerates
src/generated/reasonix-constants.ts from the Go constants and
summary prompt (when they change).
- Commits and opens a PR with a summary of what changed.
The generated constants are imported by this package so tuning values stay
traceable to upstream.
Publish to GitHub / community catalog
This repository is designed to be published as a standalone public GitHub repo.
The 1024Store catalog
discovers public repos with the dsh-plugin topic and statically validates the
dsh.bundle.patch declaration (the patch file must exist in the same tree).
# 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 will:
- Create a public GitHub repo and push this repository.
- Add
dsh-plugin, deepseek-harness, and reasonix topics.
After that, deepseek1024.com lists the entry
(browse-only until the npm package is published; installs come from npm).
License
MIT
