Preface

DeepSeek Harness (DSH) adopts a plugin-based architecture, aiming to address Token overhead in long sessions through extensible components. As a layered Token optimization pipeline, dsh-token-optimizer does not reimplement the compression capabilities already provided by the DSH core. Instead, it uses real API calls to implement incremental compression and scheduling, helping reduce Token consumption while preserving model capabilities.

Plugin Positioning

  • Name: dsh-token-optimizer
  • Maintainer: Zoria-Lind
  • Category: Model inference
  • License: MIT
  • Positioning: An incremental compression and scheduling plugin based on the DSH plugin API.

Core Features

This plugin coordinates multiple modules to cover four dimensions: text processing, tool output, file management, and session scheduling:

  1. Layered Compression Orchestration (layeredCompact): Implements a tiered strategy with L0 observation, L1 lossless trimming, and L2 lossy compression.
  2. Long-Text-to-Image Summarization: For long text (≥1000 characters), it supports rendering the text into an image for a Vision model to read and generate summaries, with dynamic resolution adjustment.
  3. Tool Output Routing: Performs structure-aware compression or sampling based on output type (error results, JSON/CSV, Shell output).
  4. File Diff Detection: Detects repeated file-read operations; if the file is unchanged, it collapses the read result, and if changed, it sends only the changed sections.
  5. Tool Visibility Management: Reduces unnecessary tool Schemas from entering requests through static trimming and MCP lazy loading.
  6. Compression Scheduling: When the Agent is idle, it drives core compression using a custom pressure ratio, addressing the issue that long-session windows may fail to trigger compression.
  7. Session Statistics: Provides post-session Token savings statistics, real Usage aggregation, and cache hit rate.

Installation

Run the following command in the DSH project directory to install the plugin:

dsh plugin --profile web add ./dsh-token-optimizer

Configuration

After mounting the plugin, configure it in the Profile’s cordis.patch.yml. Since the Web deployment disables the core compression backend by default, it must be enabled manually:

- id: compaction-basic
  disabled: false
- id: command-compact
  disabled: false

The main configuration sections of the plugin include:
* text2img: Controls the threshold, resolution tiers, and caching strategy for long-text-to-image summarization.
* outputLadder: Configures the compression ratio, the number of leading and trailing lines to preserve, and the Shell sampling interval.
* fileDiff: Sets the minimum size and context lines for file diff detection.
* toolTrim: Controls tool visibility management and the MCP lazy loading switch (disabled by default).
* compactionDriver: Sets the pressure ratio for triggering compression (default 45%) and the minimum Token count.

Permissions and Boundaries

This plugin is a high-privilege plugin and requires access to files, network, commands, and credentials at runtime. Its specific behavioral boundaries are as follows:

  • File Boundaries: Writes only to the plugin’s own state directory (~/.dsh/token-optimizer/) and temporary artifacts; it does not modify Profile configuration or the DSH core.
  • Network Boundaries: Sends requests only to https://api.deepseek.com/v1 (for summarization).
  • Command Boundaries: Uses PowerShell + .NET System.Drawing for text rendering on Windows; on non-Windows systems, it automatically degrades to disk-only operation.
  • Credential Boundaries: Used only for text2img Vision calls; credentials are not persisted or sent externally.
  • Failure Boundaries: All modules adopt a Fail-open strategy. If any step fails, the operation degrades by skipping it (preserving the original text) without affecting the core workflow.
  • Runtime Dependencies: Zero npm dependencies (except for external services).

Compatibility Scope

  • DSH Version: Based on DSH >= 0.1.1-rc.2.
  • Node Version: Node >= 18.
  • Known Unvalidated Versions: Compatibility with 0.1.2+ and 0.1.3+ has not been validated yet.

Conclusion

Through layered compression, intelligent routing, and lazy loading mechanisms, dsh-token-optimizer provides a targeted Token optimization solution for DSH. Its fail-open design ensures availability in unstable environments. For the full source code and documentation, refer to the GitHub repository.