dsh-better-workbench
可扩展的 DSH Web 工作台宿主，支持持久实例、模板以及页面、面板和胶囊呈现
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-better-workbench@0.3.2
Better Workbench 以 dsh-better-workbench 发布，当前版本为 0.3.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Install: dsh plugin --profile web add github:omdsh-dev/dsh-better-workbench
A DeepSeek Harness Web UI plugin that provides a permanent Workbench home, durable application instances, templates, and reusable page, panel, and capsule presentation hosts for third-party DSH applications.
DSH plugins can contribute tools, services, and small UI entries, but a complete browser application needs more than a component mount. It needs a stable place in navigation, persistent instances, a route that survives reloads, explicit coexistence rules with Conversation, and recovery when an application is temporarily unavailable.
dsh-better-workbench owns that shared infrastructure. Applications register a definition with the Workbench Client Service; Workbench renders their instances, stores only stable JSON state, and removes each contribution with its Cordis fiber. Applications remain responsible for their own UI, resources, and asynchronous teardown.
The built-in home is always available, even when no Workbench application is installed.
conversation, workbench-home, and workbench-instance routesappId valuespage presentation for an exclusive center applicationpanel presentations with push or overlay behaviorcapsule presentationsdocs/examples/design-board/Open 首页 in the Workbench section of the expanded DSH sidebar. The home shows every stored instance as a card.
Use 创建工作台 to reveal templates and installed applications. Selecting a template or application creates an instance and opens its default presentation. Existing cards reopen their instance directly.
The sidebar also provides Workbench search, view options, creation, renaming, deletion, and ordering. The compact sidebar does not insert a separate Workbench-home icon.
This repository's root package is a DSH bundle (package.json declares dsh.bundle and dsh.client) published on npm as dsh-better-workbench. No DSH source changes or config.yaml entries are required. There are two supported activation paths — pick one, and never register the same package both ways: the plugin row id would be inserted twice and startup fails with a duplicate loader entry.
As a profile bundle (standard, for consumers):
dsh plugin --profile web add dsh-better-workbench
# or from GitHub (source / pre-release):
dsh plugin --profile web add github:omdsh-dev/dsh-better-workbench
# or from a local checkout:
dsh plugin --profile web add /path/to/dsh-better-workbench
Because the package declares dsh.bundle, dsh plugin add records it in the profile's dsh.profile.bundles and activates it as a bundle layer. Adding or removing a bundle, or changing the package's bundle manifest or its dependencies, requires restarting dsh web, then hard-refreshing the browser to load the Client bundle.
As a user plugin row (hot reload, for local development):
dsh plugin --profile web add /path/to/dsh-better-workbench
# then add to ~/.dsh/profiles/web/cordis.patch.yml:
# - insert:
# - id: workbench name: 'dsh-better-workbench'
# - id: design-board name: 'dsh-better-workbench-design-board'
A user plugin row is live-applied by the DSH watchUserPatches watcher, so source or bundle-content changes apply without a dsh web restart — refresh the browser (or use dev-mode HMR) to load the Client bundle. Only bundle-manifest/dependency changes still require a restart. When using this path, keep the package out of the profile's dsh.profile.bundles (running dsh plugin can re-add bundle-declaring packages there).
Released revisions include committed lib/ artifacts and are published on npm as dsh-better-workbench. Rebuild the base and example artifacts before publishing or installing from source: a source-only change does not update an installed GUI.
The reference application is intentionally not enabled by the base bundle. Clone the repository, install the base first, then install the example package:
git clone https://github.com/omdsh-dev/dsh-better-workbench.git
cd dsh-better-workbench
dsh plugin --profile web add "$PWD"
dsh plugin --profile web add "$PWD/examples/design-board"
No dsh web restart is needed: refresh the browser and DSH UI 样式看板 appears as a default Workbench instance and as a creation template.
dsh plugin --profile web update dsh-better-workbench
# or from GitHub:
dsh plugin --profile web update github:omdsh-dev/dsh-better-workbench
For a local-path installation, pull the replacement checkout and run add again for the root and any installed example packages. The change is live-applied: refresh the browser afterward (restart only if you changed the bundle manifest or dependencies).
Remove applications before removing their Workbench host:
dsh plugin --profile web remove dsh-better-workbench-design-board
dsh plugin --profile web remove dsh-better-workbench
Removing an application preserves its stored instances as unavailable records. Reinstalling an application with the same appId restores those instances.
A Workbench application is a DSH Client plugin that declares a hard dependency on the workbench Client Service and registers its contributions inside Cordis effects:
import type { WorkbenchClientContext } from 'dsh-better-workbench/client'
import { MyWorkbench } from './MyWorkbench.tsx'
export const inject = ['workbench']
export function apply(ctx: WorkbenchClientContext): void {
ctx.effect(() => ctx.workbench.registerApp({
protocolVersion: 1,
config: {
version: 1,
defaults: () => ({ section: 'overview' }),
validate(config) {
if (typeof config.section !== 'string') throw new Error('Invalid section')
},
},
appId: 'example-workbench',
title: 'Example Workbench',
presentations: [{ kind: 'page', conversation: 'exclusive' }],
defaultPresentation: 'page',
renderMain: MyWorkbench,
}), 'example-workbench: app registration')
}
Applications declare only presentations they can render:
| Presentation | Conversation | Required renderer | Purpose |
|---|---|---|---|
page | exclusive | renderMain | Full center application; optional renderSecondary |
panel | resident | renderPanel | Right or bottom panel using push or overlay |
capsule | resident | renderCapsule | Lightweight floating surface only |
Read the Workbench application-authoring Skill and the complete English reference before publishing an application. A Chinese reference is available in docs/application-authoring.zh.md.
IndexedDB persists instance metadata and plain acyclic JSON configuration in atomic full-state transactions, with revision checks for conflicting writes. Routes and remembered per-instance presentations live separately in per-tab sessionStorage. Initial import reads the old localStorage keys without deleting them. Ordinary instance creation uses UUIDs; explicit default IDs and imported IDs retain their meaning. Business files are not hosted or backed up by Workbench.
The unreleased redesign keeps one application protocol, protocolVersion: 1, with mandatory config.version/defaults/validate, optional async config.migrate, and asynchronous creation/save/rename/delete/reorder. It does not support the old synchronous application API. Optional source is self-reported metadata, not authenticated provenance. A new activation generation prevents stale app callbacks from writing after replacement.
Every application, template, and Agent Creator registration returns a disposer owned by the contributing Cordis Client fiber. When the fiber stops, Workbench removes the contribution but keeps its durable instances. Re-registering the same stable ID restores availability without duplicating entries.
Client HMR replaces the complete Client plugin fiber; React local state is not preserved. Installing a new package or changing a package manifest, bundle ID, or dependency graph still requires a rebuild plus a page refresh or DSH Web restart.
The instance Surface offers JSON export of instance metadata/config and recorded config backups. restoreBackup is available only as a service API, requiring matching active configVersion, validation and revision CAS; it also backs up the current config. No automatic downgrade, JSON import or backup-restore UI is provided.
The DOM compatibility layer requires no DSH source changes. It preserves the Conversation React tree, mounting Workbench separately and restoring its owned styles on unload. It observes the optional real sessions.list selection plus narrow bubbling session-row clicks. A New Session action that reuses the already selected blank session may not close Workbench; this is not a universal navigation-intent API. Session menus and nested controls are excluded.
Right panels use min(360, container width), bottom panels min(280, container height * .55). Push falls back to overlay below width 720 (right) or height 560 (bottom). Applications receive effective presentation. Capsules are floating-only. Creator cancellation signals AbortSignal; it does not guarantee remote Agent termination or roll back committed work.
| Symptom | Resolution |
|---|---|
| The Workbench section or 首页 does not appear | Verify the bundle is present with `dsh --profile web --dump-config |
| The design board does not appear | Install the root package before examples/design-board, verify both packages are in the web profile, then restart and hard-refresh |
| A stored card says the application is unavailable | Reinstall or reactivate the package that owns the same appId; the record is preserved intentionally |
| Changes to Client source do not appear | Rebuild lib/client.js. HMR only works while the matching DSH Client watcher is running; otherwise refresh or restart |
| A page covers Conversation instead of unmounting it | This is the current DSH 0.1.x compatibility adapter. It suppresses Conversation interaction but does not unmount the Conversation React tree |
| An application disappears after a plugin update | Check that its registerApp, registerTemplate, styles, listeners, and other registrations are returned from ctx.effect() and that it still injects workbench |
examples/design-board is the first reference application for the protocol. It is a browser-only page + conversation: exclusive Workbench application and registers a default instance plus an instance template.
Its information architecture is fixed:
总览基础资源规范产品页面The board is derived from current DSH component source. It documents semantic tokens, typography, icons, primitives, shell regions, settings, session UI, conversation flow, the real Composer, trajectory, overlays, states, and accessibility. It is a design reference, not a generic component gallery.
The base and design-board example add no model tools, prompts, or Session-log events. Workbench UI state is not model-visible. An optional Agent Creator is a separate application contribution and must record every new model-visible request and result through an auditable Session/Agent path.
Builds use repository-local helpers; no DSH checkout or DSH_CHECKOUT is required. Build tooling supports Node ^22.18.0 || >=24.11.0. Source tests use Node 22.18+ TypeScript stripping and must also satisfy dependency engine requirements; this is separate from the published runtime engine badge above. Verification builds use temporary directories without replacing lib:
pnpm install
pnpm run build:verify
pnpm run check
pnpm test
pnpm --dir examples/design-board run build:verify
pnpm run check:example
pnpm run verify:i18n
Before release or a source-based installation, explicitly regenerate both sets of committed artifacts:
pnpm run build
pnpm run build:example
--dry-run prints the plan without writes; --check and --verify use temporary output. examples/starter demonstrates the public dsh-better-workbench/build/client-bundle helper in a standalone package layout; it is distinct from the design-board repository example. Copied standalone-layout validation is not a fresh registry-install test; registry use requires publication of the new helper and protocol artifacts.
Repository layout:
src/ — Workbench Client Service, persistence controller, sidebar, home, and presentation hoststests/ — service lifecycle, routing, migration, templates, and unavailable-instance recoverydocs/ — Workbench application-authoring Skill and bilingual protocol referencesexamples/design-board/ — complete reference Workbench application with its own bundle manifestlib/ — committed base-plugin build outputBSD-3-Clause