简体中文 # dsh-context-triage A session context triage plugin for DeepSeek Harness (dsh) that automatically manages context volume during long sessions: it identifies and handles stale, duplicate, failed, oversized, and low-value message content to save token budget and curb context bloat. ## Features - Deterministic, zero model dependency: all verdicts and rewrites are produced by heuristic rules—no LLM calls, no extra services; behavior is predictable and testable offline. - Five Screeners, each independently switchable: | Screener | Verdict rule | Handling action | | --- | --- | --- | | Stale output staleOutput | Tool call pairs more than N turns after the latest user message, with results still complete | Call block rewritten to an archive summary, result block removed | | Repeated call repeatedCall | Call pairs with the same tool and same arguments (JSON key order irrelevant) | Only the most recent is kept; older call pairs are cut | | Failed call failedCall | Stale error results (isError) | Input arguments replaced with a failure stub (prevents leakage / saves space), error text kept and trimmed | | Oversized block oversizedBlock | Tool result text exceeds the character cap | Head/tail trimmed, middle annotated with the omitted amount | | Stale reasoning staleReasoning | Reasoning blocks beyond the retention turns; kept blocks exceeding the length cap | Removed; or trimmed (within the reserve region only trim, never delete) | - Reserve area (reserve): content within the most recent N user turns is never touched, avoiding disruption of context the model is currently using. - Exemption list (exempt): two-dimensional tool-name and file-path glob exemption (protects stateful tools like task/skill/todowrite/todoread/write/edit/batch by default). - "Worth it" check: any archive/stub action requires the rewrite to be strictly smaller than the original, ruling out changes that cost more; call-pair-level actions (archive = rewrite + cut) take effect or are abandoned as atomic groups. - Audit report: every triage outputs structured statistics—counts and savings per reason, per-item details, and suggested compression ranges; visible through the tool, the command, and the CLI. - Native integration with the dsh compression seam: implements ctx.compaction (CompactionEngine); auto-pressure, context overflow, manual, and forced region compression all go through the official harness mechanism. Replacement summary messages use a checkpoint source recognized by any backend-agnostic consumer. ## Installation and mounting The plugin is distributed as a bundle: dsh.bundle.patch in package.json points to cordis.patch.yml (the patch inserts the plugin line; config can be overridden on the line). ### Installing in DSH bash dsh plugin --profile demo add github:JohnXu22786/context-pruner Option 1 (mount from a local directory, recommended): bash dsh plugin --profile web add link:/absolute/path/context-pruner Option 2 (manual patch): merge the entry in cordis.patch.yml into the profile's cordis.patch.yml, or launch it directly as an overlay: bash dsh web --patch ./cordis.patch.yml Option 3 (git source): bash dsh plugin --profile web add "github:your-repo/context-pruner#main" After mounting, use dsh --profile web --dump-config to check whether the plugin line reaches the startup tree. > Note: ctx.compaction allows only one provider per context. If your profile already loads another compression implementation (e.g., the built-in base compression backend), disable one of them via the patch's disabled: true—they cannot coexist. ## Interface ### Entry point (manifest) | Item | Value | | --- | --- | | Package name | dsh-context-triage (dsh.bundle.patch in package.json declares the bundle) | | Main entry | lib/index.js (main/exports; ./core and ./dsh subpaths available for embedders) | | Plugin name | context-triage | | Dependency injection | tools (required); the command registry is optionally probed via ctx.get('commands'), silently skipped if absent | | Config | Exports Config (Schemastery Schema); defaults in the config table below | The plugin is a functional plugin: it exports name / inject / Config / apply(ctx, config), called by cordis after validating config and filling defaults. ### Provided extension points | Extension point | Description | | --- | --- | | Service ctx.compaction | TriageCompactionEngine extends CompactionEngine, implementing compactIfNeeded (auto-pressure / overflow), compactNow (manual idle compression), compactRegion (forced region compression) | | Tool triage_history | Model-visible; parameter dryRun?: boolean. Runs one triage and returns the audit report to the model; with dryRun=false and a worth-handling region present, applies it directly | | Command /triage | Human command, bypasses the model; outputs the audit report and applies worthwhile handling | ### How a compression transaction lands Triage results are written to the session log as a standard compression transaction (append-only; history is not rewritten): 1. compaction/start (holds the lock until the paired compaction/end) 2. compaction/summary (summary content, masked regions, masked seq list, and heuristic token cost; llmStreamCall absent = non-model summary) 3. user/message + surfaceOp: { op: 'replace', start, end } + sourceEventSeqs (replacement summary message, source is the checkpoint source) 4. compaction/end The model-visible history is derived from the session log; after the replacement, deriveMessages() naturally yields [summary message, ...retained content]—no in-place modification of historical records is needed. ## Configuration All fields have defaults; only override what you want to adjust. Invalid values (negative turns, out-of-range ratios, etc.) throw at load time. Example: yaml # cordis.patch.yml - insert: id: context-triage name: dsh-context-triage config: budget: contextTokens: 200000 # lower for smaller-context models softRatio: 0.6 screeners: staleOutput: { turns: 5 } staleReasoning: { enabled: false } exempt: tools: [task, skill, write, edit] | Field | Default | Description | | --- | --- | --- | | enabled | true | Master switch | | reserve.turns | 3 | Reserve area: content within the most recent N user turns is not processed | | budget.contextTokens | 1000000 | Estimated context window (tokens); determines the pressure ratio | | budget.softRatio | 0.7 | Usage above this ratio → auto-compression triggers (pressure) | | budget.hardRatio | 0.9 | Usage above this ratio → pressure report marked forced (hard) grade | | budget.minSavingsTokens | 2000 | No action when estimated savings are below this | | screeners.staleOutput.turns | 8 | Call pairs more than N turns after the latest user message are archived | | screeners.repeatedCall.enabled | true | Repeated calls cut | | screeners.failedCall.turns | 4 | Failed-call handling threshold (turns) | | screeners.failedCall.errorKeepChars | 400 | Error text kept for failed calls (chars) | | screeners.oversizedBlock.capChars | 6000 | Tool result text cap (chars); beyond it, head/tail trimmed | | screeners.oversizedBlock.headChars / tailChars | 800 / 400 | Head/tail length kept during trimming | | screeners.staleReasoning.keepTurns | 3 | Keep reasoning blocks within the most recent N user turns | | screeners.staleReasoning.maxBlockChars | 2000 | Length cap for kept reasoning blocks; beyond it, trimmed | | exempt.tools | [task, skill, todowrite, todoread, write, edit, batch] | Exempt tool names | | exempt.filePatterns | [] | Exempt path globs (match call arguments filePath/path), e.g. ['**/*.lock'] | | summary.capChars | 20000 | Compression summary char cap | | summary.headRatio | 0.4 | Head retention ratio when trimming the summary | ## Local experience (no dsh required) src/core is a framework-agnostic engine with an offline replay CLI; it runs directly against a JSONL session file: bash npm install npm run build node lib/cli/replay.js examples/session.sample.jsonl --config examples/demo.config.json node lib/cli/replay.js examples/session.sample.jsonl --config examples/demo.config.json --show-transcript Replay format (one JSON event per line; seq determined by line order): jsonl {"type":"user/message","text":"项目构建失败了"} {"type":"assistant/message","reasoning":"…","calls":[{"id":"c1","name":"bash","arguments":"{\"cmd\":\"npm run build\"}"}]} {"type":"tool/result","callId":"c1","text":"…","isError":false} Sample output in examples/report.example.md; tests cover all screeners, merge priorities, atomic groups, audit consistency, and end-to-end replay (npm test). ## Design trade-offs - Token estimation is heuristic: CJK ≈ 1 token/char, others ≈ 4 chars/token; used only for pressure verdicts and audit statistics, not for billing. Configure budget.contextTokens per your actual model window. - Rewrites always yield net savings: archive summaries, failure stubs, and trimming all compare the sizes before and after the action; unattractive findings are automatically abandoned. Call-pair actions are judged as atomic groups, so there is no half-done state like "summary kept, result split." - Prompt caching: compression changes the message sequence, invalidating the prompt cache prefix after that point. In long sessions, saved tokens usually vastly outweigh cache recomputation cost; for pay-per-request providers (no cache billing) it is pure gain. - Never touches user input: the oversized-block screener only acts on tool results; user messages are never rewritten unless the whole reserve region covers them. ## License Released under the MIT License.