Host trust boundaryA plugin runs with the permissions of the dsh process, outside the Agent sandbox. Review code, dependencies, and install scripts before loading it.

Choose the shortest honest path.

LearnSource + overlay

Prove one module and its lifecycle before packaging.

IntegrateTyped Agent tool

Prove schema, execution, canonical value, and render.

DistributeBundle + profile

Prove install discovery, layer order, and removal.

Start from official coordinates.

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

Record git remote get-url origin and git rev-parse HEAD. Similar repository and package names do not prove provenance.

The smallest plugin is one function.

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] loaded')
}
ModuleExports apply

All contributions begin inside the Cordis lifecycle.

→
OverlayInserts one row

An absolute path makes local resolution explicit.

→
Web profilePrints the signal

The existing surface must still boot.

Runtime loading and TypeScript discovery are separate.

RuntimeModule URL

POSIX paths load directly. A Windows drive path must become a canonical file: URL.

≠
Editor + tscScratch tsconfig

Extend ../tsconfig.base.json to inherit official workspace aliases, then include only src.

pnpm exec tsc -p scratch-plugin/tsconfig.json

Keep the scratch project outside the official Host aggregate. Never add include or files to the shared base config just to silence local diagnostics.

On Windows, convert the path—do not rewrite it by eye.

$pluginPath = Join-Path $PWD 'scratch-plugin\src\my-plugin.ts'
node -e "const {pathToFileURL}=require('node:url'); console.log(pathToFileURL(process.argv[1]).href)" $pluginPath
FilesystemF:\repo\plugin.ts

Valid path, invalid raw ESM scheme.

→
Node URLfile:///F:/repo/plugin.ts

Canonical escaping survives spaces and Unicode.

→
Loaderplugin loaded

The terminal signal proves this boundary passed.

Current alpha source can also anchor ./src/my-plugin.ts to the overlay file. Use the generated file URL for rc.2 or uncertain mixed prerelease installations.

Make the Agent call it.

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 }
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }]
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    }
  }))
}
Waitinject

Declare the hard service dependency.

Validateparameters

Reject malformed model arguments.

Executeexecute

Return the canonical business value.

Renderoutput.render

Convert the value to model-visible content.

A bundle is not a profile.

You shipBundle

An npm package whose dsh.bundle.patch points to a configuration layer.

+
User runsProfile

An ordered composition under $DSH_HOME/profiles/<name>, maintained by the CLI.

The four-command acceptance loop.

  1. Installdsh plugin --profile plugin-lab add ./hello-plugin
  2. Inspectdsh --profile plugin-lab --dump-config
  3. Bootdsh --profile plugin-lab
  4. Removedsh plugin --profile plugin-lab remove dsh-hello-plugin
Git install scripts are an execution decision.

pnpm 10 requires an explicit allowance before a Git dependency may run its prepare build. Pin the commit and audit the script; it executes on the Host, not in the Agent sandbox.

Route the first failure.

Module missing

Check the absolute development path or packaged entry point.

No bundle layer

Inspect the installed manifest's dsh.bundle.patch.

Service undeclared

Add a true hard dependency to inject, or use guarded optional access.

Tool absent

Verify the active composition, registry injection, and unique tool name.

Primary evidence.

Keep the complete lab.

The canonical guide includes configuration schemas, bundle files, layer precedence, distribution choices, an acceptance checklist, and the full failure router.

Read the complete guide on GitHub