Introduction

DeepSeek Harness (DSH), open-sourced on August 13, follows the core design principle: everything is a plugin. Unlike monolithic end-user products such as Claude Code and Codex, DSH functions as an underlying Agent runtime framework defined by the formula: Agent = LLM Model + Harness. All core capabilities are modularized: model adapters, tool functions, dialogue storage, main loop scheduling, and web UI components can be freely replaced without modifying framework source code.

By default, the DSH web interface lacks a direct workspace file tree. The Agent can only scan directories via repeated tool calls, which creates redundant token consumption. The open-source plugin dsh-workspace-enhance solves this pain point. It adds a visual file list sidebar to the DSH web UI and injects structured workspace context into Agent prompts, reducing repeated file scanning and improving overall coding efficiency.

This article breaks down the underlying Cordis plugin runtime mechanism, demonstrates full workflows including plugin installation, source code parsing, and custom plugin development. It distinguishes Host-side Node plugins and Client-side Web UI plugins, clarifying communication rules between the two runtime environments.

Relevant repositories:

1. Core Principles of DeepSeek Harness Plugin System

1.1 Underlying Kernel: Cordis Framework

The DSH plugin runtime is built upon the self-developed Cordis kernel. Three foundational concepts govern all plugin execution:

  1. Context: A shared global object. All services (tools, system prompts, web view components) attach to Context. Plugins avoid direct mutual imports; all cross-plugin communication runs through Context.
  2. Inject Dependency Declaration: Plugins declare required services. The kernel waits until all dependencies are ready before executing plugin logic.
  3. apply(ctx): The single entry function for every plugin. Cordis invokes this function automatically with the shared Context. Plugins register tools, web routes, event listeners, and configuration logic inside this method.

Automatic cleanup is built into the lifecycle: listeners and registered resources created by ctx.effect() are automatically released when a plugin unloads, preventing memory leaks.

1.2 Two Plugin Categories in DSH

Plugins are split into two isolated runtime environments with strict boundary limitations:

Plugin Type Runtime Environment Capability Scope Typical Examples
Host Plugin Node.js Backend Register tool functions, read/write local files, execute shell commands, inject system prompts Custom file operation tools, Git interaction plugins
Client Plugin Browser Frontend Extend web UI, add sidebar tabs, render new interface components dsh-workspace-enhance, UI beautification plugins

Critical constraint: Host plugins cannot manipulate DOM elements. Client plugins cannot directly access the local file system. All cross-environment communication relies on DSH’s internal event bus.

1.3 Full Plugin Loading Workflow

  1. DSH starts, loads the active profile configuration, and parses the plugin manifest list.
  2. Cordis resolves all inject dependencies, sorts plugins by topological order.
  3. Each plugin’s apply(ctx) function is invoked sequentially to register tools, UI components and event handlers.
  4. After all plugins finish loading, the Agent runtime can access newly added tools and interface modules.

Plugin configurations are stored under ~/.dsh/profiles/[profile-name]. Installed plugins reside inside the node_modules directory under the target profile.

2. Hands-On Practice 1: Install dsh-workspace-enhance

Plugin Overview

The dsh-workspace-enhance plugin adds a persistent sidebar file tree inside the DSH web interface to display workspace directory structure. It simultaneously generates condensed workspace context and feeds it to the Agent, minimizing repeated directory scanning and lowering token overhead.

Prerequisite

Ensure the DSH CLI is installed globally:

npm install -g @deepseek-ai/dsh

Installation Command

Install directly from the GitHub repository to the web profile:

dsh plugin --profile web add git+https://github.com/luis1232023/dsh-workspace-enhance

After installation completes, restart the DSH service to load the plugin:

dsh restart web

Visit http://127.0.0.1:3080. A new Workspace Files tab will appear on the sidebar, displaying all files within the active workspace directory.

Uninstall Command

dsh plugin --profile web remove dsh-workspace-enhance

Common Troubleshooting

  1. Plugin fails to take effect after installation: A full dsh restart web is mandatory; hot reloading is not supported.
  2. Blank file tree: Verify the workspace directory is selected within the DSH interface.
  3. Git connection failures: Ensure the host environment has Git installed, as the plugin manager pulls source code via Git protocol.

3. Source Code Deep Dive: dsh-workspace-enhance

Clone the repository locally for code analysis:

git clone https://github.com/luis1232023/dsh-workspace-enhance
cd dsh-workspace-enhance

3.1 Project Structure

dsh-workspace-enhance/
├── src/
│   ├── host/index.ts     # Backend Host plugin logic
│   └── client/index.ts   # Frontend Client UI plugin logic
├── package.json
└── tsconfig.json

3.2 package.json Core Configuration

The dsh field inside package.json acts as the official identification marker for DSH plugins:

{
  "name": "dsh-workspace-enhance",
  "dsh": {
    "host": "./lib/index.js",
    "client": "./lib/client.js"
  }
}
  • host: Compiled output path for Node backend logic
  • client: Compiled output path for browser frontend components

3.3 Host Plugin Logic (src/host/index.ts)

The Host plugin monitors workspace change events. It scans directory structures and generates condensed workspace summaries. This structured overview is injected into Agent context, allowing the model to understand project layout without repeated file read tool calls.

3.4 Client Plugin Logic (src/client/index.ts)

The Client plugin registers a new sidebar tab inside the DSH web view. It does not directly access local files. All file metadata is requested from the Host backend via the internal event bus. This separation conforms to browser security rules and avoids cross-origin and local file access limitations.

The decoupled frontend-backend architecture is a standard practice for developing DSH UI extensions. When teams manage multiple LLM services and plugin deployments, unified traffic routing can be managed via an API gateway such as Treerouter to streamline backend access.

4. Build Your First Custom DSH Plugin

We will implement a minimal demo plugin: register a Host tool function, and render a corresponding new tab on the web sidebar.

Step 1: Initialize Plugin Project

mkdir dsh-plugin-demo
cd dsh-plugin-demo
pnpm init
pnpm add -D typescript @deepseek-ai/cordis

Configure TypeScript compilation targets compatible with both Node and browser environments.

Step 2: Write Host Plugin Code

Implement the apply entry function, declare dependency injection, and register a custom tool available to the Agent runtime.

Step 3: Write Client Plugin Code

Register a new sidebar label inside the web UI, create a simple view component, and set up event channels to communicate with the Host backend.

Step 4: Compile & Install Plugin

Compile TypeScript code, then install the local plugin into your DSH web profile:

dsh plugin --profile web add .

Restart DSH web service. The new sidebar tab will load, and the Agent can invoke your newly defined tool function.

5. Critical Development Best Practices

  1. Runtime Isolation Boundary: Host plugins cannot access DOM; Client plugins cannot read local files. All data exchange must go through the internal event bus.
  2. Declare All Dependencies in inject: If your plugin uses built-in services such as tools or systemPrompt, list them explicitly in inject arrays. The kernel will delay plugin startup until all dependencies are initialized.
  3. Use ctx.effect() for Resources: All event listeners, timers and persistent connections created in plugins must be wrapped inside ctx.effect() to enable automatic cleanup and prevent memory leaks.
  4. Profile Separation: Web and headless profiles are independent. Install plugins to the matching profile. Plugins installed under web will not load in headless mode.

6. When to Develop Custom DSH Plugins

  • You need to extend Agent capabilities with custom tool functions (Git operations, cloud resource management, test automation).
  • You want to expand the web UI: add sidebar panels, custom dashboards, or dedicated configuration views.
  • You require customized Agent behavior: dynamically modify system prompts, intercept tool calls, or build multi-agent collaboration pipelines.

If your requirements only involve simple prompt adjustment, you can avoid plugin development and use built-in workflow configuration. For persistent, reusable extensions, the plugin system provides a standardized distribution mechanism.

7. Conclusion

The plugin system is the core extensibility foundation of DeepSeek Harness. The dsh-workspace-enhance plugin serves as an ideal starter example. It demonstrates how to split logic into Host backend and Client frontend modules, and how to leverage the Cordis kernel to build decoupled extensions.

Mastery of three core concepts — Context, inject dependency injection, and the apply entry function — allows developers to freely expand Agent workflows without forking the main DSH repository. The open plugin ecosystem lowers the barrier to building customized, production-ready Agent runtime environments. As the ecosystem expands, more reusable community plugins will accelerate engineering-oriented Agent development.

Learn more：https://treerouter.com