Introduction

The philosophy of DSH is “everything is a plugin.” For plugin developers, writing a single tool or hook is not difficult; the challenge lies in packaging Config, Tool, Events, Service, Hook, and the browser client half into a single installable bundle and enabling it to activate correctly within a profile.

Below is an introduction to dsh-plugin-template. It is not a specific business plugin but a starter template: it uses minimal readable code to demonstrate common DSH plugin shapes, making it suitable as a local development template and as a reference for understanding the structural boundaries of DSH plugins.

What is it

dsh-plugin-template is an entry-level template for DSH plugin development. The repository path is kun2-5code/dsh-plugin-template, the package name is dsh-plugin-template, the version in package.json is 0.1.0, and the license is MIT.

It demonstrates six common plugin shapes within a single installable bundle:

  • Config
  • Tool
  • Events
  • Service
  • Hook
  • Browser half (client)

It follows DSH’s bundle distribution model: it declares dsh.bundle and cordis.patch.yml within the package and activates it as a config layer using dsh plugin add.

The package.json also declares the browser entry point:

{
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    },
    "client": {
      "platform": "web",
      "inject": [
        "slots"
      ]
    }
  }
}

Here, client.platform is web and inject includes slots. This means it simultaneously covers the host-side plugin logic and the browser-side UI registration.

Core Capabilities

Config

The template includes a Config interface and a Schemastery schema. It applies validation and defaults upon loading.

This type of configuration is suitable for learning how DSH plugins plug internal plugin state into the settings namespace, rather than maintaining a separate configuration system.

Tool

Tools are registered via the following API:

ctx.tools.register(defineTool(...))

The greet tool in the template has a presentResult render intent.

Events

Events use ctx.on / ctx.emit and provide typed events through declaration merging.

This is suitable for observing how DSH plugin events extend at the type level, rather than relying on string event names.

Service

Service is a class-form plugin that can provide services to other plugins.

service.ts is an optional example and is disabled by default.

Hook

Hook provides a tools/pre-execute permission gate, allowing you to reject tool invocations based on configuration.

hook.ts is also an optional example and is disabled by default.

Browser half

The Browser half registers browser UI on 14 surfaces. The locations listed in the documentation include:

  • clickable config card
  • sidebar footer action
  • input dock
  • shell overlay
  • header utility
  • input tool-row buttons
  • /dsh-demo command row
  • General settings row
  • Plugins tab
  • settings header action
  • session header action
  • composer dock
  • per-message actions

The clickable config card can write greeting, maxRetries, and verbose. On a stock harness, this card renders a read-only “not exposed” explainer rather than simply disappearing.

There is a boundary to distinguish here: only the data path of the config card is restricted by the harness allowlist; the other thirteen are pure slot registrations and will work on any harness.

Demo Commands

The template also includes two demo slash commands:

  • /hello: replies “world”
  • /dsh-demo: custom row

These commands are used to verify host-side command registration and the display location of client-side command rows.

Installation and Activation

Local Directory Installation

First, perform a local installation, which is suitable for confirming the template works:

dsh plugin --profile demo add /path/to/dsh-plugin-template

Here, /path/to/dsh-plugin-template needs to be replaced with the actual directory on your machine.

After installation, you can first check the config layer:

dsh --profile demo --dump-config

You should normally see a layer marked # == dsh-plugin-template.

Then, start DSH:

dsh --profile demo

Note: Custom-named profiles, such as demo, only contain dsh-base and are headless, lacking a GUI. To view the Web GUI and config card, you need to use the web profile.

GitHub Installation

The GitHub installation example given in the README is:

dsh plugin --profile demo add github:you/dsh-plugin-template

Here, you is a placeholder command and should be replaced with your own repository path after forking.

GitHub installation pulls source code; pnpm executes prepare, which builds lib/ using tsdown.

When using pnpm ≥10, the first prepare for a git-dependency may be rejected. You need to add the package name output by pnpm to the profile’s pnpm-workspace.yaml and retry:

allowBuilds:
  dsh-plugin-template: true

allowBuilds authorizes the execution of that package’s code during installation. Only add this to trusted source code, and prefer fixing the commit:

github:you/dsh-plugin-template#<sha>

Local Development Overlay

If you are developing within a deepseek-harness source code checkout, you can load the template source code directly:

pnpm dsh web --patch /absolute/path/to/dsh-plugin-template/dev/cordis.yml

/absolute/path/to/dsh-plugin-template needs to be replaced with the absolute path on your machine.

The --patch overlay only loads the plugin’s host half. To test the browser-half config card, you must install the plugin to a profile and resolve it as name: dsh-plugin-template.

During development, you can run these checks:

pnpm install
pnpm typecheck
pnpm build
node test/smoke.mjs

If this template is located inside a deepseek-harness checkout, pnpm install might be captured by the parent workspace. In this case, you should use:

pnpm install --ignore-workspace

Or clone the template separately and install it.

Use Cases and Notes

It is suitable for the following tasks:

  • Learning the structure of DSH plugins: Config, Tool, Events, Service, Hook.
  • Viewing how the browser client half registers on multiple UI surfaces.
  • Understanding the bundle installation relationship between dsh.bundle, cordis.patch.yml, and dsh plugin add.
  • Using it as a starting point for forking your own DSH plugin.

Notes before use:

  • Plugins run with the permissions of the current dsh process; you should check the source code and license before installing.
  • service.ts and hook.ts are optional examples and are disabled by default.
  • Custom profiles like demo are headless; to view the config card and Web GUI, you need the web profile.
  • allowBuilds authorizes the execution of code within the package during installation and should only be added to trusted source code.
  • Do not interpret this repository or community directories as the DeepSeek official app store; community directories are independent sites and should not be written as having an official affiliation with DeepSeek or High-Fin (幻方).

Summary

The value of dsh-plugin-template lies in putting the six most common DSH plugin shapes into a single installable bundle and clearly distinguishing the boundaries of host half, browser half, config card, slot registration, and bundle activation. It is suitable for understanding the structure first, and then adapting it into your own plugin.

  • GitHub: https://github.com/kun2-5code/dsh-plugin-template
  • License: MIT

Since the existing documentation does not provide a verified community directory page URL, this article does not provide a specific directory link.