dsh-plugin 1.4.13 → 1.5.0

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.13",
+  "version": "1.5.0",
   "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

@@ -310,8 +310,7 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                     if (kind === 'pnpmMissingDep') {
                       // profile 里留着指向 registry 上不存在（404）的包的依赖：pnpm 连得上 registry，
                       // 是被明确告知包不存在 —— 该 profile 的任何安装都会先卡在这条依赖上，与本次要装的
-                      // 插件无关（#73 的 issue 就是这么被误挂到正在安装的插件上的）→ 点名缺失的包 +
-                      // 删除条目指引，不引导提 Issue
+                      // 插件无关 → 点名缺失的包 + 删除条目指引，不引导提 Issue
                       const pkg = missingRegistryPackageOf(r.message)
                       return h('div', null, [
                         pkg ? h('div', { className: styles.failNetworkTarget }, t('failPnpmMissingDepTarget', { pkg })) : null,

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

@@ -424,8 +424,7 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
               : failureKind === 'pnpmMissingDep'
               // profile 里留着指向 registry 上不存在（404）的包的依赖：pnpm 连得上 registry，
               // 是被明确告知包不存在 —— 该 profile 的任何安装都会先卡在这条依赖上，与本次要装的
-              // 插件无关（#73 的 issue 就是这么被误挂到正在安装的插件上的）→ 点名缺失的包 +
-              // 删除条目指引，不引导提 Issue
+              // 插件无关 → 点名缺失的包 + 删除条目指引，不引导提 Issue
               ? h('div', null, [
                 (() => {
                   const pkg = missingRegistryPackageOf(message)

package/src/client/logic/failures.ts

@@ -315,17 +315,16 @@ export function classifyFailure(message: string): FailureKind {
   // 与 pluginPrepare 同类（插件打包/分发问题），引导去仓库提 Issue
   if (/\[packaging\]|entry file missing/i.test(message)) return 'pluginPrepare'
   // 依赖在 registry 上不存在（`ERR_PNPM_FETCH_404` / `Not Found - 404`）：pnpm 连得上 registry，
-  // 是被明确告知「这个包不存在」—— 不是插件问题。profile 里留着一条指向未发布包的依赖条目时，
-  // 该 profile 的**任何**安装都会先卡在这条依赖上（宿主尾部只有 `dsh: plugin command failed`）。
-  // 必须在 pluginPrepare 之前：否则该尾部会被下面的 `Command failed` 判定吞成
-  // 「插件分发不完整」，把 Issue 误挂到正在安装的插件上，而不是 404 的那个依赖（#73）
+  // 是被明确告知「这个包不存在」—— 属于 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` 区分大小写：宿主尾部提示是小写的 `dsh: plugin command failed`，
-  //   那只是「这条命令失败了」的通用说明 —— 带 /i 会让任何带该尾部的未知失败都被判成
-  //   「插件分发不完整」，把 Issue 误挂到正在安装的插件上，见 #73）
+  // 再判 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'
@@ -386,16 +385,15 @@ export function summarizeError(message: string, maxChars: number = MAX_CORE_CHAR
 }
 
 /** 提取首个错误代码（如 ERR_PNPM_PREPARE_PACKAGE），无则 null。
- *  代码里可能含数字（ERR_PNPM_FETCH_404 / ERR_PNPM_EBADPLATFORM_...），字符类必须带上 0-9，
- *  否则会被截成 `ERR_PNPM_FETCH_`（#73 的 issue 正文就是这么被截断的）。 */
+ *  代码里可能含数字（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-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。
- *  调用方据此在提示里点名具体是哪个依赖缺失 —— 光说「有个包 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

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,17 +39,22 @@ 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. */
 export function repoFromInstallTarget(value: string): string {
   const input = value.trim()
+  // release 直链（预构建 .tgz）走同一条身份归一化：解析出所属仓库，已装态/更新信号才能
+  // 认回目录条目；仅接受固定形态直链，跨仓/非法目标不接受，继续走下面的常规解析。
+  const release = githubReleaseTarget(input)
+  if (release !== null) return release.repo
   if (/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(input)) return input
   const patterns = [
     /^github:([^/]+)\/([^/]+)$/i,

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) {
               // 错误消息按客户端界面语言提示：中文界面给中文、英文界面给英文，
               // 让用户一眼看懂是网络问题而非插件问题

package/src/server/services/install/npm-resolve.ts

@@ -18,6 +18,8 @@ const cache = new Map<string, string | null>()
 
 /** 单次 registry 查询超时（ms）：慢网络下失败返回 null，不阻塞安装流程。 */
 const REQUEST_TIMEOUT_MS = 8000
+/** npm search 是相关性搜索而非 repository 精确索引；拉满单页结果后再本地做严格 repo 过滤。 */
+const SEARCH_RESULT_LIMIT = 250
 
 /**
  * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
@@ -39,13 +41,49 @@ export function resolveNpmPackage(repo: string, registry = ''): Promise<string |
   return name.then((found) => found ?? null)
 }
 
+type NpmSearchPackage = {
+  name?: unknown
+  keywords?: unknown
+  links?: { repository?: unknown }
+  repository?: { url?: unknown }
+}
+
+type NpmSearchObject = { package?: NpmSearchPackage }
+type NpmSearchResponse = { objects?: NpmSearchObject[] }
+
+/**
+ * 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: NpmSearchObject[], repo: string): string | null {
+  const needle = `github.com/${repo}`.toLowerCase()
+  const matches: Array<{ name: string; isDshPlugin: boolean }> = []
+
+  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: string, registry: string): Promise<string | null | undefined> {
   const [owner, name] = repo.split('/')
   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 +95,8 @@ function searchRepo(repo: string, registry: string): Promise<string | null | und
       res.on('data', (chunk: Buffer) => { body += chunk.toString() })
       res.on('end', () => {
         try {
-          const data = JSON.parse(body) as { objects?: Array<{ package?: { name?: unknown; links?: { repository?: unknown }; repository?: { url?: unknown } } }> }
-          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)
+          const data = JSON.parse(body) as NpmSearchResponse
+          resolve(selectNpmPackageForRepo(data.objects ?? [], `${owner}/${name}`))
         } catch {
           resolve(undefined)
         }

package/src/server/services/install/preflight.ts

@@ -18,6 +18,7 @@ import { join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 import { promisify } from 'node:util'
 import { githubRepoOf } from '../profile/profile.ts'
+import { githubReleaseTarget } from './release-target.ts'
 import { resolvePackageEntry } from './package-entry.ts'
 
 const execFileAsync = promisify(execFile)
@@ -37,6 +38,9 @@ export interface PreflightResult {
 }
 
 export async function preflightTarget(target: string): Promise<PreflightResult> {
+  // 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 }
   const [owner, repo] = source.split('/')