A starter template for DeepSeek Harness (dsh) plugins: six plugin shapes, fourteen browser UI surfaces, and demo slash commands in one installable bundle.
Pending human review — the facts below come from the source repository.
A starter template for DeepSeek Harness (dsh) plugins: six plugin shapes, fourteen browser UI surfaces, and demo slash commands in one installable bundle.
Users who want this capability in DSH; check the source and docs before installing.
dsh plugin --profile web add github:kun2-5code/dsh-plugin-template No supported platforms were declared.
dsh) plugins. It demonstrates the six most common plugin shapes in one minimal installable bundle: - Config — Config interface + Schemastery schema; validation and defaults apply at load time (docs) - Tool — ctx.tools.register(defineTool(...)) registers a model-callable tool (docs) - Events — ctx.on / ctx.emit with declaration merging for typed events (docs) - Service — a class-form plugin that provides a service to other plugins (docs) - Hook — a tools/pre-execute permission gate that denies tool calls by config (docs) - Browser half (client) — src/client/ registers browser UI on fourteen surfaces (index: docs/ui-surfaces.md): a clickable config card under Settings → Plugins → Configurable (writes greeting / maxRetries / verbose into the settings document, taking effect live; on a stock harness the card renders a read-only "not exposed" explainer instead of vanishing), a sidebar footer action button, an input dock strip above the composer, a shell overlay pill, a header utility badge, input tool-row buttons (left/right), a custom command row for /dsh-demo, a General settings row, a Plugins tab, a settings header action, a session header action, a composer dock strip, and per-message actions on AI replies — plus a presentResult render intent on the greet tool. Only the config card's data path is gated by the harness allowlist; the other thirteen are pure slot registrations that work on any harness. The template follows the official bundle distribution model: the package declares dsh.bundle plus cordis.patch.yml, and dsh plugin add activates it as a config layer. ## Directory structure dsh-plugin-template/ ├── package.json # npm manifest + dsh.bundle / dsh.client declarations + prepare build script ├── tsconfig.json # strict type-check configuration (tsc --noEmit) ├── tsdown.config.ts # build config: Node library (lib/) + client bundle (lib/client.js), self-contained for git-install prepare ├── cordis.patch.yml # bundle config layer: inserts the plugin rows ├── dev/cordis.yml # local dev overlay (points at source; use with dsh web --patch; host half only) ├── docs/ │ └── ui-surfaces.md # where the plugin registers UI + index of every slot (bilingual: ui-surfaces.zh.md) ├── src/ │ ├── index.ts # main plugin: Config + tool + events + effect, config wired through the settings namespace │ ├── commands.ts # host half: demo slash commands /hello (replies world) and /dsh-demo (custom row) │ ├── service.ts # optional example: Service provider (disabled by default) │ ├── hook.ts # optional example: hook permission gate (disabled by default) │ └── client/ # browser half: one module per UI surface (see docs/ui-surfaces.md) │ ├── index.ts # client entry: inject + apply, assembles the registrations │ ├── constants.ts # shared NAMESPACE + DEMO_COMMAND_NAME (keep in sync with package.json name / cordis.patch.yml) │ ├── types.ts # minimal structural types for ctx services (no @deepseek-ai client imports) │ ├── styles.ts # one injected <style> with all dtpl-* classes (theme tokens only) │ ├── config-card.ts # settings.plugin.item: the clickable config card (staged form + status states) │ ├── sidebar-action.ts # sidebar.footer.action: sidebar-footer button │ ├── input-dock.ts # conversation.input.dock: strip above the composer (session-scoped) │ ├── shell-overlay.ts # shell.overlay: frame-wide floating pill │ ├── header-utilities.ts # conversation.session.header.utilities: right-aligned header badge │ ├── input-left.ts # conversation.input.left: tool-row control at the left end │ ├── input-right.ts # conversation.input.right: tool-row control next to send │ ├── commandview.ts # conversation.chat.commandview: custom row for /dsh-demo │ ├── general-item.ts # settings.general.item: one preference row in Settings → General │ ├── plugins-tab.ts # settings.plugins.tab: a new tab in the Plugins page │ ├── settings-action.ts # settings.action: button in the settings header │ ├── header-actions.ts # conversation.session.header.actions: session-title action button │ ├── composer-dock.ts # conversation.composer.dock: strip under the composer card │ └── assistant-actions.ts # conversation.chat.assistant-actions: per-message button └── test/smoke.mjs # smoke test on the build output (incl. settings wiring unit test) ## Quick start ### Install as a bundle (for users) From any directory, install this package (or your fork) into a dsh profile: sh # local directory dsh plugin --profile demo add /path/to/dsh-plugin-template # or directly from GitHub (replace with your own repo after forking) dsh plugin --profile demo add github:you/dsh-plugin-template A GitHub install pulls source; pnpm runs prepare (i.e. tsdown) to build lib/. On pnpm ≥10 the first git-dependency prepare is refused; add the package name pnpm prints to the profile's pnpm-workspace.yaml and retry: yaml allowBuilds: dsh-plugin-template: true > This allowlist authorizes executing that package's code at install time — only allow source you trust, and prefer pinning a commit: github:you/dsh-plugin-template#<sha>. Verify the config layer and boot: sh dsh --profile demo --dump-config # should show a "# == dsh-plugin-template" layer dsh --profile demo > Note: a custom-named profile (e.g. demo) contains only dsh-base and is headless (no GUI). > For the Web GUI and the config card below, use the web profile (= dsh-base + dsh-web-app) — see testing the config card. ### Local development (modifying the plugin) From the root of a deepseek-harness source checkout, load this repo's source directly via an overlay (no install, no build): sh pnpm dsh web --patch /absolute/path/to/dsh-plugin-template/dev/cordis.yml Set name in dev/cordis.yml to this repo's absolute path on your machine, open http://127.0.0.1:3080, and ask the model to call the greet tool. > ⚠️ A --patch overlay only loads the plugin's host half (module resolution cannot reach package-level declarations). > To test the browser-half config card you must install into a profile (resolved by name: dsh-plugin-template) — see the next section. Run the checks yourself during development: sh pnpm install pnpm typecheck pnpm build node test/smoke.mjs > If this repo sits INSIDE a deepseek-harness checkout (nested, as in the harness repo root), pnpm install is captured by the parent workspace and installs nothing here — the template is not a workspace member. Use pnpm install --ignore-workspace (pnpm ≥9.5) so the template installs its own node_modules from its own lockfile; or clone the template standalone. ### Testing the config card (in the GUI) The config card renders in the browser and depends on dsh's client-modules discovering the dsh.client declaration by package name, so the package must be installed into a profile (a --patch source path won't do): sh # 1. Build (produces lib/index.js + lib/client.js) cd /path/to/dsh-plugin-template && pnpm build # 2. Install into the web profile (= dsh-base + dsh-web-app, full GUI) dsh plugin --profile web add /path/to/dsh-plugin-template # 3. Boot the web GUI (`dsh web` is equivalent to `dsh --profile web`) dsh web Open http://127.0.0.1:3080: 1. Bottom-left Settings → Plugins → Configurable tab: you should see a dsh-plugin-template card. On a stock harness it renders a read-only "not exposed" status card (see below); after the one-line harness change it renders the editable greeting / maxRetries / verbose fields; 2. Change greeting, click Save — the status line should confirm it takes effect immediately; 3. Back in a session, ask the model to call the greet tool — you should see the new greeting (the host half reads the resolved namespace value live, no restart); 4. The change lands in the settings document (settings.yaml under $DSH_HOME) and survives restarts; to restore a default, edit the field back or clear it in the card. After editing the client half (src/client/), rerun pnpm build and refresh the page (the client bundle's rev query cache-busts). ### The config card on a stock harness (no source edits) The card is a browser plugin (src/client/config-card.ts) that binds the settings namespace dsh-plugin-template through the settingsScope service. It always renders — but on a stock harness it shows a read-only "not exposed" status card instead of editable fields. Why: dsh's web gateway serves settings namespaces only from an explicit allowlist (WEB_SETTINGS_NAMESPACES in packages/host/apiproxy/src/api-proxy.ts), and a namespace absent from it answers settings-not-exposed even when its owner plugin registered it. This is a harness-side registration decision (the same source comment calls moving the declaration into settings.register() "deferred work"), not a template defect: the built-in cards render because their namespaces (shell, agent-loop, …) are allowlisted, and there is currently no plugin-side channel to add one — the gateway's RPC map is compile-time fixed and no registration flag exists yet. What works on a stock harness with zero edits: - the entire host half — the greet tool, events, the service, the hook gate — including live config reads: writes are only gated at the web RPC, the plugin itself reads the resolved namespace value on every execution; - the card slot itself: the card appears under Settings → Plugins → Configurable and explains the exposure state instead of vanishing silently. To make the card editable, pick one: 1. add 'dsh-plugin-template' to WEB_SETTINGS_NAMESPACES in packages/host/apiproxy/src/api-proxy.ts (one line; rebuild/restart the harness; lost when you update the checkout): ts const WEB_SETTINGS_NAMESPACES = [ 'agent-loop', 'shell', 'locale', 'permission', 'ui-conversation', 'ui-theme', 'web-search-deepseek', 'dsh-plugin-template', // ← add this line ] as const 2. wait for the harness's deferred work — moving the exposure declaration into settings.register() — which this template already targets by registering the namespace the canonical way (installSettingsSection). ## Making it your own plugin 1. Rename the package: keep package.json name (npm name, e.g. dsh-my-plugin), src/index.ts name, and cordis.patch.yml id/name consistent; when renaming the ./service subpath, update exports/files too. Renaming also touches browser-half spots: the client bundle id in tsdown.config.ts (__ModuleLoader__.load({ id })), NAMESPACE in src/client/constants.ts, and dsh.client in package.json (if you need inject). 2. Change the Config interface and Config schema: anything two deployments should be able to set differently must be a config field (design principles). The config is wired to the settings namespace — does the GUI card auto-render a form from your schema? No: the card in src/client/config-card.ts is hand-written; add a field row there for each new config field. 3. Register your tool in apply: ctx.tools.register(defineTool({...})); execute returns the canonical value declared by output.schema, and output.render is the pure function for model-visible rendering (tool reference). 4. To provide capabilities to other plugins, enable src/service.ts and uncomment its row in cordis.patch.yml. 5. Remember to declare module '@deepseek-ai/cordis' to merge Context / Events types — that is what keeps cross-package boundaries type-safe. 6. To intercept tool calls, act as a permission gate, or respond to system hooks, enable src/hook.ts (uncomment its cordis.patch.yml row): ctx.on('tools/pre-execute', ...) returns { kind: 'deny', reason } or calls next() to allow (extension cookbook). 7. Config reads: every read in src/index.ts goes through configSource() (the resolved settings-namespace value, falling back to the composition entry). If you derive registration-level facts from config in apply (e.g. register different tools by config), rebuild them in installSettingsSection's onChange rather than reading only at execution points (see bash-local). ## How the browser half works - package.json declares dsh.client: { platform: "web" } + exports["./client"] → dsh's client-modules discovers it and loads lib/client.js as a browser plugin; - the client entry (src/client/index.ts) assembles one registration per UI surface — the config card (settings.plugin.item), the sidebar footer action (sidebar.footer.action), and the input dock (conversation.input.dock) — see the UI surfaces index; - the config card binds the dsh-plugin-template namespace via the settingsScope service: reads snapshots, stages drafts, and writes field-by-field on save (revision-fenced); - the host half (src/index.ts) registers the same namespace with installSettingsSection (the cordis.yml config is the base layer) and reads the resolved value lazily in the tool → saving takes effect immediately; - at runtime the client half depends only on react (provided by the browser platform module table); everything else goes through ctx services and no @deepseek-ai client package is imported — keep that discipline when editing the template. ## Publishing - npm: pnpm publish (files already includes the build output and the patch; no extra steps) - tarball: pnpm pack, then dsh plugin --profile demo add ./dsh-plugin-template-0.1.0.tgz - git: dsh plugin add github:you/dsh-plugin-template (combined with the allowBuilds step above) ## Related docs - Plugin development intro: basic/index.md - Plugin config: basic/config.md - Tool development: basic/tool.md - Packaging & installation: basic/publish.md - Plugins & lifecycle: framework/index.md - Services & dependencies: framework/service.md - Event system: framework/events.md - Cordis tutorial: cordis-tutorialNot by stars — picked by hand, one at a time.
A visual settings dashboard for DeepSeek Harness: every registered settings namespace — including third-party plugin ones the official UI never covers — rendered as editable, schema-driven forms. Early, but the right direction: stop hand-editing YAML.
A DIY trajectory visualizer for DeepSeek Harness: watch the agent’s plan and execution unfold as a graph instead of scrolling raw logs. Early, but it fills a real gap — understanding at a glance what the agent is doing.
Dispatch DSH work from Claude Code / Codex: spin up in-host DSH agent sessions with per-tier presets, watch native subagent progress, and borrow a multimodal bridge that lends the text-only harness vision and image generation. An orchestration plugin that turns DSH into a backend for other coding agents.