DeepSeek Harness plugin UI: settings cards and slots

DeepSeek Harness plugin UI development is not "write a frontend page": it means writing two halves in one package — a Host half that registers a settings namespace with ctx.settings.installSection(), and a browser half that registers a card into the settings.plugin.item slot. The namespace pairs them automatically, with no change to the host repository. The same two-half structure applies to any DSH plugin.

DSH plugin UI: the two halves, one package with two entries

The settings page is built from a Host half and a browser half, and a missing half means no card. The official Cookbook puts it plainly: the Host serves every registered settings namespace and the Plugins section keys its cards on the namespace they edit, so the two halves are paired up automatically. Both live in one package — the Host half under src/, the browser half under src/client/, exported as ./client and declared with dsh.client (source).

my-plugin/
├── src/index.ts          # Host half: register the namespace
├── src/client/index.tsx  # Browser half: register the card
└── package.json          # exports['./client'] + dsh.client

There is exactly one pairing key: the namespace. Make it a constant (such as MY_PLUGIN_NS = 'my-plugin') that both halves import, so a typo cannot silently make the card disappear.

DSH plugin Host half: register a settings namespace

A plugin that already has a cordis.yml entry should use ctx.settings.installSection(), which layers the entry under the user document and keeps working when no settings provider is mounted. The official Host half:

import type { Context } from '@deepseek-ai/cordis'
import type {} from '@deepseek-ai/dsh-settings'
import z from '@deepseek-ai/schemastery'

export const MY_PLUGIN_NS = 'my-plugin'

export interface Config {
  endpoint?: string
  retries?: number
}

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

export function apply(ctx: Context, config: Config) {
  let source = () => config
  ctx.inject(['settings'], (settingsCtx) => {
    settingsCtx.settings.installSection(ctx, MY_PLUGIN_NS, Config, config, {
      // Constraints the schema cannot express refuse the write, not the next use.
      validate: value => void assertReachable(value.endpoint),
      setSource: (current) => { source = current },
      onChange: () => { rebuildFromSettings(source()) },
    })
  })
}

Two easy-to-miss declarations: role('secret') on a field keeps its value off every response (the card then writes it into an update/mutate payload or addresses a credential reference through the credentials domain); and applies: 'restart' tells a configuration surface that the owner only acts on the change at the next start.

DSH plugin browser half: register the card into the slot

Cards register into the settings.plugin.item slot, and key must match the Host half's namespace. The official example:

import type { Context as ClientContext } from '@deepseek-ai/cordis'
// Type-only: the keyed slot's declaration. Cross-plugin collaboration goes
// through cordis services; a value import fails the client bundle-purity gate.
import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'

export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope']

export function apply(ctx: ClientContext): void {
  const card = new MyPluginCardController(ctx.settingsScope.bind({ namespace: MY_PLUGIN_NS }))
  ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
    name: 'settings.plugin.item',
    key: MY_PLUGIN_NS,
    locale: 'settings.myPlugin',
    inject: () => card.inject(),
  }, MyPluginCard))
}

The card owns everything inside it: chrome, controls, and copy. Note that import type {} line — across plugins only type imports are allowed, because a value import fails the bundle-purity gate.

DSH plugin config read and write semantics: value, base, user

The scope snapshot carries the three layers a form needs, and "is it overridden" is decided by key presence rather than value (source).

Write with scope.set(field, value) to store a single field, and scope.unset(field) to clear it back to the composition layer. Every write is fenced with the revision it read, which prevents two settings surfaces from overwriting each other.

DSH plugin UI display rules and packaging

The display rule is direct: a card renders only when the Host serves its key and the card claims it; if the Host does not serve the key, the card does not appear at all; and a served namespace no card claims renders nothing — which is exactly why ui-theme, permission, and llm-* stay off that tab. Card order equals registration order, and a keyed entry cannot declare its own order.

Three packaging requirements (source):

1. Expose the browser half through exports['./client'] and declare dsh.client (with platform and the client packages it injects);
2. the bundle must be the loader's expected lazy-CJS factory artifact — no published preset exists outside the repo, so you reproduce the output format yourself;
3. no cross-plugin value imports: the card brings its own chrome and staging model, and owns its own staging and revision fencing.

The moment cordis.yml mounts the plugin, it appears on the page without rebuilding the web app, because the client module system scans enabled entries and serves each built artifact according to dsh.client.

DSH plugin UI checklist and next steps

Run through this before shipping:

1. Do both halves import the same namespace constant?
2. Does the Host half handle validate (constraints the schema cannot express), setSource, and onChange?
3. Are sensitive fields marked role('secret'), and is applies: 'restart' set where a change lands at the next start?
4. Does the card use type-only imports across plugins?
5. Are exports['./client'] and dsh.client in place, with a lazy-CJS factory bundle?

Tool-call cards are a separate track (presentCall / presentResult, which must be pure functions) — see how to write a tool plugin. For configuration outside the UI, see plugin configuration; for distribution, see packaging into a bundle and publishing to the plugin hub.