ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness Cookbook: Add a Settings Card

Plugin DevelopmentPublished 2026-11-18Author: DeepSeek Plugin Market
DeepSeek HarnessDSH pluginsettings cardVolatileCookbook
A DeepSeek Harness settings card has a Host half and a browser half. Learn the five Cookbook steps, the unique profile id rule, and four persistence checks.

A DeepSeek Harness settings card is not just a form: the Host half owns fields and persistence, the browser half owns display, and the two align through a profile entry id and the client module system. The official Cookbook splits the work into five steps (source). This walkthrough follows them and adds the four checks to run when a field refuses to persist.

DeepSeek Harness: Volatile fields: declare and read at the right time

Settings fields are live references, not plain variables. Declare them with .volatile() in the Config schema and export a Config interface containing Volatile<T> (source):

ts
export interface Config {
  endpoint: Volatile<string | undefined>
  retries: Volatile<number>
}

export const Config = z.object({
  endpoint: z.string().volatile(),
  retries: z.number().step(1).min(0).default(3).volatile(),
})

Read with .get() at operation start. If one request needs a consistent snapshot, capture the values once. Reading at module load caches the old value and ignores later saves.

Use .check() for cross-field validation. The Host runs it before persistence, and it does not enter the serialized form schema. .check() answers “can these values be saved together,” not “does one field look right.”

For credential-like values, do not pass plaintext through a normal field. Use a credential reference; role('secret') keeps a value out of form responses but does not replace a credential reference.

DeepSeek Harness: Compose the plugin: unique id and secret

A settings card works only when the plugin instance is uniquely identifiable. Give each instance a unique profile entry id; the base bundle mounts settings and config-editor, and custom profiles should read the package README before mounting them (source).

Three easy mistakes:

  1. Reusing an id — saves locate by id and can land on another entry.
  2. Treating secret as enough — role('secret') hides values from responses but is not a credential reference.
  3. Putting runtime state in settings — every save overwrites it.

Composition order also matters: settings and config-editor must be available before the form has a host. Wrong order often looks like “the page opens, but Save does nothing.”

A quick check: list the profile entry ids and confirm yours is unique and stable. If the id changes, existing settings may lose their owner.

DeepSeek Harness: Verify an edit in four places

Saved is not persisted; check four places. The official verification is the profile patch, the next consumer operation, an unchanged plugin instance id, and recovery after restart (source).

CheckWhat to look atCommon failure
Profile patchThe entry contains the new valueWritten to another id
ConsumerThe next operation reads the new value.get() too early or cached
Instance idIt stays the sameSave rebuilt the instance
RestartThe value survivesOnly memory changed

Run one negative test too: submit an invalid value and confirm both the config file and the current Volatile value stay unchanged. If an invalid value persists, .check() or the Host validation path has a gap.

Four positive checks and one negative one are worth keeping. “The page shows the new value” can be a front-end state change without persistence.

DeepSeek Harness: Contribute to another plugin's page

A settings card does not have to own a page; it can contribute to another plugin's page. Three slots: plugins.detail.actions (header controls), plugins.detail.badge (title badge), and plugins.detail.section (content below the page) (source).

Each entry renders with the page subject: { kind: 'bundle', pkg }, { kind: 'row', pkg, row }, or { kind: 'item', id }. Return null for subjects you have nothing to say about; do not render an empty block.

This fits “my plugin adds a hint or action to someone else's settings page.” It is lighter than a new page but requires correct subject handling; otherwise the content appears where it should not.

Ask whether the content is only meaningful for your plugin. If yes, keep your own page. If it supplements a bundle or item, use a detail slot.

DeepSeek Harness: Where the browser half mounts

When the browser half does not load, it is usually on the wrong loader row. The client module system scans enabled Loader entries for packages declaring dsh.client and mounts a half only on the row whose specifier is exactly the bare package name; subpath export rows never get a half (source).

Three consequences:

  1. A split bundle keeps its half on the root row — close the root row and the pages go with it.
  2. Subpath exports carry no half — a page that must outlive the row should be its own package.
  3. The build must be a lazy-CJS factory — register the package name and factory(require) with the page loader.

Write platform and inject correctly in dsh.client: platform: 'web' keeps it Web-only, and inject lists client-module dependencies. A wrong value does not error; it just leaves the page absent.

If the half never loads, check the loader row, then dsh.client, then the build format. Only then inspect the client module system itself.

DeepSeek Harness: When a field will not persist

Debug in four directions: write, locate, read, rebuild. Each corresponds to a failure branch (source):

  1. Write failed — the Host rejected, .check() blocked, or the Save API failed.
  2. Wrong target — the profile entry id is duplicated or points at another instance.
  3. Read failed — the consumer read too early or cached the old value.
  4. Rebuild overwrote — Save recreated the instance and changed the id or defaults.

The most common pair is wrong target plus stale read: the save went to another id and the consumer read the old instance. Confirm the id first, then the read timing.

The full contracts are in dev-settings-namespace and develop-plugin-ui; this article covers the Cookbook walkthrough. Align Host half, browser half, and unique id, and the settings card stops being a black box.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

What is a Volatile field in a DeepSeek Harness settings card?

A Volatile field is a DeepSeek Harness config reference read with .get() at operation start. It lets a saved change apply on the next operation without restarting the plugin or process.

Why must a DeepSeek Harness settings card use a unique profile entry id?

DeepSeek Harness writes settings by profile entry id. Reusing an id across instances can write to another instance, so each plugin instance needs its own stable id.

How do I confirm a DeepSeek Harness settings field really persisted?

In DeepSeek Harness, check four places: the profile patch, the next consumer operation, the unchanged plugin instance id, and recovery after restart. All four are needed for a real persist.

Why does a DeepSeek Harness browser half sometimes not load at all?

In DeepSeek Harness, the client module system mounts a half only on the loader row whose specifier is the bare package name. Subpath export rows never get the half, so pages should be a separate package or live on the root row.

Related Terms

Volatile
Volatile is a DeepSeek Harness config reference read at operation start with .get(); a saved change applies on the next operation.— DeepSeek Harness reference - Live config form
profile entry id
A profile entry id uniquely identifies one DeepSeek Harness plugin instance in a profile; settings writes and hot updates locate it by this id.— DeepSeek Harness reference - Live config form
browser half
The browser half is the Web-client part of a DeepSeek Harness plugin, declared through dsh.client and delivered as a lazy-CJS factory.— DeepSeek Harness reference - Live config form
plugins.detail.section
plugins.detail.section is a DeepSeek Harness settings-page slot that lets a plugin contribute a section to another plugin's detail page.— DeepSeek Harness reference - Live config form

Sources