dsh-community-plugins

A DeepSeek Harness (dsh) plugin that teaches agents how to discover, evaluate and install community plugins — and gives them two tools to check those plugins against the dsh build actually running on this machine: one that stays offline, and one that fetches a package before it is installed.

English · 中文

Scope

This plugin is fully adapted to DSH Desktop (DeepSeek Harness Desktop) and also runs under dsh web and other hosts: its skill and both tools register through official public interfaces and use no desktop-only API.

Installation and judgement follow the profile that is actually running by default (read at runtime from the official profileContext service's name / dir). desktop and web are peer profiles whose dsh.profile.bundles, dependencies and compatibility.json are independent; an install must target the running one, or the files on disk will be correct while the interface and the runtime change not at all. Measured (2026-09-30, Windows, dsh 0.2.0-rc.2): the desktop application composes the desktop profile, and installing a skin into the web profile produced no visible effect.

Every --profile web in this document is an example; on DSH Desktop substitute --profile desktop.

When a plugin takes effect

A bundle layer is composed once, at process startup. dsh plugin add only rewrites the profile's dsh.profile.bundles and its dependencies; it does not change the running process's graph. "Installed successfully" and "visible in the interface" are therefore two independent facts, and a plugin's behaviour may only be judged after the application has been fully quit and started again.

Three states are independent, and only the third proves a plugin is active:

dsh_plugin_audit compares the calling process's start instant against the profile configuration and each installed package, reports an activation notice in the report header, and prints an activation: line under the affected plugin: a bundle layer written after that instant is not in that process's graph and takes effect only after a restart. This check is advisory and never changes a compatibility verdict.

The full criteria are in the skill's §7 (when a plugin takes effect) and §8 (the adaptation lines for skin and theme plugins).

This bundle adds three things to every session:

1. A skill (dsh-community-plugins) — how to find plugins through the GitHub dsh-plugin topic, curated indexes and npm; how to vet one before installing; how to install through the official dsh plugin mechanism; how to verify the result.
2. An offline tool (dsh_plugin_audit) — compares installed plugins against this machine's dsh build and reports, per plugin, what is broken, what is merely risky, and what could not be determined. It fetches nothing.
3. A networked tool (dsh_plugin_inspect) — downloads a package's published tarball, verifies it against the registry's published hash, unpacks it into a temporary directory, and judges it before it is installed. It never installs anything and never runs the package's lifecycle scripts.

The two tools are separate on purpose. The audit's promise is that it touches no network; a flag that sometimes made it fetch would make the promise conditional, and a conditional promise is not one. Two tools, two guarantees, and each says which one it is.

Why this plugin

DeepSeek Harness provides plugin capabilities through two complementary mechanisms: Tools and Skills.

A marketplace tool alone is not enough, because agent behavior is driven by context knowledge. web_search has an intuitive description and is any model's default approach; market_search is DSH-specific. Without this skill the agent does not know it exists, does not associate it with installing plugins, and does not understand the local profile layout, the bundle mechanism, the vetting workflow, or the restart requirement.

And knowledge alone is not enough either: the ecosystem's one hard practical question — "will upgrading dsh break what I have installed?" — cannot be answered reliably by hand, because the rc-prerelease rule below defeats eyeballing.

Why a live probe instead of a compatibility dataset

Upstream declares the API surface unstable on purpose:

• README.md — "THERE WILL BE COMPATIBILITY-BREAKING CHANGES."
• AGENTS.md — "Public APIs are pre-stable; update every consumer."

A cached snapshot of that API surface therefore starts decaying the moment it is written. Measured here: 16 0.x prereleases in one month — roughly one breaking change a week. A dataset would need continuous maintenance and would be wrong between updates, and a verification tool that is confidently wrong is worse than no tool at all.

So this plugin stores nothing. dsh_plugin_audit reads the dsh install root and the profile on every call and answers for this machine, right now; dsh_plugin_inspect reads the tarball it just downloaded and answers against that same build. No telemetry, no cache, no data to keep fresh — and when something genuinely cannot be checked, both say unknown and give the reason instead of guessing.

This is the difference from the ~75 marketplace plugins, the 3+ static auditors already in the ecosystem, and even the official runtime inspector: those list, rank, scan for security, or describe what is live right now. None compare a plugin's declared ranges and actual API usage against your dsh build, and none can do it for a plugin that is not installed yet.

Complementary to the official runtime inspector. @deepseek-ai/dsh-tool-cordis ships cordis_inspect_*, which queries the live runtime exactly (Service.listService, Event.listEvents, Tool.listTools, and Slots.listSubTree for real client-side slot props). For "what does the runtime look like right now", that is strictly the better tool. This plugin answers a different question — "do the declarations on disk still line up with the build installed here" — and it still works where the inspector cannot: a plugin that failed to load is not in the live runtime, so the inspector cannot see it at all. Static inspection reads the disk; the inspector reads the process. Both are needed.

Neither predicts a future upgrade. Both only ever see the build installed on this machine; the honest answer to "what will break after I upgrade" is to run them again after upgrading.

The offline audit tool

dsh_plugin_audit({})                                  # every third-party plugin in the profile
dsh_plugin_audit({ target: 'dsh-llm-local-token' })   # one package (name or directory)

Per plugin it reports:

Verdicts are graded, not binary:

Symbol-level checking, and why "the package still exists" is not enough

A plugin that does import { PiAiAdapter } from '@deepseek-ai/dsh-llm' keeps working only while that package still exports PiAiAdapter. A rename or a split leaves the package in place and the binding gone — and an ESM named import of a binding the module does not provide is a link-time throw, not a degraded feature.

Confirming that is harder than grepping one file, because a package's export surface is a graph. Official declarations are barrels, and TypeScript emits the source extension:

export * from './attribution.ts';          // the file shipped beside it is attribution.d.ts
export { BlockAssembler } from './assembler.ts';

A single-file scan reports every re-exported symbol as missing. So the check walks the graph — relative specifiers, the .ts/.js → .d.ts mapping, bare specifiers into other packages — and keeps two things strictly apart:

• the set of symbols it confirmed, and
• whether that set is complete.

Only a complete graph licenses the word removed. An incomplete one yields unknown, because "I could not resolve it" is not "it is gone". The declared-type surface is unioned with the runtime entry's own export list, so a stale declaration cannot manufacture a failure.

Validated on this machine (2026-09, dsh 0.1.5-rc.1): 279 official packages inspected, 276 declaration graphs resolved completely, 1,874 runtime export names checked, 0 unconfirmed. The three incomplete graphs are reported as unknown, never as removals. The suite re-runs this sweep on whatever machine it is run on.

A bad plugin can stop dsh from booting

This is why the layer check comes first. Three of these throw rather than degrade, so the whole profile fails to start:

And one that fails silently: a readable patch whose package is not in dsh.profile.bundles — the layer is never applied, so the plugin does nothing at all. The usual cause is installing with pnpm add inside the profile instead of dsh plugin add, which is what reconciles that list (apps/cli/src/plugin.ts:59-91).

The tool prints one layer … line per plugin and raises the rest as blockers, so you can see all of this before restarting dsh. These particular judgements are exact — they read package.json and the filesystem, not source heuristics.

The rc-prerelease trap this exists to catch

^0.1.0-rc.5 expands to >=0.1.0-rc.5 <0.2.0-0. Does it match 0.1.5-rc.1?

No. A prerelease only satisfies a range when some comparator pins the same major.minor.patch and is itself a prerelease. The comparators are [0,1,0] and [0,2,0]; the version is [0,1,5]. Neither matches, so the prerelease rule rejects it.

Verified against npm's own semver. This matters because pnpm does not block installs on unsatisfied peers by default — so "it installed" has never meant "the range matches", and the Issues with peer dependencies found warning is telling the truth.

The pre-install tool

dsh_plugin_inspect({ spec: 'dsh-llm-local-token' })          # npm, latest
dsh_plugin_inspect({ spec: '@scope/pkg@^1.2' })              # npm, a range
dsh_plugin_inspect({ spec: 'github:owner/repo#v1.2.0' })     # a repository
dsh_plugin_inspect({ spec: 'https://host/pkg.tgz' })         # a tarball URL
dsh_plugin_inspect({ spec: ['pkg-a', 'pkg-b', 'pkg-c'] })    # screen many candidates at once

spec as an array is the screening mode, and it downloads no package bytes at all: it reads the registry documents only, judges the declared peer ranges, dsh's version gate and the manifest's lifecycle scripts, and states what it could not see. It exists because "which of these forty candidates can I actually install here?" used to cost forty downloads. Use a single spec string on the survivors for the full audit.

This is the only part of the plugin that uses the network, and it says so in its own name, its description, and its output. What it does:

What it does not do: install anything, write to the profile, or run the package's lifecycle scripts. A postinstall hook is reported as a high-severity finding, not obeyed.

Because it handles bytes nobody in this repository produced, the extractor is hand-written and hardened rather than pulled in:

The report also flags install-time risk, including the class SKILL.md warns about: a repo-provided install.sh / setup.ps1 that edits the profile directly and links the package into node_modules by hand, bypassing dsh plugin's dependency management — after which dsh plugin update and remove no longer manage it.

Positioning: lightweight by design

The tool definitions are written by hand as plain objects rather than built with defineTool from @deepseek-ai/dsh-tools. ctx.tools.register only requires { name, description, parameters, output: { schema, render }, execute } — a plain object cannot break when upstream renames or moves an exported symbol, which the "pre-stable" policy says will happen. The test suite proves both shapes are acceptable by running them through dsh's own assertSupportedJsonSchema and validateJsonSchemaValue.

Both tools are attached through ctx.get('tools') rather than inject = ['tools']. Declaring it as a dependency would put the whole plugin — including the skill — into a waiting state on any deployment that composes no tools service. The skill must always load; the tools degrade away quietly, and one rejected registration does not take the other tool down with it.

Both declare a timeoutMs budget and actually honour it. That field is a promise rather than a decoration: dsh's contract states that declaring timeoutMs asserts the tool forwards exec.signal and can reach quiescence when the budget aborts. execute therefore passes the signal down into the scan and into the download, and an abort surfaces as an AbortError instead of a silent overrun. (The budget is never sent to the model; schemas() whitelists only name, description, and parameters.)

Neutrality

This plugin is deliberately not a recommendation engine. It teaches method and reports facts; it does not rank, endorse, or recommend any third-party plugin or marketplace. Candidate plugins are presented with verifiable facts (form, license, activity, known risks) and the user makes the choice. The tools report compatibility, never "better".

Install

Prerequisite: the dsh CLI (or invoke apps/cli/lib/bin.js from the dsh install root).

# GitHub direct install (pure JS, no build scripts, no build authorization)
dsh plugin --profile web add github:HubaKing/dsh-community-plugins

# Gitee mirror (faster in mainland China)
dsh plugin --profile web add https://gitee.com/HubaKing/dsh-community-plugins.git

# tarball (works offline)
curl -LO https://github.com/HubaKing/dsh-community-plugins/releases/download/v0.4.0/hubaking-dsh-community-plugins-0.4.0.tgz
dsh plugin --profile web add ./hubaking-dsh-community-plugins-0.4.0.tgz

# source + link (development mode, edits to SKILL.md take effect immediately)
git clone https://github.com/HubaKing/dsh-community-plugins.git "${DSH_HOME:-~/.dsh}/plugins/dsh-community-plugins"
dsh plugin --profile web add link:${DSH_HOME:-~/.dsh}/plugins/dsh-community-plugins

⚠️ Always use the @hubaking/ scope for the npm form. The unscoped name dsh-community-plugins on npm belongs to a different project (funcodingdev/dsh-community-plugins, TypeScript, with build scripts), so dsh plugin add dsh-community-plugins silently installs that other package.

⚠️ The scoped package is not on npm yet. dsh plugin add @hubaking/dsh-community-plugins returns 404 as of 2026-09; the release workflow publishes it on a v* tag once NPM_TOKEN is configured. Use one of the forms above until then.

Restart dsh after installing (bundle layers are composed at startup). Installation succeeded when dsh-community-plugins appears in <available_skills> and both dsh_plugin_audit and dsh_plugin_inspect appear in the tool list.

When dsh is not on PATH, there are two shapes rather than one path to memorise:

• Packaged install — the CLI lives inside the asar and is launched by the shim the app manages: & "<install root>\resources\runtime\cli\bin\dsh.cmd" plugin --profile web add <spec>. Note <install root>\resources\app.asar.unpacked\dsh contains only node_modules, so apps/cli/lib/bin.js does not exist there.
• Source checkout — node <checkout>/apps/cli/lib/bin.js plugin --profile web add <spec>.

Location order for the install root: $DSH_ROOT → walk up from the running process entry to a directory holding packages/ and apps/cli/ → ~/work/deepseek-harness, ~/deepseek-harness, ~/dsh. Only a source checkout can serve as the install root for the audit's API-surface checks; a pure packaged install degrades those to unknown and says so under limits of this run:.

How it works

Development

npm install      # only `yaml`
npm test         # semver + symbols + live audit + fixtures + tar + pre-install + contract + integration

The suites are designed to be useful on any machine:

• test/semver.test.mjs — cross-validates lib/semver.js against npm's semver when one is reachable (930 range/version pairs and 900 ordering pairs, currently zero mismatches, plus explicit assertions).
• test/symbols.test.mjs — the export-graph resolver against synthetic packages: .ts-suffixed export *, aliased re-exports, private classes in a barrel, unresolvable graphs, and the import forms that used to be mis-attributed.
• test/audit.test.mjs — runs the audit against this machine's real installation and prints the report; machine-specific values are printed, never asserted. It also re-runs the whole export-surface sweep described above as a self-consistency oracle.
• test/fixtures.test.mjs + test/fixtures.mjs — builds synthetic dsh homes in a temp directory (profile, installed plugins, fallback, optional source tree) and asserts exact verdicts, including every boot-failure path and every symbol-check outcome.
• test/tar.test.mjs — the extractor against archives it is not supposed to accept.
• test/inspect.test.mjs — the pre-install tool end to end against a local HTTP server, not npm: version selection, integrity verification, refusal of traversal and link entries, temp-directory cleanup, and the "nothing was installed" guarantee.
• test/plugin.test.mjs — exercises the apply contract, all graceful-degradation paths, and validates both hand-written tool definitions with dsh's own schema validators.
• test/integration.test.mjs — loads the plugin through a real Cordis Context and a real ToolRuntime, then checks that both tools are actually visible to the model and disposed on unload.

Layout

dsh-community-plugins/
├── index.js                  # Plugin entry
├── lib/
│   ├── audit.js              # Environment probe + verdicts
│   ├── semver.js             # rc-aware range matching (no deps)
│   ├── skills.js             # SKILL.md provider
│   ├── symbols.js            # Export-graph resolution
│   ├── tool.js               # Offline tool + renderer
│   ├── registry.js           # Registry access + integrity
│   ├── inspect.js            # Pre-install audit
│   ├── inspect-tool.js       # Networked tool + renderer
│   └── tar.js                # Hardened tar reader
├── test/                     # Node-native tests, no framework
├── cordis.patch.yml          # Bundle patch layer
├── package.json              # dsh.bundle manifest
├── README.md                 # English
├── docs/lang/README_zh.md    # 中文
└── skills/dsh-community-plugins/SKILL.md

Modifying the skill content

Edit skills/dsh-community-plugins/SKILL.md; changes take effect on save (the provider re-reads from disk on every discovery), then git push to share. Changes to index.js or lib/ require a dsh restart — patchReload: live re-reads cordis.patch.yml only and does not replace source modules.

Related docs

• DeepSeek Harness official repository
• Official docs (English)
• Official docs (简体中文)
• Packaging and installing plugins
• Plugins and lifecycle
• GitHub dsh-plugin topic

License

MIT