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

• 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: 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:

1. Fetches the latest main-v2 Reasonix source.
2. Updates vendor/reasonix/compact/ with the upstream compact files and design docs.
3. Regenerates src/generated/reasonix-constants.ts from the Go constants and summary prompt (when they change).
4. 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:

1. Create a public GitHub repo and push this repository.
2. 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