@omdsh-dev

dsh-better-workbench

Name: dsh-better-workbench
Availability: InStock
Author: omdsh-dev

DSH 工作台插件，把常用的页面或者应用，Pin 在工作台

Stars: 0
Language: JavaScript
Created: Sep 9, 2026
Updated: Sep 9, 2026

Web UI

GitHub repo

Introduction

dsh-better-workbench — Extensible workspaces for DeepSeek Harness

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.

English | 中文

Why this exists

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.

Features

Permanent Workbench home integrated with the DSH sidebar
Responsive card grid for installed Workbench instances
Explicit conversation, workbench-home, and workbench-instance routes
Application registry with stable appId values
Durable instance creation, ordering, renaming, configuration, and deletion
Instance templates and optional Agent Creator templates
page presentation for an exclusive center application
Right or bottom panel presentations with push or overlay behavior
Conversation-adjacent floating capsule presentations
Unavailable-instance recovery when an application is removed and later restored
IndexedDB atomic state transactions, revision conflict checks, versioned configuration and legacy-data import
Cordis fiber disposal and reactivation for applications, templates, and creators
Application-authoring Skill and bilingual protocol reference under docs/
A complete DSH design-system reference application under examples/design-board/

Usage

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.

Install

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.

Install the design-board example

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.

Upgrade

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).

Uninstall

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.

Application model

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.

Persistence and lifecycle

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.

Integration limits

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.

Troubleshooting

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`

Design-board example

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.

Model experience

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.

Development and verification

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 hosts
tests/ — service lifecycle, routing, migration, templates, and unavailable-instance recovery
docs/ — Workbench application-authoring Skill and bilingual protocol references
examples/design-board/ — complete reference Workbench application with its own bundle manifest
lib/ — committed base-plugin build output

Community and about

Use GitHub Issues for reproducible bugs, focused feature requests, and usage questions.
Read CONTRIBUTING.md before proposing changes; report vulnerabilities privately through SECURITY.md.
See CHANGELOG.md for release and compatibility notes.

License

BSD-3-Clause