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 · 中文
This bundle adds three things to every session:
- 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.
- 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.
- 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.
| Tool (e.g. market_search) | Skill (registered by this plugin) |
|---|
| Nature | Capability channel: callable functions | Context knowledge: when, why, and how to call |
| Effect alone | Tool exists, but the agent does not recognize it | No marketplace interface to call |
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:
| Check | Source of truth |
|---|
| Can its bundle layer be mounted? | whether dsh.bundle.patch exists on disk, and whether the package is named in dsh.profile.bundles |
peerDependencies ranges satisfied? | the version of each package actually on this machine, including vendor/ |
Imported @deepseek-ai/* packages still exist? | the dsh install root (packages/, vendor/, node_modules/@deepseek-ai) |
| Are the named exports those imports need still exported? | the package's declaration entry, walked through export * re-exports, unioned with its runtime entry |
| Registered client slots still defined? | slot contracts extracted from official packages/client + packages/core source |
inject service names resolvable? | the live Cordis context |
| Install-time risk signals? | npm lifecycle scripts, child_process, eval, remote import, network |
Verdicts are graded, not binary:
| Verdict | Meaning |
|---|
compatible | every check this tool can perform passed |
at-risk | a declared range no longer matches or its layer is not composed in, though the code may still run — the normal state of this ecosystem |
incompatible | hard evidence: a package, export or slot it needs is gone from this build, or its bundle layer cannot be mounted |
unknown | something needed a check that cannot be done offline; the reason is always stated |
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:
| Situation | Upstream behaviour |
|---|
Declares dsh.bundle.patch but the package does not contain that file | failed to read overlay — throws (packages/boot/app-boot/src/index.ts:315-323) |
Declares dsh.bundle with no patch path | declares no dsh.bundle — throws (packages/boot/app-boot/src/profile.ts:792-797) |
dsh.profile.bundles names a package that cannot be resolved | layer resolution fails — throws (same file) |
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.
| Range | Version | Result |
|---|
^0.1.0-rc.5 | 0.1.5-rc.1 | ✗ not satisfied |
^0.1.0-rc.6 | 0.1.5-rc.1 | ✗ not satisfied |
^0.1.0-rc.5 | 0.1.0-rc.6 | ✓ satisfied |
^0.1.0-rc.5 | 0.1.5 | ✓ satisfied |
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
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:
| Step | Detail |
|---|
| Resolve | reads the registry document and picks one concrete version, so the report can state which version it judged |
| Download | streams the tarball with a 64 MiB ceiling |
| Verify | checks the registry's published integrity (sha512/sha384/sha256) or shasum before unpacking — a mismatch aborts the audit |
| Unpack | into an mkdtemp directory, then deletes it on every exit path |
| Judge | the same verdict engine as the offline audit, run against the same local dsh build |
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:
| Attack | Behaviour |
|---|
../escape.txt, package/../../escape.txt | refused and reported |
/absolute.txt, C:\… | refused and reported |
| symlink / hardlink entries | skipped, never created — so a later entry cannot be written through the link |
| a header that overstates its size | the reader stops instead of reading past the end |
| a decompression bomb | per-file, total-size, and entry-count caps stop it loudly |
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
| Property | Value |
|---|
| Runtime dependencies | 1 (yaml, used only to parse the bundle patch) — the tar reader is hand-written rather than a dependency |
| Build step | None — plain JavaScript, no prepare script, no allowBuilds authorization |
| Plugin form | bundle + two host tools; no dsh.client, no UI surface |
| Network / telemetry | dsh_plugin_audit: none, reads local files only. dsh_plugin_inspect: read-only GETs, only when called; no telemetry, no credentials |
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, use node <dsh install root>/apps/cli/lib/bin.js plugin --profile web add <spec>.
How it works
| File | Responsibility |
|---|
index.js | Plugin entry: registers the skill provider, then attaches both tools via ctx.get('tools') |
lib/skills.js | Parses skills/<name>/SKILL.md bundles and registers them on ctx.skills |
lib/tool.js | The offline tool definition and the human-readable report renderer |
lib/inspect-tool.js | The networked tool definition and its renderer |
lib/audit.js | Locates the dsh root and profile, scans plugins, produces verdicts |
lib/symbols.js | Walks declaration graphs through export * barrels to confirm named exports |
lib/semver.js | Dependency-free semver matching aligned with node-semver, including prerelease rules |
lib/registry.js | Registry/repository resolution, integrity verification, capped downloads |
lib/inspect.js | Fetches, unpacks and judges a not-yet-installed package, then deletes the temporary tree |
lib/tar.js | Hand-written hardened tar reader: traversal, link entries and bombs are refused |
cordis.patch.yml | Bundle patch layer: the - insert: row mounts the plugin at profile startup |
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
License
MIT
