dsh-refine

English | 简体中文

A refinement UX layer for the DeepSeek Harness (dsh): the /refine human command plus a settings panel with entry browsing, a refinement history timeline, one-click rollback, and auto-gate audit. It drives the dsh-continual-harness engine, which is optional at runtime — when the engine is not mounted, every operation degrades into an actionable instruction instead of an error.

The plugin is the shell, and since 1.2.0 it mounts the engine itself: dsh-continual-harness starts as a child plugin under ctx.isolate('commands'), so the engine's own /refine adapter never registers and dsh-refine keeps the full command surface (status / list / history / rollback / triggers) while forwarding the engine's --global / --local grammar to it. List only dsh-refine in your profile's dsh.profile.bundles; a profile that still mounts dsh-continual-harness as its own row keeps working — the shell detects the already-registered engine, skips its own mount, and falls back to the engine's /refine.

This project is a port and practical adaptation of the prime-agent /refine idea for the dsh ecosystem.

Features

• /refine command — status / list [kind] / history [n] / rollback <id>, plus free-text refinement instructions (owned by the engine when it is mounted; provided by dsh-refine otherwise)
• Settings panel — harness timeline, entry browsing, one-click rollback, auto-gate audit
• Bilingual & themed — the panel reads the host locale (Simplified Chinese / English) and adapts to the dark and light themes through dsh design tokens with no hardcoded colors
• Session-history compatibility — the harness/refinement session event written by older engine builds is registered into the host reader so legacy refined-session logs stay loadable (the 0.3.0 engine self-registers and no longer writes it; dsh-refine keeps an idempotent defensive registration)
• Host gap bridging — where the installed engine's turn-time code reads session.events but the dsh host only exposes snapshotEvents(), dsh-refine installs a guarded events getter so the engine's projection/planner stops crashing with Cannot read properties of undefined (reading 'length')
• Engine optional — without the engine you get actionable setup guidance; nothing errors out, nothing pollutes the session

Requirements

• Node.js ≥ 18
• dsh 0.1.2-rc.1+ (aligned @deepseek-ai/dsh-home-paths and @deepseek-ai/dsh-typert-protocol)

Installation

Mount this package and the engine in your dsh profile (e.g. ~/.dsh/profiles/web/cordis.yml):

plugins:
  - dsh-continual-harness   # the engine (optional, but required to actually trigger refinements)
  - dsh-refine              # this UX layer (required)

Or point at a local checkout with link: during development:

plugins:
  - link:/path/to/dsh-refine

Restart dsh web to apply (host-side changes need a restart; client panel changes hot-reload while pnpm run dev:web is running).

Usage

Command

Input	Description
/refine status	Overview of engine/rollback state
/refine list [kind]	List current entries (filter by prompt/memory/skill/subagent)
/refine history [n]	Recent refinement history (default 10, max 50)
/refine rollback <id>	Roll back one committed refinement (ids from history)
/refine <any text>	Trigger an engine refinement; returns immediately, results appear later in the panel / history

/refine <text> treats the text as a refinement instruction handed to the engine's planner. For ordinary chat, just type in the input box without the / prefix. When dsh-continual-harness@0.3.0+ is mounted it owns /refine (plan + rollback); the panel below still offers the browse / timeline / one-click-rollback views.

Panel

Settings → Refine Harness: a settings-style overview of engine and state path, browse prompt / memory / skill / subagent entries, inspect the history timeline and roll back with one click, and audit auto-gate decisions.

How it works

engine mounted (dsh-continual-harness@0.3.0+):
  /refine  ──► engine's own /refine ──► coordinator ──► harness_state.json / refinements.jsonl

engine absent:
  /refine  ──► dsh-refine /refine ──► tools.execute('harness_refine') ──► actionable setup instruction

panel (always): 设置 → 精炼 Harness ──► refineUx data/rollback ──► ESP files + harness_refine

• Instruction triggers are background fire-and-forget: the engine and agent are validated synchronously, then the command acks immediately so the input box is never frozen for a planner round-trip; engine results land in the panel timeline and /refine history.
• Rollback is synchronous: it applies the stored inverse edits only, with no LLM round-trip.
• Session-event compatibility: lib/compat.js registers harness/refinement into the host reader's known event-type set (KNOWN_SESSION_EVENT_TYPES) — one registration keeps logs from older engine builds loadable; as of 0.3.0 the engine no longer writes the event and self-registers the type itself.

Development

npm install
npm run lint    # ESLint (lib/ + smoke-host.mjs)
npm test        # smoke suite — no engine required; extra host-registration
                # assertions run when dsh is on PATH

The smoke suite is hermetic: minimal engine ESP fixtures are bootstrapped automatically when ~/.dsh/harness lacks them, and it also exercises the real dsh install paths for compatibility regression (skipped gracefully when dsh is not on PATH). Run DSH_HOME=/tmp/fresh npm test to reproduce the CI environment in a clean directory.

See CONTRIBUTING.md for commit style, changelog policy, and the release process; see SECURITY.md for reporting vulnerabilities.

License

MIT © dushaobindoudou