Skip to content
Back to search

dsh-plugin-gating-hub

DSH plugin - framework upgrade safety & plugin gating: contract pre-check, rollback point, auto-rollback on failure, evidence-based auto-disable; plus a multi-source plugin market. Unofficial. | DSH 插件:框架升级安全 + 插件门控——升级前契约预检、回滚点、失败自动回滚、有确证证据才自动禁用;另带多源插件市场。非官方社区项目。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Noob-stupid/dsh-plugin-gating-hub with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Noob-stupid/dsh-plugin-gating-hub'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/noob-stupid--dsh-plugin-gating-hub/badge.svg)](/listings/noob-stupid--dsh-plugin-gating-hub)

HTML

<a href="/listings/noob-stupid--dsh-plugin-gating-hub"><img src="/api/listings/noob-stupid--dsh-plugin-gating-hub/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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**.

<details><summary><b>More install options</b> (deploy script / hand it to an AI)</summary>

Option 2: deploy script (fallback when network is restricted)

Windows (PowerShell):

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"

Linux / macOS:

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

The script copies the plugin into `$DSH_HOME/profiles/<profile>/node_modules/` and idempotently appends an enable entry to `cordis.patch.yml`. Afterwards:

1. Restart the dsh service (host code changes need a process restart; CLI restarts the process, the desktop client exits and reopens); 2. Refresh the page → Settings → Plugins → **Plugin Console**.

Option 3: hand it to an AI in one sentence

> Install the DSH plugin hub (dsh-plugin-hub): run `dsh plugin --profile web add @noob-stupid/dsh-plugin-console` (npm release); if there is no dsh CLI, clone https://github.com/Noob-stupid/dsh-plugin-gating-hub to `~/.dsh/profiles/web/node_modules/` and register it in `cordis.patch.yml` (id: plugin-console, name: @noob-stupid/dsh-plugin-console). Restart dsh web afterwards.

Requires: DSH ≥ 0.1.0-rc.6 (web profile, with `dsh-client-modules` / `dsh-host-plugin-inventory`).

</details>

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 678 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <sub><b>Web</b> &amp; <b>Desktop</b> — both supported.</sub>
  2. > **English**: [README.md](README.md) | **中文**: [README.zh.md](README.zh.md)
  3. ---
  4. # DSH Plugin Gating Hub (dsh-plugin-gating-hub)
  5. *Renamed from `dsh-plugin-hub` — old URLs redirect.*
  6. **Framework-upgrade safety and plugin-version gating for DSH.** A failed upgrade rolls back.
  7. A framework changed by **any** update channel is still guarded. A version the host cannot
  8. take is refused, not installed.
  9. [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
  10. [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
  11. [![GitHub stars](https://img.shields.io/github/stars/Noob-stupid/dsh-plugin-gating-hub?style=flat-square&logo=github)](https://github.com/Noob-stupid/dsh-plugin-gating-hub/stargazers)
  12. [![License](https://img.shields.io/github/license/Noob-stupid/dsh-plugin-gating-hub?style=flat-square)](LICENSE)
  13. [![Last commit](https://img.shields.io/github/last-commit/Noob-stupid/dsh-plugin-gating-hub?style=flat-square)](https://github.com/Noob-stupid/dsh-plugin-gating-hub/commits/main)
  14. [![Registry CI](https://img.shields.io/github/actions/workflow/status/Noob-stupid/dsh-plugin-gating-hub/registry.yml?label=registry%20CI&style=flat-square)](https://github.com/Noob-stupid/dsh-plugin-gating-hub/actions/workflows/registry.yml)
  15. [![topic: dsh-plugin](https://img.shields.io/badge/topic-dsh_plugin-4D6BFE?style=flat-square)](https://github.com/topics/dsh-plugin)
  16. [![npm version](https://img.shields.io/npm/v/@noob-stupid/dsh-plugin-console?style=flat-square)](https://www.npmjs.com/package/@noob-stupid/dsh-plugin-console)
  17. [![npm downloads](https://img.shields.io/npm/dw/@noob-stupid/dsh-plugin-console?label=npm%20downloads%20week&style=flat-square)](https://www.npmjs.com/package/@noob-stupid/dsh-plugin-console) [![npm downloads total](https://img.shields.io/npm/dt/@noob-stupid/dsh-plugin-console?label=npm%20downloads%20total&style=flat-square)](https://www.npmjs.com/package/@noob-stupid/dsh-plugin-console)
  18. [![GitHub Release](https://img.shields.io/github/v/release/Noob-stupid/dsh-plugin-gating-hub?style=flat-square)](https://github.com/Noob-stupid/dsh-plugin-gating-hub/releases)[![dsh.so security](https://www.dsh.so/badge/dsh-plugin-hub.svg)](https://www.dsh.so/artifact/dsh-plugin-hub)
  19. [![dsh.so install · dsh 0.2.0-rc.1](https://www.dsh.so/badge/install/dsh-plugin-hub@0.2.0-rc.1.svg)](https://www.dsh.so/artifact/dsh-plugin-hub/)
  20. **Install (npm, one line)**
  21. ```sh
  22. dsh plugin --profile web add @noob-stupid/dsh-plugin-console
  23. ```
  24. Then restart the dsh service → refresh the page → **Settings → Plugins → Plugin Console**.
  25. ![Upgrade safety panel, expanded in place](docs/images/upgrade-safety-panel.png)
  26. **Three hard guarantees**
  27. - 🛡️ **Contract pre-check → rollback point → auto-rollback.** A data-driven **contract pre-check**
  28. runs first (message contract / dependency API / config schema / removed API / loader contract);
  29. then config backup + a full-tree **rollback point**. A failed install or relaunch **auto-rolls
  30. the tree back**, a 「roll back to previous」 button restores the last version, and plugins the
  31. new framework cannot load are **auto-disabled** — version check catches fake success, 15-min
  32. timeout + stall detection.
  33. - 👁️ **Even when another update channel changes the framework.** An **environment fingerprint**
  34. catches changes made by the official desktop updater or a manual `pnpm`: it auto-runs a
  35. **read-only pre-flight**, and disables a row **only with hard evidence** (package unresolvable /
  36. `file://` target gone / named in a boot-failure log). `@deepseek-ai/*` and **protected / core
  37. rows are never auto-disabled**; each auto-disable writes a one-command recovery record.
  38. - 🔒 **Plugin install & upgrade gating.** Version/declaration gate (`dsh.engines.framework` /
  39. `engines.dsh` / `@deepseek-ai/*` ranges, built-in zero-dependency semver), a **repo-size gate**
  40. on source channels, and explicit handling of **non-registry sources** — a bare version is
  41. written back only once the registry really resolves it, otherwise the package is materialized
  42. as `link:`. Install scripts are never auto-authorized, and pnpm's supply-chain gate is never
  43. bypassed.
  44. <img width="1170" height="609" alt="DSH Plugin Gating Hub" src="https://github.com/user-attachments/assets/b802d606-14ba-4151-9956-ff642ed12b0a" />
  45. > **Discovery layer on top**: a **built-in multi-source plugin market & index** (500+ plugins /
  46. > 300+ skills, zero GitHub API calls) — and **every source is swappable**: install source
  47. > (incl. a private intranet registry), search source (URL template + headers), index source
  48. > (self-hosted intranet index), Git source (incl. a local `file://` bare repo), so plugins can be
  49. > installed on an **intranet-only or fully offline** machine.
  50. ## Why DSH Plugin Gating Hub
  51. - 🛡️ **Framework upgrade safety, end-to-end** — one-click upgrade: config backup + full-tree
  52. checkpoint (rollback point) → online install (service stays up, page never disconnects) →
  53. version verification → auto-restart. A failed install **auto-rolls the whole tree back**,
  54. version check catches fake success, 15-min hard timeout + stall detection — the framework is
  55. never left broken. → [details](docs/upgrade-safety-adapt-gate.md)
  56. - ↩️ **One-click rollback to the previous version** — after an upgrade the framework card keeps
  57. a 「roll back to previous」 button: stop service → restore full tree → relaunch → health check,
  58. state visible throughout.
  59. - 🚫 **Incompatible plugins auto-disabled** — the **adapt gate** force-disables plugins the new
  60. framework cannot load (enable locked; the server rejects `/toggle` with 409 — unbypassable);
  61. 「Check update → Update & adapt」auto-verifies and unlocks them.
  62. - 🔒 **Plugin upgrade gating** — a version/declaration gate (`dsh.engines.framework` /
  63. `engines.dsh` + `@deepseek-ai/*` ranges, built-in zero-dependency semver engine) decides
  64. whether a plugin version may run on this host, so an upgrade can't silently take plugins out.
  65. - 🧩 **Built-in discovery layer** — multi-source plugin market (GitHub / Gitee / custom sources)
  66. plus the static index of `dsh-plugin` repos (500+ by stars) and a Skills tab (up to 300);
  67. browse, search, one-click install, **zero GitHub API calls** (served via CDN).
  68. **Every source is swappable** — private intranet npm registry, custom search source (URL template +
  69. headers), self-hosted index source, Git source (incl. local `file://` bare repo) — so an
  70. **intranet-only / offline** machine can still browse and install.
  71. - 🤖 **AI Empower** — give the console a package name or GitHub repo, the local AI
  72. reads its docs and drafts a safe, confirmable deployment plan (install / config /
  73. start / health-check); server components get an automatic control card.
  74. → [details](docs/ai-empower.md)
  75. ## Install
  76. ```sh
  77. # npm release (recommended: prebuilt, no git / build authorization needed)
  78. dsh plugin --profile web add @noob-stupid/dsh-plugin-console
  79. # or install from GitHub source (needs git; allowBuilds authorization on first add)
  80. dsh plugin --profile web add github:Noob-stupid/dsh-plugin-gating-hub
  81. ```
  82. Then restart the dsh service → refresh the page → **Settings → Plugins → Plugin Console**.
  83. <details><summary><b>More install options</b> (deploy script / hand it to an AI)</summary>
  84. ### Option 2: deploy script (fallback when network is restricted)
  85. Windows (PowerShell):
  86. ```powershell
  87. 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"
  88. ```
  89. Linux / macOS:
  90. ```bash
  91. 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
  92. ```
  93. The script copies the plugin into `$DSH_HOME/profiles/<profile>/node_modules/` and
  94. idempotently appends an enable entry to `cordis.patch.yml`. Afterwards:
  95. 1. Restart the dsh service (host code changes need a process restart; CLI restarts the
  96. process, the desktop client exits and reopens);
  97. 2. Refresh the page → Settings → Plugins → **Plugin Console**.
  98. ### Option 3: hand it to an AI in one sentence
  99. > Install the DSH plugin hub (dsh-plugin-hub): run `dsh plugin --profile web add @noob-stupid/dsh-plugin-console` (npm release); if there is no dsh CLI, clone https://github.com/Noob-stupid/dsh-plugin-gating-hub to `~/.dsh/profiles/web/node_modules/` and register it in `cordis.patch.yml` (id: plugin-console, name: @noob-stupid/dsh-plugin-console). Restart dsh web afterwards.
  100. Requires: DSH ≥ 0.1.0-rc.6 (web profile, with `dsh-client-modules` / `dsh-host-plugin-inventory`).
  101. </details>
  102. ---
  103. ## Highlights
  104. | | Benefit | Detail |
  105. |---|---|---|
  106. | 🤖 | **AI Empower ** | Give the console a package name or GitHub repo — the local AI reads docs, drafts a **deployment plan** (install / write config / start service / health check) and executes it safely after your confirmation; server-type components get an automatic control card |
  107. | 🛡️ | **Framework upgrade safety & adapt gate ** | Force-disables plugins incompatible with the new framework (enable locked; 「Check update → Update & adapt」auto-verifies and unlocks); full-tree checkpoint before upgrade, automatic rollback on relaunch failure, one-click rollback to the previous version |
  108. | 🏠 | **Family-bundle cards & safety ** | Same-root subpath exports group into one family card (collapse/expand, batch check-update, one-click unlock-adapted, known-check preview); never-crash safety (pre-enable import probe + patch auto-heal + exports fallback); adapt-gate source-scan hard criterion & migrate detection; deleting a bundle sub-row disables only that row |
  109. | 🚀 | **Server component cards** | Left-side floating card auto-aligned to the main panel: start / stop / status / **open Web UI** buttons, multi-server dropdown, collapsible |
  110. | 🧩 | **Plugin & skill hub** | Auto-collected index of `dsh-plugin` topic repos (**500+** by stars) plus a **Skills tab** (`agent-skills` ∪ `claude-skills` ∪ `dsh-skill`, up to 300) — browse, search, one-click install, no GitHub API calls |
  111. | 🤖 | **Auto-collection CI** | GitHub Actions reruns `build-index` every 6 hours (manual trigger available); authors just add the `dsh-plugin` / `agent-skills` / `claude-skills` / `dsh-skill` topic — no application needed |
  112. | ⚡ | **Instant, rate-limit-free** | The index is served as a static `marketplace/index.json` via jsDelivr CDN (10-min host cache); terminal users make **zero GitHub API calls** |
  113. | 🔄 | **Version detection & one-click update** | Semver-based; installed entries match npm `dist-tags.latest` / `beta`; subpackage mismatch warnings prevent mixed-version breakage |
  114. | 🔀 | **Multi-source** | GitHub / Gitee (direct-repo mode) / custom search sources (URL template + header auth + private http); `⊞` merges GitHub + all custom sources in parallel |
  115. | 🔒 | **Safe by default** | Loopback-only routes; AI fallback behind an explicit cost-consent modal; infrastructure rows are toggle-protected |
  116. | 🧯 | **Runtime lag guard (observer)** | Trips runaway WebSocket retries and short-interval polling, records the owning package, and lists up to 10 incidents in the gate panel; the run-mode switch is the only enable |
  117. | 🧩 | **Version-change auto-block** | Any framework version change runs the same compat preflight as the upgrade path, disables `fail` rows, writes them to `pending`, and refreshes the gate list |
  118. | 📜 | **Session-preset contract check** | Daily read-only probe of the installed `dsh-agent-preset` version/entry hash plus declaration-row audit; cached for 24h, `force=1` to recheck |
  119. <details>
  120. <summary><b>📑 目录 / Table of Contents</b></summary>
  121. - [Highlights](#highlights)
  122. - [AI 赋能与服务器组件控制](#ai-赋能与服务器组件控制)
  123. - [One-click install](#one-click-install)
  124. - [Usage](#usage)
  125. - [Features](#features)
  126. - [Runtime lag guard](#runtime-lag-guard-observer-mode)
  127. - [Version-change auto-block](#version-change-auto-block)
  128. - [Session-preset contract](#session-preset-contract)
  129. - [How it works](#how-it-works)
  130. - [Compatibility](#compatibility)
  131. - [Project layout](#project-layout)
  132. - [HTTP endpoints](#http-endpoints)
  133. - [安全](#security)
  134. - [Known limitations](#known-limitations)
  135. - [Help & Ecosystem](#help--ecosystem)
  136. - [Contributing](#contributing)
  137. - [Changelog](#changelog)
  138. - [License](#license)
  139. </details>
  140. ---
  141. ## Usage
  142. 1. Restart DSH → open the Web GUI → **Settings → Plugins → Plugin Console**.
  143. 2. **Installed list**: toggle plugins on/off (HMR applies within ~1s), search by name/id,
  144. expand details (version, repository, README summary).
  145. 3. **市场**: empty query on the GitHub source opens the static index (instant);
  146. type a query to search live. Switch sources via the login pill (GitHub / Gitee / custom);
  147. `⊞` merges all sources; `★` filters to `dsh plugin add`-installable packages.
  148. 4. **Skills tab**: switch 插件/技能 next to the search box to browse and install skills
  149. (cloned into `~/.dsh/skills/<name>/`).
  150. 5. **Install**: click 添加到本地 → the chain runs in the background (safe to leave the page);
  151. 「检测更新」/「更新 → vX」 appear automatically for installed entries.
  152. ---
  153. ## Screenshots · 界面一览
  154. > 入口挂在**官方插件管理页自己的插槽**(`plugins.bundle.config`,key = 包名):装完之后它出现在
  155. > 「设置 → 插件 → 已安装」里我们这一条下面,用的是官方容器与官方风格 —— 不是 DOM 注入,官方更新也不怕。
  156. **1 · 已安装列表里的入口**(官方页,点开我们这条即见)
  157. ![Entry inside the official plugins page](docs/images/official-plugins-page.png)
  158. **2 · 「升级安全」面板**(就地展开:运行模式 / 框架版本 / 回滚点 / 环境指纹 / 补声明 / 契约预检 / 各功能入口)
  159. ![Upgrade safety panel expanded in place](docs/images/upgrade-safety-panel.png)
  160. **3 · 框架升级 / 回滚**(可选目标版本、常驻的升级进度、一键回滚上一版)
  161. ![Framework upgrade and rollback panel](docs/images/framework-upgrade-rollback.png)
  162. **4 · 门控明细**(谁被隔离、为什么:升级预扫 or 启动失败隔离,附来源与时间)
  163. ![Compatibility gate detail list](docs/images/compat-gate-detail.png)
  164. ---
  165. ## Features
  166. ### Installed plugins (one-click toggle + details)
  167. - **Shows only third-party plugins by default** (extra/non-bundled), tagged
  168. "Third-party" with a delete entry; click "All" to see the full list (1.5s flash feedback);
  169. - Lists every plugin entry (name, load state, enabled state); search by name/id;
  170. - Disable = append `- id: X` + `disabled: true` to the user patch layer, effective via HMR;
  171. - Enable = remove that entry; bundle-layer rows disabled by default are overridden with
  172. `disabled: false`;
  173. - Tags "Patch-disabled / Patch-forced" distinguish user patch state;
  174. - **Infrastructure protection**: host transport/hmr/storage/settings chain plugins
  175. (70+ rows) are marked "Protected" and cannot be toggled — disabling them would break HMR;
  176. - **Details panel**: version, repository/homepage links and a README summary for each plugin;
  177. - **Version check**: 检测更新 reads npm `dist-tags.latest` (curl channel, works even when
  178. node networking is blocked) and warns about subpackages that need syncing (depsOutdated).
  179. ### Framework one-click upgrade (deepseek-harness card)
  180. - The **deepseek-harness** card shows **「框架升级 → vX」** when a newer framework version is
  181. available (stable `latest` preferred; `next` channel when `latest` equals the installed
  182. version); clicking runs the full flow: backup config + framework snapshot (rollback point)
  183. → **online install** (service stays up, page never disconnects) → version verification →
  184. **auto-restart to apply**;
  185. - **Real-time progress**: a `DSH-Upgrade` console window pops up showing live pnpm download
  186. progress; the in-panel progress card shows the waiting time;
  187. - **Upgrade protection**: failed installs **auto-rollback** (robocopy, backup verified before
  188. upgrade), version check catches fake success, 15-min hard timeout, stall detection
  189. (no debug-log updates → auto switch registry), global trap fallback, and 15-min stale-state
  190. cleanup — the framework is never left broken;
  191. - **pnpm channel**: npm-cli.js freezes at startup in the schtasks task environment (0-byte
  192. debug log, no network requests ever sent); upgrades use `corepack pnpm` (starts in ~0.4s,
  193. installed rc.8 in 11.5s) against the **npmmirror (China) registry**, with
  194. `dangerouslyAllowAllBuilds` so native modules (node-pty/koffi) compile;
  195. - **Runtime bin resolution**: under the pnpm layout `@deepseek-ai/dsh` is a Junction — the
  196. relaunch step resolves `bin.js` at runtime (follows the Junction to the current version)
  197. instead of using a path baked in at script-generation time;
  198. - **Card dismiss semantics**: terminal states (done/failed) are permanently dismissed on ✕
  199. (persisted); in-progress dismissal is session-only and the card returns after a refresh.
  200. ### Marketplace (multi-source)
  201. - **Source switcher**: click the login pill to switch between **GitHub / Gitee / custom
  202. sources** (persisted); title, loading text, placeholder and note all follow the source;
  203. - **GitHub**: default query `dsh-plugin`, browser-direct with server fallback;
  204. - **Gitee**: official search API is retired, so it uses **direct-repo mode** — enter
  205. `owner/repo` (Chinese paths and full URLs supported) to find and install a repository;
  206. - **Custom sources**: add in Source Manager (URL template with `{q}`/`{page}` placeholders),
  207. optional **header auth** (e.g. `Authorization: Bearer ...`), and **local/private http URLs**;
  208. - **Multi-source summary**: the `⊞` toggle searches GitHub + all custom sources in parallel,
  209. merging results with source labels;
  210. - **★ official filter**: shows only packages installable via `dsh plugin add` — root packages
  211. with a `dsh.bundle` manifest (official) or aggregate repos whose **subpackage carries
  212. `dsh.bundle`** (subpackage-installable); markers are enriched by the server (curl dual-channel)
  213. with a client-side fallback;
  214. - **Type badges**: 官方 / 聚合 / 技能 (repo contains SKILL.md) recognized automatically.
  215. > **Network environment notes (why a multi-source setup can look "all dead")**
  216. > - **Accelerators/proxies that rewrite hosts kill the direct sources**: tools like Steam++ often point
  217. > `github.com` at `127.0.0.1`, so the GitHub direct source, `raw.githubusercontent.com` and
  218. > `api.github.com` all become unreachable — the plugin is not broken. The console now reports this
  219. > honestly as "local proxy / certificate interception (…) — an accelerator or proxy was detected,
  220. > turn it off and retry" instead of a vague "network unreachable".
  221. > - **Free mirrors are unreliable for the git protocol on large packs, while archive/raw are usually
  222. > fast**: measured on the same ghproxy.net host, archive (plain HTTP) ran at **4 MB/s** while the git
  223. > protocol moved **0 B/s**. Since this version the git channel has a stall criterion (switch source
  224. > after 20 s below 1 B/s) plus its own budget, and falls back to the **archive channel** (download the
  225. > tarball, extract, create the repo — equivalent to a clone) when all git sources fail. No manual
  226. > source switching needed.
  227. > - To reorder transports, use **Source Manager**: **git sources**, **archive sources** and **index
  228. > sources** all support primary→backup plus self-hosted mirrors (internal Gitea/GitLab, local
  229. > `file://` bare repos).
  230. #### Download-install channels and dependency forms
  231. Which channel gets used depends on **what the package actually is** — not on a setting:
  232. | Channel | Target | When it is used | Written in the manifest as | Needs plugin-src |
  233. |---|---|---|---|---|
  234. | ① pnpm (registry) | npm registry | **if the package is on the registry, this is the main channel** | `<name>: <version>` | no |
  235. | ② curl tarball (registry) | npm registry tarball | **races in parallel** with ① (takes over when pnpm is blocked/stuck) | same as above | no |
  236. | ③ GitHub Release asset | prebuilt tgz of an upstream release | when **both registry sources 404** | `link:<absolute path>` | yes |
  237. | ④ git clone | repository source | no npm package / no release asset | `link:…` | yes |
  238. | ⑤ archive (tar.gz) | codeload / mirrors | when the git protocol cannot move any bytes | `link:…` | yes |
  239. In one sentence: **has an npm package → ①/②, write a version, keep the lock clean; no npm package →
  240. fall back to ③/④/⑤, materialize into `~/.dsh/plugin-src/<pkg>` and write `link:`.**
  241. Environment reminder: an accelerator/proxy that rewrites hosts makes the direct sources unreachable
  242. (see above), and free mirrors are unreliable for the **git protocol** on large packs while
  243. **archive/raw are usually much faster** — the console already switches by itself.
  244. #### Development installs (`link:`)
  245. Ordinary installs go through the package manager (`pnpm add`); that is the baseline, not a feature here.
  246. `link:` is the separate, **explicit** route: mount a **local directory / plugin you are developing**
  247. directly into the profile.
  248. - **Source edits take effect immediately**: `node_modules/<name>` in the profile is a **link** to your
  249. local directory, not a copy — edit the source, refresh the page. No reinstall, no repackaging.
  250. - **Who it is for**: plugin authors, or anyone who wants to edit a plugin's source. If you just want
  251. to *use* a plugin, an ordinary install is simpler.
  252. - **What it pins**: the local artifact is written into the profile manifest `dependencies`
  253. (`link:<absolute path>`) and gets a matching entry in `pnpm-lock.yaml` — so lockfile health checks
  254. and rebuilds never treat it as an orphan, and it **survives restarts and instance updates**.
  255. - **What the console completes for it** (otherwise the usual outcome is "installed, but it will not load"):
  256. - **the target directory's own `dependencies`**: one install run inside that directory, filling in
  257. what the local directory is missing;
  258. - **the framework peer shim root**: when the local directory lives **outside** the profile tree,
  259. Node's resolution chain never reaches the profile's `node_modules`. The console links the framework
  260. peers it **declares and currently cannot resolve** (`@deepseek-ai/*`) at the **plugin root**,
  261. pointing at `~/.dsh/profiles/node_modules/@deepseek-ai/<pkg>`. It is a **link**, not a copy —
  262. both sides share the same realpath, so Cordis service classes and LLM error classes keep their
  263. **module identity shared with the host**.
  264. - **Boundaries** (always reported honestly, never faked):
  265. - moving or deleting the local directory **breaks** the link (the manifest `link:` then points at a
  266. path that no longer exists);
  267. - shims only fill peers it **declares** and that are genuinely missing; a package the framework side
  268. does not have is never invented;
  269. - anything **already present** at the target path (including a dangling link) is **never overwritten**
  270. — it is skipped and reported;
  271. - **uninstall removes the shims the console created** (only its own; links you placed by hand are
  272. never touched);
  273. - if completion fails (target directory not writable, dependency install failed, …) the **install
  274. still completes**, and the result honestly says "not ready + what is missing" together with an
  275. action you can run.
  276. ### Static index market (plugin & skill tabs)
  277. > **Hybrid architecture**: browsing uses the static index (instant, zero GitHub API calls),
  278. > searching uses live channels (GitHub search API / multi-source parallel) — they complement
  279. > each other: a brand-new repo can be found by live search even before it enters the index.
  280. - Empty query on the GitHub source shows the **static index** (`marketplace/index.json`,
  281. jsDelivr CDN + 10-min host cache): 500+ plugins by stars, instant, **zero GitHub API calls**;
  282. - **插件 / 技能 tabs** next to the search box: the skills tab lists auto-collected
  283. `agent-skills` ∪ `claude-skills` ∪ `dsh-skill` repos (up to 300);
  284. - **Auto version check**: installed entries in the market are checked against npm
  285. `dist-tags.latest` in the background — cards turn into **「更新 → vX」** buttons;
  286. - **Skill install**: skill entries install by git-clone into `~/.dsh/skills/<name>/`
  287. (frontmatter `name` wins over repo name; SKILL.md found at repo root or first-level
  288. subdirectory). Installed skills show a grey 「已装」 badge.
  289. ### Source Manager
  290. The floating "Sources" button (right of the title row, semi-transparent) opens the manager:
  291. ![Source Manager](https://github.com/user-attachments/assets/ef712900-65ae-4f6f-9584-bacdd8d34ea1)
  292. - **Install sources (registry)**: add / inline edit / set primary / restore defaults;
  293. private and intranet addresses supported; **deletion is protected** (install-critical);
  294. - **Search sources**: built-in GitHub, Gitee + custom search sources (add/remove, `🔒` shows
  295. header count);
  296. - **Gitee login (optional)**: direct mode needs no login; login only raises rate limits —
  297. create a third-party app (gitee.com → Data management → Third-party apps, scopes
  298. user_info, projects), fill client_id / client_secret, save, then authorize.
  299. ---
  300. <img width="393" height="525" alt="56ccd0b3-f174-4365-848b-64013b27d604" src="https://github.com/user-attachments/assets/5a2816ce-12d9-4001-b895-1e422c11d423" />
  301. ### Run mode (managed / observer)
  302. The mode decides **who leads framework upgrades** — nothing else:
  303. - **Observer (default)**: the console only preflights, gates, and guards the rollback point. It does not take over upgrades.
  304. - **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.
  305. - **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.
  306. **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.
  307. **Auto-disable on confirmed evidence (0.5.32)**: when the fingerprint-triggered auto-preflight, or a
  308. boot-failure record, provides **confirmed evidence** (the row's package resolves on **none** of the
  309. resolution bases, a `file://` target truly does not exist, or the boot log names the row), the console
  310. writes `disabled: true` for those rows **itself** (no click needed). Safety rails: **only rows with
  311. evidence**; `@deepseek-ai/*` (framework-owned) and protected/core rows are **never** auto-disabled;
  312. a **safe-boot snapshot is written first**, so any auto-disable is one command away from a rollback;
  313. when there is nothing to write, **not a single byte is written**; every auto-disable leaves a record in
  314. `dshHome()/plugin-console/auto-disable.log` (time / row id / evidence / restore command).
  315. Prefer "report only, let me click" (enabled by default) — replace `<host:port>` with your instance
  316. (the default `dsh web` profile listens on `127.0.0.1:3080`):
  317. ```bash
  318. curl -X POST http://<host:port>/plugin-console/compat-ack \
  319. -H 'Content-Type: application/json' -d '{"autoDisableOnEvidence":false}'
  320. ```
  321. **How to roll an auto-disable back**: the route `POST /plugin-console/safe-boot` with
  322. `{"action":"restore-last-good"}` (the current state is backed up first), or — when the service will not
  323. start — from the plugin directory:
  324. ```bash
  325. node scripts/safe-boot.mjs --list # see which snapshots exist
  326. node scripts/safe-boot.mjs --restore-last-good # restore the newest good snapshot byte-for-byte
  327. node scripts/safe-boot.mjs --disable-suspects # or: append disabled: true to named rows only (nothing deleted)
  328. node scripts/safe-boot.mjs --mark-good # mark a snapshot as good (never removed by retention)
  329. ```
  330. Safe-boot snapshots live under `dshHome()/plugin-console/safe-boot/` (**not** in the profile directory),
  331. keeping the newest 3 plus the one you marked as good.
  332. ### Runtime lag guard (observer mode)
  333. The **run mode** switch is the only enable. In **Observer** the guard is active; in **Managed** it
  334. records the same events but never blocks a connection.
  335. - **WebSocket retries**: a per-URL counter watches connection failures. A URL that fails **20 times
  336. in 30s** is tripped for **120s**; during the cooldown the caller receives a non-network placeholder
  337. socket, so a failed endpoint cannot spin at full speed. The next real attempt is allowed after the
  338. cooldown.
  339. - **Short-interval polling**: `setInterval` with a delay ≤ 1s is counted per call site. **≤500ms**
  340. intervals trip at **120 ticks/60s**; **≤1s** intervals trip at **300 ticks/60s**. In Observer the
  341. interval is cleared and the reason is reported; in Managed it is only recorded.
  342. - **Allowlist**: DSH's own connections are never touched — same-origin WebSockets, the desktop host
  343. port (`19387`), and the standalone web port (`3080`) always pass through.
  344. - **Attribution**: the calling script is taken from the stack (`/plugins/<pkg>/…` or
  345. `/node_modules/<pkg>/…`); when the stack is unavailable, installed packages are searched read-only
  346. for the URL/port. Official and third-party plugins use the same path.
  347. - **Event-loop sampling**: a 1s heartbeat records drift above 50ms. Jumps above 60s are treated
  348. as system sleep / clock changes (`clockJumps`) and do not pollute the displayed max drift.
  349. The latest sample is exposed as `runtimeHealth` on `GET /plugin-console/state`.
  350. - **Gate panel**: the gate modal shows **up to 10** runtime-guard records (kind, owning package,
  351. URL or polling interval/count, event-loop drift) plus a clear action. The records live in
  352. `dshHome()/plugin-console/runtime-health.json` (bounded to 50).
  353. - **Endpoints**: `GET /plugin-console/runtime-guard` returns the current mode and thresholds;
  354. `POST /plugin-console/runtime-health` accepts `report` / `config` / `clear`.
  355. - The guard never edits another plugin's code, never kills a process, and never throws into the page.
  356. ### When the service won't start because **framework packages were wiped**
  357. The rollback above restores the **config layer** (`cordis.patch.yml`). There is a second failure
  358. class where the **package payloads** are gone — framework packages emptied or deleted. Then the
  359. patch is perfectly fine, restoring it changes nothing, and **the console itself runs inside dsh**:
  360. if dsh cannot boot, the console was never loaded (real outage, 2026-10-14: `cordis`'s store entity
  361. emptied plus `dsh-llm`/`dsh-tools`/`dsh-web` turned into empty directories ⇒
  362. `54 plugins failed to import` ⇒ `exit code=1`).
  363. That class needs the **out-of-process** closure preflight (also needs no running service):
  364. ```bash
  365. node scripts/fw-preflight.mjs --check # diagnose only: list unresolvable packages, write nothing
  366. node scripts/fw-preflight.mjs --repair # restore from the **local npm cache** by lock integrity, then re-verify
  367. ```
  368. The criterion is "**can the dependency closure be resolved**", not "is the directory empty" —
  369. the latter is completely blind to "the shell is still there, the inside was emptied"
  370. (measured: a naive empty-dir scan reported 237 false positives; the closure criterion passed all
  371. 287 packages and named exactly the one that broke). `--repair` is **offline and never guesses a
  372. version** (a package missing from the lock is reported as `no-lock-entry`), and it **never kills or
  373. spawns a process and never grabs a port** (that is exactly what produces
  374. "The application failed to start or stopped unexpectedly") — restart the service yourself afterwards.
  375. ## Framework compatibility
  376. Measured on isolated instances (fresh `DSH_HOME`, real HTTP probes) — **supported: framework ≥ `0.1.5-rc.2`**, no workarounds needed.
  377. | | 0.1.7-rc.2 (current) | 0.1.5-rc.2 / 0.1.2-rc.1 |
  378. |---|---|---|
  379. | Official plugins page (`@deepseek-ai/dsh-client-ui-plugin-manager`) | present | **not shipped by the framework at all** |
  380. | The official-style **Upgrade safety** entry | shown (hosted in that page's own `plugins.bundle.config` slot) | not shown — there is no page to host it |
  381. | Classic **Plugins** tab (`settings.plugins.tab`) | shown | **shown** |
  382. | Server-side features (upgrade / rollback / gating / marketplace) | all available | **all available** (every route answered 200 in the matrix) |
  383. | Errors | none | **none** (the slot registration degrades silently) |
  384. 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.
  385. 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`.
  386. ### Version-change auto-block
  387. Any framework version change — from the desktop updater, a manual install, or an npx cache change —
  388. runs the same compatibility preflight used before an upgrade. Rows judged `fail` are written with
  389. `disabled: true` and recorded in `compat-pending` as `pending`; framework-owned, protected, core, and
  390. the console's own row are never auto-disabled. The gate list is refreshed automatically so a blocked
  391. row appears as 「待适配」 instead of leaving an empty panel.
  392. The last gated version is stored in `compat-gate.json` (`version` / `gatedAt`). A successful scan is
  393. the only thing that advances it; a failed scan retries on the next status query. `autoDisable` is on
  394. by default and can be turned off with `POST /plugin-console/compat-gate`
  395. (`{"autoDisable":false}`), in which case the version is recorded but no patch is written.
  396. A panel that shows no pending rows after a scan is not necessarily broken: it means the current rows
  397. were `pass` or `unknown`, not `fail`.
  398. ### Session-preset contract
  399. `GET /plugin-console/preset-contract` performs a read-only daily check of the installed
  400. `@deepseek-ai/dsh-agent-preset` package: its version and entry-file hash, the number of
  401. `preset-*` declaration rows in the profile patch, and the existing declaration-vs-disk audit
  402. (`stale` / `missing` / `orphan` / `targetMissing`). Results are cached for 24h;
  403. `?force=1` recomputes.
  404. The check never writes `.agent-presets/**` and never edits the profile patch. The safety panel shows
  405. the contract version, declaration count, and drift count, with a 「检查」 button. A contract-hash
  406. change between checks is reported as `contractChanged` — it means the official preset package
  407. changed and the declarations should be reviewed.
  408. ## Documentation
  409. - [AI Empower 与服务器组件控制](docs/ai-empower.md)
  410. - [Framework upgrade safety & plugin adapt gate](docs/upgrade-safety-adapt-gate.md)
  411. - [**契约规则库 Upgrade contract rules**](docs/contracts/README.md) — 框架每次变更会打断什么、怎么发现、怎么修(数据在 `lib/contracts/rules.json`,**欢迎 PR 补充**:每个事故都应该变成一条规则)
  412. - [How it works](docs/how-it-works.md) · [Compatibility](docs/compatibility.md) · [Project layout](docs/project-layout.md)
  413. - [HTTP endpoints](docs/http-endpoints.md) · [Local AI fallback & consent](docs/ai-fallback.md)
  414. - [Framework patch (cordis.patch.yml)](docs/framework-patch.md) · [Security & disclaimer](docs/security-disclaimer.md)
  415. ---
  416. ### Update integrity
  417. An update can be requested for a specific version. That version is carried into every download channel; if
  418. a channel ends up with a different version, the job reports a failure with both versions named, and the
  419. existing copy on disk is kept rather than replaced. The manifest and lock record a **version number** for
  420. such packages — a normal install does not produce a `link:`.
  421. Installs and updates are tracked per target: two different plugins can update at the same time, while the
  422. same plugin cannot be started twice.
  423. A finished install leaves two small records under `<DSH_HOME>/plugin-console/`:
  424. - `pending-restart.json` — plugins that are installed but not yet loaded, so the panel can keep showing
  425. "installed · takes effect after restart" across a host restart. Entries are dropped once the plugin is
  426. actually loaded.
  427. - `install-jobs.json` — the last fifty settled jobs, with the requested version, the version that landed,
  428. and the error if any. A failure can therefore still be explained after the process that produced it is gone.
  429. Drift between the manifest and the lock is reconciled in the background with a cooldown, without blocking
  430. `/state`. Source-type dependencies (`link:`, `file:`, git) are excluded from that automation. A mismatch is
  431. reported as a failure only when it would actually lose the plugin; a lock or version drift is shown as a
  432. collapsible note instead.
  433. ### Dev links (`link`)
  434. `link:` is a **development** mechanism — ordinary download installs and updates do not produce it. The
  435. `link` entry in the feature-pack toolbar is the working surface for it:
  436. - pick a registered dev root from the dropdown, or type an absolute path;
  437. - **Pin** is a two-step action: it first returns a read-only plan, and executes only after you confirm. No
  438. code path skips that confirmation;
  439. - each row shows the target directory and its last-modified time, which is how you tell whether it is the
  440. directory you are editing right now;
  441. - per-row actions appear only when they apply — **fill dependencies**, **build shims** (no pnpm run), and
  442. **unpin**;
  443. - **Browse…** is rendered only when the desktop preload bridge is present. On a web instance it is not
  444. rendered, rather than shown as a button that cannot work.
  445. ### Disable provenance
  446. A row can be off for different reasons, and the panel distinguishes them:
  447. - **disabled by this console's patch** — removing the patch block enables it normally;
  448. - **disabled by the plugin or the framework default** — the console can only write an explicit
  449. `disabled: false` override, which is what the **forced on by patch** badge refers to;
  450. - **force-enable had no effect** — the override exists but the row still is not running, and no peer veto
  451. explains it. That override can be revoked from the row.
  452. ### Operational details
  453. - Market enrichment runs behind a single limiter: four concurrent requests, one in flight per URL, a
  454. ten-minute memory for failures and a five-minute success cache. A batch of unreachable mirrors therefore
  455. cannot saturate the connection or delay installs.
  456. - `Disk audit` lists what occupies `<DSH_HOME>/plugin-console` and deletes only after an explicit
  457. confirmation. The framework rollback point counts as protected.
  458. - The gate panel shows the current pending adaptations up front and keeps its history collapsed.
  459. ## Known limitations
  460. - Host code changes require a **service restart**; client changes only need a page refresh.
  461. - On a **desktop-hosted** instance the console **refuses** to restart and says so: the official path is to
  462. fully quit and reopen the client. It never kills or spawns a process there — a manual relaunch would
  463. fight the host for the port and produce "The application could not start or stopped unexpectedly".
  464. - On a **standalone (web) instance** the restart button is available: it relaunches detached, waits for
  465. the port to free, and lets the old process exit gracefully. The toolbar entry is rendered only where it
  466. can work — a desktop-hosted instance does not show it.
  467. - Live GitHub search depends on GitHub reachability (browser-direct + server fallback;
  468. during network-blackout windows retry later);
  469. - Version detection works for npm-published packages; skill-type repos have no version concept;
  470. - The static index is capped (500 plugins / 300 skills per build); authors bump their star
  471. count or wait for the 6h CI cycle to enter the index;
  472. - Skills are discovered by `dsh-skill-filesystem` — if the current profile does not enable
  473. that plugin, installed skills stay dormant until it is enabled and DSH restarted.
  474. - The runtime guard covers **WebSocket retries** and **short `setInterval` polling** only.
  475. Longer polling (1s+), `requestAnimationFrame` loops, renderer long tasks, and work inside
  476. workers are outside its scope; the event-loop sampler reports server-side drift but does not
  477. cancel arbitrary work.
  478. - The version-change gate can only disable rows it can resolve and that are toggleable; protected
  479. and framework-owned rows stay enabled and rely on rollback. A scan with `0 fail` correctly
  480. produces an empty pending list.
  481. - The preset-contract check reports the **installed** official package, not the registry's latest
  482. version, and never rewrites presets automatically.
  483. ---
  484. ## Help & Ecosystem
  485. - **Panel missing**: restart dsh → refresh → Settings → Plugins → Plugin Console.
  486. - **Toggle does nothing**: infrastructure rows are "Protected" (by design); normal toggles
  487. take effect via HMR within 1-3s.
  488. - **Compatibility warning**: a breaking upstream release arrived; see Compatibility.
  489. - **Search empty/fails**: GitHub uses browser-direct (falls back to the server channel);
  490. Gitee is direct-repo mode (enter `owner/repo`); check custom-source URL/headers; retry
  491. during network blackout windows.
  492. - **★ filter empty**: ★ shows only `dsh plugin add`-installable packages (official +
  493. subpackage-bundle aggregates); markers are backfilled in 1-3s — no false "none" report.
  494. - **Install fails**: confirm the repo has package.json and the package is published; npm
  495. failures fall back to git install; switch the primary source if npmmirror is unstable.
  496. - **Skill not found by DSH**: enable `@deepseek-ai/dsh-skill-filesystem` in the profile
  497. (`cordis.yml`) and restart; skills live in `~/.dsh/skills/<name>/`.
  498. ---
  499. ## Ecosystem & discoverability
  500. - Listed on [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) (the community main list) and [DSH Directory](https://dsh.directory);
  501. - 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;
  502. - If you build DSH plugins, this panel is your distribution channel: one-click install for every user of the hub.
  503. ## Support
  504. If this panel saves you time or makes DSH more fun to use:
  505. - ⭐ **Star this repo** — it directly helps more DSH users find it;
  506. - Share it with DSH users or in DSH communities;
  507. - Submit your own plugin (tag it `dsh-plugin`) to grow the ecosystem;
  508. - Found a bug or want a feature? [Open an issue](https://github.com/Noob-stupid/dsh-plugin-gating-hub/issues).
  509. ---
  510. ## Contributing
  511. Contributions of all kinds are welcome — issues, PRs, docs, translations.
  512. - **Guidelines**: [CONTRIBUTING.md](CONTRIBUTING.md)
  513. - **Code of Conduct**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
  514. - **Security policy**: [SECURITY.md](SECURITY.md) (report vulnerabilities privately)
  515. - **Issue templates**: bug reports & feature requests via the [new issue](https://github.com/Noob-stupid/dsh-plugin-gating-hub/issues/new/choose) page
  516. ---
  517. ## Changelog
  518. See [CHANGELOG.md](CHANGELOG.md).
  519. ---
  520. ## License
  521. MIT
  522. ---
  523. ---
  524. ## Preview (experimental · not for production)
  525. The layered-refactor preview lives in its **own repository**: [**`Noob-stupid/dsh-plugin-hub-refactor`**](https://github.com/Noob-stupid/dsh-plugin-hub-refactor)
  526. - **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;
  527. - **Verified**: 19 test suites green · 8 architecture-guard assertions · **route inventory identical** (`status` + response fields) against the stable build;
  528. - **Not yet exercised**: real framework upgrade / rollback, restart guardian, component start/stop, real AI run, Gitee OAuth (~10–25% long-tail risk, subjective);
  529. - **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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.