dsh-plugin-builder

中文文档

An Agent Skill for deciding, building, incrementally modifying, validating, packaging, and managing installable DeepSeek Harness (dsh) plugins.

It chooses the narrowest supported extension point before generating code: tool, policy guard, provider seam, LLM adapter, Client Conversation Node, theme or shell contribution, protocol bridge—or no plugin at all. Valid requests become independent TypeScript ESM packages with a dsh.bundle, development overlay, design record, smoke tests, and verification commands.

Validated on Windows with @deepseek-ai/dsh@0.1.0-rc.6. Harness is still a developer preview and may introduce breaking changes.

Real, tested showcase

The repository includes four plugins produced with this Skill. All are installed in the local web profile, visible in Settings, and tested through the actual Web UI.

Package	Shape and extension point	Visible effect
dsh-aurora-ui	Pure Client Web UI; ctx.theme.register(), additive shell.overlay, and ctx.layout	Recolors the whole application with a cyan/violet Aurora theme and adds a floating controller for theme, sidebar, and details actions.
dsh-luna-pet	Pure Client Web UI; additive shell.overlay with an embedded 8×9 WebP atlas	Reuses the user's existing Luna pet with a frameless, draggable overlay, persistent placement, nine animations, and compact mode.
dsh-release-readiness	Host tool + Client Conversation Node; ctx.tools.register() and conversation.chat.node	The model submits evidence-backed gates and Chat renders a scored release dashboard with warnings and blockers. The card replays after a service restart from core tool/result metadata.
dsh-command-safety	Monotonic policy guard; ctx.tools.guard()	Destructive-looking bash or pwsh calls are denied before the shell runs, with the matched rule shown in the conversation.

Whole-app Aurora workbench

dsh-aurora-ui registers a third-party semantic theme and contributes an additive shell overlay. The real controller below switched between Aurora and the original theme, collapsed and restored the sidebar, and closed the details panel without replacing first-party shell surfaces.

Animated Luna desktop pet

dsh-luna-pet reuses the user's existing Luna atlas without modifying ~/.codex/pets/luna. This real DSH Web capture shows the frameless overlay after Luna was dragged away from the input area. Drag Luna herself to reposition her; the viewport-clamped position survives reloads. The controls switch among idle, work, wait, review, patrol, and failure states, while hover, click, and compact mode retain their original interactions.

Release dashboard

A configured third-party model called release_readiness with five real project gates. The plugin calculated 90/100, rendered four passes and one warning, and the same card was verified again after restarting Harness.

Command denial

The model attempted a Remove-Item -Recurse -Force probe against a path confirmed not to exist. dsh-command-safety denied it before PowerShell ran and surfaced the exact matching policy.

Searchable plugin inventory

Searching showcase in Settings → Plugins → Plugin list returns all four mounted and enabled entries.

These five images are direct captures from the live local service at http://127.0.0.1:3080; they are not generated or composited.

Install the Skill

Clone the repository into a Skill directory scanned by your agent client. Keep the folder name dsh-plugin-builder.

git clone https://github.com/kingjly/dsh-plugin-builder.git "$HOME/.grok/skills/dsh-plugin-builder"

Common locations:

~/.grok/skills/dsh-plugin-builder/       # Grok
~/.claude/skills/dsh-plugin-builder/     # Claude Code
.agents/skills/dsh-plugin-builder/       # project-local clients

The Skill is ready when SKILL.md exists at the directory root.

Use it

Explicit invocation:

/dsh-plugin-builder Create a release-readiness tool with a replayable Web conversation card. Package it as an installable bundle and test it locally.

For the most precise result, state the capability and side effects, output directory, required delivery form (--patch, installable bundle, or both), and credential environment-variable names. Never paste live secrets into generated files.

Defaults are an out-of-tree Host plugin, TypeScript ESM, the web profile, no agent-loop changes, and a local overlay test before installation.

Modify an existing plugin

The Skill can update an existing out-of-tree plugin without regenerating its scaffold. Point it at the package and describe the desired behavior:

/dsh-plugin-builder Modify ./showcase/dsh-luna-pet: remove the outer card, make Luna draggable, persist her position, then rebuild and verify it in the real Web UI.

For modification tasks, the Skill first audits the current package and extension shape, then preserves the package name, raw entry id, configuration keys, and existing persistence semantics. It changes only the necessary source and documentation, reruns the static validator and package tests, and exercises the relevant Host or Client behavior. Client UI changes are checked in a fresh browser page; dependency or bundle-manifest changes still require a service restart.

Decision-first workflow

Request	Selected extension
Add a structured model capability	Tool registered with defineTool()
Deny or constrain an existing tool call	Monotonic ctx.tools.guard() policy
Replace filesystem, shell, search, sandbox, or subagent execution	Existing Service Provider seam
Add or route a model backend	Configure dsh-llm-pi-ai first; write an adapter only when necessary
Add a replayable Chat surface	Host result/event plus Client Conversation Node
Change the whole Web UI or add shell controls	Client plugin using a semantic theme and additive shell slot
Connect an IM, IDE, or automation protocol	Protocol bridge over ctx.agents
Modify agent-loop, duplicate bash, or rewrite an existing MCP tool	Refuse and point to the supported seam

Every generated package records its choice in plugin-design.md before implementation.

Run the showcase

Prerequisites: Node.js 22+, pnpm, Python 3.10+, and DeepSeek Harness.

pnpm add --global @deepseek-ai/dsh@0.1.0-rc.6
py -3 scripts/render_showcase_overlays.py
cd showcase
pnpm install
pnpm build
pnpm test

Run all four packages from source:

dsh web --patch ./cordis.dev.yml

Or install all four into a persistent web profile from the repository root:

$env:DSH_HOME = (Join-Path (Get-Location) '.dsh-home')
dsh plugin --profile web add .\showcase\dsh-aurora-ui .\showcase\dsh-luna-pet .\showcase\dsh-release-readiness .\showcase\dsh-command-safety
dsh --profile web --dump-config
dsh web --port 3080

Always use the same DSH_HOME for plugin installation and every restart. Starting once without it opens a different profile and storage root, which can make model settings and conversations appear to have disappeared even though the original data is still intact.

On Windows, local ESM entries in cordis.dev.yml must be file:///C:/... URLs. render_showcase_overlays.py regenerates portable absolute import specifiers for the current checkout.

No model key is required for compilation, static validation, tests, bundle installation, or --dump-config. A configured model is required only for an end-to-end conversation.

Hot-enable and disable installed plugins

The Skill now distinguishes runtime state from installation state. For a package that remains installed and listed in dsh.profile.bundles, add an exact entry override to the active profile's cordis.patch.yml:

- id: showcase-aurora-ui
  disabled: true

Set disabled: false (or remove only that override) to enable it again. DSH watches the user patch layer, so the Host inventory changes without restarting the service. An already-open browser page may still need one refresh to load or unload a Client UI contribution.

This is different from dsh plugin add/remove or editing the profile package.json: those operations change dependencies and bundles and require a service restart. Always resolve the live process's actual DSH_HOME and raw bundle entry id first; an inventory id such as include:showcase-aurora-ui is a Loader path, not necessarily the id to write into the patch.

Try the visible effects

With dsh-aurora-ui installed, the complete Web UI switches to Aurora and the bottom-right controller can restore the original theme, toggle the workspace sidebar, or close the details panel.

With dsh-luna-pet installed, drag Luna herself to move the frameless overlay; the chosen position survives reloads. Use the floating controls to select Idle, Work, Wait, Review, Patrol, or Oops. Hover Luna for her head-pat response, click her for the contented animation, and use Compact to leave only the animated pet visible.

Ask the model to call release_readiness with explicit gates such as Build, Tests, Documentation, Screenshots, and Distribution. Each gate must be pass, warn, or fail; the dashboard is deterministic.

For the safety demo, first confirm the probe path does not exist:

Test-Path -LiteralPath .\__dsh_plugin_builder_nonexistent_probe__

Then ask the model to call pwsh with:

Remove-Item -LiteralPath ".\__dsh_plugin_builder_nonexistent_probe__" -Recurse -Force

The policy should deny the call in Chat. The sample rule is intentionally illustrative; do not treat it as a complete sandbox.

Generated package contract

dsh-<slug>/
├── src/index.ts          # name + inject + apply + Schemastery Config
├── src/client/index.ts   # optional Web Client plugin: node, theme, or shell contribution
├── test/smoke.test.mjs   # success, failure, and replay/guard paths
├── cordis.dev.yml        # source overlay with absolute import specifier
├── cordis.patch.yml      # installed bundle layer
├── plugin-design.md      # shape decision and verification record
├── package.json          # ESM + dsh.bundle + optional dsh.client
├── tsconfig.json
└── README.md

Validate a generated plugin

py -3 scripts/validate_dsh_plugin.py ./showcase/dsh-release-readiness
py -3 scripts/validate_dsh_plugin.py ./showcase/dsh-command-safety
py -3 scripts/validate_dsh_plugin.py ./showcase/dsh-aurora-ui
py -3 scripts/validate_dsh_plugin.py ./showcase/dsh-luna-pet

The validator checks ESM and bundle metadata, entries, exported plugin contract, Schemastery config, Client metadata when present, collisions with shipped tool names, likely hard-coded credentials, and invalid bare Windows paths. It is a fast static gate; real delivery should also compile, run tests, load the overlay, inspect --dump-config, and exercise the Web UI.

Repository map

├── SKILL.md                 # routing and delivery contract
├── assets/templates/        # ESM plugin and bundle templates
├── references/              # tool, guard, adapter, UI, lifecycle, safety, publish rules
├── scripts/                 # overlay renderer and static validator
├── showcase/                # four meaningful, tested plugins
├── examples/                # request fixtures
└── evals/                   # rubric, failure taxonomy, evaluation cases

Important limits

• DeepSeek Harness is in developer preview; re-check official contracts when versions change.
• The official plugin inventory is read-only. This Skill can safely edit the active profile patch, but the current Settings list does not expose enable/disable controls.
• Host entries hot-switch in the running process; existing pages may require a refresh before Client UI appears or disappears.
• dsh-command-safety is an example policy layer, not a complete shell sandbox or approval system.
• dsh-release-readiness stores its UI payload in core tool/result presentation metadata so persisted sessions remain replayable.
• dsh-aurora-ui activates its custom theme at runtime; Harness persists only its built-in theme preference, so the plugin re-applies Aurora when the Client bundle mounts and restores that preference when requested or unloaded.
• dsh-luna-pet embeds the validated 1.69 MB Luna WebP atlas in its Client bundle (about 2.26 MB after base64 embedding). Its row 3/4 interactions are intentionally named petted and content to match the user's existing artwork rather than generic wave/jump labels.
• Git installs run prepare only when package-manager build permissions allow it. Prefer trusted, commit-pinned sources or prebuilt tarballs.
• The four showcase packages have not been published to npm.

License

MIT