Agent · AI Programming · OpenAI

How DeepSeek Harness Assembles Its Plugin Tree: Bundles, Profiles, and Whole-Row Patches

By 怕浪猫 · Aug 18, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Agent frameworks that compose behavior from plugins need a predictable override system. dsh's whole-row replacement and empty-root-on-boot discipline prevent the configuration drift and merge ambiguity that plague layered config systems in production.

Summary

Three concepts govern dsh's plugin assembly: Bundles package plugins for distribution, Profiles declare which bundles to stack and hold user overrides, and Patches replace an entry's entire config by id. The startup chain parses CLI arguments, composes four patch layers in a strict bottom-up order, rewrites the root config to an empty list on every boot to prevent state accumulation, and deep-clones patch objects to avoid reference aliasing during hot reloads.

Patch semantics are deliberately whole-row, not deep-merge. Changing one field requires restating the full config, a tradeoff that makes the final configuration tree completely predictable without inferring merge behavior. The `--dump-config` command prints the composed tree for debugging.

Three default bundles ship with the distribution: dsh-base provides model adapters, tools, persistence, sandboxing, and platform-gated shell stacks; dsh-web-app adds a web host, API gateway, and HMR; dsh-headless adds a one-shot runner for CI. Custom profiles follow a six-step workflow of copying a template, editing the bundle list, writing patches, and installing out-of-tree plugins.

Takeaways

— Bundles are packaged plugin distributions whose inserted content can always be overridden by higher patch layers.

— Profiles are named assembly manifests that list bundles, store out-of-tree plugins, and hold a cordis.patch.yml for user overrides.

— Patches locate an entry by id and replace its entire config; they do not deep-merge individual fields.

— The patch stacking order is: empty list → bundle patches → profile patch → home patch → --patch command-line overlay.

— Every startup rewrites the root config to an empty list to prevent the Cordis Loader's write-back mechanism from duplicating entries.

— structuredClone is used on patch lists to prevent insert-row reference aliasing from leaking user overrides into bundle memory objects.

— dsh-base performs platform gating: win32 gets only the pwsh stack, POSIX gets only the bash stack.

— Hot-reload watchers monitor profile-level and home-level cordis.patch.yml files and recompose patches with fresh clones on change.

— Custom profiles are created by copying a template, editing the bundle list in package.json, writing cordis.patch.yml, and installing plugins via the CLI.

— The --dump-config flag prints the final composed config tree; --dump-default-config prints only the bundle layer without user overrides.

Conclusions

Choosing whole-row replacement over deep merge is a readability-over-writability tradeoff: the final config is self-contained and requires no mental merge resolution, but users must restate complete configs for any change.

Rewriting the root config to an empty list on every boot is a defensive measure against Cordis's persistence write-back, not a cosmetic reset. Skipping it would cause bundle insertions to compound across restarts.

The structuredClone calls in both boot and live-reload paths address a subtle aliasing bug where Include inserts rows by reference, and subsequent id-targeted patches mutate the original bundle objects in place.

Platform gating inside dsh-base means the same profile declaration produces different plugin trees on Windows versus POSIX, which shifts compatibility responsibility from the user to the bundle author.

Concepts & terms

Bundle

A distribution format for a group of Cordis plugins, declared via dsh.bundle in package.json. Its patch file inserts entries that can be overridden by higher layers.

Profile

A named assembly manifest stored in the Harness home directory. It lists bundles to stack, holds a user's cordis.patch.yml, and stores out-of-tree plugins installed via the CLI.

Patch

A YAML file that locates a configuration entry by id and replaces its entire config object. dsh uses whole-row replacement, not deep merge, so any omitted fields are lost.

Cordis Loader write-back

A persistence mechanism in the Cordis plugin engine that saves the current configuration tree when a plugin self-uninstalls. dsh counters this by rewriting the root config to an empty list on every boot.

structuredClone

A JavaScript built-in that performs deep cloning. dsh uses it on patch lists to prevent Include-inserted rows from being mutated in place by subsequent id-targeted patches.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗