[KongchangAI]
· 4 min read· 2,031 words

DeepSeek Harness Plugin Architecture Explained: The Cordis System Where Everything Is a Plugin

DeepSeek Harness Plugin Architecture Explained: The Cordis System Where Everything Is a Plugin

DeepSeek Harness is a general-purpose agent framework built on the Cordis plugin system, where everything is replaceable.

The article systematically introduces the architecture and usage of DeepSeek Harness (DSH). Positioned as a general-purpose Agent Harness, DSH ships with an agent loop, tools, system prompts, session storage, and an interface, and offers multiple delivery forms including Web, desktop, SDK, and ACP. Its foundation is a plugin system called Cordis, where the agent loop, tools, model providers, and even the frontend GUI are all plugins that collaborate through shared context, dependency injection, and events. The article details four ways to emit events, the code structure of three example plugins, the YAML layered configuration loading mechanism, and demonstrates how Creator mode lets the agent write plugins for itself, finally clarifying the relationship between Cordis and DeepSeek.

What Is DeepSeek Harness: A General-Purpose Agent Framework

According to a Chinese-subtitled video reposted on Bilibili, DeepSeekAd Harness (hereafter DSH) is not a specialized tool built only for coding scenarios, but a general-purpose Agent Harness. It ships with an agent loop, built-in tools, system prompts, session storage, and a complete user interface, while also letting users plug in their own tools and models.

DSH currently comes in several delivery forms: a web app for developers, an Electron-wrapped desktop client, TypeScript and Python SDKs, and an ACP integration. The video's author mostly demos the desktop version, since it wraps the web version and is functionally equivalent.

DeepSeek Harness delivery forms

The most recognizable element of the interface is the mode switcher: Standard mode launches a conventional coding agent; PTC mode writes tool calls as scripts so that multiple tools run in parallel within a single tool call—the author notes this is exactly how early small agents worked; Minimal mode compresses context as much as possible; and Creator mode injects skills and context about DSH's own extensibility, letting the agent modify and extend itself.

The word harness originally means "tack/harness for a horse"; in software it refers to the outer shell wrapped around a core capability that drives and constrains how it runs. For a language model, the model itself only generates tokens from input—it has no ability to loop continuously, call external tools, or persist conversation state. The Agent Harness is the engineering skeleton that assembles this "bare model" into a usable agent, typically including the main loop (deciding when to call the model, when to execute tools, and when to stop), tool dispatch and result feedback, context management, error retry, and the user interaction interface. Harness designs vary widely across vendors, which means the same underlying model can perform very differently under different harnesses. Understanding this is essential to grasping why the article stresses that DSH is a "general-purpose" rather than "coding-specific" framework.

Cordis: The Underlying System That Makes "Everything Is a Plugin" Possible

DSH's slogan is "everything is a plugin," and what supports this design is a plugin system called Cordis. The author deliberately clarifies a commonly misunderstood piece of history: Cordis and DeepSeek are not the same entity, the Cordis repository does not belong to DeepSeek, and its first commit predates the founding of DeepSeek by about a year. Yet the two are closely linked—Cordis's author later joined DeepSeek and worked on DSH, the official Cordis page points to the DSH project, and the related paper was published by DeepSeek.

Cordis itself is not limited to coding agents; it can drive any kind of application, though its composability advantages are most obvious in the coding agent scenario. The author suggests reading the first few pages of the paper first, considering DeepSeek's paper writing to be high quality and the introductory section not difficult.

How Thoroughly Are the Boundaries Pluginized

In explaining the architecture, the author lists the things made into plugins: the agent loop itself, the tool registry and every individual tool (the Bash tool, the filesystem, the MCP client), the system prompt, the tool execution layer, model providers (including the DeepSeek model integration), skills, session logs and storage, and the user interface. This means that in theory you could replace the agent loop to build an agent that never calls a language model and only echoes user input; or replace the tool execution layer to run tools on a remote machine for stronger security.

More unusually, DSH actually contains two Cordis applications: one on the backend, and the frontend GUI itself is another, with the two cooperating through communication.

Dependency Injection is the foundation of Cordis's plugin collaboration mechanism. Its core idea: a component does not create the objects it depends on itself, but declares "what I need," and an external container passes in the instances at the appropriate time. In Cordis, plugins declare the names of the services they depend on via the inject field, and the framework uses this to ensure that depended-upon plugins finish mounting first before providing the corresponding context capabilities to the current plugin. The benefit is that plugins need not hardcode each other's import paths; when a plugin is replaced or disabled, the framework uniformly handles mounting order and cleanup logic for dependents. It also provides the engineering prerequisite for the "replaceable agent loop" and "replaceable tool execution layer" mentioned in the article—as long as the new implementation provides a service with the same name, upper-layer plugins run without modification.

How Plugins Cooperate: Shared Context, Dependency Injection, and Events

All plugins connect to the same context exposed by Cordis (defined as CTX in the code), so they can access application-wide shared capabilities. Some plugins are service providers—such as the session plugin, the tools plugin, and the model provider plugin—while others mainly listen to events in the context, such as the compaction plugin, the hooks plugin, and the headless UI.

Events are the core of coding agent functionality

Plugin capabilities fall into a few categories: declaring a name to provide a service; declaring dependencies via inject to achieve dependency injection and ensure depended-upon plugins mount first; registering with a service via the register method; and listening to context events. In the video's examples, the greet tool plugin must inject the Tools plugin before it can register a new tool in its apply function; the logging plugin likewise injects the Tools plugin, but it listens to tool result events and prints logs.

The author emphasizes that Cordis records everything a plugin defines, so when a plugin is disabled it knows in what order to clean up, which capabilities to unregister, and which names to release, avoiding removal of components still in use by other plugins.

The Four Ways to Emit Events

Events are the core of how a coding agent operates. Plugins can emit events in four ways: plain emit (fire-and-forget, such as tool results), waterfall (such as LLM streaming generation or multi-tool execution within a single agent turn), serial (waiting in sequence, such as an agent turn stopping and needing to wait for the agent to be created), and parallel. Plugins can also declare their own new events for other plugins to listen to; the compaction plugin creates its own Compaction event.

Events converge in the same context

Events are scoped by context. Plugins can be nested, and nested plugins share the parent context, with events emitted to the parent context. The author cautions against nesting all plugins together; a better approach is to have plugins connect to the same context and establish dependencies through dependency injection.

Waterfall events are a rather special pattern in the event system, common in scenarios where multiple listeners process the same piece of data in sequence. Unlike plain emit's "fire-and-forget," a waterfall event passes the previous listener's return value as input to the next listener, forming a processing chain; each listener must explicitly return next (or an equivalent token) to signal passage, and if it returns an interrupt object such as deny, the chain terminates immediately and blocks the subsequent default flow. The article's tool guard plugin exploits exactly this to intercept bash commands before the tool actually executes. This pattern is also widely used in LLM streaming generation and multi-tool parallel turns, because it lets the framework insert cross-cutting logic such as authentication, auditing, and rate limiting without modifying core code.

Understanding the Code Structure Through Three Example Plugins

In a cloned DSH repository, the author creates a scratch-plugin directory and puts three plugins in it. The first is a minimal plugin: it exports an apply function that receives a context parameter and simply prints hello world.

The second is the greet tool plugin: it exports name and inject (depending on tools), and in apply registers a greeting tool via the define tool method.

The third is the tool guard plugin: it also injects tools, listens to tool result events and logs them; it also intercepts the tools pre-execute waterfall event, and if the bash command called by the model contains rmrf, it returns a deny object to block execution and prompts the model to have the user run it themselves. The author explains that waterfall events must return next to continue the normal flow, and to interrupt they must return an object such as deny.

How Plugins Are Loaded: YAML Configuration Rather Than Hardcoding

In Cordis, plugins are loaded as configuration rather than hardcoded in the code. Loading requires a YAML file that specifies an ID and name for each plugin under the insert property; if the plugin has been published as an npm package, fill in the package name, and to run local code directly, fill in the absolute file path. The author also uses the --patch parameter to append a self-built configuration to the end of the existing Cordis configuration in the web profile, demonstrating the three plugins taking effect in the local web client—the greet tool is successfully called, and the rmrf command is intercepted by the guard plugin.

Plugins load by package name or path

Configuration is layered: the base bundle's Cordis configuration file, the patch file, and finally the user configuration, located in the profiles directory under the user's home directory, distinguished by profile and overriding previous layers. The author opens their own desktop Cordis.patch.yaml, showing how the configured flags and properties are passed to the corresponding plugins, such as the default model and UI chat settings, as well as models connected through Hugging Face. Loading plugins on the desktop usually requires packaging the plugin as an npm package and then adding it through DSH's service rather than manually editing Cordis files—manual patching only helps understand the underlying mechanism.

In Practice: Creator Mode Lets the Agent Write Its Own Plugins

The author demonstrates the most effortless everyday approach: switch to Creator mode and directly ask DSH to create a Hello World tool plugin that greets by name. The agent generates a directory structure containing package.json and index.js, and successfully calls it during testing. This also confirms Creator mode's positioning—it does not change the agent's capabilities themselves, but injects knowledge about DSH's extensibility and plugin architecture so the agent can write plugins for itself.

The video ends with an end-to-end validation using two plugins: the greet tool is available on the desktop client, and the rmrf command is blocked by the guard plugin. For developers who want to deeply understand this architecture, the author suggests reading the first few pages of the Cordis paper to build intuition, then observing how plugins are assembled layer by layer in the repository's bundle configuration.

ACP (Agent Client Protocol) is an integration method DSH provides for external clients to interact with the agent via a standardized protocol. It abstracts "starting a session, sending messages, receiving streaming output and tool call events" into a unified protocol interface, enabling editors, IDE plugins, or other host programs to integrate without understanding DSH's internal implementation. Compared with interface-carrying delivery forms like the web app and desktop client, ACP is better suited to embedding into a developer's existing work environment. It differs from the SDK in that the SDK is a code-level library call where developers manage the lifecycle and event loop themselves, whereas ACP is an inter-process protocol where the host and agent can be separate processes, facilitating isolation and reuse.

One-line Summary

DeepSeek Harness is a general-purpose agent framework built on the Cordis plugin system, where everything is replaceable.

Paragraph Summary

The article systematically introduces the architecture and usage of DeepSeek Harness (DSH). DSH is positioned as a general-purpose Agent Harness with a built-in agent loop, tools, system prompts, session storage, and interface, and it offers multiple delivery forms including Web, desktop, SDK, and ACP. At its foundation is a plugin system called Cordis, where the agent loop, tools, model providers, and even the frontend GUI are all plugins, collaborating through shared context, dependency injection, and events. The article details four ways to emit events, the code structure of three example plugins, the YAML layered configuration loading mechanism, and demonstrates how Creator mode lets the agent write plugins for itself, finally clarifying the relationship between Cordis and DeepSeek.

#DeepSeek Harness#Cordis plugin system#agent framework#plugin architecture#dependency injection#YAML configuration
Share:

Related articles