Foreword

DeepSeek Harness (DSH) adopts an “everything is a plugin” architecture. For plugins that still rely on the legacy Claude Code or Codex ecosystem, direct integration often has compatibility issues. @rvaim/dsh-compat provides a compatibility layer that ingests these legacy plugins as complete lifecycle units into DSH, enabling them to be managed, run, and updated as a whole, just like native plugins.

Core Features

Separated Management of Source and Plugin

Plugins distinguish two concepts: Source is responsible for fetching and caching content (Git repository, local directory, or archive), while Plugin is responsible for runtime behavior. A single Source can contain one or more Plugins.

Supported Sources and Formats

Supports Git URLs, github: shorthand, local directories, and ZIP/TAR/TGZ archives.
Supports Claude Code, Codex Marketplace, and hybrid Marketplaces. Without a Marketplace, it identifies a single plugin in the root directory.

Lifecycle Operations

Supports atomically installing one or more Plugins at a time. Provides overall enable, disable, update, check, and uninstall functions. Changes are not committed if installation fails.

Capability Adaptation

Supports discovery and adaptation of capabilities such as Skill, MCP (stdio and streamable-http access), Hook (including parameter boundaries, event mapping, and timeout control), Command, and Agent.

Installation

Install to the specified profile via npm:

dsh plugin --profile web add @rvaim/dsh-compat@latest

After the first installation or upgrade, you need to restart the profile and reload the Web page, because the DSH Host/Client plugin graph has changed.

Usage

Web UI Management

After starting the profile, open “Compatible Plugins” in DSH Web settings. Click “Add” and enter a source (Git URL, local path, or archive). Single-plugin sources are installed directly, while multi-plugin sources display a checkbox list; after confirmation, installation is performed from the same snapshot.

Use toggles to enable or disable plugins online, and use the refresh button to check for updates. The uninstall operation removes the plugin.

API Invocation

Other plugins can declare inject: ['compat'], then invoke service APIs through ctx.compat to perform operations, for example:
- ctx.compat.sourceAdd(source, options?)
- ctx.compat.sourceRemove(sourceId)
- ctx.compat.sourceUpdate(sourceId, options?)
- ctx.compat.sourceList()
- ctx.compat.sourceInspect(sourceId)
- ctx.compat.prepareInstall(source, options?)
- ctx.compat.install(sourceOrSourceId, options?)
- ctx.compat.checkUpdates()
- ctx.compat.update(pluginId, options?)
- ctx.compat.enable(pluginId)
- ctx.compat.disable(pluginId)
- ctx.compat.uninstall(pluginId)
- ctx.compat.list()
- ctx.compat.inspect(pluginId)

Architecture and Data

Transformation Flow

The source parser resolves Git/archives into Source, the plugin parser resolves the contents in the Source into specific Skill/MCP/Hook, and finally CompatPlugin adapts them to the DSH runtime.

Storage Layout

Data is stored under $DSH_HOME/dsh-compat/, divided into sources (cached source content) and installed (managed plugin state).

Security Model

No build scripts are executed during the installation phase; Git does not create a working tree, only reads and parses. Archives are checked for risks such as path traversal and symbolic links. Sensitive configurations use references rather than writing plaintext.

Applicable Scenarios and Notes

Suitable for workflow developers who need to uniformly manage legacy Claude Code/Codex plugins. Note: plugins run with the permissions of the current DSH process; check the source code and license before installation. Build scripts and Command/Agent are not executed.

Summary

@rvaim/dsh-compat provides a standardized integration path for legacy plugins by separating the Source and Plugin model, and provides complete lifecycle management.