Introduction

DeepSeek Harness (DSH) uses a plugin-based architecture, enabling capability extension in Web composer. In agent development, troubleshooting often relies on static code or ambiguous logs. dsh-debug-mode aims to introduce debugging capabilities to Web environments, providing multiple run modes and runtime instrumentation to help agents obtain verifiable evidence of failures.

Plugin Introduction

dsh-debug-mode is the Debug Mode Bundle for DeepSeek Harness.

  • Objective: Provide Normal, Plan, and Debug modes in Web composer, and assist troubleshooting with runtime instrumentation or backend debuggers.
  • Maintainer: svcgv
  • License: MIT
  • Directory: DeepSeek Harness Plugin Directory
  • Repository: GitHub

Core Features

The plugin provides a complete debugging pipeline:

  • Multi-mode support: Provides Normal, Plan, and Debug mode switching in Web composer, controlled by a Debug/Normal toggle.
  • Commands and projections: Supports the /debug command and view projections.
  • Front-end instrumentation: Provides front-end Local Log and Listener instrumentation.
  • Backend debugging: Supports Node/CDP and Python/DAP backends, with process assistance and cleanup tools.
  • Runtime tools: Provides the debug_control tool and traceTransport support, as well as reproductionScope support (used to control reproduction scope).

Installation and Activation

The installation process is completed through Harness’s Web startup script.

  1. Copy config.example.ini to a local config.ini.
  2. Fill in api_key under the [deepseek] section.
  3. Run pnpm config:check to validate the configuration (the script only checks the key length and does not print the key).
  4. Set DSH_HARNESS_DIR (by default it uses the adjacent ../deepseek-harness directory), and run pnpm harness:web.

Running pnpm harness:web installs the currently packaged plugin into a temporary profile at .dev/dsh-home and starts Harness Web with DEEPSEEK_API_KEY.

Typical Usage

After configuration, the debugging features can be used as follows:

Trace Transport Configuration
* By default, the front-end debug_start uses traceTransport: 'listener'. The probe collects events through the plugin service and saves them to the current run’s .dsh-debug/<runId>/trace.jsonl file, which can be read by debug_control.
* Use traceTransport: 'local-log' only when you need to view the console or terminal only. This mode does not start a service and does not generate log files.

Reproduction Scope
* The debug_start command supports the reproductionScope parameter, with values local, lan, or auto. The model decides the advertised endpoint scope based on the user’s description (for example, local advertises only 127.0.0.1, and lan advertises a LAN address).

Use Cases and Cautions

  • Use cases: Suitable for developers who need to debug agent behavior in a Web composer environment, especially scenarios involving Node.js or Python backend integration testing.
  • Notes:
    • The plugin must output the Client bundle in the factory format window.__ModuleLoader__.load({ id, factory }).
    • Flutter has not been verified in a real project.
    • The backend “stop existing service → debug → restore” loop is not implemented; currently, regular services using the same script receive a safe failure notice (no automatic service shutdown).
    • Full end-to-end reproduction for Harness Web (instrumentation/breakpoint evidence capture) has not been fully closed within a browser session.

Conclusion

dsh-debug-mode provides mode switching and runtime debugging capabilities for Web development in DeepSeek Harness. By configuring traceTransport and reproductionScope, developers can locate issues more easily. For more details, see the GitHub repository.