DeepSeek Harness settings panel: DSH plugin config forms

The DeepSeek Harness settings panel builds forms by projecting the Config fields of active profile entries; writes come in three flavors — update, replace, and mutate — each validating the full Config and rejecting stale revisions, while config changes notify a refresh through settings/document-updated (source). For the file-level config: blocks and patch overrides, see Change DeepSeek Harness plugin config; this article covers how the panel side reads and writes.

Where the DeepSeek Harness settings panel comes from: projecting the active profile's Config

The settings service projects the volatile Config fields of active profile entries, the config editor then persists edits through Cordis patches, and business consumers call .get() on their own Config reference (source). Structural points:

1. Forms are namespaced by entry id — the namespace is the local id that uniquely locates an entry in the current profile. Expected: multiple plugin instances each get independent forms as long as their entry ids differ.
2. Descriptors carry four kinds of information — the actual value, the inherited value, explicit profile overrides, and an optimistic revision. Expected: the panel shows whether a value is inherited or something you explicitly changed.
3. Ordinary fields are excluded — not every field appears in a form. Expected: not seeing a key does not mean it is absent, only that it is not part of the form.
4. Where panel plugins come from — the entries that appear in settings are the plugins the current profile loads. Expected: to add a configurable plugin, browse community implementations on DSH Plugin Hub and install it into the profile.

The three write modes of the DeepSeek Harness settings panel

update merges the submitted fields; replace first resets immediate fields to inherited configuration and then applies the submitted fields; mutate edits by individual paths and preserves secret values not included in the client response (source). How to choose:

1. update: change just a few fields — merges the submitted fields into that entry's config. Expected: for changing one or two things day to day, leaving other values alone.
2. replace: reset a whole section — resets immediate fields to inherited configuration before applying the submission. Expected: use it to bring an entry back to an "inheritance-based" state.
3. mutate: edit by path, keep secrets — applies ordered edits to individual paths; secret values not included in the client response are preserved, and unsetting an array index removes that element. Expected: prefer this for fine-grained changes involving secret fields.
4. Writes validate immediately — every write validates the full Config and rejects stale revisions before persisting. Expected: if you submit against an old descriptor, the revision will not match and the write is refused, so re-run describe.

When the DeepSeek Harness settings panel takes effect, and secret fields

settings/document-updated invalidates form descriptors after a Loader config change, which is a UI notification; remote reads always use redactSecrets: true, so fields marked role('secret') can never be returned in the response (source). Key points:

1. Re-read after invalidation — on the event, the form client re-reads that entry's schema, resolved values, and revision. Expected: the panel refreshes automatically after a change, with no restart.
2. Tell the two refresh signals apart — UI uses settings/document-updated; use loader/volatile-update only when a consumer needs to refresh registration information. Expected: do not mix them up.
3. Secret fields never leave — every remote read of ctx.settingsController is redacted, and role('secret') cannot travel in the response. Expected: the panel can display configuration safely.
4. When native editing is needed — openSettingsDocument materializes the provider-owned settings document and opens it in a native text editor. Expected: use this path to edit the file directly rather than copy-pasting a path.

Notes and common questions

1. A revision conflict is not a bug: it is concurrency protection; re-read the descriptor and resubmit.
2. Secret fields show no value: that is by design, not a load failure; change them with mutate and keep the original value.
3. Panel writes land in patches: the editor persists through Cordis patches, so file-level layers show the change too.
4. A form is not the full config: ordinary fields are excluded; for the complete field list see Which items a DeepSeek Harness plugin can configure.
5. The panel entry point is the Web UI: for opening settings and configuring models and workspaces, see How to use the DeepSeek Harness Web UI.

Sources: Plugin config forms (official docs), Use the Web UI (official docs)