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 创意工坊

本仓库打上 dsh-plugin topic 后，会被 DSH 创意工坊 自动扫描收录。 在线地址：https://JxaMe.github.io/dsh-workshop/

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

也可以从 GitHub 安装：

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

本地开发 / 构建

pnpm install
pnpm build

然后在 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: 32768
    recentTailMaxTokens: 98304
    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: 32768
    recentTailMaxTokens: 98304
    summaryMaxTokens: 16384

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

Modularity

• The plugin only registers ctx.compaction and its own automatic listeners.
• 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 / DSH Workshop

This repository is designed to be published as a standalone public GitHub repo. The DSH creative workshop discovers public repos with the dsh-plugin topic.

# 1. Authenticate GitHub CLI once
gh auth login

# 2. From this repository root, publish and add workshop 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, the workshop index at https://JxaMe.github.io/dsh-workshop/ will pick it up automatically (it scans dsh-plugin topic repositories).

License

MIT