ChatGPTClaudeGrok / X / CursorGemini

DSH plugin cordis.yml ids: override, disable, locate

Plugin DevelopmentPublished 2026-11-05Author: DeepSeek Plugin Market
DSH plugincordis.ymlpatchentry idconfig override
Changed the same plugin across three patch layers and it still does not apply? The id is usually why. Three scenarios separate id, name, and package name.

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:

yaml
- insert:
    - id: web
      name: '@deepseek-ai/dsh-web-app'
      config:
        port: 3080

The user wants 8080 and adds this to the profile patch:

yaml
- id: web
  config:
    port: 8080

The port stays 3080. Two causes, either sufficient:

  1. The row has no insert, so it expects to hit an existing id; if earlier layers use a different id, nothing matches;
  2. Even when it matches, config is replaced wholesale — writing only port removes 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:

NameAnswersExample
Package nameWhere to load the module from@deepseek-ai/dsh-web-app
nameWhich module this row points to@deepseek-ai/dsh-web-app
idWhich row this is, for overrides and diagnosticsweb

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:

yaml
- 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:

  1. When overriding another layer, write every key the row needs, not just the one you changed;
  2. 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:

yaml
- 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:

  1. Run <command> --profile <name> --dump-config;
  2. Find the id you care about in the output;
  3. Read four fields: path, name, status, configRef;
  4. No id means the row never entered the composition — look upstream at patches or the bundles list;
  5. 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can a DSH plugin entry id in cordis.yml be omitted, and what happens if it is?

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.

Why does overriding one DSH plugin field by id wipe the rest of the config?

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.

Why did user customizations stop working after I renamed a plugin entry id?

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.

How do I confirm which DSH plugin row an id maps to and whether it is healthy?

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