DeepSeek Harness Plugin Tutorial: Build and Run Your First Plugin

DeepSeek Harness follows the design principle "everything is a plugin". This tutorial shows how to write a minimal plugin, register it, and use it, then explains how to install and configure production‑grade plugins.

1. Prepare the source environment

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run build

The article tested with Node.js v24.19.0, which satisfies the Harness requirement ^22.19.0 || >=24.0.0. Running pnpm run build is required; installing dependencies only will not produce the web assets.

2. Create the plugin file

Create scratch-plugin/src/greet-tool.ts with the following minimal structure:

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' }
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }]
    },
    async execute(args) {
      return `你好，${args.name}！你的第一个 Harness 插件已经运行。`
    }
  }))
  console.log('[greet-tool] loaded; tool name: greet')
}

The plugin consists of four parts:

name : plugin identifier.

inject : declares the Harness services the plugin needs (here the tools service).

apply(ctx) : entry point that registers the tool.

ctx.tools.register(...) : registers a tool that the model can call, defining parameters, output, and the async execute implementation.

3. Insert the plugin into Harness

Obtain the absolute path of the repository and add an entry to scratch-plugin/cordis.yml:

- insert:
  - - id: greet-tool
    name: '/Users/yourname/deepseek-harness/scratch-plugin/src/greet-tool.ts'

Place the plugin inside the Harness source tree; otherwise you may encounter Cannot find module errors.

4. Start and check

pnpm dsh web --patch ./scratch-plugin/cordis.yml

If port 3080 is occupied, use a different port:

pnpm dsh web --patch ./scratch-plugin/cordis.yml --port 3082

Successful start shows lines such as:

[greet-tool] loaded; tool name: greet
dsh web: http://127.0.0.1:3082

Enable the plugin in the UI (Settings → Plugins → Plugin List) and verify that its status is "Enabled".

5. Let the Agent call it

In a standard session type: 请调用 greet 工具问候 Datawhale。 The tool call displays:

IN   { "name": "Datawhale" }
OUT  你好，Datawhale！你的第一个 Harness 插件已经运行。

This confirms the full loop: plugin loaded → tool registered → model invoked → structured result returned.

6. Install a production‑grade plugin (DSH Vision Toolkit)

Install the vision toolkit:

dsh plugin --profile web add @dsh-external/dsh-vision-toolkit

Configure the visual model endpoint, model name, and a credential key (e.g., VISION_API_KEY) via the Harness Settings → Vision Tools page, then test the connection.

7. Use vision tools in a conversation

Load the skill: /vision-tools Example commands:

请用 vision_glance 分析 ./screenshot.png，告诉我页面上出现了什么错误。
请用 vision_ground 定位截图里的发送按钮，并生成带标注的预览图。
请比较 reference.png 和 actual.png，告诉我差异最大的区域。

Generated artifacts (cropped images, heatmaps, reports) are saved under .dsh-vision-toolkit/artifacts.

8. Update or uninstall plugins

dsh plugin --profile web update
dsh plugin --profile web remove @dsh-external/dsh-vision-toolkit

Restart the web profile after any change.

9. Precautions before installing third‑party plugins

Check whether the repository is public, its license, and who maintains it.

Inspect what the install script downloads and whether it runs extra programs.

Identify required directory, network, and credential permissions.

Verify supported Harness version, uninstall method, and testing procedure.

Because Harness plugins run in the trusted host process, always review source code and permission requirements even if the install command is a single line.

10. Summary of workflows

Minimal plugin development flow:

apply(ctx) → register tool → execute(args) → return structured result

Using an existing plugin flow:

plugin add → restart profile → configure credentials → load skill → call tool

The first approach helps you understand Harness internals; the second makes Harness practically useful.