@Noob-stupid/dsh-plugin-gating-hub

_{Web & Desktop — both supported.}

English: README.md | 中文: README.zh.md

DSH Plugin Gating Hub (dsh-plugin-gating-hub)

Renamed from dsh-plugin-hub — old URLs redirect.

Framework-upgrade safety and plugin-version gating for DSH. A failed upgrade rolls back.
A framework changed by any update channel is still guarded. A version the host cannot
take is refused, not installed.

Install (npm, one line)

dsh plugin --profile web add @noob-stupid/dsh-plugin-console

Then restart the dsh service → refresh the page → Settings → Plugins → Plugin Console.

Three hard guarantees

• 🛡️ Contract pre-check → rollback point → auto-rollback. A data-driven contract pre-check
  runs first (message contract / dependency API / config schema / removed API / loader contract);
  then config backup + a full-tree rollback point. A failed install or relaunch auto-rolls
  the tree back, a 「roll back to previous」 button restores the last version, and plugins the
  new framework cannot load are auto-disabled — version check catches fake success, 15-min
  timeout + stall detection.
• 👁️ Even when another update channel changes the framework. An environment fingerprint
  catches changes made by the official desktop updater or a manual pnpm: it auto-runs a
  read-only pre-flight, and disables a row only with hard evidence (package unresolvable /
  file:// target gone / named in a boot-failure log). @deepseek-ai/* and protected / core
  rows are never auto-disabled; each auto-disable writes a one-command recovery record.
• 🔒 Plugin install & upgrade gating. Version/declaration gate (dsh.engines.framework /
  engines.dsh / @deepseek-ai/* ranges, built-in zero-dependency semver), a repo-size gate
  on source channels, and explicit handling of non-registry sources — a bare version is
  written back only once the registry really resolves it, otherwise the package is materialized
  as link:. Install scripts are never auto-authorized, and pnpm's supply-chain gate is never
  bypassed.

Discovery layer on top: a built-in multi-source plugin market & index (500+ plugins /
300+ skills, zero GitHub API calls) — and every source is swappable: install source
(incl. a private intranet registry), search source (URL template + headers), index source
(self-hosted intranet index), Git source (incl. a local file:// bare repo), so plugins can be
installed on an intranet-only or fully offline machine.

Why DSH Plugin Gating Hub

• 🛡️ Framework upgrade safety, end-to-end — one-click upgrade: config backup + full-tree
  checkpoint (rollback point) → online install (service stays up, page never disconnects) →
  version verification → auto-restart. A failed install auto-rolls the whole tree back,
  version check catches fake success, 15-min hard timeout + stall detection — the framework is
  never left broken. → details
• ↩️ One-click rollback to the previous version — after an upgrade the framework card keeps
  a 「roll back to previous」 button: stop service → restore full tree → relaunch → health check,
  state visible throughout.
• 🚫 Incompatible plugins auto-disabled — the adapt gate force-disables plugins the new
  framework cannot load (enable locked; the server rejects /toggle with 409 — unbypassable);
  「Check update → Update & adapt」auto-verifies and unlocks them.
• 🔒 Plugin upgrade gating — a version/declaration gate (dsh.engines.framework /
  engines.dsh + @deepseek-ai/* ranges, built-in zero-dependency semver engine) decides
  whether a plugin version may run on this host, so an upgrade can't silently take plugins out.
• 🧩 Built-in discovery layer — multi-source plugin market (GitHub / Gitee / custom sources)
  plus the static index of dsh-plugin repos (500+ by stars) and a Skills tab (up to 300);
  browse, search, one-click install, zero GitHub API calls (served via CDN).
  Every source is swappable — private intranet npm registry, custom search source (URL template +
  headers), self-hosted index source, Git source (incl. local file:// bare repo) — so an
  intranet-only / offline machine can still browse and install.
• 🤖 AI Empower — give the console a package name or GitHub repo, the local AI
  reads its docs and drafts a safe, confirmable deployment plan (install / config /
  start / health-check); server components get an automatic control card.
  → details

Install

# npm release (recommended: prebuilt, no git / build authorization needed)
dsh plugin --profile web add @noob-stupid/dsh-plugin-console

# or install from GitHub source (needs git; allowBuilds authorization on first add)
dsh plugin --profile web add github:Noob-stupid/dsh-plugin-gating-hub

Then restart the dsh service → refresh the page → Settings → Plugins → Plugin Console.

git clone https://github.com/Noob-stupid/dsh-plugin-gating-hub "$env:TEMP\dsh-plugin-console" 2>$null; & "$env:TEMP\dsh-plugin-console\deploy.ps1"

git clone https://github.com/Noob-stupid/dsh-plugin-gating-hub /tmp/dsh-plugin-console 2>/dev/null; bash /tmp/dsh-plugin-console/deploy.sh

Highlights

Usage

1. Restart DSH → open the Web GUI → Settings → Plugins → Plugin Console.
2. Installed list: toggle plugins on/off (HMR applies within ~1s), search by name/id,
   expand details (version, repository, README summary).
3. 市场: empty query on the GitHub source opens the static index (instant);
   type a query to search live. Switch sources via the login pill (GitHub / Gitee / custom);
   ⊞ merges all sources; ★ filters to dsh plugin add-installable packages.
4. Skills tab: switch 插件/技能 next to the search box to browse and install skills
   (cloned into ~/.dsh/skills/<name>/).
5. Install: click 添加到本地 → the chain runs in the background (safe to leave the page);
   「检测更新」/「更新 → vX」 appear automatically for installed entries.

Screenshots · 界面一览

入口挂在官方插件管理页自己的插槽（plugins.bundle.config，key = 包名）：装完之后它出现在
「设置 → 插件 → 已安装」里我们这一条下面，用的是官方容器与官方风格 —— 不是 DOM 注入，官方更新也不怕。

1 · 已安装列表里的入口（官方页，点开我们这条即见）

2 · 「升级安全」面板（就地展开：运行模式 / 框架版本 / 回滚点 / 环境指纹 / 补声明 / 契约预检 / 各功能入口）

3 · 框架升级 / 回滚（可选目标版本、常驻的升级进度、一键回滚上一版）

4 · 门控明细（谁被隔离、为什么：升级预扫 or 启动失败隔离，附来源与时间）

Features

Installed plugins (one-click toggle + details)

• Shows only third-party plugins by default (extra/non-bundled), tagged
  "Third-party" with a delete entry; click "All" to see the full list (1.5s flash feedback);
• Lists every plugin entry (name, load state, enabled state); search by name/id;
• Disable = append - id: X + disabled: true to the user patch layer, effective via HMR;
• Enable = remove that entry; bundle-layer rows disabled by default are overridden with
  disabled: false;
• Tags "Patch-disabled / Patch-forced" distinguish user patch state;
• Infrastructure protection: host transport/hmr/storage/settings chain plugins
  (70+ rows) are marked "Protected" and cannot be toggled — disabling them would break HMR;
• Details panel: version, repository/homepage links and a README summary for each plugin;
• Version check: 检测更新 reads npm dist-tags.latest (curl channel, works even when
  node networking is blocked) and warns about subpackages that need syncing (depsOutdated).

Framework one-click upgrade (deepseek-harness card)

• The deepseek-harness card shows 「框架升级 → vX」 when a newer framework version is
  available (stable latest preferred; next channel when latest equals the installed
  version); clicking runs the full flow: backup config + framework snapshot (rollback point)
  → online install (service stays up, page never disconnects) → version verification →
  auto-restart to apply;
• Real-time progress: a DSH-Upgrade console window pops up showing live pnpm download
  progress; the in-panel progress card shows the waiting time;
• Upgrade protection: failed installs auto-rollback (robocopy, backup verified before
  upgrade), version check catches fake success, 15-min hard timeout, stall detection
  (no debug-log updates → auto switch registry), global trap fallback, and 15-min stale-state
  cleanup — the framework is never left broken;
• pnpm channel: npm-cli.js freezes at startup in the schtasks task environment (0-byte
  debug log, no network requests ever sent); upgrades use corepack pnpm (starts in ~0.4s,
  installed rc.8 in 11.5s) against the npmmirror (China) registry, with
  dangerouslyAllowAllBuilds so native modules (node-pty/koffi) compile;
• Runtime bin resolution: under the pnpm layout @deepseek-ai/dsh is a Junction — the
  relaunch step resolves bin.js at runtime (follows the Junction to the current version)
  instead of using a path baked in at script-generation time;
• Card dismiss semantics: terminal states (done/failed) are permanently dismissed on ✕
  (persisted); in-progress dismissal is session-only and the card returns after a refresh.

Marketplace (multi-source)

• Source switcher: click the login pill to switch between GitHub / Gitee / custom
  sources (persisted); title, loading text, placeholder and note all follow the source;
• GitHub: default query dsh-plugin, browser-direct with server fallback;
• Gitee: official search API is retired, so it uses direct-repo mode — enter
  owner/repo (Chinese paths and full URLs supported) to find and install a repository;
• Custom sources: add in Source Manager (URL template with {q}/{page} placeholders),
  optional header auth (e.g. Authorization: Bearer ...), and local/private http URLs;
• Multi-source summary: the ⊞ toggle searches GitHub + all custom sources in parallel,
  merging results with source labels;
• ★ official filter: shows only packages installable via dsh plugin add — root packages
  with a dsh.bundle manifest (official) or aggregate repos whose subpackage carries
  dsh.bundle (subpackage-installable); markers are enriched by the server (curl dual-channel)
  with a client-side fallback;
• Type badges: 官方 / 聚合 / 技能 (repo contains SKILL.md) recognized automatically.

Network environment notes (why a multi-source setup can look "all dead")

• Accelerators/proxies that rewrite hosts kill the direct sources: tools like Steam++ often point
  github.com at 127.0.0.1, so the GitHub direct source, raw.githubusercontent.com and
  api.github.com all become unreachable — the plugin is not broken. The console now reports this
  honestly as "local proxy / certificate interception (…) — an accelerator or proxy was detected,
  turn it off and retry" instead of a vague "network unreachable".
• Free mirrors are unreliable for the git protocol on large packs, while archive/raw are usually
  fast: measured on the same ghproxy.net host, archive (plain HTTP) ran at 4 MB/s while the git
  protocol moved 0 B/s. Since this version the git channel has a stall criterion (switch source
  after 20 s below 1 B/s) plus its own budget, and falls back to the archive channel (download the
  tarball, extract, create the repo — equivalent to a clone) when all git sources fail. No manual
  source switching needed.
• To reorder transports, use Source Manager: git sources, archive sources and index
  sources all support primary→backup plus self-hosted mirrors (internal Gitea/GitLab, local
  file:// bare repos).

Download-install channels and dependency forms

Which channel gets used depends on what the package actually is — not on a setting:

In one sentence: has an npm package → ①/②, write a version, keep the lock clean; no npm package →
fall back to ③/④/⑤, materialize into ~/.dsh/plugin-src/<pkg> and write link:.

Environment reminder: an accelerator/proxy that rewrites hosts makes the direct sources unreachable
(see above), and free mirrors are unreliable for the git protocol on large packs while
archive/raw are usually much faster — the console already switches by itself.

Development installs (link:)

Ordinary installs go through the package manager (pnpm add); that is the baseline, not a feature here.

link: is the separate, explicit route: mount a local directory / plugin you are developing
directly into the profile.

• Source edits take effect immediately: node_modules/<name> in the profile is a link to your
  local directory, not a copy — edit the source, refresh the page. No reinstall, no repackaging.
• Who it is for: plugin authors, or anyone who wants to edit a plugin's source. If you just want
  to use a plugin, an ordinary install is simpler.
• What it pins: the local artifact is written into the profile manifest dependencies
  (link:<absolute path>) and gets a matching entry in pnpm-lock.yaml — so lockfile health checks
  and rebuilds never treat it as an orphan, and it survives restarts and instance updates.
• What the console completes for it (otherwise the usual outcome is "installed, but it will not load"):
  • the target directory's own dependencies: one install run inside that directory, filling in
    what the local directory is missing;
  • the framework peer shim root: when the local directory lives outside the profile tree,
    Node's resolution chain never reaches the profile's node_modules. The console links the framework
    peers it declares and currently cannot resolve (@deepseek-ai/*) at the plugin root,
    pointing at ~/.dsh/profiles/node_modules/@deepseek-ai/<pkg>. It is a link, not a copy —
    both sides share the same realpath, so Cordis service classes and LLM error classes keep their
    module identity shared with the host.
• Boundaries (always reported honestly, never faked):
  • moving or deleting the local directory breaks the link (the manifest link: then points at a
    path that no longer exists);
  • shims only fill peers it declares and that are genuinely missing; a package the framework side
    does not have is never invented;
  • anything already present at the target path (including a dangling link) is never overwritten
    — it is skipped and reported;
  • uninstall removes the shims the console created (only its own; links you placed by hand are
    never touched);
  • if completion fails (target directory not writable, dependency install failed, …) the install
    still completes, and the result honestly says "not ready + what is missing" together with an
    action you can run.

Static index market (plugin & skill tabs)

Hybrid architecture: browsing uses the static index (instant, zero GitHub API calls),
searching uses live channels (GitHub search API / multi-source parallel) — they complement
each other: a brand-new repo can be found by live search even before it enters the index.

• Empty query on the GitHub source shows the static index (marketplace/index.json,
  jsDelivr CDN + 10-min host cache): 500+ plugins by stars, instant, zero GitHub API calls;
• 插件 / 技能 tabs next to the search box: the skills tab lists auto-collected
  agent-skills ∪ claude-skills ∪ dsh-skill repos (up to 300);
• Auto version check: installed entries in the market are checked against npm
  dist-tags.latest in the background — cards turn into 「更新 → vX」 buttons;
• Skill install: skill entries install by git-clone into ~/.dsh/skills/<name>/
  (frontmatter name wins over repo name; SKILL.md found at repo root or first-level
  subdirectory). Installed skills show a grey 「已装」 badge.

Source Manager

The floating "Sources" button (right of the title row, semi-transparent) opens the manager:

• Install sources (registry): add / inline edit / set primary / restore defaults;
  private and intranet addresses supported; deletion is protected (install-critical);
• Search sources: built-in GitHub, Gitee + custom search sources (add/remove, 🔒 shows
  header count);
• Gitee login (optional): direct mode needs no login; login only raises rate limits —
  create a third-party app (gitee.com → Data management → Third-party apps, scopes
  user_info, projects), fill client_id / client_secret, save, then authorize.

Run mode (managed / observer)

The mode decides who leads framework upgrades — nothing else:

• Observer (default): the console only preflights, gates, and guards the rollback point. It does not take over upgrades.
• Managed: framework upgrade and rollback are owned by this console. It switches to managed automatically when you upgrade through this console, and records the reason.
• Switches back to Observer automatically (0.5.32): when the desktop-host shape is detected (the existing detectHostShape() criteria), a mode that was not set by hand (compat-mode.json source is auto:*; a missing field counts as manual) is switched back to Observer on startup / first status query, with a one-line notice. Once you switch it by hand it is never changed automatically again; when it is already Observer nothing is written.

Boot-failure quarantine is not affected by the mode. When the service cannot start, the console locates the culprit from the boot log and disables it (broken presets are renamed to .broken-*; with no clear culprit it falls back to safe mode so the service can start). A console that cannot boot cannot gate anything — so this rescue path always runs.

Auto-disable on confirmed evidence (0.5.32): when the fingerprint-triggered auto-preflight, or a
boot-failure record, provides confirmed evidence (the row's package resolves on none of the
resolution bases, a file:// target truly does not exist, or the boot log names the row), the console
writes disabled: true for those rows itself (no click needed). Safety rails: only rows with
evidence; @deepseek-ai/* (framework-owned) and protected/core rows are never auto-disabled;
a safe-boot snapshot is written first, so any auto-disable is one command away from a rollback;
when there is nothing to write, not a single byte is written; every auto-disable leaves a record in
dshHome()/plugin-console/auto-disable.log (time / row id / evidence / restore command).

Prefer "report only, let me click" (enabled by default) — replace <host:port> with your instance
(the default dsh web profile listens on 127.0.0.1:3080):

curl -X POST http://<host:port>/plugin-console/compat-ack \
  -H 'Content-Type: application/json' -d '{"autoDisableOnEvidence":false}'

How to roll an auto-disable back: the route POST /plugin-console/safe-boot with
{"action":"restore-last-good"} (the current state is backed up first), or — when the service will not
start — from the plugin directory:

node scripts/safe-boot.mjs --list                 # see which snapshots exist
node scripts/safe-boot.mjs --restore-last-good    # restore the newest good snapshot byte-for-byte
node scripts/safe-boot.mjs --disable-suspects     # or: append disabled: true to named rows only (nothing deleted)
node scripts/safe-boot.mjs --mark-good            # mark a snapshot as good (never removed by retention)

Safe-boot snapshots live under dshHome()/plugin-console/safe-boot/ (not in the profile directory),
keeping the newest 3 plus the one you marked as good.

When the service won't start because framework packages were wiped

The rollback above restores the config layer (cordis.patch.yml). There is a second failure
class where the package payloads are gone — framework packages emptied or deleted. Then the
patch is perfectly fine, restoring it changes nothing, and the console itself runs inside dsh:
if dsh cannot boot, the console was never loaded (real outage, 2026-10-14: cordis's store entity
emptied plus dsh-llm/dsh-tools/dsh-web turned into empty directories ⇒
54 plugins failed to import ⇒ exit code=1).

That class needs the out-of-process closure preflight (also needs no running service):

node scripts/fw-preflight.mjs --check     # diagnose only: list unresolvable packages, write nothing
node scripts/fw-preflight.mjs --repair    # restore from the **local npm cache** by lock integrity, then re-verify

The criterion is "can the dependency closure be resolved", not "is the directory empty" —
the latter is completely blind to "the shell is still there, the inside was emptied"
(measured: a naive empty-dir scan reported 237 false positives; the closure criterion passed all
287 packages and named exactly the one that broke). --repair is offline and never guesses a
version (a package missing from the lock is reported as no-lock-entry), and it never kills or
spawns a process and never grabs a port (that is exactly what produces
"The application failed to start or stopped unexpectedly") — restart the service yourself afterwards.

Framework compatibility

Measured on isolated instances (fresh DSH_HOME, real HTTP probes) — supported: framework ≥ 0.1.5-rc.2, no workarounds needed.

So on an older framework the plugin is the old UI with the full feature set — the new entry simply has nowhere to live. It never white-screens and never throws.

Verification matrix, raw logs and the one framework-side caveat (0.1.2-rc.1 ships patchReload: "live" for a web tree without the HMR service → boot exits 1 after ~10s; unrelated to this plugin) are recorded in .testdir/fw-old-matrix/report.md.

Documentation

• AI Empower 与服务器组件控制
• Framework upgrade safety & plugin adapt gate
• 契约规则库 Upgrade contract rules — 框架每次变更会打断什么、怎么发现、怎么修（数据在 lib/contracts/rules.json，欢迎 PR 补充：每个事故都应该变成一条规则）
• How it works · Compatibility · Project layout
• HTTP endpoints · Local AI fallback & consent
• Framework patch (cordis.patch.yml) · Security & disclaimer

Known limitations

• Host code changes require a service restart: the panel's restart button only points at the
  official path (restart inside the desktop client; the console never kills or spawns a
  process — a manual relaunch would fight the host for the port and produce
  "The application could not start or stopped unexpectedly"); client changes just need a page refresh;
• Live GitHub search depends on GitHub reachability (browser-direct + server fallback;
  during network-blackout windows retry later);
• Version detection works for npm-published packages; skill-type repos have no version concept;
• The static index is capped (500 plugins / 300 skills per build); authors bump their star
  count or wait for the 6h CI cycle to enter the index;
• Skills are discovered by dsh-skill-filesystem — if the current profile does not enable
  that plugin, installed skills stay dormant until it is enabled and DSH restarted.

Help & Ecosystem

• Panel missing: restart dsh → refresh → Settings → Plugins → Plugin Console.
• Toggle does nothing: infrastructure rows are "Protected" (by design); normal toggles
  take effect via HMR within 1-3s.
• Compatibility warning: a breaking upstream release arrived; see Compatibility.
• Search empty/fails: GitHub uses browser-direct (falls back to the server channel);
  Gitee is direct-repo mode (enter owner/repo); check custom-source URL/headers; retry
  during network blackout windows.
• ★ filter empty: ★ shows only dsh plugin add-installable packages (official +
  subpackage-bundle aggregates); markers are backfilled in 1-3s — no false "none" report.
• Install fails: confirm the repo has package.json and the package is published; npm
  failures fall back to git install; switch the primary source if npmmirror is unstable.
• Skill not found by DSH: enable @deepseek-ai/dsh-skill-filesystem in the profile
  (cordis.yml) and restart; skills live in ~/.dsh/skills/<name>/.

Ecosystem & discoverability

• Listed on awesome-dsh-plugin (the community main list) and DSH Directory;
• This hub's own auto-collection index (500+ plugins / 300 skills, refreshed by CI every 6h) includes any repo tagged dsh-plugin / agent-skills / claude-skills / dsh-skill — tag your repo and it appears in the market automatically, no application needed;
• If you build DSH plugins, this panel is your distribution channel: one-click install for every user of the hub.

Support

If this panel saves you time or makes DSH more fun to use:

• ⭐ Star this repo — it directly helps more DSH users find it;
• Share it with DSH users or in DSH communities;
• Submit your own plugin (tag it dsh-plugin) to grow the ecosystem;
• Found a bug or want a feature? Open an issue.

Contributing

Contributions of all kinds are welcome — issues, PRs, docs, translations.

• Guidelines: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md (report vulnerabilities privately)
• Issue templates: bug reports & feature requests via the new issue page

Changelog

See CHANGELOG.md.

License

MIT

Preview (experimental · not for production)

The layered-refactor preview lives in its own repository: Noob-stupid/dsh-plugin-hub-refactor

• What it is: the monolithic lib/index.js (8547 lines) split into layers — lib/index.js 141 lines + lib/server/** 38 modules; feature-equivalent to 0.3.57, maintainability only;
• Verified: 19 test suites green · 8 architecture-guard assertions · route inventory identical (status + response fields) against the stable build;
• Not yet exercised: real framework upgrade / rollback, restart guardian, component start/stop, real AI run, Gitee OAuth (~10–25% long-tail risk, subjective);
• For everyday use stick to the latest npm release of @noob-stupid/dsh-plugin-console (npm view @noob-stupid/dsh-plugin-console version), or main of this repo.