DSH Plugin Scout
English | 中文
· MIT
Discover and verify DeepSeek Harness plugins published under the GitHub topic dsh-plugin, from inside DSH. Plugins are grouped by purpose, ranked by trust score, and checked against the official peer-compatibility rule. Supports DSH 0.2.x (>=0.2.0-rc.2 <0.3.0); tested on desktop 0.2.0-rc.2.
The in-app UI is currently Chinese only. The plugin's title and description in the official Plugins page are localized (locale/en.json, locale/zh.json).
Install
Open the official Plugins page → Add plugin, and enter one of:
| Spec | Notes |
|---|
dsh-plugin-scout | Recommended. Prebuilt npm package with provenance; no install scripts, no build approval needed |
Absolute path of a prebuilt dsh-plugin-scout-<version>.tgz, if supplied with a release | Bypasses the npm registry; the current tag workflow creates release notes only and does not attach a tarball |
From the CLI: dsh plugin --profile <profile> add dsh-plugin-scout. Enable it on the Plugins page; a 发现插件 (Discover plugins) entry appears in the sidebar.
Do not install from github:fegnze/dsh-plugin-scout: a git install fetches source without lib/, and this repository deliberately ships no prepare script.
One-click install, through the official installer
The Install button in the details drawer takes the same path as the official Add plugin: inspect first, then installBundle(spec, {enabled: false, requestId, registry}). Installed plugins start disabled; Enable is a separate click (setBundleEnabled).
- Plugins with install hooks, or whose DSH peers do not cover the running version, need a second click to install.
- When the official installer blocks dependency build scripts (
pendingBuilds), they are listed by name; a double click on Allow and reinstall retries with approvedBuilds.
- Cancel install calls
cancelInstall with the same requestId; a lost reply is recovered with waitForInstall. On failure the official installer restores package.json and the lockfile.
- Uninstalling and version exemptions stay on the official Plugins page. Scout never calls
removeBundle; the tests fail if it does. Without the official pluginManager, the Install button is hidden and the drawer falls back to "copy pinned spec + open the Plugins page".
Data sources (first-party only)
| Source | Used for |
|---|
GitHub GraphQL search(topic:dsh-plugin) | Repository metadata, root package.json, cordis.patch.yml text (never evaluated) |
registry.npmjs.org/<name>/latest | The manifest that would actually be installed: peers, install hooks, repository, provenance |
Official pluginManager.listBundles / inspect | Installed state; the official pre-install check (resolves only, runs no code) |
Official pluginManager.installBundle / waitForInstall / cancelInstall / setBundleEnabled | One-click install (disabled by default), cancel, separate enable; progress from plugin-manager/install-state and install-log events |
No third-party marketplace or aggregator is used.
Crawling, measured (2026-10): the topic holds about 19,000 repositories, 12,700 of them created in August, many of them same-name copies. GitHub search returns at most 1,000 results per query, so Scout bisects time windows adaptively (≤900 results per window, 60 s minimum window). Pages are 50 items: 100-item pages return 502 in dense windows, so on 502 the page size steps down to 25, then 10, resuming from the same cursor. Later runs crawl incrementally by pushed.
Refresh is streaming and pays only for what changed:
- Newest first. Windows are seeded geometrically (last 6 h / 1 d / 3 d / 1 w / 1 mo / 3 mo / older) and paged from the newest. Window counting and paging overlap (3 workers).
- Publish while crawling. Each page is merged into the record set immediately and published every 1.5 s; the UI reloads the list when
status.rev changes. The previous index stays usable throughout. A checkpoint is written every 30 s.
- Pay for change. With an existing index, a light query fetches metadata only (100 per page, no blobs). Repositories whose
pushedAt is unchanged keep their facts and only refresh stars and similar metadata; changed ones fetch package.json and the patch by node id in batches of 50.
- npm in parallel. npm lookups run alongside the GitHub crawl (8 workers), only for repositories with new pushes, missing entries, or entries older than one day. Entries older than 7 days are refreshed oldest first, at most 800 per run.
- Activation does not wait for the index. The ~30 MB index loads in the background; the UI first sees
loaded: false and polls.
Measured on 2026-10-14 over a real network:
| Scenario | First results | Total | Notes |
|---|
| Incremental, 1,082 repos pushed | 4.5 s | 38 s | 125 refetched blobs, 963 metadata-only, 70 npm lookups |
| Cold full crawl | 6.7 s | — | ~1,000 plugins browsable within 60 s; the rest fill in the background |
Checks and trust score
| Check | Rule | Points |
|---|
| V1 | Root package.json declares dsh.bundle / dsh.client (otherwise not a plugin) | 20 |
| V2 | Official peer rule: only @deepseek-ai/dsh and @deepseek-ai/dsh-*, semver.satisfies(runtime, range, {includePrerelease}), workspace:* means the running version. Inside the App, Scout calls dsh-app-boot.evaluatePluginCompatibility directly | covered 30 · no peers 10 · not covered 5 |
| V3 | Install hooks: preinstall / install / postinstall / prepare | none +15 · present −15 |
| V4 | Source chain: the same-name npm package's repository points back to this repo | match +15 · mismatch −20 · unpublished 0 |
| V5 | npm provenance | +10 |
| V6 | Activity: archived, pushed within 90 days, version drift (V6b) | +5 / −10 |
| V9 | Uses the @deepseek-ai/ scope but the repo is not owned by deepseek-ai | −30 |
| V10 | Fork | note only |
| — | Stars: min(5, round(log10(1+s)·2)) | ≤5 |
The total is clamped to 0–100. Any ✕ marks the plugin as risky: copying its spec or installing it takes two clicks, and its badge shows ✕. Repositories sharing a package name collapse under one representative, chosen by: matching source chain > score > stars > earliest creation. The rest are listed as copies, hidden by default.
Ten purpose categories: UI, session, memory, agent, tools, models, security, development, bridges, domain. A category is scored from the official packages a plugin depends on (highest weight), topics/keywords (3), and text (2); a plugin is categorized only with a score of at least 2. On 41 hand-labelled plugins, the top-1 category is correct for at least 35.
UI and integration points
- Discover page: sidebar 发现插件 →
main panel with search, filters (compatibility, risk, kind, installed state, copies), category chips, sorting and paging.
- Details drawer: checklist, score breakdown, category evidence, source chain and copies, surface (cordis inserts,
client.inject, peers), and the official pre-install check. Footer:
- Install / Enable / Cancel install, as described above.
- Copy pinned spec: copies
name@npmVersion, or github:owner/repo when unpublished.
- Open in Plugins page / Add on Plugins page: installed plugins open their official details via
pluginNavigation.openBundle; others switch to the official Plugins page.
- Official Plugins page:
plugins.detail.badge (trust score) and plugins.detail.section (checklist plus a link back to Scout). Packages missing from the index render null, taking no space.
Development
npm install --ignore-scripts
npm test # builds lib/, then runs the core / host / client / manifest suites
Local debugging: add this directory's absolute path on the Plugins page (a link install; do not move the directory). Host changes need a full App restart; client-only changes need a window reload.
GitHub token, in order: DSH_SCOUT_GITHUB_TOKEN / GITHUB_TOKEN / GH_TOKEN, or gh auth token run through the DSH subprocess service. The token stays in process memory: never written to disk, never sent to the browser. Without one, the page asks you to run gh auth login.
Data and configuration
- Index:
~/.dsh/dsh-plugin-scout/index.json stores facts only (repo metadata, slimmed manifests, npm cache) and is re-judged against the current runtime on every load, so compatibility verdicts follow DSH upgrades automatically.
- Auto refresh: an in-process timer checks 45 s after start and runs an incremental crawl when the index is older than
autoRefreshHours (default 24; 0 disables). No LaunchAgent or external scheduler.
- Optional config:
dataDir, topic, runtimeVersion (overrides runtime detection), autoRefreshHours.
Security boundaries
- Routes live on DSH's own webServer (
/dsh-plugin-scout/api/*). Every request must carry the custom header x-dsh-plugin-scout: 1 and pass DSH connection.admit (Host/Origin fence plus browser auth). Without the connection service, requests are refused (fail closed).
cordis.patch.yml is scanned for name: with a regex; YAML tags are never parsed. Crawled code is never executed and tarballs are never downloaded.- Style tags carry
data-plugin / data-plugin-css before entering the DOM. Only --dsw-alias-* tokens are used; class names avoid substrings that host skins target; the drawer does not use role="dialog".
Layout
src/core/: classify.mjs (categories), verify.mjs (checks and score), crawl.mjs (GraphQL, windows, npm), store.mjs (fact index, queries).src/host.mjs: runtime and token detection, refresh state machine, same-origin routes, in-process timer.src/client/: Discover page, drawer, installer, official-page badge/section, styles.scripts/build.mjs: esbuild bundling; both artifacts are executed after writing, as the gate.test/: core (real GraphQL page, 41 labelled samples), host (fake-fetch end-to-end refresh, route auth), client (Happy DOM loading the built artifact), manifest (official packaging conventions).
After a DSH upgrade, re-check the official Plugins page slot names, the pluginManager methods, and the dsh-app-boot exports before re-accepting.
Official conventions followed
Based on the official repository's docs/user/develop/basic/publish, docs/cookbook/adding-a-package §5, and the @deepseek-ai/dsh-package-manifest types; test/manifest.test.mjs asserts each one.
| Convention | This package |
|---|
Bundle: dsh.bundle.patch; patch rows reference the package by name | ./cordis.patch.yml → name: 'dsh-plugin-scout' |
Only public author fields under dsh | manifestVersion: 1, bundle, client (platform: web) |
Display metadata: locale/en.json is the entry, other languages use the same fields; export ./locale/*.json and ./package.json, and ship them | meta.title / meta.description in en.json and zh.json |
| Icon: relative path inside the package, ≤256 KiB, self-contained | ./icon.svg |
Packages sharing host instances are peers; the version gate reads only @deepseek-ai/dsh* peers | @deepseek-ai/cordis ~4.0.4; @deepseek-ai/dsh-app-boot >=0.2.0-rc.2 <0.3.0 (optional, declares the range for the official gate) |
engines.dsh is declarative | >=0.2.0-rc.2 <0.3.0 |
| Ship prebuilt artifacts; never ask users to approve builds | Published to npm with --provenance; no prepare or other install hooks |
Releasing
- Prepare the intended
version in package.json and commit the release changes to main.
- Manually dispatch
publish.yml from main with expected_sha set to the full approved commit SHA. Keep dry_run: true (the default) for validation first: the workflow checks the SHA, installs dependencies without lifecycle scripts, runs tests (including the build), and previews the package with npm pack --dry-run --ignore-scripts. A dry run does not publish. For an approved release, dispatch the same SHA with dry_run: false to run npm publish --access public --provenance --ignore-scripts.
- npm authenticates through Trusted Publishing (OIDC), so no npm token is stored in the repository; provenance is attached automatically. Configure npmjs.com → package Settings → Trusted Publisher for this GitHub repository and workflow
publish.yml, or use npx npm@latest trust github dsh-plugin-scout --file publish.yml --repo fegnze/dsh-plugin-scout.
- Separately,
git tag v<version> && git push origin v<version> triggers release.yml. It checks that the tag matches the package version and creates a GitHub Release with generated notes only; it neither publishes to npm nor builds or attaches a tgz. Supply a prebuilt archive separately if offering tarball installation.
- Keep the repository public with the
dsh-plugin topic so it appears on https://github.com/topics/dsh-plugin and in Scout itself.
