# dsh-plugin-shop
**The plugin shop for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)** β discover, install,
enable and update dsh plugins from a browsable, git-auditable catalog.
[](https://www.npmjs.com/package/dsh-plugin-shop)
[](https://LivXue.github.io/dsh-plugin-shop/v1/index.json)
[](https://LivXue.github.io/dsh-plugin-shop/v1/index.json)
[](LICENSE)
[](https://github.com/LivXue/dsh-plugin-shop/actions/workflows/plugin.yml)
[](https://github.com/LivXue/dsh-plugin-shop/actions/workflows/daily.yml)
English | [δΈζ](README.zh.md)
---
## π¦ Install the shop
Two tracks. They do the same thing; pick the one that matches who is reading.
### π§ For people
**Prerequisites:** Node.js. Running the harness itself needs no install β the
upstream-documented form is `npx -y @deepseek-ai/dsh web`. Plugin management
goes through `dsh plugin`, which spawns both the `dsh` command and `pnpm` β
install them once with `npm install -g @deepseek-ai/dsh pnpm` and verify with
`dsh --version` and `pnpm --version`.
```sh
# dsh on PATH (global install). Pin the version: pnpm 11 holds back very
# recent releases, so a bare `add dsh-plugin-shop` can hand you an older
# version for a while. This is the current release β refresh it with
# `npm view dsh-plugin-shop version`.
dsh plugin --profile web add dsh-plugin-shop@0.7.4
# or straight through npx, nothing installed:
npx -y @deepseek-ai/dsh plugin --profile web add dsh-plugin-shop@0.7.4
```
Replace `web` with your profile if you use another one. Restart `dsh` once β a newly
added bundle is not applied to a running process β then open
> **Settings β Plugins β Plugin shop**
### π€ For agents
Non-interactive. `--profile` is **mandatory**; without it `dsh plugin` exits with
`error: required option '--profile ' not specified`.
```sh
# 1. resolve a profile name ($DSH_HOME defaults to ~/.dsh; node_modules is not a profile)
ls -1 "${DSH_HOME:-$HOME/.dsh}/profiles" | grep -v '^node_modules$'
# 2. install β pin the version: it bypasses pnpm's release cooldown and
# deterministic installs are the point of the agent path
dsh plugin --profile add dsh-plugin-shop@0.7.4
# 3. verify β a zero exit above only means pnpm resolved the package
dsh plugin --profile list --depth 0 # dsh-plugin-shop must appear
# 4. restart the profile; a new bundle is not hot-applied
dsh --profile
```
The same fact as step 3 lives in `$DSH_HOME/profiles//package.json` under
`dsh.profile.bundles`, if you would rather read the manifest than parse CLI output.
Per-failure diagnostics are in the
[package README](packages/dsh-plugin-shop/README.md#failure-modes).
## πΌοΈ Screenshots
 |
 |
| Installing an unreviewed plugin requires an explicit acknowledgement |
The same shelf in the dark theme |
## β¨ Highlights
- **π Whole-registry harvest** β every npm package keyed `dsh-plugin` or
`deepseek-harness`, plus every GitHub repository using them as topics. Nothing is
submitted here; there is no queue to join.
- **π§Ή Hard filtering** β every candidate is gated mechanically on every build, and
one that fails becomes a named rejection carrying one of seventeen recorded reasons,
in words its author can read. The `plugins` and `filtered` badges above count both
sides, live.
- **π Dependency check on your machine** β your installation resolves each recorded
peer name against your own profile, the question dsh's loader asks at mount, so a
card reads **Incompatible** only when the modules are really missing *here*.
- **ποΈ Daily rebuild** β committed to git, so every change is a reviewable diff. A
new plugin lands the next morning; a repository that disappears drops out the same
way.
- **ποΈ Seven categories** β an author who declares `dsh.catalog` picks their own; the
rest are classified for them.
## πΊοΈ How it fits together
**In this repository β the daily build.** Everything here is `registry/`.
```mermaid
flowchart TB
subgraph HARVEST["1 Β· Harvest β the whole public registry, every day"]
direction LR
NPM(["npm packages
keyword dsh-plugin
keyword deepseek-harness"])
GH(["GitHub repositories
the same keywords,
used as topics"])
end
subgraph GATE["2 Β· Gate β every candidate must clear all five, on every build"]
direction LR
G1["a plugin at all?
a dsh.bundle the
loader can mount"]
G2["auditable?
a license,
a live repository"]
G3["installable?
not deprecated on npm Β·
repo listings also need
no build scripts and
no workspace: deps"]
G4["what it claims?
tarball integrity, publish time,
not a near-miss of another name"]
G5["anything to show?
a valid dsh.catalog,
or an npm description"]
end
subgraph SHELVE["3 Β· Shelve β what the catalog records"]
direction LR
CAT["one of 7 categories"]
PEER["the declared peer NAMES,
never their version ranges"]
end
NPM --> G1
GH --> G1
G1 -.-> REJ
G2 -.-> REJ
G3 -.-> REJ
G4 -.-> REJ
G5 -.-> REJ
REJ[["rejected β one author-readable reason per name"]]
G5 ==>|"all five clear"| CAT
PEER ==> PUB[["4 Β· Publish β content-addressed JSON, committed to git, then GitHub Pages and npm"]]
```
**On your machine β the npm package.** Everything here is `packages/dsh-plugin-shop/`.
The two halves share no code, only the schema.
```mermaid
flowchart LR
CAT[["the catalog
index.json + plugins.sha256.json"]]
CAT ==> HOST["5 Β· Host half
races every origin
verifies sha256 Β· caches"]
HOST ==> DEP{"6 Β· Dependency check
resolve each recorded peer
against YOUR profile"}
DEP -->|"one or more absent"| BAD["Incompatible
the card names
what is missing"]
DEP -->|"all resolve"| GOOD["installable"]
BAD --> CLIENT["Client half β the Settings tab
nine shop/* methods
no network Β· no filesystem"]
GOOD --> CLIENT
CLIENT ==>|"dsh plugin add"| PROF[("your dsh profile")]
```
Two parts are worth naming, because they are the ones people expect to work
differently:
- **The gate rejects; it never silently drops.** Every candidate that fails becomes a
named rejection with a reason, attached to the build.
- **The dependency check is not a catalog fact.** The build records only the peer
*names* β never their version ranges, because nearly every dsh plugin declares
`"*"` and the harness's own prereleases do not satisfy ordinary ranges, so checking
them would accuse plugins that work. Whether a name resolves is decided by your
installation, against your profile.
## β
What it is
| | |
|---|---|
| **Public and community-run** | Publishing to npm with the `dsh-plugin` or `deepseek-harness` keyword is all it takes to be discovered. Nothing is submitted to this project. |
| **Git-auditable** | Every daily catalog change is a reviewable diff, not a row in someone's database. |
| **Tiered trust, honestly reported** | A review is pinned to the exact version it covered, so an author who passes review once cannot publish a malicious version and inherit the trust. **Today `registry/verified.yml` is empty: no listing has been read by a human, every entry is community-tier, and every install asks for the acknowledgement.** The filtering above is mechanical, and it is not a substitute for reading the code you are about to run. |
| **Zero-privilege UI** | Compromising the browser interface does not compromise the runtime. |
## π« What it is not
> **It is not a sandbox.** A dsh plugin, once mounted, holds the full `ctx` β your
> filesystem, your shell, and the requests going to the model. Installing one is
> complete trust. This project does not change that; it tells you the truth before you
> click.
It also carries no download counts, ratings, or reviews, and it will never offer an
"install from arbitrary URL" button. That capability stays in `dsh plugin add`, where
enabling build scripts and pinning a commit are decisions you make explicitly.
## π The catalog
Built daily and published as static JSON, to two places at once: the npm package
`dsh-plugin-shop-catalog` and GitHub Pages. Your installation races them β the
registry you have configured, npmmirror, npmjs, then Pages β and takes whichever
answers first, because the link to one of them can be far slower than the link to
another from where you sit. All of them carry the same bytes, and the sha256 in the
pointer is checked before any of them is trusted. `DSH_SHOP_CATALOG_URL` opts out of
the race and reads only what you name.
| Artifact | Purpose |
|---|---|
| [`/v1/index.json`](https://LivXue.github.io/dsh-plugin-shop/v1/index.json) | The pointer β `schemaVersion`, `builtAt`, the entry `count` and `rejected` totals (the badges above read them live), and the content hash. Small enough to poll. |
| `/v1/plugins..json` | The data β content-addressed, safe to cache indefinitely. |
| `/v1/stars..json` | GitHub star counts by package name, when the daily build could fetch them |
Each build's rejection report, carrying an author-readable reason for every rejected
package, is attached to the workflow run. Nothing disappears without a reason attached
to its name.
The data files are content-addressed, so each build publishes new names and the previous
ones stop existing, while the pointer above them is cached for ten minutes. If you fetch
`/v1/` yourself, re-read `index.json` whenever a data URL answers 404 β or read the same
bytes from the npm package `dsh-plugin-shop-catalog`, where the pointer and the data it
names always ship in one tarball.
## π·οΈ Listing a plugin
Add a harvest keyword (`dsh-plugin` or `deepseek-harness`) to your `package.json` and publish to npm; the daily build picks it up. A plugin that never publishes to npm is listed from its GitHub repository instead: add the same keyword as a repo *topic* and keep a `package.json` at the root with a `name` and `dsh.bundle` β the catalog pins the default-branch commit as the version.
A `dsh.catalog` section is optional β declare it to control your own category, summary
and capabilities, or omit it and the catalog derives a listing from your npm
`description` instead.
```json
{
"name": "dsh-hello-plugin",
"keywords": ["dsh-plugin"],
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"catalog": {
"category": "tool",
"summary": { "en": "...", "zh": "..." },
"capabilities": ["fs", "shell"]
}
}
}
```
Full field reference: [docs/schema.md](docs/schema.md).
**Not listed, and why:** a package without `dsh.bundle` is a library rather than an
installable plugin. A package without a license or a repository cannot be audited. A
package with neither a `dsh.catalog` section nor an npm `description` has nothing to
show.
## ποΈ Repository layout
| Path | What lives there |
|---|---|
| `registry/` | The catalog pipeline β a pure core (`gate`, `tier`, `emit`, `pipeline`) behind an impure shell (`npm-client`, `build`) |
| `registry/verified.yml` | The human review record, pinned per version |
| `registry/denied.yml` | The denylist; every entry states why |
| `registry/snapshots/` | `manifest.lock`, committed daily |
| `packages/dsh-plugin-shop/` | The npm package β Host half and Client half |
| `docs/design/` | The specification. It is the authority; code follows it. |
## π οΈ Development
```sh
pnpm install
pnpm test # vitest
pnpm typecheck
```
`pnpm build:catalog` runs the real harvest against npm and GitHub β thousands of live
requests and several minutes. The tests cover every policy decision without a
network, so reach for it only when you have changed the fetching or writing layer.
Status and open work: [docs/plans/2026-08-18-remaining-work.md](docs/plans/2026-08-18-remaining-work.md).
Specification: [docs/design/2026-08-18-dsh-plugin-shop-design.md](docs/design/2026-08-18-dsh-plugin-shop-design.md).
## π License
[Apache-2.0](LICENSE) Β© LivXue
