dsh-zcode-breaker
DeepSeek Harness 自动压缩的快速补充断路器：停止无效的“压缩-补充-压缩”循环。该循环没有尝试次数上限，每一步都会消耗一次摘要调用，并告知用户是哪个过大的读取结果或工具输出导致了该问题。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:BOWLUNA/dsh-zcode-breaker#06db74698ff97e5bf5428479707800e916be154aZcode Breaker 以 dsh-zcode-breaker 发布，当前版本为 1.0.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
A rapid-refill circuit breaker for DeepSeek Harness automatic compaction: it stops the futile compact-refill-compact loop and tells the user which oversized read or tool output caused it. Derived from the ZCode implementation of the same idea.
Automatic compaction has two trigger paths in @deepseek-ai/dsh-compaction-basic:
| Trigger | Entry point | Attempt bound |
|---|---|---|
| Step-boundary pressure | agent/pre-step calls compactIfNeeded(agent, "pressure") | none |
| Context-overflow recovery | agent/request-error calls compactIfNeeded(agent, "context-overflow") | maxOverflowRetries |
The pressure path is unbounded: once measured pressure exceeds thresholdRatio, the next step compacts again, and every compaction is a full summarization model call. One oversized file read or tool output therefore produces a loop that burns a model call per step until the session is abandoned, and the transcript shows only this repeating line:
compaction (step pressure): shadowed N surface nodes (seqs A-B, ~T tokens)
It extends BasicCompactionEngine and wraps exactly one method, compactIfNeeded:
toolTurnThreshold tool turns after the previous one counts as a rapid refill.maxConsecutiveRapidRefills in a row the attempt is refused before it runs, so the summarization call is never spent.CompactionRapidRefillError carrying actionable advice.compactIfNeeded and continues the turn: a thrown error alone would leave the person with no explanation./compaction-breaker reports the state and can re-arm it.Everything else stays the base engine's: trigger policy, retention, surface mutation, tool-pairing safety and summarization.
compaction-basic exists twice in a stock harness: once as a host-plane row in @deepseek-ai/dsh-base, and once inside the agent preset's compaction group, which is declared isolate: { compaction: true, toolResultPruner: true }. An agent session resolves ctx.compaction inside that isolated realm, while a session that joins no preset resolves the host row. That is why a profile patch alone cannot change an agent's compaction, and why the preset row in the second half of this section exists.
The seam is single-slot: a second provider in the same isolate scope makes ctx.provide() throw, and ctx.reflect.set() accepts writes only from the owning fiber. Each plane is therefore covered by replacing its row, never by shadowing it.
| Plane | Who it serves | How this package covers it |
|---|---|---|
| Host | sessions that join no agent preset | automatically, through the bundle patch the installer mounts |
| Agent realm | every ordinary session | one row replaced inside your agent preset, because no profile patch can reach a realm |
dsh plugin --profile web add dsh-zcode-breaker
The install mounts cordis.patch.yml, which disables the host-plane compaction-basic row and puts this engine in its place. Replacing rather than wrapping is forced by the single slot.
Then, for agent sessions, replace the row inside your preset's compaction group in agent.cordis.yml:
- id: compaction
name: cordis:group
group: true
isolate:
compaction: true
toolResultPruner: true
config:
- id: compaction-breaker
name: 'dsh-zcode-breaker'
config:
toolTurnThreshold: 2
maxConsecutiveRapidRefills: 3
- id: command-compact
name: '@deepseek-ai/dsh-command-compact'
Copy the preset into your user preset directory rather than editing the shipped one, or a harness upgrade will overwrite the edit.
Every base-engine key survives, re-declared on the subclass so it is neither rejected by the base engine's strict validator nor lost:
| Key | Default | Meaning |
|---|---|---|
thresholdRatio | 0.8 | pressure ratio that triggers compaction |
retainRatio | 0.16 | retained tail ratio after compaction |
retainTokens | none | absolute token retention instead of the ratio |
summarizationProvider | empty | route used for summaries |
summarizationModel | empty | model used for summaries |
maxTokens | 8192 | summary output cap |
compactionRetries | 1 | retries after a failed summary |
maxOverflowRetries | 1 | overflow-recovery retries |
modelPolicies | none | per provider and model overrides of the keys above |
auto | true | automatic compaction master switch |
Added by this plugin:
| Key | Default | Meaning |
|---|---|---|
toolTurnThreshold | 2 | a gap under this many tool turns is rapid; exactly the threshold is not |
maxConsecutiveRapidRefills | 3 | refuse on the Nth consecutive rapid refill |
announceInPrompt | true | inject the advisory prompt section once tripped |
That is 13 config keys in total, and this file declares compatibility with dsh >=0.1.5-rc.2 <0.2.0-0.
| Surface | What it shows |
|---|---|
| Log | one warn line naming the consecutive count, the threshold and the last gap |
/compaction-breaker | a state report; /compaction-breaker reset re-arms |
| Prompt section | injected while tripped, instructing the model to relay the situation |
/compact. A person deliberately compacting is new information and should not be refused because of what the automatic path did earlier.A trip is not a global disable: the session keeps working, only automatic compaction is off for it.
ctx.compaction slot, and none of them can be mounted alongside this engine. That is a limitation of the seam rather than a choice made here.ctx.compaction is not reliably the one whose private initializers ran, and a private-field read would throw inside the compaction path where the host swallows it.ctx.compaction inside a real realm is verified; see docs/MEASUREMENTS.md.The policy core is exported so another backend can adopt it in roughly twenty lines:
import { RapidRefillTracker } from 'dsh-zcode-breaker/tracker';
const tracker = new RapidRefillTracker({ toolTurnThreshold: 2, maxConsecutiveRapidRefills: 3 });
tracker.noteToolTurn();
const gate = tracker.gate();
if (gate.blocked) throw new Error('rapid refill loop');
const result = await myEngine.compact();
if (result !== null) tracker.commitCompaction(gate.projectedConsecutiveRapidRefills);
npm test
19 tests in 2 suites, with no services, no model and no session: the policy core in test/tracker.test.js and the engine wiring in test/engine.test.js. The wiring suite needs the peer packages resolvable and skips rather than fails where they are missing.
@deepseek-ai/dsh-compaction-basic.MIT