DeepSeek Harness architecture: plugins, profiles, and events

DeepSeek Harness is a plugin-oriented coding-agent runtime built on Cordis. Its command-line process is best understood as a plugin tree: a profile chooses a named assembly, bundles mount related behavior, core services expose stable capabilities, and events connect the agent loop to persistence and live control. This architecture lets features be replaced or composed without turning every package into a direct dependency of every other package.

The concepts below are an independent explanation of the official Chinese architecture document. Names and package boundaries may change while DeepSeek Harness remains in developer preview.

Cordis and the plugin tree

Cordis is the framework underneath the runtime. In this model, a component is mounted as a plugin and should register reversible side effects: when the plugin is removed, the services, listeners, and resources it introduced can be cleaned up predictably.

That matters for a coding-agent harness because one process may combine model providers, tools, session storage, interfaces, and policy layers. A plugin tree provides an explicit place for each responsibility and a lifecycle for turning it on or off.

When debugging, ask two questions first: which plugin registered the behavior, and where was that plugin mounted? Those questions are usually more useful than searching for a single monolithic application entry point.

Profiles, bundles, and configuration order

A profile is a named assembly stored in the Harness home. It selects which bundles and patches should compose the runtime. Bundles distribute configuration and mounting logic; examples in the upstream design include dsh-base, dsh-web-app, and dsh-headless.

Configuration is layered in a defined order:

1. profile bundles;
2. the profile patch;
3. the Harness home patch; and
4. the command-line overlay.

Later layers can refine earlier ones. To inspect the effective result rather than guessing which file won, dump the resolved configuration:

dsh --profile web --dump-config

Use profiles for coherent operating modes, such as Web or headless execution. Use a local patch for environment-specific adjustments. Avoid copying an entire bundle just to change one value, because doing so makes upstream changes harder to inherit.

Core services in the runtime

The architecture document identifies several services on the Cordis context, including sessions, system prompts, tools, agents, the agent loop, scope, and LLM access. These services are coordination points rather than a promise that every implementation is fixed.

A tool package can depend on the tool service without knowing which UI is active. An agent loop can depend on an LLM capability without owning provider credentials. Session storage can persist events without becoming responsible for live interface state. This division keeps the dependency direction understandable.

See the DeepSeek Harness tool catalog for the user-facing capabilities built on top of these services.

Persistent events and live agent events

DeepSeek Harness uses more than one event domain. The distinction is important:

• session events are persistent facts appended to the conversation log;
• agent/* events represent live control, state, and interception during execution; and
• capability-seam events allow providers and consumers to meet without a hard package dependency.

Do not write ephemeral progress into the session log merely because a UI needs it for a moment. Conversely, do not keep a fact only in a live event if session replay must reconstruct it later. The Agent lifecycle guide maps these event domains onto one complete turn.

Turns, steps, and the append-only session log

A step is one model request plus any associated tool work. A turn starts from an input and can contain zero or more steps. Tool results may require another model request, so one user prompt does not necessarily equal one step.

The session is modeled as an append-only event log. New facts are added instead of rewriting the past. This supports replay and auditing, but it also means developers must decide which facts deserve persistence. For example, a durable user message belongs in the session; a transient “currently streaming” indicator belongs in live state.

Capability seams

A capability seam separates three roles:

1. a service definition describes the contract;
2. one or more providers implement it; and
3. consumers call the capability without importing a concrete provider.

This is useful for replaceable functions such as shell execution or model access. A local provider, a remote provider, and a test provider can satisfy the same service definition while the consumer remains stable.

Use a seam when a capability genuinely needs interchangeable providers or a package boundary. Do not create one merely to avoid a normal function call. Every abstraction carries discovery, lifecycle, and error-handling costs.

Where should new behavior live?

Use this decision path when adding a feature:

• put reusable, mountable behavior in a plugin;
• put a coherent group of plugins and configuration in a bundle;
• use a profile to assemble a user-facing operating mode;
• add a persistent session event only when replay must retain the fact;
• use an agent/* event for live execution control or observation; and
• introduce a capability seam when provider replacement is an explicit requirement.

If the feature crosses the Host and Client boundary, also read the API Gateway guide. If it changes model requests or tool scheduling, trace it through the Agent lifecycle before implementation.

Official source

This article was independently created from the official DeepSeek Harness architecture guide, reviewed on 2026-08-20. Consult the upstream document for current package names and implementation-level details.