dsh-better-workbench

Readme

# dsh-better-workbench — Extensible workspaces for DeepSeek Harness

[![Version v0.3.0](https://img.shields.io/badge/version-v0.3.0-5B4CF0?style=flat-square)](https://github.com/omdsh-dev/dsh-better-workbench/releases)
[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-0B7285?style=flat-square)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%5E20%20%7C%20%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
[![DSH profile](https://img.shields.io/badge/DSH-Web-5B4CF0?style=flat-square)](cordis.patch.yml)

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

<img width="3024" height="1482" alt="Snipaste_2026-09-10_11-52-30" src="https://github.com/user-attachments/assets/5f469016-c897-47a1-b036-b7e5258f8b8c" />
<img width="3024" height="1478" alt="Snipaste_2026-09-10_11-52-57" src="https://github.com/user-attachments/assets/68236ec4-72df-4e51-9f8f-69869cfeb17e" />


[English](README.md) | [中文](README.zh.md)

## 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/`
- A two-page Skills + MCP reference application under `examples/skill-mcp-panels/`, ported from [Fishquito7/dsh-skill-mcp-panel](https://github.com/Fishquito7/dsh-skill-mcp-panel)

## Usage

Open **首页** in the Workbench section of the expanded DSH sidebar. The home shows every stored instance as a card.

Use **创建工作台** to open the creation dialog. Choose a template or application, confirm its name and configuration, then create and open it. Selecting or cancelling a draft does not create an instance. The built-in **从网页地址创建** template adds an HTTP(S) website with a DSH-tinted favicon. Existing cards reopen their instance directly; single-instance applications offer opening the existing instance. See [Website Workbench](docs/website-workbench.md) for browser isolation and compatibility limits.

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

```sh
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):

```sh
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:

```sh
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.

### Install the skills + MCP panels example

`examples/skill-mcp-panels` is an independent bundle and is likewise not enabled by the base. Install it after the base — **instead of** the standalone `dsh-better-workbench-skill-mcp` plugin, because both register the same `skillsViewer`/`mcpManager` remote service names:

```sh
dsh plugin --profile web add "$PWD/examples/skill-mcp-panels"
```

Refresh the browser and **技能** and **MCP** appear in the Workbench sidebar and home. It is ported from [Fishquito7/dsh-skill-mcp-panel](https://github.com/Fishquito7/dsh-skill-mcp-panel) (MIT); see [its README](examples/skill-mcp-panels/README.md) for the full attribution.

### Upgrade

```sh
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:

```sh
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:

```ts
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](docs/application-authoring/SKILL.md) and the [complete English reference](docs/application-authoring.md) before publishing an application. A Chinese reference is available in [docs/application-authoring.zh.md](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 | grep workbench`, restart DSH Web, and hard-refresh the browser |
| 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`](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:

1. `总览`
2. `基础资源`
3. `规范`
4. `产品页面`

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.

## Skills + MCP panels example

[`examples/skill-mcp-panels`](examples/skill-mcp-panels) is a **port of [Fishquito7/dsh-skill-mcp-panel](https://github.com/Fishquito7/dsh-skill-mcp-panel)** (MIT, Copyright (c) 2026 dsh-skill-viewer contributors) into two Workbench pages:

- **技能** (`dsh-better-workbench-skill-mcp-panels:skills`) manages the skills on disk: card/tree list and search, per-scope hot enable/disable, delete, add by `.md`/`.zip`/folder/drag, a workspace bar, a group bar, and batch migration.
- **MCP** (`dsh-better-workbench-skill-mcp-panels:mcp`) manages the managed block of the profile `cordis.patch.yml`: stdio and streamable-http servers, add/edit with masked secrets, enable/disable, delete, and a live connection test. Rows outside the managed block stay read-only.

Both are `page + conversation: exclusive` applications sharing one host half. The upstream UI and on-disk skill conventions are preserved, and the upstream MIT notice ships in [`examples/skill-mcp-panels/LICENSE`](examples/skill-mcp-panels/LICENSE). For this repository the example drops the upstream `dsh-panel` CLI, repackages the client for the local build helper, and traces its two 16x16 icons from the upstream PNGs.

## Model experience

The base provides a unified `@` source through DSH inputTriggers. Selecting an available workbench inserts a native reference chip; sending serializes only its instance ID, application ID and title into the ordinary user-message pipeline. No model tools, file resolver, page content, secrets or application configuration are added. These are browser-stored instance references, not filesystem paths; see [Workbench references](docs/workbench-references.md). Other Workbench UI state remains model-invisible. An optional Agent Creator is a separate application contribution and must record model-visible requests and results 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`:

```sh
pnpm install
pnpm run build:verify
pnpm run check
pnpm test
pnpm --dir examples/design-board run build:verify
pnpm run check:example
pnpm --dir examples/skill-mcp-panels run build:verify
pnpm run check:example:panels
pnpm run verify:i18n
```

Before release or a source-based installation, explicitly regenerate both sets of committed artifacts:

```sh
pnpm run build
pnpm run build:example
pnpm run build:example:panels
```

`--dry-run` prints the plan without writes; `--check` and `--verify` use temporary output. [examples/starter](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
- `examples/skill-mcp-panels/` — two-page Skills + MCP example ported from Fishquito7/dsh-skill-mcp-panel
- `lib/` — committed base-plugin build output

## Community and about

- Use [GitHub Issues](https://github.com/omdsh-dev/dsh-better-workbench/issues) for reproducible bugs, focused feature requests, and usage questions.
- Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes; report vulnerabilities privately through [SECURITY.md](SECURITY.md).
- See [CHANGELOG.md](CHANGELOG.md) for release and compatibility notes.

## License

BSD-3-Clause