Introduction

DeepSeek Harness (DSH) adopts an “everything is a plugin” architecture. Developing a new tool plugin typically requires handling tedious workflows such as configuration, Schema definition, packaging, and publishing. dsh-plugin-template provides a minimal viable skeleton with a pure ESM architecture, zero-dependency configuration, and scaffolding scripts to help developers get started quickly.

Plugin Overview

This repository contains template code for DSH plugins and is used to create new npm bundle plugins.
- Name: dsh-plugin-template
- Maintainer: ZhijiangTang
- Category: Client
- License: MIT
- Core Value: A minimal viable skeleton for scaffolding a new tool plugin.

Core Features

  • Pure ESM architecture, without the need for Babel/TypeScript compilation.
  • Zero dependencies, using the core libraries in peerDependencies directly.
  • Includes a hello_world placeholder tool that demonstrates parameter definitions, output schema, rendering, and execution logic.
  • The mount self-check mechanism runs through the real ctx.tools.execute pipeline.
  • Includes a built-in scaffold.sh scaffolding script.

Usage Steps

Do X first, then do Y. The following steps use creating a new package named dsh-mytool as an example.

1. Initialize the Project

Use the scaffolding script included in the template repository to generate the skeleton.

bash scripts/scaffold.sh dsh-mytool

2. Modify the Configuration Files

After generation, manually adjust the core configuration:

  • package.json:
  • Remove the private: true field (otherwise it cannot be published to npm).
  • Change name to your npm package name.
  • Change keywords, for example ["dsh-plugin", "dsh-mytool"].
  • cordis.patch.yml:
  • Change id: the stable identity of the plugin; it is remounted on each startup.
  • Change name: the plugin code is referenced by the npm package name.
  • index.js:
  • Change the plugin name export const name.
  • Change the tool name name: 'hello_world'.
  • Rewrite the parameter definitions, output schema, and execution logic as needed.

3. Local Verification

This template itself is not an installable plugin (private: true), so it must be published first or loaded locally using the file: protocol.

# 安装本地插件（必须使用 file: 协议）
dsh plugin --profile px-tdemo add file:./plugins/dsh-mytool

# 启动并观察自检日志
dsh --profile px-tdemo --port 0 2>&1 | grep -m1 'self-test ok'

4. Publish

After confirming the configuration is correct, publish to npm.

cd plugins/dsh-mytool
pnpm publish

Common Notes

  • Local Installation Protocol: For local testing, you must use the file:./path protocol. Using ./path is resolved as a symbolic link and may cause module-not-found errors.
  • Schema DSL Limitations: output.schema does not accept a top-level required array; use property-level required: true instead.
  • pnpm 24-hour Gating: If a new version is less than 24 hours old, pnpm add may resolve to an older version. It is recommended to specify an explicit version.
  • Native Dependency Handling: If the plugin includes native dependencies (such as node-pty), configure allowBuilds in the profile’s pnpm-workspace.yaml. Keep plugins free of native dependencies whenever possible.
  • Non-Publish Repository: This repository itself sets private: true, is not published to npm, and is intended only as a template.

Summary

dsh-plugin-template is a lightweight development scaffold for developers who need to build DSH plugins quickly. It lowers the development barrier through a pure ESM design with zero dependencies and no build step.
- GitHub: https://github.com/ZhijiangTang/dsh-plugin-template
- Directory page: https://www.skillhub.cn/plugins/ZhijiangTang/dsh-plugin-template