After Everything Becomes a Plugin: A New Paradigm for Agent Engineering

This article introduces DeepSeek Harness's plugin-based architecture, which uses fine-grained, transparent components to optimize AI agent effectiveness and cost.

By Wang Chen

The term "new paradigm" is used quite often, but it is an apt description of Deepseek Harness.

Deepseek Harness introduces an entirely new paradigm for building Agents. Engineers who previously designed engineering projects and products around the LangChain paradigm will gain unprecedented opportunities to innovate.

The LangChain paradigm was designed to reduce the complexity of Agent development, whereas Deepseek Harness was designed to reduce the complexity of optimizing Agent experience and cost. The finer the plugin granularity, the more transparent the Agent's operation.

Different goals call for different architectures, and architecture is the bottleneck in applying intelligence.

01 What Is a Plugin-Based Architecture?

A plugin is a common term in software architecture.

Browsers provide plugin capabilities, such as plugins for translating pages and video subtitles. Broadly speaking, software in mobile app stores can also be considered plugins for the operating system. These are all ways to extend software functionality. A vivid analogy is LEGO: basic rectangular, square, circular, and other pieces can be assembled into furniture, appliances, buildings, and more.

Plugins therefore have the following characteristics:

Decoupling: A plugin is a complete functional unit in its own right and requires no changes to the software's main code.
Pluggability: Install it and it becomes available; remove it and it disappears, without affecting the original software.
Replaceability: Different plugins can use the same slot, such as replacing a translation plugin with a better one.
Standardization: Everyone follows the same interface rules. As long as those rules are followed, plugins written by different people remain compatible.

In the context of DeepSeek Harness, "everything is a plugin" means that model connections, tool invocation, session maintenance, conversation memory, interaction presentation, and even the Agent's main loop itself are all planned as pluggable components, taking fine-grained plugin design to its logical extreme. The starting point is to make Agent operation sufficiently transparent: in the Trajectory view, every Agent run is traceable, and everything can be replayed, forked, and audited, greatly reducing the complexity of optimizing Agent experience and cost.

The finer the plugin granularity, the fewer the black boxes and the more transparent the execution. The more clearly we can see it, the greater the scope for Agent optimization.

02 How Does It Differ from Development Frameworks Based on the LangChain Paradigm?

LangChain, along with LlamaIndex, AutoGen, CrewAI, and others, emerged to help engineers unfamiliar with LLMs quickly build working applications. Its abstractions move upward through encapsulation, providing high-level abstractions such as Chain, Agent, Tool, Memory, and Retriever. Prompt assembly, tool scheduling, and state management are wrapped into the framework, hiding runtime details so developers have less to worry about.

High-level abstraction lowers the barrier to building Agents, but when model interpretability is already weak, it makes Agent behavior harder to understand.

The Model Itself Is Already a Black Box

The decision-making process of today's large models inherently lacks transparency: why a particular tool is chosen, why a particular piece of reasoning is generated, or why a particular step fails. We can see only the inputs and outputs; it is difficult to know precisely how the internal weights operate.

High-Level Abstraction Adds Another Framework Black Box

To reduce development complexity, frameworks such as LangChain encapsulate a great deal: Agent loops, tool-call orchestration, Memory management, Prompt assembly, retry logic, middleware, and more. Much of this is hidden inside the framework.

Developers mainly work with objects such as Agent, Chain, and Tool. Understanding what actually happens during execution, such as how context is assembled, how tool results are truncated or injected, and how the loop decides whether to continue or stop, often requires enabling additional tracing, inspecting source code, or relying on external observability tools such as Alibaba Cloud AgentLoop to see clearly. When problems arise, such as hallucinations, infinite loops, confused tool calls, or soaring costs, diagnosis often requires navigating multiple layers of abstraction before reaching the actual data and event flows.

As a result, we can see what the Agent produced, but it is difficult to clearly explain why it acted that way, exactly what the context looked like at each intermediate step, or which part wasted tokens.

Model black box + framework black box = two layers of opacity.

Atomic Plugins

DeepSeek Harness proposes an architectural solution: make everything a plugin and treat the log as the single source of truth. Under this architecture:

Every piece of content seen by the model, every tool call and result, every context injection, and every loop decision is recorded in a replayable event stream.
Plugin boundaries are clear. When a layer, such as Prompt assembly or the tool execution pipeline, is replaced or intercepted, the scope of its impact is controllable and observable.
Fewer abstractions eliminate situations where "the framework makes decisions for you without telling you."

Of course, this transparency comes at a price: development requires understanding more low-level details, raising the barrier to entry. In return, given the reality of weak model interpretability, we can at least make framework-layer behavior as clear as possible, enabling more targeted optimization of effectiveness and cost.

03 How Does It Differ from Pi Agent?

Pi Agent (pi-mono) is a highly influential minimalist terminal Coding Harness today. It maintains a minimal core: just four built-in tools, Read, Write, Edit, and Bash, and a very short system prompt. Other capabilities are loaded on demand through TypeScript extensions, Skills, and Packages. With tree-structured Sessions, strong cache friendliness, and self-extension capabilities, Pi often delivers leading success rates and cost performance when the same model is switched to Pi in evaluations such as Composio.

Pi's philosophy is "minimal core + on-demand extensions." It suits terminal workflows and emphasizes control, low noise, and high cache hit rates.

DeepSeek Harness goes further: not only are tools extensible, but the loop, sessions, sandbox, UI, and scheduling are themselves plugins. It provides a Web UI and multiple operating modes (standard, minimal, creative, and PTC), with a more complete Session event stream. It targets broader Agent infrastructure development, rather than only terminal Coding Agents.

Pi is like a precision scalpel; DeepSeek Harness is like an operating table and instrument library that can be freely reconfigured.

Both pursue transparency and customization, but DeepSeek takes plugin-based design further and applies it to general-purpose Agents, not just Coding.

04 Which Plugins Does DeepSeek Harness Include?

In packages/bundle/base/cordis.patch.yml, the actual loading manifest for the base bundle (dsh-base) can be roughly divided into six layers:

Layer	Representative Plugins	Responsibilities
Model Layer	`dsh-llm-deepseek`, `dsh-llm-pi-ai`, `dsh-llm-retry`, `dsh-token-meter`	Official adapter, multi-provider adapter, request retries, token metering
Execution Layer	`dsh-sandbox-local`, `dsh-sandbox-policy`, `tool-bash/pwsh`, `tool-fs`, `tool-fs-search`, `tool-jobs`	Sandbox and command execution, file reading/writing/editing, glob/grep searches, background tasks
Orchestration Layer	`tool-subagent` family, `tool-workflow`, `tool-ralph`, `plan-mode`, `tool-todo`, `tool-goal`	Subagent spawning and control, workflows, fixed-round loops, planning mode
Context Layer	`compaction-basic`, `compaction-tool-result-pruner`, `spill-local`, `agent-instructions`, `skill`	Context compaction, tool-result pruning, spilling large results, reading `AGENTS.md`, loading skills
Governance Layer	`dsh-user-approval`, `dsh-permission-presets`, `fs-observation-policy`	Human approval, three permission presets (read-only / workspace-write / danger-full-access), read-before-write policy
Persistence and Observability Layer	`session-persistence-jsonl`, `session-query-sqlite`, `session-telemetry-otel`, `settings-file`, `credentials-local`	Persisting session logs to disk, session retrieval, OTel telemetry (disabled by default), configuration and credentials

DeepSeek Harness plugins are not simply laid out side by side; instead, layers are stacked to form a complete plugin tree. A running dsh is this tree: at startup, the configuration layers are stacked in a fixed order to form the set of plugins that actually takes effect.

The main layers are as follows, stacked from bottom to top:

1. Bundle (package collection) layer: This is the most basic "plugin package." A Bundle is an npm package that uses cordis.patch.yml to declare which plugin entries it mounts (model adapters, tools, persistence, sandbox, settings, and so on).

Official built-in examples:

dsh-base: The first layer of every Profile, containing core capabilities such as model adapters, tools, persistence, sandbox and approval policies, settings, credentials, and telemetry.
dsh-web-app: Adds a browser Web UI on top of base.
dsh-headless: A one-shot execution mode without a server.

A Bundle is a distributable, installable unit; subsequent layers can override the content it inserts.

2. Profile (configuration profile) layer: A Profile is a "named assembly plan" stored in the Harness home (by default, ~/.dsh/profiles/<name>). It does two things:

Lists the Bundles to be stacked in order (dsh.profile.bundles).
Keeps its own copy of cordis.patch.yml (the user's personalized patch for this Profile). The official templates provide web and headless as the two template Profiles.

3. User Patch layer (two levels):

The Profile's own cordis.patch.yml (higher priority than the Bundle).
Home-level $DSH_HOME/cordis.patch.yml (machine-level preferences shared by all Profiles).

4. Command-line Overlay layer (--patch): At startup, use dsh ... --patch xxx.yml to temporarily stack the highest-priority patches, which take effect in argument order.

Stacking order (starting from an empty list): Bundle (in Profile list order) → Profile patch → Home-level patch → --patch overlay.

Use this command to view the complete configuration tree actually used at startup:

dsh --profile web --dump-config

Any printed entry can be replaced in its entirety or added by your own patch, based on its id.

There is also the concept of a Capability Seam: each replaceable capability usually consists of three parts, "interface definition + Provider implementation + Consumer usage." Replacing a Provider can affect the entire related chain.

05 How Do You Use and Contribute Plugins?

Using Plugins

1. Use the Official Combinations Directly

npx @deepseek-ai/dsh web          # Use web Profile
# or
dsh --profile headless ...

2. Inspect and Debug the Current Plugin Tree

dsh --profile web --dump-config

3. Install a Community Bundle or Your Own Bundle

dsh plugin --profile web add <npm package name or local path>

After installation, it is automatically added to the Bundle list of that Profile.

4. Write a temporary local patch: Create cordis.patch.yml, use insert or replace by id, then run:

dsh web --patch ./my-patch.yml

5. Use in code: Plugins use ctx to register services (such as ctx.tools, ctx.llm, ctx.sessions). Other plugins use inject to declare dependencies and automatically obtain the corresponding capabilities at runtime.

Contributing Plugins

There are two main ways to contribute:

1. Write an Installable Bundle (Recommended for Community Use)

1. Create an npm package directory containing:

package.json (declaring "dsh": { "bundle": { "patch": "./cordis.patch.yml" } })
cordis.patch.yml (describing the plugin entries to insert/override)
The actual plugin code (a TypeScript module exporting apply(ctx))

2. After it is published to npm, others can use dsh plugin add to install it.
3. It is recommended that your GitHub repository include the dsh-plugin topic to improve discoverability (the official project also encourages this).

2. Contribute Directly to the Official Repository or Write Local Plugins

Quick local experiments: Write a module exporting apply(ctx) and use --patch to insert it.
Formal contributions: Refer to the repository's CONTRIBUTING.md, docs/cookbook/ (with guides for adding a package, tool, LLM adapter, and Chat node), as well as the architecture documentation.
Plugins can take the form of functions, objects, or classes (extending Service).

Basic template for writing a plugin:

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

export const name = 'my-plugin'
export const inject = ['tools']  // Optional: Declare dependencies

export function apply(ctx: Context) {
  // Register tools, listen to events, provide services, etc.
  ctx.tools.register(...)
}

Everything registered is reversible: it is automatically cleaned up when the plugin is unloaded.

DeepSeek Harness uses Bundle → Profile → Patch → Overlay layering to turn "everything is a plugin" into manageable, overridable, distributable engineering practice. Developers can easily use existing combinations, deeply customize them by writing Bundles or Patches, and conveniently contribute them to the community.

However, it is still in developer preview, and the core API may continue to evolve. Refer to the official documentation and dsh --dump-config as the authoritative references.

06 How Does It Help Optimize Agent Effectiveness and Cost?

Precisely because DeepSeek Harness has extremely fine granularity and highly transparent execution, optimization becomes actionable:

Effectiveness tuning: Loop policies, context-injection logic, tool execution pipelines, and sandbox policies can be replaced independently. Minimal mode can be used for model benchmarking, while creative mode supports experimenting with new combinations in memory. Complete trajectory replay makes "why it failed" clear at a glance, rather than requiring black-box guesswork.
Cost tuning: Session logs expose the source of every token expenditure. Prompt assembly and tool Schema ordering can be adjusted for cache friendliness; lighter loops or toolsets can be substituted; and Provider-level optimization can be performed for specific models. Different plugin combinations with the same model can produce significant differences in success rate and unit cost.
Continuous iteration: Plugins are reversible, making hot-swapping possible. Engineers can tune architecture as they tune parameters: replace a sandbox, change an event interception point, or reorganize a Bundle, and immediately observe changes in effectiveness and cost.

Only when application architecture is no longer a bottleneck will the boundaries of applied intelligence truly open up. Once developers familiar with Agent engineering practice master this more atomic foundation, they will be able to refine Agent experience and economics with unprecedented precision.

Community

After Everything Becomes a Plugin: A New Paradigm for Agent Engineering

01 What Is a Plugin-Based Architecture?

02 How Does It Differ from Development Frameworks Based on the LangChain Paradigm?

The Model Itself Is Already a Black Box

High-Level Abstraction Adds Another Framework Black Box

Atomic Plugins

03 How Does It Differ from Pi Agent?

04 Which Plugins Does DeepSeek Harness Include?

05 How Do You Use and Contribute Plugins?

Using Plugins

Contributing Plugins

06 How Does It Help Optimize Agent Effectiveness and Cost?

Read previous post:

Read next post:

Alibaba Cloud Native Community

You may also like

Comments

Alibaba Cloud Native Community

Related Products

DeepSeek

Token Plan

QwenWork

AgentCore