How to Create a DeepSeek Harness Plugin

A DeepSeek Harness plugin extends the agent runtime through the same Cordis composition system used by the built-in capabilities. A useful plugin should solve one focused problem, declare what it needs, clean up every effect it registers, and give users enough evidence to review it before installation.

DeepSeek Harness is a developer preview. Confirm the current interfaces in the official repository before publishing a package.

1. Choose one capability boundary

Start with a concrete user outcome: connect a service, register a model-facing tool, add a UI surface, persist a specific kind of state, or observe runtime events. Avoid combining unrelated privileges in one plugin. A narrow boundary makes permissions, tests, failures, and user trust easier to understand.

Browse the complete plugin directory and plugin categories to see how existing projects describe their scope.

2. Understand the plugin lifecycle

Harness mounts plugins through Cordis. A plugin may provide or consume a service, listen for events, register tools, or contribute configuration. Every registration should have a corresponding cleanup path so unloading the plugin does not leave listeners, timers, processes, or patched state behind.

Design for these lifecycle states:

Configuration is validated before side effects begin.
Required services are present or startup fails with a useful message.
Resources are acquired only after validation succeeds.
Every listener, timer, subprocess, and temporary resource is released on unload.
Repeated mount/unmount cycles do not duplicate behavior.

3. Declare configuration and permissions

Document every configuration key, its type, default, and whether it contains a secret. Do not place credentials in source, generated bundles, example logs, or browser-visible configuration. Prefer least privilege: request only the filesystem paths, network hosts, commands, and services the plugin needs.

If the plugin exposes a model-facing tool, validate every argument at the boundary. Treat model output as untrusted input. Restrict file paths and process execution, use allowlists where practical, and return errors that do not reveal secrets.

4. Make effects reversible

Cordis tracks effects so registrations can be removed when a plugin unloads, but the plugin still has to register work through the supported lifecycle. Avoid detached global mutations. Keep long-running work cancelable and ensure shutdown does not race with an in-flight tool call.

5. Test the real behavior

At minimum, test:

valid and invalid configuration;
startup with required and missing services;
the successful user journey;
denied permissions, unavailable networks, and malformed tool input;
repeated mount and unload without leaked effects;
install and removal in an isolated Harness profile.

Do not describe a mocked provider test as production integration proof. Record the Harness version or commit used for compatibility testing.

6. Publish reviewable evidence

A good repository README should include:

the exact capability and non-goals;
installation and removal steps;
a minimal configuration example with placeholder secrets;
permissions and outbound network destinations;
compatibility evidence and the tested Harness version;
build scripts and generated artifacts;
a security contact and vulnerability-reporting path;
a changelog or release history.

Before asking users to install, follow the plugin safety checklist yourself. To add the project to this directory, use Submit a plugin and include its repository, category, description, and compatibility evidence.

Pre-publish checklist

The repository URL and package identity agree.
Installation and removal commands were tested in a clean profile.
No credentials, tokens, cookies, private keys, or local state are committed.
Tool inputs and configuration are validated.
Every effect has an unload path.
Required permissions and network access are documented.
The tested Harness version is recorded.
The README explains what the plugin does and does not do.