Introduction

DeepSeek Harness (DSH) follows the “everything is a plugin” philosophy. When a version upgrade causes third-party plugin conflicts and the GUI fails to start, conventional remediation methods stop working. In such cases, a tool that operates outside the plugin system is required. dsh-rescue is designed specifically for this scenario.

When DSH is deadlocked by a plugin conflict, dsh-rescue temporarily removes all third-party plugin layers from the profile, allowing dsh to start with a pure core and repair itself. After the repair is complete, a single command restores the original state.

What It Is

dsh-rescue is a rescue-mode tool for DeepSeek Harness (DSH), maintained by Iliyasfiel and released under the MIT license.

It is a boot-level tool, not a plugin. Its core principle is to directly edit the profile manifest (manifest file) and strip out third-party bundles defined in dsh.profile.bundles. Because built-in core layers (such as @deepseek-ai/dsh-base) are not part of dependencies, they are retained, ensuring that DSH can start with a clean core.

Core Capabilities

The tool provides the following core features:

  • Temporary stripping: Removes all third-party bundles from the profile stack.
  • Pure-core startup: Allows DSH to start without third-party plugin interference, enabling repair.
  • One-click restore: After the repair is complete, restores the original plugin stack with a single command.
  • Transactional backup: Backs up and records state before modifying the manifest, and automatically rolls back if the modification fails.
  • Coordinated exit: The exit command intelligently restores state, recovering a bundle only if its plugin package is still present in dependencies; removed plugins are not forcibly revived.
  • Zero-dependency offline: Implemented purely in Node, requires no pnpm, and works fully offline.
  • Ecosystem-compatible entry: Provides a lazy cordis bundle entry (apply() is a no-op), so it can be installed as a plugin via dsh plugin add, while the actual execution mechanism is the CLI.

Installation

Install the CLI globally (recommended; this is the rescue path):

npm install -g dsh-rescue

Or register it as an ecosystem-compatible bundle (optional):

dsh plugin --profile web add dsh-rescue

Typical Usage

By default, the working directory of the rescue tool is $DSH_HOME/profiles (DSH_HOME typically points to ~/.dsh), and the default web GUI profile is named web.

Basic Commands

dsh-rescue enter  <profile>    # 进入救援模式：仅保留核心层，隔离第三方插件
dsh-rescue exit   <profile>    # 退出救援模式：协调并还原原始插件栈
dsh-rescue status <profile>    # 查看状态：救援状态、核心层与第三方层的拆分情况
dsh-rescue help

Typical Rescue Flow

When DSH cannot start, stop the current process and perform the following steps:

# 1. 进入救援模式
dsh-rescue enter web

# 2. 此时 profile 仅包含核心层，DSH 应能正常启动
dsh web

# 3. 在 GUI 或 CLI 中修复插件冲突（例如移除冲突的包）
dsh plugin --profile web remove <conflicting-package>

# 4. 退出救援模式，还原插件栈
dsh-rescue exit web

# 5. 恢复正常启动
dsh web

Behavioral Details

  • Detection rule: The tool identifies third-party plugins solely by the intersection of dependencies and dsh.profile.bundles. It does not rely on package-name prefix assumptions, making it more robust against changes in DSH’s core form.
  • Non-invasiveness: The rescue tool cannot be installed as a plugin and run inside DSH (it would become the isolated target). Therefore, its true mechanism is the CLI, while the bundle entry is deliberately made lazy (apply() is empty) and intended only for ecosystem compatibility.
  • State management:
    • enter only removes entries from bundles, while preserving dependencies.
    • exit precisely restores bundles, recovering a plugin only if its package still exists in dependencies.
    • If the host automatically writes default configuration during rescue, exit precisely removes those auto-written settings to keep the restoration clean.

Applicable Scenarios and Cautions

  • Applicable scenario: A version upgrade prevents the GUI from starting, and the profile configuration must be repaired without starting plugins.
  • Cautions:
    • The rescue tool runs with the permissions of the current dsh process. Review the source code before installing.
    • Do not run enter again on a profile that is already in rescue mode, or perform operations on a non-profile directory or a stateless directory. The system will report an error and refuse to modify it.
    • Because the manifest is edited directly, it is recommended to back up the profile directory before operating.