Workbench Development Standard

Version: 2026-10-08 · The website is authoritative; DSH Desktop bundles a copy for offline use.

Official page: https://dshdesktop.com/workbench/docs/development-en/

Markdown source for agents: https://dshdesktop.com/workbench/docs/development-en.md

Six-step quickstart: https://dshdesktop.com/workbench/docs/quickstart-en/ (Markdown). 中文版.

This standard is intended for direct execution by an AI developing a workbench. For local development and personal use, this document is sufficient: build the package under Section 3, install it in the local DSH Desktop, and pass the Section 8 self-test. There is no requirement to publish code or upload anything.

If the author later wants to list the workbench in the Workbench Market, also read the Workbench Market Acceptance Standard. Its separate rules cover a public repository, releases, descriptions, screenshots, and listing PRs.

A workbench is a DSH plugin. It must first be a valid DSH plugin package that dsh plugin add can install and Harness can load. It then registers a business panel with Desktop and follows the rules for workbenches, sessions, and workspaces.

Rule levels are required (failure prevents installation or loading), recommended (strongly advised for usability and future listing), and optional.

1. Execution principles

Requirements confirmation gate (before code): First establish the workbench's business scenario, target users, and smallest core workflow. Copying Desktop's generic “development instructions,” opening a directory, or finding projects or dependencies inside it cannot replace the user's statement of what to develop now. Do not infer the product direction solely from a directory name or existing code. If the current request and already confirmed context do not establish all three, ask one combined question, for example: “Who is this workbench for, what business scenario should it address, and what are the core steps from entry to task completion?” Wait for the user's answer and remain at requirements confirmation. Until then, read-only checks of directories, versions, scripts, and host capabilities are allowed; creating or editing business code or UI, building, packing, installing, or submitting are not. An empty directory is not confirmed requirements. Starting implementation from generic instructions alone is an agent execution error.

Once requirements are clear, read project name, author, version, description, and test commands from the project; ask only for necessary information that cannot be found and affects implementation. A development request does not authorize publication of code, business data, or credentials.

Before development, check:

One-page execution flow

  1. Confirm requirements: Record scenario, users, and one complete task flow from the current request and confirmed context. Generic instructions and the project directory do not count. If any is unclear, use the gate above and wait.
  2. Inspect project: Identify root; run pwd and, for a Git repository, git status --short; inspect code, package manager, uncommitted work, and target Desktop version. Preserve unrelated changes.
  3. Define the smallest business flow and layout: Write down entry point, main action, completion state, and failure recovery. Under Section 4, choose a standard split or customFrame and define the first-use path without a session before choosing host capabilities.
  4. Implement: Create the plugin package and registration under Section 3; follow Sections 4–7 for applicable responsibilities and capabilities.
  5. Verify package: Run pnpm pack; inspect package.json, declared entries, cordis.patch.yml, size, and sensitive files inside the tarball.
  6. Install and test locally: Check installation capabilities under Section 3.6, install that tarball, complete the required restart, and record real UI and loading evidence under Section 8. If the agent runs inside the target DSH Desktop, ask the user to restart it manually under the boundary below.

Restart boundary inside the target app: If the agent is running in the DSH Desktop session that needs restarting, do not close or restart DSH Desktop or Harness yourself, and do not use process probes such as ps or pgrep to manage that restart. Ask the user to quit DSH Desktop completely and reopen it. Only after the user returns and confirms it has reopened should you check plugin loading, the installed list, sidebar entry, and real UI. Until then, mark those post-restart checks pending verification; do not claim they passed. An agent running outside the target app may follow the normal restart process.

Empty-directory exercise: If the directory is empty and the user only pasted Desktop's “development instructions” or said “make a workbench,” Step 1 has not passed. Ask one combined question: “Who is this workbench for, what business scenario should it address, and what are the core steps from entry to task completion?” pwd, directory inspection, and Desktop capability checks are allowed. Until the answer arrives, stop at Step 1: do not create package.json, components, or business pages; do not build, install, or submit.

2. What a workbench is

A workbench package is simultaneously:

Three identifiers have distinct purposes and must not be conflated:

IdentifierLocationPurpose
npm package namepackage.json nameInstallation, dependency resolution, cordis.patch.yml name:
Plugin entry IDid of an insert row in cordis.patch.ymlLocate that row in the Harness plugin tree
Workbench identityCanonical GitHub repository URL and market entry idLowercase owner/repository, shared by market card, sidebar entry, and session ownership
Legacy ID for compatibilityOld register({ id }) and catalog workbenchIdMigration of old data only; omit from new packages and submissions

Desktop lowercases GitHub owner and repository, so https://github.com/Owner/Repo corresponds to owner/repo. A rename or transfer changes workbench identity; migrate existing sessions under the migration rules rather than changing only the URL. The legacy wb-owner-repo is only a compatibility mapping, not a registration ID for new packages.

3. Package format

3.1 Layout

Put one workbench in one package. Typical structure:

package.json          # npm and DSH plugin declaration
cordis.patch.yml      # insert the server entry in the plugin tree
dsh/index.js          # server entry (exports["."])
lib/client.js         # built client entry (exports["./client"])
README.md  LICENSE

3.2 package.json

FieldLevelRequirement
name, versionRequiredNormal npm fields; version is full SemVer such as 1.2.0
"type": "module"RecommendedAll official examples use ES modules
main and exports["."]RequiredPoint to the server entry imported by cordis.patch.yml
dsh.bundle.patchRequiredFor example "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }, relative to package root. Without it, the package is an ordinary dependency and no plugin layer activates
dsh.client.platformRequiredMust be "web", or the client module will not load
dsh.client.injectRequiredString array that must contain dsh-desktop-workbenches so its service loads before the client; list other client packages used. This controls load order, not Cordis service injection
exports["./client"]RequiredA declared dsh.client must export the built client file, or startup fails
dsh.client.externalOptionalList modules (including subpaths) required by the client beyond the shared baseline; do not list itself
exports["./package.json"], exports["./cordis.patch.yml"]RecommendedMatch official packages
filesRecommendedInclude cordis.patch.yml, server entry, and built output
peerDependenciesRecommendedPut official @deepseek-ai/* packages such as @deepseek-ai/cordis and @deepseek-ai/dsh-client-connection here, not in dependencies, to avoid a second copy of host code. Explicitly include prereleases, for example ">=0.1.5-rc.2 <0.2.0-0", or prerelease Harness versions are excluded and installation fails with ERESOLVE
@deepseek-ai/schemasteryRecommendedUsed to define server Config; it is a runtime dependency
license, author, descriptionRecommendedProvide truthful values

Do not rely on undocumented dsh fields such as dsh.client.inline; they are silently ignored.

3.3 cordis.patch.yml

This file is a YAML array. A workbench normally needs one insert:

- insert:
    - id: my-workbench            # plugin entry ID
      name: my-workbench-package  # npm package name, so Node can resolve installed code
      config:
        root: !!js dshHomePath('my-workbench')   # optional business data directory

3.4 Server entry

import Schema from '@deepseek-ai/schemastery'

export const name = 'my-workbench'
export const inject = ['connection']
export const Config = Schema.object({ root: Schema.string().required() })

export function apply(ctx, config) {
  // Register local endpoints under this workbench, e.g. /api/my-workbench/...
}

3.5 Client entry

The client file must be a built single-file module registered through the module loader:

window.__ModuleLoader__.load({
  id: 'my-workbench-package',
  factory: (require) => {
    const React = require('react')
    function BusinessPanel({ service, entry }) { /* business panel */ }
    function apply(ctx) {
      ctx.effect(() => ctx.desktopWorkbenches.register({
        title: 'My Workbench',
        repository: 'https://github.com/owner/repository',
        description: 'Describe the problem it solves'
      }, BusinessPanel))
    }
    return { apply, inject: ['desktopWorkbenches'] }
  }
})

3.6 Build and local installation

4. UI boundary

A workbench is a plugin for a specific business scenario. This standard governs its relationship and switching behavior with sessions and workspaces; it does not prescribe a uniform business panel design.

Authors or users may define business panel layout, content, toolbar, and operations. When integrating an existing workbench, reuse its existing UI and business binding flow where possible. A universal top toolbar, session dropdown, business-area collapse control, or “generic chat” button is not required.

4.1 Choose the layout for the primary task

In either layout, make the business UI respond to the actual width of its own container. Window-wide media queries alone do not reflect the space left by the sidebar, split, or embedding. Use container queries or measure the business root; rearrange columns, collapse secondary information, or provide bounded scrolling when space is tight. Long Chinese headings, English identifiers, numbers, and action buttons must stay readable and usable, without single-character vertical wrapping, clipped controls, or page-wide horizontal overflow.

DSH reserves shared entrances for the market, workbench switcher, and settings; the business panel must not cover them. A customFrame (Section 3.5) must stay within the host-assigned main content area. Its root should fill that area using normal flex layout. Internal absolute positioning, maximization, or drag-based repositioning must remain inside the host container's positioning and clipping boundaries, never cover Desktop's left session sidebar. Put the host-provided conversation node into the business layout for native sessions; do not build a second chat UI. Native conversation capabilities and mode switching continue to follow Desktop rules.

On macOS, after the sidebar collapses, window controls and the sidebar expansion button occupy the upper-left of main content. The host reserves --dsh-frame-leading-clearance width for a left-side embedded business panel and a semantic <header> that is the first child of a customFrame root. The toolbar may stay in the original 48px top row; the whole content need not move down. A custom toolbar with a different structure should use the same variable in its own styles to clear the controls. Do not cover window controls or shell.leading.

5. Workbenches, sessions, and workspaces

6. Using a workbench without a bound session

Open the business panel immediately, even without a session or workspace. Browsing, creating, and choosing business records or projects must not require a pre-existing native session or workspace.

Check whether the current session belongs to this workbench only when an action depends on a session, such as sending an agent request or writing a draft. If unbound, guide the user to create or open a session at that action; do not block unrelated business features.

Provide a clear action such as “New workbench session in this workspace” or “Choose a file location and start a workbench session.” A business record may be created first if it needs no filesystem. Once file storage or DSH workspace creation is required, call the host directory picker first; the user must choose an existing directory or explicitly create one in the system picker. Never silently create a folder in a default location, home directory, current repository, or guessed path. After confirming location, create workspace and session, register ownership, save business association, and populate an opening draft. On cancellation, leave no directory, empty project, workspace, session, or binding. Restore existing business records only from a location the user previously confirmed; if missing, ask for a new selection rather than recreating a same-named directory. On failure, retain retryable state and never silently choose an unrelated workspace.

If the user selects a business record or project before creating the first session, preserve that selection. When opening an existing session, restore its own business mapping first; do not let another session's latest selection overwrite it.

When integrating an existing workbench, retain its project-creation guidance and independent business flow. The user need not manually create a session first; the workbench requests creation or restoration through Desktop, which validates and records ownership. Keep user-written opening drafts for the user to send; preserve them for retry if creation fails or is delayed. Automatically run business flows only in a correctly owned session, never mix them with the opening draft or let a hidden workbench send accidentally.

7. Mode entry and switching

The host supplies one mode switcher at the top of the sidebar. Its button displays only the current mode; the expanded menu switches among “Native sessions” and added workbenches, with “Workbench management” always at the far right. A workbench must not duplicate, cover, or replace these shared entrances. Switching mode changes foreground display and session filtering only; it neither reinstalls a package nor stops background tasks.

“Native sessions” and each workbench are peer modes. Current mode determines visible sessions and new-session ownership:

Explicitly opening an unbound session switches to Native sessions; explicitly opening a bound session with an available owner switches to that workbench. If its owner is removed, uninstalled, or unavailable, treat it as an ordinary session without automatically activating or reinstalling the owner. If the user navigates, switches modes, or removes an owner during asynchronous creation, do not pull the UI back to an old mode, overwrite the later selection, or bind to an invalid owner.

Mode switching must not collapse or expand the left session sidebar automatically; the user controls its state across modes. A workbench session title has a small icon of its owner; an ordinary session does not. The icon indicates ownership and needs an accessible name or tooltip. Buttons, menus, selected states, and focus rings must not clip, overlap, or overflow in collapsed or expanded states.

First entry may show a home page, empty-session state, or initialize a session under workbench conventions, but the business panel must not depend on session initialization. Later entries restore that workbench's most recent session. Navigation and switching must not delete sessions, business records, project files, favorites, or notes.

8. Local self-test checklist

Check each applicable responsibility after development. “Host responsibility” means observe current Desktop behavior and report issues; plugin authors must not copy host UI. For “only when using this capability,” mark “not applicable” with a reason if unused. Claim local self-test passed only with evidence for all applicable items.

Package and loading

Section 4: UI boundary

Sections 5–6: workspaces and sessions

Section 7: mode switching and preservation

9. Delivery when something fails

Final delivery must list actual results and evidence: changed files, package version, local installation and self-test outcomes, and unverified items. Identify anything missing; never invent success. If the toolchain is missing, installation fails, or host APIs are unavailable, keep completed code, explain why, and state the next step.

References