dsh-plugin-marketplace

DSH Plugin Marketplace

A verified DSH plugin marketplace backed by a centrally maintained Registry.

简体中文 · English · Changelog

[!IMPORTANT] The marketplace does not display every repository carrying the GitHub dsh-plugin topic. A plugin appears only after the scanner validates it and publishes it to the central Registry.

Why use it?

Quick start

Requirements and distribution

• Node.js: ^22.19.0 || >=24.0.0; use DSH's web Profile.
• Desktop: the current development build supports DSH Desktop 0.2.0-rc.2 and its desktop Profile, using bundled Node/pnpm. Do not manage Desktop with an npm-installed DSH CLI.
• DSH peers: @deepseek-ai/cordis ^4.0.1, and dsh-app-boot / dsh-typert-protocol ^0.1.0-rc.5, declared in peerDependencies. These ranges do not certify every DSH release as independently runtime-tested.
• The package includes compiled Host, Web Client and Typert entries with their declarations. Installing this plugin requires no build or lifecycle scripts.
• zod is a runtime dependency for input and remote-protocol validation, not an install script. The marketplace accesses the Registry/GitHub; user-requested installs and updates also run a package manager and access package sources, modifying the active Profile and selected plugin directory. Agent tasks use a dedicated workspace. These capabilities are not a permission-free or security-certified execution model.
• Remote Registries must use HTTPS. file: remains available for local development and test fixtures; cleartext HTTP is rejected before any request is made.

1. Install

dsh plugin --profile web add github:YELEBAI/dsh-plugin-marketplace#v0.9.5

For local development:

dsh plugin --profile web add D:/path/to/dsh_Market

2. Start DSH

dsh --profile web

Desktop installation (development build)

Launch Desktop once to initialize its Profile, save your work, and fully quit it, including the system tray. Build this repository, then install the local checkout through the desktop-bundled command in PowerShell:

& '<DSH installation>\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'D:\path\to\dsh_Market' --ignore-scripts

Reopen Desktop and go to Settings → Plugins → Plugin Marketplace. This adaptation is not in the published v0.9.5 tag. Do not start or relaunch its Host with dsh --profile desktop; Electron owns that lifecycle.

The Desktop catalog only shows entries whose Registry Profile metadata explicitly includes desktop, hiding Web-only and undeclared entries before search, category filtering, sorting, counting and pagination. Desktop-compatible guided installs remain visible, and the installed page still lists existing plugins for management. Cards show a Desktop badge; vague prose is not inferred, and the badge is not runtime or security certification or a relaxation of automatic-install/update checks. Desktop uses its own default Profile directory, shares the official manager's writer lock, and checks peer compatibility before installation without granting version exemptions. Its restart button shows quit/reopen instructions; Web restart behavior is unchanged.

With an existing installation, set DSH_DESKTOP_ROOT and run pnpm desktop:runtime-test. The test uses Electron Node mode and bundled pnpm with an isolated temporary Profile and offline fixture packages; it does not launch the GUI, touch user Profiles, or download DSH/plugins. Browser fixtures remain distinct from live Desktop window acceptance. MARKETPLACE_SCREENSHOTS_DIR can redirect browser evidence.

3. Open the marketplace

Go to Settings → Plugins → Plugin Marketplace.

The marketplace has three pages:

• Plugin Marketplace — search, filter, sort, inspect validation details, and install plugins.
• Installed Plugins — filter, check for updates, update one or many, uninstall, enable, or disable plugins in the active Profile.
• Management & diagnostics — manually install a command, choose plugin storage, and diagnose conflicts.

Installation modes

Automatic installs always use an exact GitHub commit or npm version verified by the Registry. Mutable main, latest, and Release download URLs are never passed directly to the package manager.

Manual command install

Under Management & diagnostics → Manual command install, paste:

dsh plugin --profile web add github:owner/repo#ref

You may also enter only github:owner/repo#ref. The input is never passed to a shell. The marketplace accepts one GitHub command for the active Profile and rejects extra arguments, pipes, multiple commands, and unsafe refs. A tag, branch, or omitted ref is first resolved to an exact commit, after which the manifest, bundle patch, and conflicts are validated. Lifecycle scripts stay disabled. A new package joins the Profile bundle stack; an installed package with the same name is updated from the pinned source.

Guided-install Agent

Plugins that still require guided installation show Install with Agent. Installed plugins with a guided update show Update with Agent.

Every Agent task is pinned to:

• the Registry-verified repository, package name, version, and unique commit;
• the active Profile, bundle patch, and the scanner's classification reason;
• the absolute path of the dedicated plugin-marketplace Agent workspace;
• a security boundary that treats README files, issues, scripts, and dependencies as untrusted input;
• acceptance checks for Profile dependencies, bundle layers, and enabled state.

Every guided task starts by loading the bundled install-dsh-plugin Skill. It selects the shortest safe route: use an exact commit with scripts disabled when complete runtime artifacts already exist; build in an isolated temporary checkout when artifacts are missing; or stop when a Release tarball lacks a trusted digest, identity differs, bundle/runtime files are absent, or conflicts exist. Its read-only inspector verifies Git HEAD, package identity, bundle patch, Host/Client entries, lifecycle scripts, and Bundle ID/Cordis service conflicts against the active Profile.

The Agent inspects the exact commit in read-only mode first. Before running installation, build, prepare, postinstall, or other third-party code, it must request approval through DSH's native approval layer. The marketplace never grants approval on the user's behalf. Updates preserve configuration, bundle order, and enabled state while retaining the previous exact source for rollback. If the Agent cannot prove the install source, package identity, Profile compatibility, or runtime artifacts, it stops and explains what evidence is missing.

After a successful install, the Agent's final response must include How to start, covering:

1. which Profile should be used to start DSH;
2. whether a restart is required;
3. whether the plugin loads automatically with DSH;
4. which configuration values are still required;
5. the Web entry point or actual invocation method.

[!NOTE] Agents default to $DSH_HOME/marketplace/agent-workspace and never inherit the current or recent project workspace. Select an existing directory under Management & diagnostics → Agent install and update workspace to override it. After the Agent is created, close Settings to follow its progress and respond to approval requests.

Installed plugin management

Install, update, and uninstall share one FIFO plugin-operation queue. It appears only on Installed plugins, restores active jobs only, retains at most 12 finished jobs for 10 minutes, and can clear finished history. Profile writes use both the in-process queue and a cross-process lock; transient Windows lockfile failures receive bounded retries.

Installed plugins can be selected from the current filtered view and updated, enabled, disabled, or uninstalled in bulk. A batch accepts at most 50 plugins; bulk enable checks the combined state for newly introduced conflicts, and bulk enable/disable writes the Profile manifest once.

Search and state filters can be reset in one click. Selections persist across filters; hidden selected plugins are explicitly indicated and remain included in batch actions. Clear selection clears every selected plugin.

The interface follows DSH light and dark themes, separates navigation, filters, and actions, and adapts cards, buttons, and management panels to narrow windows. Uninstall actions have a distinct danger treatment while installation and batch actions retain the existing confirmation flow. Compact cards fit two columns in a content area of at least 490px, with reduced card padding and filter spacing to shorten scrolling through long lists.

Once a custom-directory uninstall has removed the Profile association, file cleanup failures leave the plugin uninstalled and log the residual paths for cleanup after restart. They never reattach potentially partially deleted files. Cleanup of old backups and staging directories likewise cannot undo a completed installation.

Update detection is not limited to version numbers. For a plugin installed from an exact GitHub source, a different Registry-verified commit is offered as an update even when the Registry version is unchanged. npm sources continue to use verified exact release versions.

The catalog first renders the bundled Registry snapshot and a lightweight Profile dependency list while refreshing the remote Registry in the background. Full installed metadata is scanned only when needed. Check updates bypasses the cache, and the default node_modules is no longer walked for unlinked directories.

The package includes the built lib/ files and a Registry snapshot from the release. If the remote Registry is temporarily unavailable, the marketplace can continue using the bundled snapshot.

Install location, Agent workspace, and conflict diagnostics

By default, plugin entities are installed by pnpm directly into the current Profile's node_modules, and every pnpm job reuses the store the Profile is bound to, avoiding ERR_PNPM_UNEXPECTED_STORE. Windows path separators are normalized, then the actual Store path recorded by .modules.yaml is passed unchanged, including its vN suffix and existing nested directories. Background pnpm jobs run non-interactively; installs and rollbacks can recreate dependencies and update the lockfile, while explicit frozen-lockfile requests remain enforced.

The install-location panel can switch subsequent installs to a custom directory through DSH's directory picker:

• plugins in a custom directory are linked to the Profile with a file: dependency, and their runtime entry is linked back into the Profile's node_modules;
• missing Host peer dependencies (e.g. cordis → @deepseek-ai/cordis) are linked automatically;
• switching directories only affects future installs; existing plugins stay in place and remain updateable and removable;
• directories that contain a plugin not linked to the Profile are marked separately and get no Profile operations.

The Agent-workspace panel separately controls guided install and update sessions. The default directory is created automatically; a custom directory must already exist and be readable and writable. On first use, the marketplace registers it as a DSH Workspace and binds only future installer Agents to it. Existing Agent sessions and other project Workspaces are not moved or changed.

The conflict panel runs heuristic static diagnostics over enabled bundles: duplicate bundle ids and common Cordis service registration forms (ctx.provide(...), super(ctx, ...), ctx['x'] = ..., ctx.x = ...). Results are a pre-flight guard against startup crashes — JavaScript is not executed and false positives are possible (for example when an entry bundle inlines another plugin's code); install, update, and enable operations only block conflicts that are newly introduced.

How the Registry works

flowchart LR
    A["GitHub topic: dsh-plugin"] --> B["Incremental scan every two hours"]
    B --> C["Resolve default branch to a 40-character commit SHA"]
    C --> D["Statically validate manifests, patches, entries, and npm tarballs"]
    D -->|"Valid"| E["registry/plugins.json"]
    D -->|"Insufficient evidence"| F["Guided-install audit"]
    D -->|"Invalid structure"| G["registry/rejected.json"]
    E --> H["DSH Plugin Marketplace"]
    F --> H

The scanner never installs dependencies, executes third-party code, or evaluates !!js values in YAML. Temporary network failures preserve the last valid result instead of removing large numbers of entries from the marketplace.

When a repository provides dsh-plugin.json, the scanner additionally performs a dsh-std Community v0.15 static preflight. It validates the Manifest structure, host facet, protocol coordinates, fallback for optional contracts, permissions, and subscriptions against the declared tui-admission/0.15 surface. The result appears in plugin details. It is not runtime admission: actual Host capabilities, Profile installation, and user authorization for default-deny permissions can only be confirmed at activation time.

Heuristic malware scans and Agent Loop runtime probes are currently experimental and isolated from the stable Registry. Their results cannot downgrade a plugin that passed the static install checks above from one-click to guided installation.

Registry files

Unchanged GitHub sources already approved for automatic installation reuse their previous results. Guided entries and npm sources are rechecked every two hours. If a plugin later publishes a valid exact npm version, the next scan automatically promotes it to one-click installation.

Custom Registry

The default central Registry is:

https://raw.githubusercontent.com/YELEBAI/dsh-plugin-marketplace/main/registry/plugins.json

Override it with an environment variable:

$env:DSH_PLUGIN_REGISTRY_URL = 'https://raw.githubusercontent.com/OWNER/REPOSITORY/main/registry/plugins.json'
dsh --profile web

You may also set registryUrl in the plugin configuration. Remote content is cached in memory for 15 minutes and supports ETag. A refresh failure first uses the most recent valid response and then falls back to the bundled snapshot. Configure the cache with registryCacheMinutes; registryRequestTimeoutMs applies to both Registry and install-time GitHub requests.

Explicit refreshes bypass the TTL while retaining the ETag and last valid snapshot, and concurrent checks share one request. HTTP 304 responses still refresh categories and Star growth; unavailable optional discovery data preserves existing values. If the initial bundled snapshot is missing or invalid, the client tries the remote Registry.

A custom Registry may omit discovery.json and guided-audit.json:

• without discovery.json, search and installation still work, but entries use the “Other” category and report zero Star growth;
• without guided-audit.json, the Agent still performs read-only verification against the exact commit in the core Registry, but scanner-provided audit context is unavailable.

Automated scans and PAT usage

The Registry Scan workflow runs at minute 17 every two hours and can also be started manually from GitHub Actions.

Scans prefer the read-only PAT stored in the REGISTRY_GITHUB_TOKEN Actions Secret and fall back to the repository-provided GITHUB_TOKEN. The PAT is used only for GitHub API reads and never for Registry commits; writes continue to use the credential provided by Actions checkout.

Add REGISTRY_GITHUB_TOKEN under Settings → Secrets and variables → Actions. Never place a token in a workflow, README, or commit.

[!TIP] Standard GitHub-hosted runners are generally free for public repositories. Private repositories consume the Actions minutes included in the account plan and may incur charges after the allowance is exhausted. See GitHub Actions billing.

Generate the Registry locally for the first time:

corepack enable
pnpm install
$env:GITHUB_TOKEN = gh auth token
pnpm registry:test
pnpm registry:scan
pnpm registry:audit

The scanner automatically partitions GitHub Search results beyond the 1,000-result limit and continues after rate-limit resets. Read limits are:

• package.json: 256 KiB
• bundle patch: 64 KiB
• npm archive: 50 MiB
• extracted npm content: 150 MiB

Security and validation

A candidate repository must meet these baseline requirements:

• package.json is valid JSON with a valid lowercase npm package name and semantic version;
• dsh.bundle.patch points to a safe repository-relative path;
• a declared dsh.client uses the web platform and exports ./client;
• the bundle patch is a valid YAML operation array;
• the patch inserts at least one loader entry whose name equals the npm package name;
• every published field and exact commit passes the Registry Schema.

The Registry never decides automatic installation from a single keyword. It cross-checks:

• host/client entries and the optional dsh.marketplace declaration in package.json;
• whether the Git tree contains the runtime artifacts for every declared entry;
• whether the README provides dsh plugin --profile ... add github:...;
• whether an old owner or repository alias in the README resolves to the same GitHub repository ID;
• placeholders such as <profile>, your-profile, and my-profile, which are not treated as real Profile names;
• Web client plugins, which map only to web, and host-only plugins, which default to headless and web;
• pnpm options such as -w / --workspace-root, while still requiring DSH CLI's --profile;
• preinstall, install, postinstall, and prepare lifecycle scripts;
• conflicts between README Profiles and manifest declarations;
• the Registry URL, SHA-512 integrity, package identity, bundle patch, and runtime entries of same-name, same-version npm releases;
• whether an npm package contains preinstall / install / postinstall or a root-level binding.gyp.

Any GitHub source containing preinstall, install, postinstall, or prepare always requires build approval and remains guided; committed runtime artifacts do not suppress that lifecycle warning. An exact npm tarball does not execute prepare when installed as a dependency, so a release that contains all runtime artifacts and passes static validation may still be automatic.

An incorrect migration URL in a README is retained as audit information but does not block a complete, installable exact commit in the current repository. Missing or contradictory evidence keeps the plugin guided; the scanner never guesses its way to one-click installation.

Plugin authors may provide more explicit marketplace metadata in package.json:

{
  "dsh": {
    "marketplace": {
      "profiles": ["web"],
      "requiresBuildApproval": false,
      "requiresRestart": true,
      "manualSteps": false
    }
  }
}

The central Registry may also use policy/install-overrides.json to add Profile or installation metadata for manually reviewed repositories.

[!WARNING] Registry validation filters incorrect topics, ordinary repositories, and structurally incomplete pseudo-plugins. It cannot prove that third-party code is harmless. A plugin receives local process permissions after DSH restarts, so verify its source and read every approval request before installing it.

Development

Requirements: Node.js, the repository's pinned pnpm, and either a built DSH checkout or an installed DSH npm package. The compatibility baseline is DSH 0.1.7-rc.2. Source mode defaults to D:/DSH/deepseek-harness; set DSH_CHECKOUT to override it.

Alternatively, set DSH_PACKAGE_ROOT to the installed @deepseek-ai/dsh package directory containing package.json. Dependencies may be nested or hoisted by npm; scripts follow Node's search order. This uses that release's public types, Typert loader and UI components without rebuilding upstream. MARKETPLACE_TOOLS_DIR may point to an existing standalone tool directory providing esbuild and playwright; scripts never install them automatically. Set pnpm_config_verify_deps_before_run=false before checks to prevent implicit dependency changes.

pnpm install
pnpm registry:test
pnpm registry:discovery
pnpm discovery:test
pnpm profile:test
pnpm restart:test
pnpm desktop:test
pnpm web:runtime-test
pnpm self-update:test
pnpm guided-agent:test
pnpm build
pnpm verify
pnpm package:test
pnpm typecheck

Run pnpm ui:test with existing esbuild, React, Playwright and local Chromium, using real components from a DSH checkout or installed release. It checks light/dark themes, narrow layouts, Chinese/English labels, filters, batch selection and confirmation flows, and refreshes the previews in docs/screenshots. Set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH if the browser is outside Playwright's default location. The test does not download dependencies and uses an isolated page with mock data; it does not modify real Profiles or install plugins. Integration with the actual DSH host still requires verification in DSH.

Use MARKETPLACE_SCREENSHOTS_DIR to redirect screenshots. With an existing Desktop installation selected by DSH_DESKTOP_ROOT, pnpm desktop:runtime-test checks the real Host/RPC and bundled pnpm in an isolated offline Profile, without starting the GUI or changing user Profiles.

pnpm web:runtime-test uses the real Cordis Host, marketplace service and pnpm in a separate process with a temporary DSH_HOME. It checks legacy default and current custom directories, Web catalogs, install/update/uninstall, conflict rejection and preservation of disabled state. All fixtures are local archives with lifecycle scripts disabled; no user credentials or Profiles are read or modified. Browser regressions also verify that Desktop filtering, directory restrictions and restart guidance do not leak into Web. CI repeats the checks against both supported published DSH runtimes.

Failure recovery checks cover retrying Profile reads in place, installing unlinked entries, merging delayed job snapshots, and recovering after guided Agent creation fails. pnpm guided-agent:test also checks session reference release, rename/submission/navigation failures, and older session APIs without sending real model requests.

Published UI modules also reference third-party development dependencies from their manifests. To prepare a separate tool directory explicitly, set DSH_PACKAGE_ROOT first and keep MARKETPLACE_TOOLS_DIR outside the DSH installation and active Profile. CI follows the same approach and pins esbuild to verify reproducible lib/ artifacts.

npm install --prefix "$env:MARKETPLACE_TOOLS_DIR" --save-exact --ignore-scripts esbuild@0.28.2 playwright@1.62.1
$uiTools = @(node scripts/ui-tool-dependencies.mjs)
if ($LASTEXITCODE -ne 0) { throw 'Could not read DSH UI dependencies' }
npm install --prefix "$env:MARKETPLACE_TOOLS_DIR" --save-exact --ignore-scripts @uiTools
pnpm ui:test
# In addition to default development dependencies, check temporary Profiles against the target runtime.
node --import ./scripts/use-installed-dsh.mjs --experimental-strip-types scripts/profile-test.ts

Local checks can reuse Chromium/Edge; CI explicitly installs Playwright Chromium. These installation commands only prepare tools. Regular build, typecheck, and ui:test never download dependencies or browsers.

Before a release, update the version, regenerate the Registry, rebuild lib/, commit the generated artifacts, and create a version tag.

[!NOTE] The marketplace Remote method is named marketplace/installPlugin. Do not rename it to marketplace/install: install is an internal lifecycle method of the DSH Remote namespace service and would conflict with the client API.

License

MIT © YELEBAI