DSH plugin cordis.yml ids: override, disable, locate
A familiar sequence: you change the port in a profile patch and restart, nothing happens. You try another layer, still the original value. You search every config file and find no culprit.
These cases are rarely about the value. They are about the id.
DSH plugin config that will not move
When a DSH plugin patch does nothing, check the id before the value. Say a bundle contributes this row:
- insert:
- id: web
name: '@deepseek-ai/dsh-web-app'
config:
port: 3080
The user wants 8080 and adds this to the profile patch:
- id: web
config:
port: 8080
The port stays 3080. Two causes, either sufficient:
- The row has no
insert, so it expects to hit an existing id; if earlier layers use a different id, nothing matches; - Even when it matches,
configis replaced wholesale — writing onlyportremoves every other key, which can behave worse than "no effect".
A simple criterion: if the id does not match, the patch is text nobody reads.
DSH plugin id, name, and package name
In a DSH plugin the three names answer different questions, and mixing them sends patches to the wrong row. This is where beginners get lost:
| Name | Answers | Example |
|---|---|---|
| Package name | Where to load the module from | @deepseek-ai/dsh-web-app |
name | Which module this row points to | @deepseek-ai/dsh-web-app |
id | Which row this is, for overrides and diagnostics | web |
name and the package name often coincide because the module is the package entry, but local development can point name at a relative path and separate them.
The id is unrelated to both; it belongs to the row, not the module. One module can appear in two rows with different ids, and one id should appear only once in the final composition. Omitting an id is legal but loses three things: later patches cannot target the row, diagnostics are harder to read, and duplicate detection falls back to name.
DSH plugin scenario one: overriding by id
In a DSH plugin the id's main job is to be hit and replaced by a later patch. A later patch hits the same row and replaces it.
The correct form restates everything the row needs:
- id: web
config:
port: 8080
host: '127.0.0.1'
Why restate? Because a patch replaces the target row's entire config; it does not deep-merge. Write two keys and two keys remain, with everything else falling back to schema defaults.
Two consequences for bundle authors:
- When overriding another layer, write every key the row needs, not just the one you changed;
- Keep user-configurable surface small — put defaults in the schema rather than hardcoding them in config, so changing one field does not drag a dozen others.
A practical habit: run dump-config first, copy the row's current config, then edit. Reconstructing keys from memory always misses one.
DSH plugin scenario two: disabling by id
Disabling a plugin by id is faster than uninstalling it, which makes it a good temporary move. It works like this:
- id: web
disabled: true
disabled accepts booleans, null, and expression markers. A disabled row without group: true may omit required config, because the Loader never initializes it.
One trap: disabling a group: true row still validates its children as enabled, and patches inserted into a disabled group behave the same way — a disabled row with bad config can still fail. Temporary disabling is a diagnostic move, not a long-term setting; if you no longer need something, uninstall it, because a disabled row keeps participating in composition and validation.
DSH plugin scenario three: locating the row
To check whether a DSH plugin config applied, inspect the combined tree. Work through these steps:
- Run
<command> --profile <name> --dump-config; - Find the id you care about in the output;
- Read four fields: path, name, status, configRef;
- No id means the row never entered the composition — look upstream at patches or the bundles list;
- An abnormal status means the row was rejected or partially applied.
path is more precise than id. Children inside a group carry an index in their path; when your plugin sits inside a group, the id alone may not locate it, so follow the path.
Fix the diagnostic order: is the row present, is the config right, is runtime behavior correct. Reversed, you will spend an afternoon on a config that never entered the composition.
DSH plugin id naming and stability rules
Name DSH plugin ids with nouns and hyphens, not verbs. web, tool-bash, memory outlive doInit and handleRequest, because the latter describe behavior and behavior changes.
Do not embed versions or environments. web-v2 and web-dev turn every upgrade into a batch rename; environment differences belong to profiles or patch layers.
Treat the id as a public interface. Users may override your row by id, and bundles may patch each other by id. Confirm nothing external depends on it before changing it. One row, one id: two entries with the same id in dump-config means two layers inserted it, which is a duplicate insertion rather than an override, and behavior depends on composition order.
An id looks like a string and actually decides who can change a row and whether the change is visible. A minute spent naming it saves hours of override debugging. For the full rules of layer order and wholesale replacement, read packaging a bundle; for config design, read plugin config; for combining diagnostics, read local debugging.
FAQ
A DSH plugin entry id can be omitted, and the Loader accepts it. Without an id, later patches cannot target that row and diagnostics are harder to read. A non-insert patch without a non-empty id is treated as a no-op and leaves a Loader warning.
Because a DSH plugin patch replaces the entire config value for that row rather than deep-merging. Writing one key leaves only that key, with the rest falling back to schema defaults. Restate every key the row needs when overriding.
User patches target DSH plugin rows by id. When the id changes, the target no longer exists and that layer stops applying. Treat an id as a public contract and document the change as breaking.
Use dump-config to print the combined DSH plugin tree; each entry reports path, optional id, name, status, and configRef. A missing id means the row never entered the composition; an abnormal status means it was rejected or partially applied.
Related Terms
- entry
- An entry is one plugin row in cordis.yml describing which module to load, its id, its config, and whether it is disabled.— DeepSeek Harness CLI reference
- id
- An id is the stable identifier of an entry, used by later patches to target the same row and by diagnostics to locate it.— DeepSeek Harness CLI reference
- patch
- A patch is an overlay applied to the config tree in order; later layers win per row and replace the target config wholesale.— DeepSeek Harness CLI reference
- dump-config
- dump-config is a CLI command that prints the combined configuration tree without starting the service, including each entry's path, id, name, and status.— DeepSeek Harness CLI reference
Sources
- DeepSeek Harness CLI reference· deepseek-ai
- DeepSeek Harness docs: packaging and installing plugins· deepseek-harness
- DeepSeek Harness docs: plugin config· deepseek-harness