dsh-plugin 1.4.12 → 1.4.14

package/lib/http/routes.js

@@ -14,6 +14,7 @@ import { dirname, join, resolve } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { fetchViaCurl, gitLsRemote, probeUrl, systemProxy } from '../services/probe.js';
 import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubRepoOf, githubTarget, globalNpmPackagesOf, hasQueuedTarget, installTargetOf, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName } from '../services/install/install.js';
+import { githubReleaseTarget } from '../services/install/release-target.js';
 import { recordInstalledVersion, recordResolvedNpmPackage, readInstalledVersions, removeInstalledVersion } from '../services/profile/installed-versions.js';
 import { resolveNpmPackage } from '../services/install/npm-resolve.js';
 import { preflightTarget } from '../services/install/preflight.js';
@@ -801,12 +802,14 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                         sendJson(response, 200, { ok: true, task: task.id });
                         return;
                     }
-                    // 目标语法两态：GitHub 地址（owner/repo、github:、https/ssh 链接等任意写法）→ 显式
-                    // HTTPS Git 源（走装前预检）；npm 包名（@scope/name 或 name）→ 信任 registry 直接安装。
+                    // 目标语法三态：固定 GitHub release .tgz（保留其包根目录，不转成仓库 HEAD）；
+                    // GitHub 地址（owner/repo、github:、https/ssh 链接等任意写法）→ 显式 HTTPS Git 源
+                    // （走装前预检）；npm 包名（@scope/name 或 name）→ 信任 registry 直接安装。
                     // githubRepoOf 先把各种 GitHub 地址归一成 owner/repo，让「输入地址即装」兼容粘贴完整链接。
                     const gitRepo = githubRepoOf(rawRepo);
-                    const repoTarget = gitRepo !== null ? githubTarget(gitRepo) : null;
-                    let target = repoTarget ?? (validPackageName(rawRepo) ? rawRepo : null);
+                    const release = githubReleaseTarget(rawRepo);
+                    const repoTarget = gitRepo !== null && release === null ? githubTarget(gitRepo) : null;
+                    let target = release?.target ?? repoTarget ?? (validPackageName(rawRepo) ? rawRepo : null);
                     if (target === null) {
                         sendJson(response, 400, { error: 'unsupported install target' });
                         return;
@@ -836,9 +839,9 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                     }
                     // 命令行安装（目录外）按通道门禁：GitHub 源码通道受「启用 GitHub 源码安装」控制，
                     // npm 通道受「启用 NPM 安装」控制 —— 目录插件安装走目录白名单，不受开关影响。
-                    // 通道判定看反查后的最终 target：仍是 git 目标 = 走 GitHub 源码，否则走 npm。
+                    // 通道判定看反查后的最终 target：release 包与 git 目标同属 GitHub 通道，否则走 npm。
                     if (source !== 'catalog') {
-                        const isGitChannel = repoTarget !== null && target === repoTarget;
+                        const isGitChannel = release !== null || (repoTarget !== null && target === repoTarget);
                         if (isGitChannel && !settings.enableGitInstall) {
                             sendJson(response, 403, { error: 'git installs are disabled by the security settings' });
                             return;
@@ -874,8 +877,12 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                         const effectiveProxy = settings.proxy !== ''
                             ? settings.proxy
                             : (systemProxy() ?? process.env.HTTPS_PROXY ?? process.env.https_proxy ?? '');
-                        const isGitChannel = repoTarget !== null && target === repoTarget;
-                        const npmProbeTarget = `${(settings.npmRegistry.replace(/\/+$/, '') || 'https://registry.npmjs.org')}/`;
+                        const isGitChannel = release !== null || (repoTarget !== null && target === repoTarget);
+                        // release 包是 https://github.com/ 直链下载（非 git 克隆），探针按 HTTP 打 github.com 主页；
+                        // npm 通道探 registry 根。两者都是通道的稳定入口，不探具体包/仓库（404 会被误判成网络故障）。
+                        const httpProbeTarget = release !== null
+                            ? 'https://github.com/'
+                            : `${(settings.npmRegistry.replace(/\/+$/, '') || 'https://registry.npmjs.org')}/`;
                         // git 通道的探针换成克隆握手本身：git ls-remote 走的就是 pnpm 克隆前的同一套
                         // https 传输。curl 打 github.com 主页会被按协议/端口区分的防火墙与 TLS 复检
                         // 拦截（能 git 克隆、打不开网页），把可装的仓库误判成 [network] 而中止
@@ -893,9 +900,9 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                             }
                         }
                         else {
-                            net = await probeUrl(npmProbeTarget, effectiveProxy, 6000);
+                            net = await probeUrl(httpProbeTarget, effectiveProxy, 6000);
                         }
-                        const probeTarget = gitProbeTarget ?? npmProbeTarget;
+                        const probeTarget = gitProbeTarget ?? httpProbeTarget;
                         if (!net.ok) {
                             // 错误消息按客户端界面语言提示：中文界面给中文、英文界面给英文，
                             // 让用户一眼看懂是网络问题而非插件问题

package/lib/services/install/npm-resolve.js

@@ -16,6 +16,8 @@ import { get } from 'node:https';
 const cache = new Map();
 /** 单次 registry 查询超时（ms）：慢网络下失败返回 null，不阻塞安装流程。 */
 const REQUEST_TIMEOUT_MS = 8000;
+/** npm search 是相关性搜索而非 repository 精确索引；拉满单页结果后再本地做严格 repo 过滤。 */
+const SEARCH_RESULT_LIMIT = 250;
 /**
  * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
  * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
@@ -37,6 +39,31 @@ export function resolveNpmPackage(repo, registry = '') {
     });
     return name.then((found) => found ?? null);
 }
+/**
+ * Pick the installable npm package for one GitHub repository. npm search is a
+ * relevance-ranked text search, not an exact repository index, so first filter
+ * by repository URL. If a monorepo publishes both a CLI/helper package and a
+ * DSH plugin, prefer the package that explicitly advertises the `dsh-plugin`
+ * keyword instead of whichever result npm happened to rank first.
+ */
+export function selectNpmPackageForRepo(objects, repo) {
+    const needle = `github.com/${repo}`.toLowerCase();
+    const matches = [];
+    for (const obj of objects) {
+        const pkg = obj.package;
+        if (typeof pkg?.name !== 'string' || pkg.name === '')
+            continue;
+        const repoUrl = String(pkg.repository?.url ?? pkg.links?.repository ?? '');
+        if (!repoUrl.toLowerCase().includes(needle))
+            continue;
+        const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : [];
+        matches.push({
+            name: pkg.name,
+            isDshPlugin: keywords.some((keyword) => typeof keyword === 'string' && keyword.toLowerCase() === 'dsh-plugin'),
+        });
+    }
+    return matches.find((candidate) => candidate.isDshPlugin)?.name ?? matches[0]?.name ?? null;
+}
 /** 用 npm search 接口按 repository 地址反查，并做铁证校验（包元数据必须指向该仓库）。
  * 返回：包名 = 命中；null = 200 响应下确认无匹配；undefined = 本次未能确认（网络/超时/解析失败）。 */
 function searchRepo(repo, registry) {
@@ -44,7 +71,7 @@ function searchRepo(repo, registry) {
     if (owner === undefined || name === undefined || name === '')
         return Promise.resolve(null);
     const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '');
-    const url = `${base}/-/v1/search?text=${encodeURIComponent(`repository:${owner}/${name}`)}&size=10`;
+    const url = `${base}/-/v1/search?text=${encodeURIComponent(`repository:${owner}/${name}`)}&size=${SEARCH_RESULT_LIMIT}`;
     return new Promise((resolve) => {
         const req = get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
             if (res.statusCode !== 200) {
@@ -57,18 +84,7 @@ function searchRepo(repo, registry) {
             res.on('end', () => {
                 try {
                     const data = JSON.parse(body);
-                    const needle = `github.com/${owner}/${name}`.toLowerCase();
-                    for (const obj of data.objects ?? []) {
-                        const pkg = obj.package;
-                        if (typeof pkg?.name !== 'string' || pkg.name === '')
-                            continue;
-                        const repoUrl = String(pkg.repository?.url ?? pkg.links?.repository ?? '');
-                        if (repoUrl.toLowerCase().includes(needle)) {
-                            resolve(pkg.name);
-                            return;
-                        }
-                    }
-                    resolve(null);
+                    resolve(selectNpmPackageForRepo(data.objects ?? [], `${owner}/${name}`));
                 }
                 catch {
                     resolve(undefined);

package/lib/services/install/preflight.js

@@ -18,12 +18,17 @@ import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { promisify } from 'node:util';
 import { githubRepoOf } from '../profile/profile.js';
+import { githubReleaseTarget } from './release-target.js';
 import { resolvePackageEntry } from './package-entry.js';
 const execFileAsync = promisify(execFile);
 /** 单次网络操作超时（ms）：git ls-remote / codeload 下载。网络不可达时不能无限挂起，
  *  否则 `/install` 请求永远不返回、任务不入队、前端进度卡 0%。超时后放行（交给装后校验）。 */
 const PREFLIGHT_TIMEOUT_MS = 15_000;
 export async function preflightTarget(target) {
+    // release 包自带包根：拿 monorepo HEAD 的源码分发去校验它没有意义，会把完整产物
+    // 误判成缺入口文件而拦下。该包的真实性交给安装本身与装后 verifyInstalledEntry 兜底。
+    if (githubReleaseTarget(target) !== null)
+        return { ok: true, missing: null, name: null };
     const source = githubRepoOf(target);
     if (source === null)
         return { ok: true, missing: null, name: null };

package/lib/services/install/release-target.js

@@ -0,0 +1,38 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 预构建 GitHub release 安装目标（目录权威命令 → 可安装直链）。
+ * 部分插件（如 loopx）把构建产物发布成 GitHub release 的 .tgz，仓库 HEAD 反而是
+ * monorepo 根、走 git 直装会因缺入口文件失败；目录下发的权威安装命令直接指向该
+ * release 包。这里把「目录命令」解析成安全的 release 目标，供客户端选路与服务端
+ * 校验共用（单一事实来源，避免两端口径漂移）。
+ *
+ * 只接受固定形态的 HTTPS `github.com/<owner>/<repo>/releases/download/<tag>/<asset>.tgz`：
+ * 目录命令是展示数据、绝非 shell 代码，绝不执行命令文本；跨仓跳转、外部主机、凭据、
+ * 移动的 latest 链接、query/fragment、多余 CLI 参数与 shell 片段一律拒绝。
+ */
+/** 目录权威命令：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同口径）。 */
+const DSH_PLUGIN_CMD_RE = /^dsh[ \t]+plugin[ \t]+--profile(?:[ \t]+|=)[A-Za-z0-9_-]+[ \t]+(?:add|update)[ \t]+(.+)$/i;
+/** 固定形态的 release .tgz 直链：主机、路径段与扩展名全部锁死。 */
+const RELEASE_URL_RE = /^https:\/\/github\.com\/([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)\/releases\/download\/([A-Za-z0-9._+-]+)\/([A-Za-z0-9._+-]+\.tgz)$/;
+/**
+ * 解析一个 release 安装目标。
+ * @param value - 目录命令（`dsh plugin --profile web add <url>`）或裸直链。
+ * @returns 命中返回 `{ target, repo }`，否则 null。
+ */
+export function githubReleaseTarget(value) {
+    const input = typeof value === 'string' ? value.trim() : '';
+    if (input === '')
+        return null;
+    const command = DSH_PLUGIN_CMD_RE.exec(input);
+    const raw = command !== null ? command[1].trim() : input;
+    const match = RELEASE_URL_RE.exec(raw);
+    if (match === null)
+        return null;
+    // 拒绝 `.` / `..` 路径段，杜绝借路径穿越跳出 release 目录
+    if (match.slice(1).some((part) => part === '.' || part === '..'))
+        return null;
+    return { target: raw, repo: `${match[1]}/${match[2]}` };
+}

package/lib/services/profile/profile.js

@@ -10,6 +10,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { PACKAGE_RE, REPO_RE } from '../install/install-types.js';
+import { githubReleaseTarget } from '../install/release-target.js';
 /** Resolve the active profile from the booted CLI args, falling back to `web`. */
 export function readProfileArg(fallback = 'web') {
     return profileFromArgv(process.argv, fallback);
@@ -90,6 +91,11 @@ export function githubRepoOf(value) {
     if (typeof value !== 'string')
         return null;
     const input = value.trim();
+    // release 直链先归一到仓库身份：目录命令里的固定 HTTPS release 包不是 git 地址，
+    // 但它的所属仓库就是 owner/repo —— 已装态读回、去重、展示都要拿到这层身份。
+    const release = githubReleaseTarget(input);
+    if (release !== null)
+        return release.repo;
     if (REPO_RE.test(input))
         return input;
     const patterns = [

package/lib/types/services/install/npm-resolve.d.ts

@@ -9,3 +9,25 @@
  * 慢网络下失败不阻塞安装。
  */
 export declare function resolveNpmPackage(repo: string, registry?: string): Promise<string | null>;
+type NpmSearchPackage = {
+    name?: unknown;
+    keywords?: unknown;
+    links?: {
+        repository?: unknown;
+    };
+    repository?: {
+        url?: unknown;
+    };
+};
+type NpmSearchObject = {
+    package?: NpmSearchPackage;
+};
+/**
+ * Pick the installable npm package for one GitHub repository. npm search is a
+ * relevance-ranked text search, not an exact repository index, so first filter
+ * by repository URL. If a monorepo publishes both a CLI/helper package and a
+ * DSH plugin, prefer the package that explicitly advertises the `dsh-plugin`
+ * keyword instead of whichever result npm happened to rank first.
+ */
+export declare function selectNpmPackageForRepo(objects: NpmSearchObject[], repo: string): string | null;
+export {};

package/lib/types/services/install/release-target.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 预构建 GitHub release 安装目标（目录权威命令 → 可安装直链）。
+ * 部分插件（如 loopx）把构建产物发布成 GitHub release 的 .tgz，仓库 HEAD 反而是
+ * monorepo 根、走 git 直装会因缺入口文件失败；目录下发的权威安装命令直接指向该
+ * release 包。这里把「目录命令」解析成安全的 release 目标，供客户端选路与服务端
+ * 校验共用（单一事实来源，避免两端口径漂移）。
+ *
+ * 只接受固定形态的 HTTPS `github.com/<owner>/<repo>/releases/download/<tag>/<asset>.tgz`：
+ * 目录命令是展示数据、绝非 shell 代码，绝不执行命令文本；跨仓跳转、外部主机、凭据、
+ * 移动的 latest 链接、query/fragment、多余 CLI 参数与 shell 片段一律拒绝。
+ */
+/** release 包目标及其所属仓库身份（owner/repo）；非法返回 null。 */
+export interface GithubReleaseTarget {
+    /** 规范化后的安装目标（HTTPS 直链） */
+    target: string;
+    /** 该直链所属仓库（owner/repo）：供已装态读回、队列去重与展示身份复用 */
+    repo: string;
+}
+/**
+ * 解析一个 release 安装目标。
+ * @param value - 目录命令（`dsh plugin --profile web add <url>`）或裸直链。
+ * @returns 命中返回 `{ target, repo }`，否则 null。
+ */
+export declare function githubReleaseTarget(value: string): GithubReleaseTarget | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "1.4.12",
+  "version": "1.4.14",
   "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 10000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：10000+ 人工精选社区插件，每日更新。",
   "type": "module",
   "main": "lib/index.js",

package/src/client/components/modals/AboutModal.tsx

@@ -8,7 +8,7 @@
  * 客户端按接口返回渲染，不内置固定文案。
  * 图片（反馈群二维码）经 renderMarkdown 的 ![](url) 语法嵌入，居中、最大高度受控。
  */
-import { createElement as h } from 'react'
+import { createElement as h, useMemo } from 'react'
 import type { MouseEvent } from 'react'
 import styles from '../../styles/Modal.module.css'
 import type { HubAboutInfo } from '../../types.ts'
@@ -16,6 +16,19 @@ import type { LocaleId, Translate } from '../../types.ts'
 import { renderMarkdown } from '../../logic/renderMarkdown.ts'
 import { CloseIcon } from '../ui/icons.tsx'
 
+/**
+ * 反馈群二维码 URL 恒定（每次换码都是同名覆盖，文件名不变），浏览器 / CDN 会按
+ * URL 缓存旧图。这里在渲染前给二维码 URL 实时拼一个新的时间戳，强制每次打开
+ * 「关注我们」都回源拉取最新图片，无需重新构建 / 部署接口中心。
+ * 匹配规则与 renderMarkdown 的二维码识别保持一致（dsh-plugin-user-group-qr 前缀）。
+ */
+function bustQrCache(md: string, ts: number): string {
+  return md.replace(
+    /(!\[[^\]]*\]\()([^)\s]*dsh-plugin-user-group-qr[^)\s]*)/g,
+    (_m, pre, url) => `${pre}${String(url).split('?')[0]}?v=${ts}`,
+  )
+}
+
 export function AboutModal({ info, lang, t, onClose }: {
   info: HubAboutInfo | null
   lang: LocaleId
@@ -33,7 +46,10 @@ export function AboutModal({ info, lang, t, onClose }: {
           : (info.content.zh ?? info.content.en ?? '')
         : ''
     : ''
-  const contentHtml = contentRaw.trim() ? renderMarkdown(contentRaw) : null
+  // 每次打开弹窗（组件重新挂载）生成一个时间戳，用于二维码破缓存；
+  // 同一次打开内保持稳定，避免父组件重渲染导致图片被反复重载。
+  const qrTs = useMemo(() => Date.now(), [])
+  const contentHtml = contentRaw.trim() ? renderMarkdown(bustQrCache(contentRaw, qrTs)) : null
   // 更新时间：ISO 字符串转本地可读格式；非法值静默隐藏
   let updated: string | null = null
   if (info?.updatedAt) {

package/src/client/components/modals/NotificationsModal.tsx

@@ -18,7 +18,7 @@ import type { MouseEvent } from 'react'
 import styles from '../../styles/Modal.module.css'
 import type { EnvInfo, Translate } from '../../types.ts'
 import type { NotificationRecord } from '../../logic/failures.ts'
-import { classifyFailure, npmTooLowVersion, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { classifyFailure, missingRegistryPackageOf, npmTooLowVersion, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
 import type { PendingRestart, QueueTask } from '../../hooks/useTaskQueue.ts'
 import { pluginIssueUrl, pluginSiteUrl } from '../../logic/urls.ts'
 import { CloseIcon } from '../ui/icons.tsx'
@@ -307,6 +307,16 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       // 发现补丁没被用上就中止安装，任何插件都装不进来 —— 不引导提 Issue
                       return h('div', { className: styles.failPrepareHint }, t('failPnpmUnusedPatchHint'))
                     }
+                    if (kind === 'pnpmMissingDep') {
+                      // profile 里留着指向 registry 上不存在（404）的包的依赖：pnpm 连得上 registry，
+                      // 是被明确告知包不存在 —— 该 profile 的任何安装都会先卡在这条依赖上，与本次要装的
+                      // 插件无关 → 点名缺失的包 + 删除条目指引，不引导提 Issue
+                      const pkg = missingRegistryPackageOf(r.message)
+                      return h('div', null, [
+                        pkg ? h('div', { className: styles.failNetworkTarget }, t('failPnpmMissingDepTarget', { pkg })) : null,
+                        h('div', { className: styles.failPrepareHint }, t('failPnpmMissingDepHint')),
+                      ])
+                    }
                     if (kind === 'fileLocked') {
                       // profile 里的文件被其他进程占用（Windows os error 32）：通常是宿主或杀毒软件
                       // 持有句柄 —— 给出完全退出宿主的指引，不引导提 Issue

package/src/client/components/modals/modals.tsx

@@ -16,7 +16,7 @@ import { CloseIcon, ConfirmIcon, CopyIcon, LinkIcon } from '../ui/icons.tsx'
 import { ProgressView } from './ProgressView.tsx'
 import { installCommandOf } from '../../logic/install-command.ts'
 import { pluginDetailUrl, pluginIssueUrl, pluginSiteUrl } from '../../logic/urls.ts'
-import { classifyFailure, npmTooLowVersion, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { classifyFailure, missingRegistryPackageOf, npmTooLowVersion, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述；
  *  needsRestart=true（插件需重启才生效）→ 「稍后重启 / 立即重启」按钮对，点稍后重启后
@@ -421,6 +421,17 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
               // profile 里留着指向旧版本 dsh-plugin 的补丁声明（ERR_PNPM_UNUSED_PATCH）：pnpm 发现
               // 补丁没被用上就中止整次安装，任何插件都装不进来 —— 给删除条目的指引，不引导提 Issue
               ? h('div', { className: styles.failPrepareHint }, t('failPnpmUnusedPatchHint'))
+              : failureKind === 'pnpmMissingDep'
+              // profile 里留着指向 registry 上不存在（404）的包的依赖：pnpm 连得上 registry，
+              // 是被明确告知包不存在 —— 该 profile 的任何安装都会先卡在这条依赖上，与本次要装的
+              // 插件无关 → 点名缺失的包 + 删除条目指引，不引导提 Issue
+              ? h('div', null, [
+                (() => {
+                  const pkg = missingRegistryPackageOf(message)
+                  return pkg ? h('div', { className: styles.failNetworkTarget }, t('failPnpmMissingDepTarget', { pkg })) : null
+                })(),
+                h('div', { className: styles.failPrepareHint }, t('failPnpmMissingDepHint')),
+              ])
               : failureKind === 'fileLocked'
               // profile 里的文件被其他进程占用（Windows os error 32）：pnpm 无法替换被占用的文件，
               // 通常是宿主或杀毒软件持有句柄 —— 给退出宿主的指引，不引导提 Issue

package/src/client/locales.ts

@@ -326,6 +326,9 @@ export const zh = {
   failNpmMissingHint: '系统找不到 npm 命令（npm 未安装或未加入系统 PATH），无法执行全局安装。请先安装 Node.js（自带 npm），确认 npm 已加入 PATH 后重试。这不是插件本身的问题。',
   failPnpmStoreHint: '安装器调用 pnpm 时报「store 位置不匹配」（ERR_PNPM_UNEXPECTED_STORE）：你的 profile 目录里旧插件依赖是用另一个大版本的 pnpm 生成的，当前 pnpm 出于安全不认旧目录，导致任何插件装进该 profile 都会失败。请删除该 profile 目录下的 node_modules 与 pnpm-lock.yaml（可先到「系统日志」或 ~/.dsh/profiles/<profile>/hub.log 查看完整报错），再重新安装。这不是插件本身的问题。',
   failPnpmUnusedPatchHint: '安装器调用 pnpm 时报「有些补丁没有被使用」（ERR_PNPM_UNUSED_PATCH）：你的 profile 里留着一条指向旧版本 dsh-plugin 的补丁声明（例如 dsh-plugin@1.4.2），而本次安装解析到的版本已经不是它，pnpm 出于安全直接中止整次安装，因此任何插件都装不进来。这不是插件本身的问题——请在 profile 目录（~/.dsh/profiles/<profile>）的 pnpm-workspace.yaml（pnpm 11 及以上）或 package.json 的 pnpm.patchedDependencies（pnpm 10）里删除该 dsh-plugin 补丁条目后重试。',
+  // 404 依赖：点名 registry 上不存在的那个包（取不到包名时跳过这行），再给删除条目的指引
+  failPnpmMissingDepTarget: '{pkg} 在 npm registry 上不存在（404）',
+  failPnpmMissingDepHint: '安装器调用 pnpm 时报「包不存在」（ERR_PNPM_FETCH_404）：你的 profile 里留着一条指向 registry 上未发布包的依赖，pnpm 每次解析依赖都会先卡在它上面，因此任何插件都装不进来。这不是插件本身的问题——请在 profile 目录（~/.dsh/profiles/<profile>）的 package.json 里删除该依赖条目（同时删掉对应的 pnpm-lock.yaml 条目或整个锁文件）后重试。',
   failFileLockedHint: '安装过程中 pnpm 无法替换 profile 里的文件：有程序正占用着它（Windows 常见报错 os error 32「另一个程序正在使用此文件」）。通常是 DeepSeek Harness 自身或杀毒软件的实时扫描持有文件句柄。这不是插件本身的问题——请完全退出 DeepSeek Harness（Windows 可在任务管理器确认进程已结束，必要时临时关闭杀毒软件实时防护）后重试。',
   failAccessDeniedHint: '安装过程中 pnpm 写入 profile 里的文件被系统拒绝访问（Windows 常见报错 os error 5「拒绝访问」，英文为 Access is denied；Node 下的 EPERM / EACCES 同理）。常见原因是该文件或目录正被其他进程占用、文件带只读属性、目录权限受限，或杀毒软件实时防护拦截了写入——这与「文件正被占用」（os error 32）同属本机文件系统问题，任何插件装进该目录都会一样失败，不是插件本身的问题。请完全退出 DeepSeek Harness（Windows 可在任务管理器确认进程已结束，必要时临时关闭杀毒软件实时防护）后重试；若仍然失败，请检查 profile 目录及其文件是否被设为只读，并以管理员身份重新运行。',
   failFsUnavailableHint: '安装过程中 pnpm 无法把文件写进本机磁盘（这类报错与装哪个插件无关，任何插件装在同一目录都会失败，不是插件本身的问题）。请按报错对号入座：① 磁盘空间不足（ENOSPC / no space left on device，Windows 为 os error 112）——请清理 profile 所在磁盘的剩余空间后重试；② 磁盘或挂载点只读、带写保护（EROFS / read-only file system，Windows 为 os error 19）——请确认 profile 目录所在磁盘可写（外接盘/U 盘、带写保护的移动盘或只读挂载的分区都会触发），必要时把插件目录换到系统盘的可写位置；③ 进程可用的文件句柄被耗尽（EMFILE / ENFILE / too many open files）——请关闭占用大量文件的程序并重启 DeepSeek Harness 后重试。',
@@ -700,6 +703,10 @@ export const en = {
   failNpmMissingHint: 'The npm command could not be found (npm is not installed or not on the system PATH), so a global install cannot run. Please install Node.js (which bundles npm), make sure npm is on your PATH, then retry. This is not a problem with the plugin itself.',
   failPnpmStoreHint: 'pnpm reported an unexpected store location (ERR_PNPM_UNEXPECTED_STORE): the profile directory was previously set up with a different major version of pnpm, and the current pnpm refuses to reuse it — no plugin can be installed into that profile. Delete node_modules and pnpm-lock.yaml under the profile directory (see System Logs or ~/.dsh/profiles/<profile>/hub.log for the full output), then reinstall. This is not a problem with the plugin itself.',
   failPnpmUnusedPatchHint: 'pnpm reported that some patches were not used (ERR_PNPM_UNUSED_PATCH): your profile still holds a patch entry for an older dsh-plugin version (for example dsh-plugin@1.4.2), while this install resolved a different version, so pnpm aborts the whole install for safety — no plugin can be installed into that profile. This is not a problem with the plugin itself. Remove that dsh-plugin patch entry from pnpm-workspace.yaml (pnpm 11+) or from pnpm.patchedDependencies in package.json (pnpm 10) inside the profile directory (~/.dsh/profiles/<profile>), then retry.',
+  // Missing dependency: name the package that 404'd (the line is skipped when it cannot be parsed),
+  // then give the removal instructions
+  failPnpmMissingDepTarget: '{pkg} was not found on the npm registry (404)',
+  failPnpmMissingDepHint: 'pnpm reported that a package does not exist on the npm registry (ERR_PNPM_FETCH_404): your profile keeps a dependency on a package that was never published, and pnpm hits it every time it resolves dependencies — no plugin can be installed into that profile. This is not a problem with the plugin itself. Remove that dependency from package.json inside the profile directory (~/.dsh/profiles/<profile>) — along with its entry in pnpm-lock.yaml, or the lockfile itself — then retry.',
   failFileLockedHint: 'During install, pnpm could not replace a file inside the profile because another program is holding it (on Windows this shows as os error 32, "the process cannot access the file because it is being used by another process"). Usually DeepSeek Harness itself or a real-time antivirus scan holds the handle. This is not a problem with the plugin itself — fully quit DeepSeek Harness (on Windows, confirm in Task Manager that the process has ended, and temporarily disable real-time antivirus protection if needed), then retry.',
   failAccessDeniedHint: 'During install, Windows denied pnpm access to a file inside the profile (this shows as os error 5, "Access is denied"; on Node the equivalent codes are EPERM / EACCES). Typical causes: the file or directory is held by another process, the file is marked read-only, the directory permissions are restricted, or a real-time antivirus scan blocked the write. This is the same class of local file-system problem as a locked file (os error 32) — no plugin can be installed into that directory, so it is not a problem with the plugin itself. Fully quit DeepSeek Harness (on Windows, confirm in Task Manager that the process has ended, and temporarily disable real-time antivirus protection if needed), then retry. If it still fails, check whether the profile directory or its files are read-only and run as administrator.',
   failFsUnavailableHint: 'During install, pnpm could not write files to the local disk — this has nothing to do with which plugin you are installing: any plugin installed into the same directory would fail the same way, so it is not a problem with the plugin itself. Match the error you see: ① Out of space (ENOSPC / no space left on device, os error 112 on Windows) — free up space on the drive that holds the profile and retry. ② Read-only or write-protected volume (EROFS / read-only file system, os error 19 on Windows) — make sure the drive holding the profile directory is writable (external or USB drives, write-protected media, and read-only mounts all trigger this); move the plugin directory to a writable location on the system drive if needed. ③ File handles exhausted (EMFILE / ENFILE / too many open files) — close programs that hold many files open, restart DeepSeek Harness, then retry.',

package/src/client/logic/failures.ts

@@ -151,7 +151,7 @@ export function removeNotification(id: number): NotificationRecord[] {
   return next
 }
 
-export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'repo'
+export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'repo'
 
 /**
  * 失败归类：把安装输出归到具体成因，供弹窗文案、是否引导提 Issue 与 issue 预填原因使用。
@@ -191,6 +191,9 @@ export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissi
  * - pnpmUnusedPatch：profile 里留着指向旧版本 dsh-plugin 的 patch 声明，本次安装解析到的版本
  *   已经不是它（`ERR_PNPM_UNUSED_PATCH` / `The following patches were not used: dsh-plugin@1.4.2`）
  *   —— pnpm 发现补丁没被用上即中止整次安装 → 提示删掉该条目后重试
+ * - pnpmMissingDep：profile 里留着一条指向 registry 上不存在的包的依赖，pnpm 解析时收到 404
+ *   （`ERR_PNPM_FETCH_404` / `Not Found - 404`）—— 该 profile 的任何安装都会先卡在这条依赖上
+ *   → 提示按包名删掉该条目后重试（404 的包通常不是正在安装的插件，故不引导提 Issue）
  * - fileLocked：pnpm 无法替换 profile 里被其他进程占用的文件（Windows `os error 32`
  *   「另一个程序正在使用此文件」/ `EBUSY` / `resource busy or locked`）—— 通常是宿主进程或
  *   杀毒软件实时扫描持有句柄 → 提示完全退出宿主后重试
@@ -311,8 +314,18 @@ export function classifyFailure(message: string): FailureKind {
   // 装后校验拦截（服务端 verifyInstalledEntry 标记）：入口文件缺失 = git 分发缺构建产物，
   // 与 pluginPrepare 同类（插件打包/分发问题），引导去仓库提 Issue
   if (/\[packaging\]|entry file missing/i.test(message)) return 'pluginPrepare'
-  // 再判 prepare 实际执行失败：只有构建脚本真的跑挂了才是插件问题
-  if (/ERR_PNPM_PREPARE_PACKAGE|ELIFECYCLE|Command failed|prepare-guard/i.test(message)) return 'pluginPrepare'
+  // 依赖在 registry 上不存在（`ERR_PNPM_FETCH_404` / `Not Found - 404`）：pnpm 连得上 registry，
+  // 是被明确告知「这个包不存在」—— 属于 profile 的本地依赖问题，不是插件问题。profile 里留着
+  // 一条指向未发布包的依赖条目时，该 profile 的**任何**安装都会先卡在这条依赖上。
+  // 必须在 pluginPrepare 之前判定：此时宿主尾部只有通用的 `dsh: plugin command failed`，
+  // 落到下面会被当成构建失败。
+  // （两个形态：pnpm 的 `[ERR_PNPM_FETCH_404] GET <url>: Not Found - 404` 与 npm 的
+  //   `npm error 404 Not Found - GET <url> - Not found`）
+  if (/ERR_PNPM_FETCH_404|404 Not Found|Not Found - 404/i.test(message)) return 'pnpmMissingDep'
+  // 再判 prepare 实际执行失败：只有构建脚本真的跑挂了才是插件问题。
+  // `Command failed` 区分大小写 —— 只匹配 pnpm 包装出的报错，不匹配宿主那句小写的
+  // `dsh: plugin command failed`（那只是「这条命令失败了」的通用说明）。
+  if (/ERR_PNPM_PREPARE_PACKAGE|ELIFECYCLE|prepare-guard/i.test(message) || /Command failed/.test(message)) return 'pluginPrepare'
   // 其余失败（含 git prepare 被 pnpm 白名单拦截）：当前通道装不上 = 插件分发/依赖的问题，一律提 Issue
   return 'repo'
 }
@@ -371,12 +384,25 @@ export function summarizeError(message: string, maxChars: number = MAX_CORE_CHAR
   return out.length > maxChars ? `${out.slice(0, maxChars)}\n… (truncated)` : out
 }
 
-/** 提取首个错误代码（如 ERR_PNPM_PREPARE_PACKAGE），无则 null。 */
+/** 提取首个错误代码（如 ERR_PNPM_PREPARE_PACKAGE），无则 null。
+ *  代码里可能含数字（ERR_PNPM_FETCH_404 / ERR_PNPM_EBADPLATFORM_...），字符类需带上 0-9，
+ *  否则会被截断成 `ERR_PNPM_FETCH_`。 */
 export function coreErrorCode(message: string): string | null {
-  const m = message.match(/\[?ERR_[A-Z_]+\]?/)
+  const m = message.match(/\[?ERR_[A-Z0-9_]+\]?/)
   return m ? m[0].replace(/^\[|\]$/g, '') : null
 }
 
+/** 提取「registry 上不存在的包名」：从 404 行（`ERR_PNPM_FETCH_404 GET <registry>/<pkg>: Not Found - 404`）
+ *  里取请求路径中的包名（含 scope，如 `@scope/name`）；非 404 或提取不到返回 null。 */
+export function missingRegistryPackageOf(message: string): string | null {
+  for (const line of message.split(/\r?\n/)) {
+    if (!/ERR_PNPM_FETCH_404|404/.test(line)) continue
+    const m = line.match(/GET\s+https?:\/\/[^\s/]+\/((?:@[^/\s:]+\/)?[^/\s:]+)/)
+    if (m) return m[1]
+  }
+  return null
+}
+
 /**
  * 从网络类失败消息里提取「具体连不上的地址」，供弹窗精准提示（你的网络无法访问什么）。
  * 优先取服务端 [network] 预检消息括号里的探测地址（中文「（…）」/ 英文「(…)」），

package/src/client/logic/install-command.ts

@@ -4,20 +4,29 @@
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
  * Install target/command helpers: decide the install channel (npm package
- * vs explicit-HTTPS GitHub), build the display command and normalize a raw
- * install spec back to its owner/repo identity.
+ * vs prebuilt GitHub release vs explicit-HTTPS GitHub), build the display
+ * command and normalize a raw install spec back to its owner/repo identity.
  */
 import type { HubPlugin } from '../types.ts'
+import { githubReleaseTarget } from '../../server/services/install/release-target.ts'
 
 /**
  * 安装通道决策（用户无感知）：目录探测到 npm 包名 → 用 npm 包名安装
- * （走 npm registry tarball，更快、与 GitHub 网络无关）；无 npm 包名 → git 直装。
- * 返回值 target 即传给后端 /install 的安装目标（npm 包名 或 owner/repo）。
+ * （走 npm registry tarball，更快、与 GitHub 网络无关）；其次用「同仓库」的权威
+ * release 包直链（仓库 HEAD 往往是 monorepo 根、装不上，release .tgz 才是完整产物）；
+ * 都没有 → git 直装。
+ * 返回值 target 即传给后端 /install 的安装目标（npm 包名 / release URL / owner/repo）。
  */
-export function installTargetOf(p: HubPlugin): { target: string; via: 'npm' | 'github' } {
+export function installTargetOf(p: HubPlugin): { target: string; via: 'npm' | 'release' | 'github' } {
   const pkg = (p.source?.npmPackage ?? '').trim()
   const repo = (p.source?.repo ?? '').trim()
   if (pkg && repo) return { target: pkg, via: 'npm' }
+  // 目录下发的权威命令若是「同仓库」的固定 release 直链，改走该预构建包；
+  // 跨仓 / 非法 release 目标不采信，退回 git 直装。
+  const release = githubReleaseTarget(p.install?.githubCommand ?? '')
+  if (release !== null && repo !== '' && release.repo.toLowerCase() === repo.toLowerCase()) {
+    return { target: release.target, via: 'release' }
+  }
   return { target: repo, via: 'github' }
 }
 
@@ -30,12 +39,13 @@ export function installCommandOf(p: HubPlugin, withProfile = false): string {
     const cmd = p.install?.command
     if (cmd) return cmd
   } else {
+    // release 与 git 通道共用目录下发的 githubCommand（git+ 显式 HTTPS 或 release 直链）
     const cmd = p.install?.githubCommand
     if (cmd) return cmd
   }
-  return via === 'npm'
-    ? `dsh plugin${withProfile ? ' --profile web' : ''} add ${target}`
-    : `dsh plugin${withProfile ? ' --profile web' : ''} add git+https://github.com/${target}.git`
+  const prefix = `dsh plugin${withProfile ? ' --profile web' : ''} add `
+  if (via === 'npm' || via === 'release') return `${prefix}${target}`
+  return `${prefix}git+https://github.com/${target}.git`
 }
 
 /** Normalize a task/install target to its owner/repo display identity. */

package/src/client/logic/urls.ts

@@ -53,6 +53,7 @@ function reasonTitleOf(kind: FailureKind): string {
     case 'originRejected': return 'request origin rejected by the local service on the user machine'
     case 'pnpmPolicy': return 'pnpm supply-chain policy blocked the install on the user machine'
     case 'pnpmUnusedPatch': return 'stale pnpm patch entry on the user machine'
+    case 'pnpmMissingDep': return 'dependency not found on the npm registry on the user machine'
     case 'fileLocked': return 'file locked by another process on the user machine'
     case 'accessDenied': return 'file write access denied on the user machine'
     case 'fsUnavailable': return 'local file system unavailable on the user machine'

package/src/server/http/routes.ts

@@ -15,6 +15,7 @@ import { dirname, join, resolve } from 'node:path'
 import { spawn, spawnSync } from 'node:child_process'
 import { fetchViaCurl, gitLsRemote, probeUrl, systemProxy } from '../services/probe.ts'
 import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubRepoOf, githubTarget, globalNpmPackagesOf, hasQueuedTarget, installTargetOf, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName, type LoaderHandle } from '../services/install/install.ts'
+import { githubReleaseTarget } from '../services/install/release-target.ts'
 import { recordInstalledVersion, recordResolvedNpmPackage, readInstalledVersions, removeInstalledVersion } from '../services/profile/installed-versions.ts'
 import { resolveNpmPackage } from '../services/install/npm-resolve.ts'
 import { preflightTarget } from '../services/install/preflight.ts'
@@ -791,12 +792,14 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
             sendJson(response, 200, { ok: true, task: task.id })
             return
           }
-          // 目标语法两态：GitHub 地址（owner/repo、github:、https/ssh 链接等任意写法）→ 显式
-          // HTTPS Git 源（走装前预检）；npm 包名（@scope/name 或 name）→ 信任 registry 直接安装。
+          // 目标语法三态：固定 GitHub release .tgz（保留其包根目录，不转成仓库 HEAD）；
+          // GitHub 地址（owner/repo、github:、https/ssh 链接等任意写法）→ 显式 HTTPS Git 源
+          // （走装前预检）；npm 包名（@scope/name 或 name）→ 信任 registry 直接安装。
           // githubRepoOf 先把各种 GitHub 地址归一成 owner/repo，让「输入地址即装」兼容粘贴完整链接。
           const gitRepo = githubRepoOf(rawRepo)
-          const repoTarget = gitRepo !== null ? githubTarget(gitRepo) : null
-          let target: string | null = repoTarget ?? (validPackageName(rawRepo) ? rawRepo : null)
+          const release = githubReleaseTarget(rawRepo)
+          const repoTarget = gitRepo !== null && release === null ? githubTarget(gitRepo) : null
+          let target: string | null = release?.target ?? repoTarget ?? (validPackageName(rawRepo) ? rawRepo : null)
           if (target === null) {
             sendJson(response, 400, { error: 'unsupported install target' })
             return
@@ -825,9 +828,9 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
           }
           // 命令行安装（目录外）按通道门禁：GitHub 源码通道受「启用 GitHub 源码安装」控制，
           // npm 通道受「启用 NPM 安装」控制 —— 目录插件安装走目录白名单，不受开关影响。
-          // 通道判定看反查后的最终 target：仍是 git 目标 = 走 GitHub 源码，否则走 npm。
+          // 通道判定看反查后的最终 target：release 包与 git 目标同属 GitHub 通道，否则走 npm。
           if (source !== 'catalog') {
-            const isGitChannel = repoTarget !== null && target === repoTarget
+            const isGitChannel = release !== null || (repoTarget !== null && target === repoTarget)
             if (isGitChannel && !settings.enableGitInstall) {
               sendJson(response, 403, { error: 'git installs are disabled by the security settings' })
               return
@@ -863,8 +866,12 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
             const effectiveProxy = settings.proxy !== ''
               ? settings.proxy
               : (systemProxy() ?? process.env.HTTPS_PROXY ?? process.env.https_proxy ?? '')
-            const isGitChannel = repoTarget !== null && target === repoTarget
-            const npmProbeTarget = `${(settings.npmRegistry.replace(/\/+$/, '') || 'https://registry.npmjs.org')}/`
+            const isGitChannel = release !== null || (repoTarget !== null && target === repoTarget)
+            // release 包是 https://github.com/ 直链下载（非 git 克隆），探针按 HTTP 打 github.com 主页；
+            // npm 通道探 registry 根。两者都是通道的稳定入口，不探具体包/仓库（404 会被误判成网络故障）。
+            const httpProbeTarget = release !== null
+              ? 'https://github.com/'
+              : `${(settings.npmRegistry.replace(/\/+$/, '') || 'https://registry.npmjs.org')}/`
             // git 通道的探针换成克隆握手本身：git ls-remote 走的就是 pnpm 克隆前的同一套
             // https 传输。curl 打 github.com 主页会被按协议/端口区分的防火墙与 TLS 复检
             // 拦截（能 git 克隆、打不开网页），把可装的仓库误判成 [network] 而中止
@@ -880,9 +887,9 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
                 if (reachable.ok) net = reachable
               }
             } else {
-              net = await probeUrl(npmProbeTarget, effectiveProxy, 6000)
+              net = await probeUrl(httpProbeTarget, effectiveProxy, 6000)
             }
-            const probeTarget = gitProbeTarget ?? npmProbeTarget
+            const probeTarget = gitProbeTarget ?? httpProbeTarget
             if (!net.ok) {
               // 错误消息按客户端界面语言提示：中文界面给中文、英文界面给英文，
               // 让用户一眼看懂是网络问题而非插件问题