跪拜 Guibai
← All articles
DeepSeek · Agent · AI Programming

DeepSeek Harness: Webpack and Koa Were the Agent Framework All Along

By _砖家 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Front-end developers can transfer most of their existing knowledge to building agent frameworks—hooks, middleware, DI, and cleanup are all there. The real cost of entry is the new domain material: streaming protocols, context engineering, and tool-calling semantics, which the article identifies as the only genuinely new knowledge. That lowers the barrier for a large pool of developers and suggests that agent frameworks are more about combining proven architecture than inventing new paradigms.

Summary

DeepSeek Harness, an open-source agent framework, builds its plugin system on Cordis, and that system turns out to be a rehash of patterns any React or Node developer knows. Its `cordis.yml` mirrors `webpack.config.js`, its event system implements Koa's onion model, its `inject` declaration behaves like React Context with dependency resolution, and its `ctx.effect` enforces cleanup the way `useEffect` should. The article, from a front-end engineer who read the source, walks through each mapping and the surprising details: plugins start concurrently so file order doesn't matter, the entire waterfall middleware fits in 15 lines, and a missing `next()` call silently kills the rest of the pipeline. The one piece with no web equivalent is the agent loop itself: a `while` loop that assembles context, calls the model, executes tool calls, and repeats until the model requests no more tools. Everything else—permissions, sandboxes, context compression, sub-agents—sits as plugins on that loop. The article also highlights an epoch fingerprint mechanism: Cordis computes a dependency fingerprint for each plugin and reloads it whenever any injected service changes, which lets you swap a local Bash provider for a sandboxed one by editing a single line in the config.

Takeaways
— `cordis.yml` entries start concurrently; plugin execution order depends on dependency declarations, not list position.
— Cross-plugin services must be consumed via `inject` declarations, not `import`, to get compile-time types and runtime readiness guarantees.
— Cordis's `waterfall` event mode implements onion middleware with a recursive `next()`; its source is 15 lines.
— In waterfall, listener execution order and value computation order are reversed: the first listener's transform runs last.
— An observational listener that forgets to call `next()` silently stops all downstream listeners and crashes on `undefined.kind`.
— `ctx.effect` forces a disposer to run on plugin unload; resources not registered with Cordis, like raw `setInterval`, leak and keep the process alive.
— A plugin's epoch fingerprint combines its revision and the UIDs of its injected dependencies; any change reloads the plugin automatically.
— The agent loop is a `while` loop that assembles context, calls the model, runs tool calls, and breaks when no tool call is requested.
Conclusions

Mapping Cordis to Webpack, Koa, and React is a strong onboarding aid, but it obscures the genuinely hard parts of agent development: streaming chunk assembly, KV cache byte consistency, and context-window constraints have no web equivalents.

The epoch fingerprint design turns dependency resolution into string equality, making hot reload trivial, but it also means any change to a service reloads every dependent plugin, which could become a performance hazard in larger systems.

The silent failure when `next()` is omitted in an observational listener suggests Cordis's contract should be explicit: observers must always pass control to the next listener, or the semantics become 'veto' rather than 'observe'.

Concepts & terms
Onion model middleware
A middleware pattern where each handler calls `next()` to pass control downstream, then executes code after the downstream completes, allowing pre- and post-processing around the core logic.
Waterfall event dispatch
Cordis's event mode where listeners are called in order, each receiving a `next` function that recursively invokes the next listener; the last listener's return value becomes the input to the previous listener's post-processing, so execution order and computation order are reversed.
Epoch fingerprint
A string computed from a plugin's revision and the unique IDs of its injected dependencies; any change to a dependency's UID alters the fingerprint, triggering Cordis to reload the plugin. This enables automatic hot reloading and service replacement without explicit teardown logic.
Effect disposer
In Cordis, `ctx.effect` registers a function whose returned cleanup (disposer) is guaranteed to run when the plugin is unloaded. Unlike React's `useEffect`, which relies on developer discipline, Cordis enforces the cleanup at runtime.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗