dsh-compaction-cacheaware

August 27, 2026 · View on GitHub

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

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

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: $\text{clamp}(\text{window} \times 10%, 32\text{K}, 96\text{K})$ .
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