dsh-plugin-directory

A plugin directory for the DeepSeek Harness (DSH) Web GUI. It renders a Plugin directory tab inside Settings → Plugins that lets you browse, search, filter, and compare GitHub repositories tagged with the dsh-plugin topic — including each plugin's install command, function category, install form, language, license, stars, and a quality score.

中文说明见 README.zh.md。

Install

This plugin is itself a DSH plugin. Install it with the dsh CLI:

npm

dsh plugin add dsh-plugin-directory

git (when published under a GitHub org/user)

dsh plugin add github:dingzhenyao/dsh-plugin-directory

manual / local checkout

dsh plugin --profile <profile-name> add ./dsh-plugin-directory

After installation, open the DSH Web GUI and go to Settings → Plugins → 插件目录 (Plugin directory).

Compatibility

The plugin works with DeepSeek Harness 0.1.0-rc.5 (source checkout) and 0.1.0-rc.6 (npm). Its client peer dependencies accept >=0.1.0-rc.5 <0.2.0, so both a local pnpm dsh checkout and an npm-installed dsh satisfy them.

Usage

The tab is a client-side directory over a snapshot of the dsh-plugin topic. Repos are included when their README documents a dsh plugin command, they carry the dsh-plugin topic, or their name/description mentions dsh-plugin — the repo name itself does not need to contain "dsh". Candidates are ranked by stars so real plugins outrank list/boilerplate repos:

• Search — filter by plugin name, owner, or description; the query also triggers a live GitHub search for the latest matching repos (see below).
• Category multi-select — combine any number of function categories (tool, skill, memory, vision, UI skin, MCP, orchestration, CLI/TUI, web, agent, other).
• Install-form filter — restrict to bundle / repository / client / unknown.
• Group-by dimension — group cards by function category, install form, language, or star bucket (default: no grouping).
• Sort — by quality score, stars, or most recent update (default: stars).
• Statistics dashboard — totals and breakdowns by category, install form, language, and star bucket.
• One-click install — a card's Install button copies the plugin's install command, shown only when the plugin's own README documents a real dsh install command (see the extraction policy below).
• My plugins — a personal management panel below the directory. Clicking Install records the plugin, and you can also add plugins manually (the source repository owner/repo is required) and remove or refresh existing entries. The list is stored in the browser's localStorage under dsh-plugin-directory:installed (see the note below).
• Refresh — a manual refresh button re-pulls the latest snapshot from the CDN.

Install-method extraction policy

Every listed plugin carries an install field describing how to install it. It is derived in priority order:

1. Plugin's own README — the first real install invocation found in the README becomes the command, with the source line kept as a snippet. The scanner accepts dsh plugin add <target>, dsh plugin --profile <name> add <target>, pnpm dsh plugin [--profile <name>] add <target>, and a bare .dsh-plugin reference (github:<owner>/<repo>#<ref>&path:/.dsh-plugin). The --profile flag is preserved when present. Prose mentions without a concrete target are ignored.
2. package.json signals — when the README has no install command but the plugin's manifest declares dsh.client or dsh.bundle, the npm package name is used: dsh plugin add <package-name>.
3. .dsh-plugin directory — a repository plugin (no client/bundle manifest) is installed from the repo: dsh plugin add github:<owner>/<repo>&path:/.dsh-plugin.
4. Fallback — when nothing above applies: dsh plugin add github:<owner>/<repo>.

The Install button is shown only for step 1 — when the plugin's own README actually documents a dsh install command. Derived commands (steps 2–4) are recorded on the entry for future use but never surface a button, so a repository whose README does not explain how to install it is never given a guessed install button.

Data sync

• data/plugins.json and data/meta.json are regenerated by the sync-data GitHub Actions workflow every 6 hours (cron 0 */6 * * *), fetching repos whose README documents a dsh plugin command, that carry the dsh-plugin topic, or that mention dsh-plugin in name/description (a repo name need not contain "dsh"), ranked by stars, and committing the resulting snapshot back to the default branch.
• pnpm sync runs the same pipeline manually (deep-inspection results are cached in data/.inspect-cache.json and reused while a repo's pushed_at is unchanged).
• data/overrides.json lets humans correct the keyword-based category classification, keyed by owner/repo.
• The snapshot is bundled into the client as an offline fallback, and the tab refreshes it from a CDN at runtime (see below).

Runtime data refresh & live search

• CDN refresh — on open, the tab fetches the latest snapshot from GitHub raw (https://raw.githubusercontent.com/dingzhenyao/dsh-plugin-directory/main/data); if it succeeds (and is no older than the bundled snapshot) it replaces the bundled snapshot and shows the last sync date, and if it fails (offline) it silently keeps the bundled snapshot. The owner (dingzhenyao) is the GitHub account hosting the dsh-plugin-directory repository — a single fixed value baked in at build time, shared by every installer (not per-installer). raw.githubusercontent.com follows the branch within minutes and serves files with Access-Control-Allow-Origin: *.
• Live search — typing a query also queries the GitHub Search API for topic:dsh-plugin repositories matching the query (debounced, 20 results), and appends them as a Live results section (deduped against the snapshot). Live results have no README inspection, so they show no install button. On rate-limit / failure the tab degrades to local results with a notice.

My plugins (host-file management)

The My plugins panel records the plugins you manage through this directory. It is backed by a host-side data file at $DSH_HOME/storages/dsh-plugin-directory/installed.json, written through a Typert Remote (ctx.remote.pluginManager.*) from the browser:

• Clicking a card's Install button adds the plugin (recorded with the github:<owner>/<repo> source and method search).
• Add accepts a manual source repository — owner/repo or github:owner/repo — and rejects anything that is not a valid owner/repo (method manual). The display name is the repo basename.
• Update refreshes an entry's timestamp (reinstall); Delete removes it.
• Sync status reads the harness's real Loader inventory (the built-in read-only pluginInventory Remote) and shows a per-entry badge: installed (with enabled/failed/loading refinements), disabled, not installed, or unknown (inventory unavailable). Matching is by the Loader moduleName against the ledger id/source, with a unique-basename fallback so an npm install of the same project still lines up with a recorded git source. The inventory is re-read automatically every 30 seconds (and on demand via the Sync status button).

The ledger is bookkeeping only: it records which plugins you triggered an install for (plus manual additions), and it does not actually run dsh plugin add/remove or read your exact install state back into the file — the real install state is shown live via the inventory sync, not persisted.

How the Remote works

The host exports PluginManagerGateway (a TypertRemoteService subclass with @Remote('list' | 'add' | 'delete' | 'update') methods). The host gateway discovers it through its SRC fallback (resolveSrcDescriptor) — no generated ./typert manifest is required. The client half hand-writes the matching TYPERT_REMOTE contribution (src/client/remote.ts) with strict zod codecs (the client gateway rejects src-json), mounts it via ctx.remote.$mount(...), and the tab calls ctx.remote.pluginManager.*. The real install status comes from the harness's own read-only ctx.remote.pluginInventory Remote (mounted by @deepseek-ai/dsh-api-remotes).

The browser bundle needs @deepseek-ai/dsh-api-remotes injected (it provides ctx.remote), and the host build lowers the standard @Remote decorator via a tsdown transform (ts.transpileModule) so the method markers register at runtime.

The validation helpers (isSourceRepo / normalizeSource) are shared between the host (src/data/installed.ts) and client (src/data/installed-types.ts).

Development

pnpm install
pnpm build       # tsdown → lib/index.js (host half) + lib/client.js (browser half)
pnpm test        # vitest
pnpm sync        # refresh data/ from the GitHub dsh-plugin topic
pnpm typecheck   # tsc --noEmit

In the DSH file sandbox, vite's Windows realpath probe spawns a suppressed child process, so run tests through the shim:

NODE_OPTIONS=--require=./scripts/vitest-sandbox.cjs pnpm test

Known limitations

• Category label language — fixed copy (tab name, buttons, placeholders) follows the active UI language immediately, but category/install-form label dictionaries are read when the tab page opens: after switching the UI language, reopen the tab for the updated labels.
• "My plugins" is bookkeeping, status is live — the panel stores which plugins you triggered an install for (and manual additions) in the host data file, but does not write the harness's real install state back; the per-entry installed/disabled/failed badge is read live from the Loader inventory via Sync status, so an install performed outside this directory only shows up if its moduleName matches a recorded entry.
• CDN cache delay — raw.githubusercontent.com serves the branch with a ~5-minute cache, so a fresh CI commit reaches the CDN refresh within minutes (and a stale edge cache is rejected in favor of the bundled snapshot); live search covers the gap for the very newest repos.
• Unauthenticated search quota — the live-search feature queries GitHub's search API from the browser (unauthenticated, 10 requests/minute); it is debounced and degrades to local results on rate-limit. The sync pipeline uses GITHUB_TOKEN in CI (see .github/workflows/sync.yml).
• CDN requires the repo to be published — the CDN refresh and git-install line point at github.com/dingzhenyao/dsh-plugin-directory; until that repository exists (pushed to GitHub), the tab silently falls back to the bundled snapshot. Change src/client/data.ts (CDN_BASE) if the repo moves.

License

MIT