Introduction

DeepSeek Harness (dsh) adopts an “everything is a plugin” architecture and aims to extend system capabilities through plugins. In long conversation scenarios, the model input consists of all historical messages, where tool results (such as search results, file contents, and command output) often occupy most of the context and include many details that are not valuable for subsequent reasoning. In addition, repeated tool calls and verbose responses can continuously bloat the context and even induce dead loops.

dsh-compactor is a context compaction plugin maintained by lionwill. Without breaking the dsh append-only session log, it prunes and summarizes the context through a three-layer processing mechanism (real-time layer, batch layer, and archive layer), and provides dead-loop guardrails and data rollback.

Core Capabilities

The plugin mainly addresses context bloat in long sessions. Its core capabilities include:

  1. Three-layer processing mechanism:

    • Real-time layer: When tool results (tool/result) enter the event stream, prune them according to fixed policies (for example, keep only titles/links for searches, and keep only previews for files).
    • Batch layer: When the session token count exceeds a threshold, replace compressible segments (tool results, verbose responses) with summaries. Compression boundaries are automatically aligned, and the most recent N messages are left untouched.
    • Archive layer: The original replaced content is written to an append-only archive directory and can be fully restored through commands.

  2. Two summary engines:

    • API summary: Depends on DEEPSEEK_API_KEY and calls deepseek-chat to generate skeleton summaries; automatically downgrades when no key is available.
    • Local rule compression: Based on regular expressions and fixed rules (such as collapsing repeated sentences and truncating long output), with no network request required and zero extra dependencies.

  3. Commands and tools:

    • Semantic-aware compaction (/su-compact): Feeds intent and strategy to an LLM to preserve key conclusions.
    • Local rule compression (/local-compact): Executes compression based on a rules file and requires user confirmation.
    • Data rollback (/restore): Reinjects compressed original content into the session.
    • Dead-loop guardrails: Monitors tool calls and injects anti-loop prompts or records cancellation decisions when thresholds are triggered.

Installation and Enablement

The plugin runs with dsh host permissions. Please ensure the source is trustworthy before installation.

Local directory installation (file: protocol) is recommended, avoiding handling of git build scripts:

# 1. 克隆仓库
git clone https://github.com/lionwill/dsh-compactor.git
cd dsh-compactor

# 2. 构建产物（lib/ 目录由 prepare 钩子自动生成）
npm install && npm run build

# 3. 安装插件
dsh plugin add "dsh-compactor@file:$PWD"

Commands and Usage

After installation, dsh explicitly re-enables the built-in /compact command through a bundle patch. This plugin adds the following commands:

  1. Local rule compression:
    The first call only outputs a risk explanation and must be confirmed by the user before execution:
    /local-compact confirm
  1. Semantic-aware compaction:
    Uses an LLM to understand the intent of the context and generate a summary:
    /su-compact
  1. Data rollback:
    Restores data from the most recent compaction operation:
    /restore

Configuration

The plugin can be configured via cordis.patch.yml (built-in) or environment variables. The main configuration options include:

  • thresholdTokens: token threshold that triggers compaction (default 32768).
  • targetTokens: target token count after compaction (reference value).
  • qualityThreshold: alert threshold for the retention rate of key information (default 0.85).
  • exemptTools: list of exempt tools (defaults write, edit, task).
  • localRulesPath: custom path to a local rules file.

Example configuration fragment:

- insert:
    - id: dsh-compactor
      name: dsh-compactor
      config:
        thresholdTokens: 32768
        targetTokens: 8192
        retainRecentRounds: 3
        qualityThreshold: 0.85
        exemptTools: [write, edit, task]
        enablePruning: true
        enableSummary: true

Notes

  1. Information loss: Compaction is a process of “retaining the skeleton and discarding details.” Details such as snippet and middle sections of long outputs may be lost. If subsequent reasoning depends on these details, result quality may degrade.
  2. Token estimation bias: The plugin uses heuristic methods to estimate tokens, which may differ from actual billed tokens.
  3. Permission risk: The plugin runs with host permissions. It is recommended to install only from trusted sources and pin the version.
  4. Archive directory: The default is $DSH_DATA_DIR/archive/ or ./.dsh-compactor-archive/. Ensure the directory is writable and do not edit it manually.
  5. Command conflict: This plugin explicitly re-enables the built-in /compact command in dsh through patching. If other plugins that also register the same /compact command are installed simultaneously, command conflicts may occur and cause the command to fail.
  6. Hot reload: After modifying the rules file, there is no need to restart the session; each execution of /local-compact rereads it.