dsh-compaction-instant
VCC 风格的即时、近乎无损的确定性压缩引擎，适用于 DeepSeek Harness——可直接替代 @deepseek-ai/dsh-compaction-basic
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:KitDoesIt/dsh-compaction-instant#03a53466b1d7eaef18e5b35f9f0d8be4f5ff41f0Compaction Instant 以 dsh-compaction-instant 发布，当前版本为 0.1.4。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Instant, near-lossless context compaction for DeepSeek Harness — a drop-in replacement for @deepseek-ai/dsh-compaction-basic that replaces LLM summarization with the deterministic conversation-compiler principle of lllyasviel/VCC.
A compaction compresses a shadowed history span in milliseconds, with zero model calls, keeping original tokens only — no paraphrase, no hallucination, no summarizer cost. Everything that is cut is still recoverable through (seq N) pointers into the durable session log.
seq, and prior checkpoints are copied verbatim.compaction-basic; every built-in preset loads it unchanged (alias install).A region containing a user request, an assistant text + tool call, and its result compiles to:
[user]
please fix the bug
[assistant]
on it
* read "a.js" (seq 2 -> result 3)
[user]
next question
Every tool call is ONE line: the key argument for whitelisted tools (toolArgTools), name-only for the rest (* job_kill (seq 9 -> result 10)), nothing at all for hideTools rows. Tool results never occupy entries — the -> result N pointer keeps them one recall(type:"result") away. Long user/assistant text is truncated to its budget with ...(truncated from seq N); every elision names the durable event that still holds the full content.
The package also ships the counterparts that close the near-lossless loop — same-session recall for the agent and the human. Because the session log is append-only, every token the compiler ever elided is still recoverable:
| Entry point | Module | What it does |
|---|---|---|
recall tool (model-facing) | dsh-compaction-instant/tool | Typed restore: type:"seq" with (seq N)/(seqs A-B) markers, type:"result" with the result N pointer, type:"checkpoint" with a [checkpoint N] ordinal — restores exact original content into the current tool result |
search tool (model-facing, grep) | dsh-compaction-instant/tool | Keyword/regex search over the whole durable log — including content elided by compaction — returning matching events with their (seq N) pointers, ready for recall |
/recall command (human, grep) | dsh-compaction-instant/command | `/recall <keyword |
| Shared cores | dsh-compaction-instant/recall + dsh-compaction-instant/search | Seq parsing (12, 3-7, seq 12 / seqs 3-7), log expansion, budgets, projection; regex compilation and hit rendering |
Recall keeps everything: text, reasoning, raw tool-call arguments, nested tool-result content; log-only events render as labeled data dumps; missing seqs are reported; a maxRecallTokens budget (default 16000) cuts with a provenance marker and counts the skipped remainder; searches cap shown hits (maxSearchHits, default 50). Both plugins are separate rows, so they can be mounted next to any compaction backend — they only read the durable log.
Every checkpoint also frames a short RECALL guide at its head, telling the model exactly how to use recall / search to recover elided content. When a prior checkpoint is elided under cap pressure it never vanishes silently: it leaves a single [checkpoint N] line (N = compaction ordinal, 1 = oldest), which recall(type:"checkpoint", id:"N") restores in full.
All fields optional; defaults shown.
| Key | Default | Meaning |
|---|---|---|
thresholdRatio | 0.5 | Fraction of the routed model's context window that triggers automatic compaction |
retainRatio | 0.05 | Fraction of the context window kept verbatim at the surface tail |
retainTokens | — | Exact tail budget; mutually exclusive with retainRatio |
manualRetainRatio | 0.05 | Fraction of the measured surface kept verbatim by a manual /compact (so the recent conversation is never compiled away) |
manualRetainTokens | — | Exact manual tail budget; mutually exclusive with manualRetainRatio |
auto | true | Register agent/pre-step pressure and agent/request-error overflow recovery |
maxTokens | 8192 | Floor of the total cap for one compiled checkpoint (density-aware tokens) |
checkpointScale | 0.1 | The effective cap is max(maxTokens, shadowed × checkpointScale), ceilinged at checkpointCap — a large span never crushes every entry into a sliver |
checkpointCap | 65536 | Absolute ceiling of the scaled checkpoint cap |
textTokens | 512 | Budget per assistant text block |
userTextTokens | 1024 | Budget per user text block |
toolCallTokens | 128 | Budget per tool-call one-liner (never rescaled — see the elision rules) |
toolResultExcerptTokens | 256 | Accepted for compatibility; inert — tool results no longer occupy entries |
includeReasoning | false | Keep reasoning blocks in the checkpoint |
The tool and command plugins each take their own { maxRecallTokens?: 16000, maxSearchHits?: 50 } config.
Cordis config gotcha: the plugin row's config passes through the schemastery schema, whose
~standardadapter injects[]for every absent array key (toolArgTools,hideTools,noisePatterns,toolKeyFields,modelPolicies). The resolver treats an empty list as unset and falls back to the defaults — so a missingtoolArgToolskeeps the built-in whitelist (never disable it by writingtoolArgTools: []; empty means default).debug: truewrites per-compile diagnostics to the configureddebugLogPath(default$DSH_HOME/compaction-debug.log).
Budgets are enforced twice — by token count and by a budget × 4 character ceiling — so pathological unbroken runs (base64 blobs, minified files) cannot bypass them. Tool calls are always one line: they are never rescaled, and the cap loop shrinks only the conversation-text budgets (floor 32 tokens each). If the compiled region still exceeds the (scaled) cap, the oldest tool rows are removed first ([N tool/result entries elided: seqs a-b]), and only then the oldest remaining entries ([N earlier entries elided: seqs a-b]) — tool calls can never squeeze the dialogue out. The newest content always survives.
Since 0.1.4 the engine exposes a user-owned settings namespace (compaction-instant) on every deployment that composes the settings domain (the standard web/desktop profiles do). The editable subset, persisted to settings.yaml and layered over the plugin row's cordis config:
| Field | Meaning |
|---|---|
checkpointScale | Checkpoint budget = shadowed tokens × this ratio |
checkpointCap | Absolute ceiling of the scaled budget |
maxTokens | Total compiler-token cap for one checkpoint |
auto | Register automatic between-step compaction |
debug | Write engine debug lines to the log file |
debugLogPath | Debug log path (empty = $DSH_HOME/compaction-debug.log) |
Everything else (modelPolicies, toolArgTools, …) stays cordis-config-only. The settings layer never breaks the engine: every settings write is re-validated by the full config resolver before it is persisted, and non-exposed entry fields keep their composed values. Without a settings service the engine behaves exactly as before (composition entry only). The card is registered on the client bundle, so it appears without touching any deployment config beyond installing the package — restart dsh web once so the boot graph picks up the dsh.client bundle.
The tokenizer is a character-class heuristic: ASCII letter runs and digit runs count as one token each, punctuation is per-character, whitespace is free, and every other code unit is its own token. Concretely:
| Content | Tokens |
|---|---|
CJK (你好，世界！) | 1 per code point (6) |
| Cyrillic / Arabic | 1 per code unit |
Accented Latin (café) | ASCII runs stay grouped (caf + é) |
Emoji (😀) | 2 (surrogate pair) |
Every truncation, excerpt, and cap cut is taken at a code-point boundary — a slice never leaves a lone surrogate half, so emoji and other astral characters always reach the model intact (pinned by test/multilang.test.js). The character-density ceiling uses UTF-16 length, which is the conservative side for astral content.
The harness token meter (used for the shrink guarantee and /compact reporting) is a separate chars / 4 + block overhead estimator; the two deliberately coexist — see the top-level design notes.
seq; prior checkpoints are copied verbatim.ctx.tokenMeter), and failure vocabulary as compaction-basic, including the shrink guarantee (a checkpoint that would not reduce the surface is rejected).toolResultPruner service exactly like basic (it helps the retained tail; the compiler collapses the shadowed region).Rates measured on real session logs (this project's own development sessions), compiled without dropping a single entry — every row survives, only per-entry truncation and one-line tool rows apply. Percentages are of the original token count.
| Load | Raw tokens | Compiled | Retained | Compressed |
|---|---|---|---|---|
| Tool-dense session, full (3,181 nodes: 1,438 tool calls + 1,540 results) | 2,523,012 | 226,205 | 9.0% | 91.0% |
| Another session, full (864 nodes) | 685,088 | 62,705 | 9.2% | 90.8% |
| Same tool-dense session, recent 800 messages | 625,927 | 45,031 | 7.2% | 92.8% |
| Pure text only (same session minus all tool rows) | 160,963 | 109,945 | 68.3% | 31.7% |
Where the ratio comes from (no drops):
-> result N pointer keeps each one one recall away. That is the biggest win.Budget scan (same 2.5M-token tool-dense session): dropping starts at a cap of ~226K tokens (9% of the raw size — close to the default checkpointScale of 0.1, but the 64K hard cap cuts it short). Below that the cost is a cliff, not a slope:
| Cap | Compiled | Retained | Entries | Dropped |
|---|---|---|---|---|
| 8,192 | 8,243 | 0.33% | 111 | 2,090 |
| 32,768 | 22,263 | 0.88% | 232 | 1,969 |
| 65,536 (deployment default) | 55,737 | 2.2% | 325 | 1,876 |
| 65,536 | 55,737 | 2.2% | 325 | 1,876 |
| 131,072 | 131,047 | 5.2% | 1,142 | 1,058 |
| 226,205 (no-drop threshold) | 226,205 | 9.0% | 2,199 | 0 |
All three methods below install the package (published to npm as dsh-compaction-instant) with the harness's own plugin manager (which runs pnpm inside the profile directory, making the package resolvable to both the host composition and every agent preset):
dsh plugin --profile web add <spec>
dsh-command-compact (/compact) is backend-independent, so it keeps working unchanged in every method.
dsh plugin --profile web add "@deepseek-ai/dsh-compaction-basic@npm:dsh-compaction-instant"
dsh currently has no way to choose the compaction engine, and the built-in agent presets (standard, code, cordis) pin the package name @deepseek-ai/dsh-compaction-basic in their compositions. To use this engine inside those built-in presets you therefore masquerade as the built-in plugin: preset rows resolve bare package names from the profile's node_modules (which outranks the harness installation), so installing our package under the built-in name makes every built-in preset load this engine automatically — no preset files are touched, and preset upgrades keep working.
The masquerade is safe by construction: this engine is a contract-exact drop-in — the same ctx.compaction seam, the identical inject list (llm, tokenMeter, sessions), the same event protocol and error vocabulary, and its Config accepts every key of basic's configuration surface. Removing the alias dependency restores the real basic.
This install is not recognized as a bundle (the harness resolves the name @deepseek-ai/dsh-compaction-basic from its own installation, which declares no dsh.bundle), so nothing is automatic — add the recall tools and /recall command to the profile's cordis.patch.yml yourself (new rows ride an insert list; the file hot-reloads, no restart needed). Row names must use the alias package name, the only one resolvable in this install; the engine row is optional, needed only as a host fallback for presets without compaction (e.g. minimal):
- id: compaction-basic
disabled: true # host-level swap (optional fallback)
- insert:
- id: compaction-instant
name: '@deepseek-ai/dsh-compaction-basic' # host fallback for presets without compaction
- id: tool-recall
name: '@deepseek-ai/dsh-compaction-basic/tool'
- id: command-recall
name: '@deepseek-ai/dsh-compaction-basic/command'
dsh plugin --profile web add dsh-compaction-instant
Then open a session with the preset-authoring preset (the shipped cordis preset, "creation mode") and ask the AI to:
Copy the
standardpreset and swap its compaction engine row todsh-compaction-instant.
The AI uses agentPresets.copy('standard', '<id>') to create a locally authored preset, swaps the compaction row's name in the copy, mount-validates it with standingKeyFor('<id>'), and can set it as the default by patching the agent-presets row (config.default: <id>). The new preset appears in the UI picker; the built-in presets stay untouched.
Since v0.1.1 the package also declares dsh.bundle, so the direct install registers itself as a profile layer automatically: the built-in summarizer row is disabled and the instant engine + recall tools are inserted host-side (see cordis.patch.yml in the package). No manual patch rows needed for the host; only the preset copy above.
dsh plugin --profile web add dsh-compaction-instant
mkdir -p "$DSH_HOME/.agent-presets/<id>"
# copy composition + metadata from the built-in preset you want as a base
# (the preset roster lists every preset's real path):
cp <built-in-preset>/agent.cordis.yml "$DSH_HOME/.agent-presets/<id>/agent.cordis.yml"
# write preset.yml beside it with name + description
Then hand-edit the copy's compaction group — one row name change, inside the same isolate realm:
- id: compaction
name: cordis:group
group: true
isolate:
compaction: true
toolResultPruner: true # the pruner must share this realm
config:
- id: compaction-instant
name: dsh-compaction-instant # was '@deepseek-ai/dsh-compaction-basic'
- id: command-compact
name: '@deepseek-ai/dsh-command-compact'
# ... keep the pruner row
Rules: never edit the shipped preset install; keep the isolate realm; a successful standingKeyFor mount (or simply starting a session on the preset) is the real validation — the roster's broken flag only catches parse errors.
No host-level rows are needed for Methods 2 and 3: the dsh.bundle mentioned above registers everything automatically.
| Method | Engine in built-in presets | Touches preset files | Extra preset in picker | Setup effort |
|---|---|---|---|---|
| 1. Alias replace | ✅ automatic (standard/code/cordis) | no | no | one command + patch rows |
| 2. AI-authored copy | only the new preset | the copy | yes | one prompt |
| 3. Manual preset | only the new preset | the copy | yes | manual edit |
Only one
ctx.compactionimplementation may be mounted per context (the seam documents "load one implementation per context"); preset mounts keep their own isolate realm, so host and preset instances never collide.
npm test # node --test (compiler units, config validation, session integration, engine)
npm run check # node --check over all sources
The package is dependency-light: @deepseek-ai/schemastery for the Config schema; everything else is a peer (the harness provides it). src/compiler.js is deliberately dependency-free so it is unit-testable without a running harness.
/compact keeps a verbatim recent tail (manualRetainRatio, default 0.05 of the measured surface) instead of compiling the whole history, so the active conversation is never compacted away; the compiled checkpoint only covers the older span.compaction/summary event carries the compiled entries themselves — the UI's expandable checkpoint row shows exactly the body the model sees, wrapped in an adaptive Markdown code fence (the fence grows longer than any ``` inside, so messages containing markdown render as one tidy code block), and the checkpoint heads with a short RECALL guide telling the model how to recover elided content via recall / search.retainRatio and manual manualRetainRatio) is where active work lives, and everything else stays recoverable through (seq N) pointers + recall.MIT licensed.
stripNoiseXml | true | Strip configured noise wrappers from user text |
noisePatterns | see compiler | Noise XML regex sources, applied with the s flag |
toolKeyFields | built-ins | Extra tool-name → argument-field map for one-liners |
toolArgTools | see compiler | Whitelist whose key argument renders in the one-liner (read/write/edit/glob/grep/bash/shell/web_search/skill/subagent/…); every other tool is name-only |
hideTools | — | Bookkeeping tools dropped from the checkpoint entirely |
modelPolicies | — | Per provider/model overrides of thresholdRatio/retain* (basic-compatible shape) |
compactionRetries / maxOverflowRetries | 1 / 1 | Retry budgets, same semantics as basic |
summarizationProvider / summarizationModel | — | Accepted for config drop-in compatibility; inert — this backend never routes a model |