跪拜 Guibai
← All articles
Artificial Intelligence · Design Patterns · Architecture

DeepSeek Harness: A Plugin Runtime Where the Agent Loop Itself Is Replaceable

By Cosolar ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Most coding agents hardcode the loop that calls models and runs tools. Harness makes that loop a replaceable plugin, so teams can swap models, execution environments, and safety policies without rewriting the agent. The framework's strict lifecycle management and session-auditability also make it viable for production deployments where resource leaks and unreconstructable model inputs are unacceptable.

Summary

DeepSeek Harness treats every agent capability as a plugin mounted on a shared runtime context. A YAML configuration file wires together session management, system prompts, tools, LLM adapters, file access, subprocesses, sandboxes, and the agent loop itself. The underlying Cordis micro-framework enforces strict lifecycle management: registrations are effects that auto-revoke on unload, dependency injection is continuously tracked rather than checked once, and the session log serves as a reconstructable source of truth for every input the model sees.

The architecture splits each capability into three independently evolving roles—service definition, provider, and consumer—so swapping a local shell for a sandboxed one changes nothing in the tools or loop. Hot module replacement works out of the box because unloading a plugin rolls back its effects and reloading satisfies the dependency graph. A built-in diagnoser surfaces exactly which plugin is stuck in PENDING state when a required service is missing.

Compared to Claude Code and Codex, Harness is a framework for platform engineers who need to self-host, embed, and evolve an agent runtime with replaceable models and loops. Against Alibaba's AgentScope, it trades Python's multi-agent workflows and visualization tooling for TypeScript's configuration-driven composition and strict engineering discipline—100% test coverage gates, branded types, and declarative surface validation.

Takeaways
— Every capability in Harness—tools, LLM adapters, sandboxes, file access, and the agent loop—is a plugin assembled through a single cordis.yml file.
— Only one package in the entire repository contains concrete loop logic; all other behaviors like retry, compaction, and sandboxing are implemented by subscribing to events.
— Each capability is split into three roles (service definition, provider, consumer) so swapping a provider requires zero changes to the definition or consumer code.
— Registrations are effects: any tool registration, event listener, or child plugin is automatically revoked when the owning plugin unloads.
— Dependency injection is continuously tracked at runtime, not checked once at startup; if a service disappears, dependent plugins unload and reload when it returns.
— Hot module replacement works by unloading a plugin (rolling back its effects) and reloading it, with the dependency graph automatically re-satisfied.
— The session log is the source of truth: anything delivered to the model must be reconstructable from session events, enabling audit, replay, and fork.
— Misconfiguration fails loudly at load time; a plugin with a missing dependency stays PENDING and a built-in diagnoser reports exactly which service is absent.
— Built-in bridge packages let existing Claude Code and Codex hooks.json files run directly on Harness without modification.
— The framework enforces 100% test coverage gates, branded types for cross-boundary IDs, and declarative surface validation as engineering invariants.
Conclusions

Making the agent loop itself a replaceable plugin is a genuinely unusual architectural choice. Most frameworks treat the loop as sacred infrastructure; Harness demotes it to just another component, which means the entire agent's behavior can be rewritten without forking the framework.

The 'model-visible equals logged' invariant is a hard architectural constraint, not a logging best-practice. This means debugging a bad model response becomes deterministic replay rather than guesswork—a property that matters for compliance and production incident response.

Harness's engineering discipline (100% coverage gates, branded types, type-equiv doc sync) signals that it is built as infrastructure for other products, not as an end-user tool. The strictness is a feature for platform teams who need the runtime to never silently fail.

The comparison with AgentScope reveals two competing philosophies for agent frameworks: configuration-driven plugin runtimes versus imperative component libraries. Harness bets that YAML composition and hot-swapping beat Python's flexibility when the goal is a long-lived, self-hosted platform rather than rapid experimentation.

Concepts & terms
Cordis
A micro plugin framework vendored inside DeepSeek Harness that provides a shared Context, dependency injection, lifecycle management via effects, and an event bus. Every Harness capability is a Cordis plugin.
Capability Seam
A design pattern that splits each agent capability into three independently evolving roles: a Service Definition (abstract interface), one or more Service Providers (concrete implementations), and a Consumer (the model-facing tool). Swapping a provider requires no changes to the other two roles.
Effect
In Cordis, any registration (tool, event listener, child plugin, service instance) is an effect attached to the plugin that created it. When the plugin unloads, all its effects are automatically revoked, eliminating manual cleanup.
Fiber
The runtime handle of a loaded plugin instance. A fiber transitions through states (PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED) and can be disposed to trigger recursive cleanup of the plugin and its children.
Waterfall Event
A Cordis event dispatch mode where listeners form a middleware chain. Each listener receives the input and a next() function; it can transform the downstream result or short-circuit by not calling next(). Used in Harness for collaborative decisions like model request modification and approval routing.
Branded Types
A TypeScript pattern using Brand<B> to create opaque types from primitives like string. Harness uses branded types for cross-boundary IDs (call IDs, session IDs) to prevent accidentally passing a raw string where a validated identifier is required.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗