dsh-prompt-polish

dsh-prompt-polish

Prompt polishing for the DeepSeek Harness web GUI — one click turns a rough composer draft into a clearer, more actionable prompt: explicit goal, concrete requirements, constraints, and acceptance criteria. The button sits right next to the model name, calls the model your session already uses, writes the result straight back into the composer, and then turns into an undo arrow.

English | 简体中文

---

Why

A prompt that a coding agent can act on usually states what to build, where, under what constraints, and how success is judged. Most drafts don't — they are quick notes. This plugin adds a polish affordance to the dsh composer: it sends the draft through a low-temperature rewrite pass over the harness's own LLM service, fills the improved text back, and keeps the original one click away.

Nothing about your intent changes: the strategy is allowed to make the ask clearer, never to invent requirements. Your API key never reaches the browser, and no part of the flow touches the session's model history.

Features

UI copy is Chinese-only in this version (button tooltips such as 优化提示词 / 取消优化 / 撤回优化, and the local-guard hints). Hooking into the harness locale namespace for zh/en dictionaries is on the roadmap; the settings section itself is described in Chinese because it renders the schema descriptions.

Screenshots are in Feature showcase below; docs/compatibility.md records what was field-verified on which build.

Feature showcase

The button, in place. The sparkle button lives in the composer tool row, immediately left of the model name, so polishing never takes you away from the draft you are writing.

Before. A quick note rather than a task brief: the goal, the constraints, and the acceptance criteria are all left implicit.

After. One click rewrites it into a structured, actionable prompt and writes the result straight back into the composer; the button then turns into the undo arrow.

How it works

flowchart LR
    A[Composer draft] --> B{Local guards<br/>empty / attachments / chips / phase}
    B -- reject --> R[Button turns red:<br/>reason shown on hover, draft untouched]
    B -- pass --> C["POST /api/prompt-polish/optimize<br/>(same-origin, cookie-authenticated)"]
    C --> D["ctx.llm.stream<br/>low-temperature rewrite"]
    D --> E[Validate finish:<br/>error / aborted / truncated → refuse]
    E --> F[Normalize:<br/>strip fences and wrapping quotes]
    F --> G["inputActions.setDraft(result)<br/>native Ctrl+Z can still undo"]
    G --> H[Button becomes the undo arrow]
    H -- click --> I[Original draft restored]

The plugin is one npm package with two halves, following the dsh plugin conventions:

• Host half (exports ".", Node): exports the Config schema (every field marked .volatile(), so dsh renders the settings form for the composition entry prompt-polish) and registers the POST /api/prompt-polish/optimize route on the shared webserver. The model call uses ctx.llm.stream with the auxiliary-call discipline the harness applies to session titles: composed deadline plus caller cancellation rechecked during and after the stream, terminal-finish validation, and refusal of truncated output.
• Browser half (exports "./client", loaded through dsh.client): registers the button into the conversation.input.right slot, reads the draft with useInput, writes it with inputActions.setDraft, renders the three button states, and mirrors undoWindowMs through ctx.configForms. It consumes exactly two services — slots and configForms — and never renders custom inject-face hooks; see docs/compatibility.md for why that distinction matters. dsh.client.inject is intentionally empty: it lists client-package dependencies for graph ordering, and this bundle has none.

The two halves never share code at runtime: the browser half receives only the wire types and the prompt normalization helper, and the host half does all credential-bearing work.

Requirements

The host half declares inject: ['llm', 'webServer'] (since 0.1.7 settings are no longer a namespace a plugin registers — the configuration is resolved from the composition entry; webServer must be declared explicitly, or the registering apply runs before that service exists and the route is silently missing); sessions and the settings domain are probed optionally and degrade gracefully when absent.

Install

From npm (recommended). The published tarball already contains the built lib/, and registry installs run no lifecycle scripts:

dsh plugin --profile web add @xyavid/dsh-prompt-polish

From a local checkout. The built lib/ is committed, so a checkout is usable as-is:

git clone https://github.com/xyavid/dsh-prompt-polish.git
cd dsh-prompt-polish
dsh plugin --profile web add .

To develop against a live checkout, build first and link the directory instead:

pnpm install
pnpm run build
dsh plugin --profile web add link:C:\path\to\dsh-prompt-polish

From a tarball. No build environment needed:

pnpm pack                        # produces xyavid-dsh-prompt-polish-<version>.tgz
dsh plugin --profile web add ./xyavid-dsh-prompt-polish-<version>.tgz

From GitHub. Installing from npm is easier — the published tarball already ships lib/, so it never runs prepare and the gate below does not apply.

The package declares a prepare script, and pnpm >= 10 blocks dependency build scripts by default, so a git install has to be allowlisted first; without it pnpm aborts with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED. Add this to the profile's pnpm-workspace.yaml ($DSH_HOME/profiles/web/):

allowBuilds:
  '@xyavid/dsh-prompt-polish@https://codeload.github.com/xyavid/dsh-prompt-polish/tar.gz/<commit>': true

Copy the key verbatim from what pnpm printed: a git/tarball dependency's key carries the resolved commit, so it changes whenever you change the ref, and a wrong key fails silently instead of erroring. (The older onlyBuiltDependencies key does nothing on pnpm 10.29.)

dsh plugin --profile web add github:xyavid/dsh-prompt-polish
# or pin a commit for reproducibility:
dsh plugin --profile web add github:xyavid/dsh-prompt-polish#<sha>

Uninstall:

dsh plugin --profile web remove @xyavid/dsh-prompt-polish
# then restart dsh web

dsh plugin add appends the bundle to dsh.profile.bundles automatically (the package declares dsh.bundle.patch); remove takes it back out. After either operation the running profile keeps its startup bundle set, so restart before expecting a change.

Usage

Type a draft, then click the sparkle button left of the model name.

The three states

What happens, step by step

1. Local guards run first. Empty or whitespace-only drafts, attachment-only drafts (a chip's trailing zero-width space is folded away correctly), drafts over maxInputChars, drafts containing /commands or @references, and a composer in a non-plain phase are refused with a tooltip. Chips are refused because filling text back would destroy them.
2. The button spins while the host calls the model. Your draft is untouched during the call, so cancelling at any moment leaves exactly what you typed.
3. On success the result is written back through the official editor API, the native undo stack stays intact (Ctrl+Z works), and the same button becomes the undo arrow.
4. Undo restores the original draft and returns the button to idle. If you keep typing after the result lands, the undo state retires itself so stale text can never overwrite your newer edits.

Interaction rules worth knowing

• Pressing send while a polish is running cancels the call and sends your original text.
• Editing the draft while a polish is running means the result is not written back; the button returns to idle and the hover text explains why.
• The undo affordance expires after undoWindowMs (default 60 s). The button reads that value through the client settings mirror, and falls back to 60 s when the mirror is unavailable (see Known limitations).
• Only one polish runs at a time per session, and a late response from a cancelled call is discarded.

Configuration

Everything lives on the prompt-polish composition entry, editable from Settings → 插件配置 or directly in that entry's config block in the profile's cordis.patch.yml. Since 0.1.7 the settings domain writes edits back to the profile patch, and the plugin reads the .volatile() references declared in its schema, so a save takes effect on the next call without a restart or a remount.

Defaults come from two places, in this order: the schema defaults below, overridden by the composition layer's config block in cordis.patch.yml, overridden by your settings section. Out of the box the composition layer pins enabled, temperature, maxOutputTokens, timeoutMs, and maxInputChars, so those five values are the effective defaults even if you never open the settings page.

"Applies" mirrors the namespace's applies: 'live' registration: every field is re-read on each request, and enabled / undoWindowMs additionally affect what the browser shows without a restart. Only changes to the composition layer itself (a cordis.patch.yml edit) require reloading the profile directory, and patchReload: live profiles pick those up on save too.

The same values can be set from the user patch layer without touching the plugin:

# ~/.dsh/profiles/web/cordis.patch.yml  (hot-reloaded on save)
- id: prompt-polish
  config:
    strength: aggressive
    timeoutMs: 90000

Model routing precedence (host side):

1. an explicit route in the request body — the wire protocol carries one, and non-browser callers may supply it; the bundled browser half does not send it, by design;
2. the route recorded in the current session's last request header;
3. the harness-wide default model (agent-default-model).

The browser half does not carry an explicit route, but it does carry the current session id (the sessionId standard prop every session-scope slot receives): the host uses it for rule 2, and the model adapter forwards it to the provider as a request marker — the x-opencode-session header the OpenCode Go / Zen gateway requires comes from exactly here, and without it the gateway rejects the call with 400 MissingSessionID. When no session id is available the host synthesizes one for the OpenCode family only; every other provider keeps receiving none (there the field means a cache key / affinity header).

If none of the three names a route the plugin answers unconfigured with an actionable message instead of guessing, which is exactly what happens in a brand-new session before any message has been sent and without a default model. The bundled client therefore behaves as "session model, falling back to the harness default".

Error handling & edge cases

Every failure path leaves the composer exactly as you typed it. Error messages surface on the button itself (red icon + hover text) — the plugin never opens a dialog or a toast.

Errors raised before a request is even sent come from the browser half and carry no code:

Architecture

dsh-prompt-polish/
├── package.json          dsh.bundle.patch (layer) + dsh.client (browser half) + scripts/exports
├── cordis.patch.yml      the composition layer: one insert row; its config is the settings base layer
├── src/
│   ├── index.ts          host apply(): config refs (.volatile()) + route + route resolution + error mapping
│   ├── enhancer.ts       ctx.llm.stream call: deadline racing, cancellation, finish validation, normalization
│   ├── prompts.ts        built-in strategy (SYSTEM/USER templates) + strength hints + output cleanup
│   ├── config.ts         schemastery schema, defaults, input checks
│   ├── protocol.ts       wire types and constants shared by both halves
│   ├── http.ts           bounded JSON body reader + JSON responder
│   └── client/
│       ├── index.tsx     browser half: three-state button, undo, slot registration, diagnostics
│       └── styles.ts     button stylesheet (single injected <style>)
├── scripts/
│   ├── build.mjs         esbuild: host ESM + browser half inside the module-loader envelope
│   └── verify-lib.mjs    rebuilds in a temp dir and byte-compares against the committed lib/
├── test/
│   ├── harness.mjs       offline regression: loads the client bundle and asserts exactly one button renders
│   ├── undo-window.test.mjs  jsdom regression for the undo window: settings read, expiry, restore
│   └── opencode-session.test.mjs  OpenCode session marker: sessionId forwarding and fallback, both halves
├── types/contract.ts     compile-time assertions against the official d.ts files
├── docs/compatibility.md interface audit, field-tested conclusions, known boundaries
├── examples/             overlay / user patch / settings examples
└── lib/                  committed build output; ships in the tarball and is loaded at startup

Data flow

browser half (React component)                    host half (Node)
  useInput(state => state.draft)                    POST /api/prompt-polish/optimize
  inputActions.setDraft(text)      ──────────▶      resolve route → ctx.llm.stream(...)
  states: sparkle / spinner / undo                  validate finish → normalize → reply

Development

Use pnpm. The repository is developed with pnpm (pnpm-workspace.yaml), and pnpm ≥ 10 refuses to run dependency install scripts until they are allowlisted. esbuild needs its postinstall to fetch the platform binary, so the workspace file ships the one-line allowance:

allowBuilds:
  esbuild: true

If pnpm install prints Ignored build scripts: esbuild, run pnpm approve-builds once (or keep the allowBuilds entry above) and re-run the install.

pnpm install

pnpm run build       # lib/index.js (host ESM) + lib/client.js (browser half)
pnpm run watch       # incremental rebuild
pnpm run typecheck   # interface contract check against the official d.ts files
pnpm test            # offline regression: the client bundle renders exactly one button
pnpm run check       # build + typecheck + test + verify:lib
pnpm run verify:lib  # fails when the committed lib/ differs from a fresh build

After a build: restart dsh web (host-half changes and the client bundle are both read at startup), then reload the page.

Two build constraints worth knowing

1. The browser half must use the automatic JSX runtime (jsx: 'automatic' in scripts/build.mjs). esbuild's classic runtime emits a reference to a global React that the module loader never provides; the shell then silently swallows the resulting React is not defined, and the symptom is "registration succeeds but no button ever appears".
2. The build stamps a source content hash — not a timestamp — into both bundles. Identical sources produce byte-identical output, which is what makes verify:lib meaningful; any source change alters the hash, so the served rev changes and a browser cannot keep serving a stale bundle.

Runtime diagnostics

copy(JSON.stringify(globalThis.__dshPromptPolish))

stage walks through module-loaded → styles-ready → slots-injected → registered → inject-face → rendering; errors / attempts / mounted explain any failure.

Troubleshooting