dsh-plugin 1.5.0 → 1.5.1

package/lib/http/routes.js

@@ -16,7 +16,7 @@ import { fetchViaCurl, gitLsRemote, probeUrl, systemProxy } from '../services/pr
 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 { isDshNpmPackageForRepo, resolveNpmPackage } from '../services/install/npm-resolve.js';
 import { preflightTarget } from '../services/install/preflight.js';
 import { isDshPlugin, isEntryLoaded } from '../services/loader.js';
 import { loadSettings, saveSettings, resetSettings } from '../services/settings.js';
@@ -814,13 +814,40 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                         sendJson(response, 400, { error: 'unsupported install target' });
                         return;
                     }
+                    const attempts = [];
+                    // Catalog metadata may outlive a packaging split: one repository can publish both a
+                    // CLI/helper package and a dedicated DSH plugin package. Keep the catalog target when
+                    // registry metadata confirms it is a DSH package for this repo. Otherwise inspect the
+                    // repository root package.json and use its package name only when that exact registry
+                    // package also points back to the repo and identifies as a DSH plugin. This avoids
+                    // relying on npm search ranking, which is not a repository index and can omit the
+                    // correct package even with a large result window.
+                    const catalogRepo = source === 'catalog' ? githubRepoOf(displayRepo) : null;
+                    if (catalogRepo !== null && release === null && repoTarget === null && validPackageName(rawRepo)) {
+                        const catalogTargetIsDsh = await isDshNpmPackageForRepo(rawRepo, catalogRepo, settings.npmRegistry);
+                        if (catalogTargetIsDsh) {
+                            recordResolvedNpmPackage(profile, catalogRepo, rawRepo);
+                        }
+                        else {
+                            const catalogGitTarget = githubTarget(catalogRepo);
+                            if (catalogGitTarget !== null) {
+                                const root = await preflightTarget(catalogGitTarget);
+                                const rootName = root.ok && root.name !== null && validPackageName(root.name) ? root.name : null;
+                                if (rootName !== null && rootName !== rawRepo
+                                    && await isDshNpmPackageForRepo(rootName, catalogRepo, settings.npmRegistry)) {
+                                    attempts.push(`catalog npm target: \`${target}\` → repository root DSH package \`${rootName}\``);
+                                    target = rootName;
+                                    recordResolvedNpmPackage(profile, catalogRepo, rootName);
+                                }
+                            }
+                        }
+                    }
                     // npm 优先：git 目标先反查该仓库的官方 npm 包，命中则改走 npm 通道。
                     // git 分发常缺构建产物/子模块，npm 包是作者发布的完整产物；未命中或
                     // 查询失败保留 github 直装（不阻塞安装，预检仍会拦截缺入口文件的情况）。
                     // 通用机制，不针对具体插件。
                     // 反查本身计入「已尝试的安装方式」：组织 scope 与 GitHub 用户名不一致时仅凭
                     // 仓库名猜不到包名，失败提 Issue 时作者看到我们查过的命令就能直接指认正确包名。
-                    const attempts = [];
                     if (repoTarget !== null) {
                         // 反查/记录统一用归一化后的 owner/repo（gitRepo），保证「输入完整链接」也走同一套 npm 反查
                         const repoIdentity = gitRepo ?? rawRepo;

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

@@ -12,6 +12,7 @@
  * 避免同一会话内重复查询 registry。
  */
 import { get } from 'node:https';
+import { githubRepoOf } from '../profile/profile.js';
 /** 反查缓存：repo 小写 → npm 包名（null 表示已确认无对应 npm 包；网络异常不缓存）。 */
 const cache = new Map();
 /** 单次 registry 查询超时（ms）：慢网络下失败返回 null，不阻塞安装流程。 */
@@ -46,15 +47,59 @@ export function resolveNpmPackage(repo, registry = '') {
  * 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();
+function repositoryUrlOf(pkg) {
+    if (typeof pkg.repository === 'string')
+        return pkg.repository;
+    if (pkg.repository !== null && typeof pkg.repository === 'object') {
+        const url = pkg.repository.url;
+        if (typeof url === 'string')
+            return url;
+    }
+    return String(pkg.links?.repository ?? '');
+}
+export function isDshPackageMetadataForRepo(pkg, repo) {
+    if (githubRepoOf(repositoryUrlOf(pkg))?.toLowerCase() !== repo.toLowerCase())
+        return false;
+    const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : [];
+    const keywordMarked = keywords.some((keyword) => typeof keyword === 'string' && keyword.toLowerCase() === 'dsh-plugin');
+    const manifestMarked = pkg.dsh !== null && typeof pkg.dsh === 'object';
+    return keywordMarked || manifestMarked;
+}
+export function isDshNpmPackageForRepo(packageName, repo, registry = '') {
+    if (packageName === '' || repo === '')
+        return Promise.resolve(false);
+    const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '');
+    const url = `${base}/${encodeURIComponent(packageName)}/latest`;
+    return new Promise((resolve) => {
+        const req = get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(false);
+                return;
+            }
+            let body = '';
+            res.on('data', (chunk) => { body += chunk.toString(); });
+            res.on('end', () => {
+                try {
+                    resolve(isDshPackageMetadataForRepo(JSON.parse(body), repo));
+                }
+                catch {
+                    resolve(false);
+                }
+            });
+        });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => resolve(false));
+    });
+}
+function matchingPackagesForRepo(objects, repo) {
     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))
+        const repoUrl = repositoryUrlOf(pkg);
+        if (githubRepoOf(repoUrl)?.toLowerCase() !== repo.toLowerCase())
             continue;
         const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : [];
         matches.push({
@@ -62,6 +107,10 @@ export function selectNpmPackageForRepo(objects, repo) {
             isDshPlugin: keywords.some((keyword) => typeof keyword === 'string' && keyword.toLowerCase() === 'dsh-plugin'),
         });
     }
+    return matches;
+}
+export function selectNpmPackageForRepo(objects, repo) {
+    const matches = matchingPackagesForRepo(objects, repo);
     return matches.find((candidate) => candidate.isDshPlugin)?.name ?? matches[0]?.name ?? null;
 }
 /** 用 npm search 接口按 repository 地址反查，并做铁证校验（包元数据必须指向该仓库）。

package/lib/services/install/preflight.js

@@ -50,11 +50,15 @@ export async function preflightTarget(target) {
     try {
         const tar = join(dir, 'pkg.tar.gz');
         await download(`https://codeload.github.com/${owner}/${repo}/tar.gz/${commit}`, tar);
-        const meta = await readTarJson(tar, 'package/package.json');
+        const rootPackage = await rootPackageEntry(tar);
+        if (rootPackage === null)
+            return { ok: true, missing: null, name: null };
+        const rootPrefix = rootPackage.slice(0, -'package.json'.length);
+        const meta = await readTarJson(tar, rootPackage);
         if (meta === null)
             return { ok: true, missing: null, name: null };
         const entry = resolvePackageEntry(meta);
-        const inTar = await hasTarEntry(tar, `package/${entry}`);
+        const inTar = await hasTarEntry(tar, `${rootPrefix}${entry}`);
         return { ok: inTar, missing: inTar ? null : entry, name: typeof meta.name === 'string' ? meta.name : null };
     }
     catch {
@@ -88,6 +92,25 @@ function download(url, dest) {
         req.on('error', reject);
     });
 }
+/** GitHub codeload tarballs use a dynamic top-level directory (`repo-<sha>/`),
+ * not npm's `package/` prefix. Pick only a package.json directly under that
+ * single archive root; nested monorepo package manifests are intentionally
+ * ignored. Exported for a small parser regression test. */
+export function rootPackageEntryOfTarList(listing) {
+    const candidates = listing
+        .split(/\r?\n/)
+        .filter((line) => /^[^/]+\/package\.json$/u.test(line));
+    return candidates.length === 1 ? candidates[0] : null;
+}
+async function rootPackageEntry(tar) {
+    try {
+        const { stdout } = await execFileAsync('tar', ['-tzf', tar], { maxBuffer: 16 * 1024 * 1024 });
+        return rootPackageEntryOfTarList(stdout);
+    }
+    catch {
+        return null;
+    }
+}
 /** 从 tarball 提取并解析一个 JSON 文件；文件不存在或解析失败返回 null。 */
 async function readTarJson(tar, entry) {
     try {

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

@@ -15,19 +15,13 @@ type NpmSearchPackage = {
     links?: {
         repository?: unknown;
     };
-    repository?: {
-        url?: unknown;
-    };
+    repository?: unknown;
+    dsh?: 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 isDshPackageMetadataForRepo(pkg: NpmSearchPackage, repo: string): boolean;
+export declare function isDshNpmPackageForRepo(packageName: string, repo: string, registry?: string): Promise<boolean>;
 export declare function selectNpmPackageForRepo(objects: NpmSearchObject[], repo: string): string | null;
 export {};

package/lib/types/services/install/preflight.d.ts

@@ -8,3 +8,8 @@ export interface PreflightResult {
     name: string | null;
 }
 export declare function preflightTarget(target: string): Promise<PreflightResult>;
+/** GitHub codeload tarballs use a dynamic top-level directory (`repo-<sha>/`),
+ * not npm's `package/` prefix. Pick only a package.json directly under that
+ * single archive root; nested monorepo package manifests are intentionally
+ * ignored. Exported for a small parser regression test. */
+export declare function rootPackageEntryOfTarList(listing: string): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "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/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, missingRegistryPackageOf, npmTooLowVersion, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { classifyFailure, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, 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'
@@ -300,7 +300,7 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                     if (kind === 'pnpmPolicy') {
                       // pnpm 11 供应链安全策略拦截（minimumReleaseAge 拒收发布太新的包 / untrusted origin）：
                       // 本机 pnpm 策略不放行，装任何「刚发布/新来源」插件都撞墙 —— 给豁免指引，不引导提 Issue
-                      return h('div', { className: styles.failPrepareHint }, t('failPnpmPolicyHint'))
+                      return h('div', { className: styles.failPrepareHint }, t(pnpmPolicyHintOf(r.message)))
                     }
                     if (kind === 'pnpmUnusedPatch') {
                       // profile 里留着指向旧版本 dsh-plugin 的补丁声明（ERR_PNPM_UNUSED_PATCH）：pnpm

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, missingRegistryPackageOf, npmTooLowVersion, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { classifyFailure, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述；
  *  needsRestart=true（插件需重启才生效）→ 「稍后重启 / 立即重启」按钮对，点稍后重启后
@@ -416,7 +416,7 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
               : failureKind === 'pnpmPolicy'
               // pnpm 11 供应链安全策略拦截（minimumReleaseAge 拒收发布太新的包 / untrusted origin）：
               // 本机 pnpm 策略不放行，装任何「刚发布/新来源」插件都撞墙 —— 给豁免指引，不引导提 Issue
-              ? h('div', { className: styles.failPrepareHint }, t('failPnpmPolicyHint'))
+              ? h('div', { className: styles.failPrepareHint }, t(pnpmPolicyHintOf(message)))
               : failureKind === 'pnpmUnusedPatch'
               // profile 里留着指向旧版本 dsh-plugin 的补丁声明（ERR_PNPM_UNUSED_PATCH）：pnpm 发现
               // 补丁没被用上就中止整次安装，任何插件都装不进来 —— 给删除条目的指引，不引导提 Issue

package/src/client/hooks/useTaskQueue.ts

@@ -11,7 +11,7 @@
  */
 import { useEffect, useRef, useState } from 'react'
 import type { HubPlugin, InstallChannel, LocaleId, Translate } from '../types.ts'
-import { installCommandOf, installTargetOf, repoFromInstallTarget } from '../logic/install-command.ts'
+import { executedCommandOf, installCommandOf, installTargetOf, repoFromInstallTarget } from '../logic/install-command.ts'
 import type { InstalledItem } from '../logic/installed.ts'
 
 /** 安装/卸载请求超时（ms）：服务端 preflight + npm 反查可能耗时（各自都有超时，合计约 20~30s），
@@ -222,7 +222,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
         : q.kind === 'uninstall' ? t('uninstallFail') : t('installFail')
       // 自定义安装（带入口渠道）：错误正文顶部精准提示「从哪张卡片发起」，目录安装保持原样
       const entry = entryLineOf(t, q.channel)
-      onError(entry ? `${entry}\n${rawDetail}` : rawDetail, q.repo, q.kind, q.command, q.attempts, q.action === 'update')
+      onError(entry ? `${entry}\n${rawDetail}` : rawDetail, q.repo, q.kind, executedCommandOf(q.command, q.attempts), q.attempts, q.action === 'update')
     }
     maybeStopPoll()
   }

package/src/client/locales.ts

@@ -333,6 +333,7 @@ export const zh = {
   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 后重试。',
   failPnpmWorkspaceHint: '安装器调用 pnpm 时报「不能把依赖装到 workspace 根目录」（ERR_PNPM_ADDING_TO_ROOT）：你的 profile 目录被 pnpm 视为 workspace 根目录，而本次安装命令没有声明在根目录操作，pnpm 直接拒绝执行，因此任何插件装进来都会失败。这不是插件本身的问题——可在 profile 目录（~/.dsh/profiles/<profile>）的 .npmrc 里加一行 ignore-workspace-root-check=true 后重试，或把 DeepSeek Harness 升级到最新版再试。',
+  failPnpmTarballIntegrityHint: 'pnpm 报 ERR_PNPM_MISSING_TARBALL_INTEGRITY：锁文件中的 tarball 条目没有校验值，无法验证下载的包。先查看完整日志，完全退出 DeepSeek Harness，并检查、备份当前 profile 的 package.json、pnpm-lock.yaml 和 pnpm-workspace.yaml。确认依赖来源后，将 pnpm-lock.yaml 改名保留，再通过同一 DSH 安装器安装适配当前宿主版本的插件，重新生成锁文件。重建会重新解析 profile 依赖，请核对新旧版本；保持完整性校验开启。',
   failPnpmPolicyHint: '安装器调用 pnpm 时被其供应链安全策略拦截——装任何插件都会撞墙，不是插件本身的问题。分两种情况处理：① 提示「Minimum release age」（ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION）：包发布还不满 24 小时，pnpm 11 出于安全会拒收这种刚发布的新包。可在 pnpm 配置（pnpm-workspace.yaml）里加 minimumReleaseAge: 0 豁免，或等满 24 小时后重试。② 提示「untrusted origin」（ERR_PNPM_UNTRUSTED_ORIGIN）：依赖来源不被本机 pnpm 信任，通常是该 profile 里之前用 github: 或非官方 npm 源装过插件，锁文件记录了不受信任的来源。请删除该 profile 目录下的 node_modules 与 pnpm-lock.yaml 后重新安装（可先到「系统日志」或 ~/.dsh/profiles/<profile>/hub.log 查看完整报错）。',
   // 自定义安装三卡片入口的渠道名（报错/日志溯源：本次安装从哪个入口发起）
   installChannelNpm: 'NPM 包',
@@ -711,6 +712,7 @@ export const en = {
   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.',
   failPnpmWorkspaceHint: 'pnpm refused to add the dependency to the workspace root (ERR_PNPM_ADDING_TO_ROOT): the profile directory is treated as a pnpm workspace root, and this install command did not declare that it operates at the root, so pnpm rejected it outright — no plugin can be installed into that profile. This is not a problem with the plugin itself. Add `ignore-workspace-root-check=true` to the `.npmrc` inside the profile directory (~/.dsh/profiles/<profile>) and retry, or upgrade DeepSeek Harness and try again.',
+  failPnpmTarballIntegrityHint: 'pnpm reported ERR_PNPM_MISSING_TARBALL_INTEGRITY: a tarball entry in the lockfile has no checksum to verify the downloaded package. Read the full log, fully quit DeepSeek Harness, and inspect and back up package.json, pnpm-lock.yaml and pnpm-workspace.yaml in the affected profile. Once the dependency sources are verified, rename pnpm-lock.yaml to preserve it, then use the same DSH installer to install a plugin version compatible with the host and regenerate the lockfile. This resolves profile dependencies again: compare the old and new versions, and keep integrity checks enabled.',
   failPnpmPolicyHint: 'The installer was blocked by pnpm supply-chain security policy — every plugin install would hit the same wall, so this is not a problem with the plugin itself. Two cases: ① "Minimum release age" (ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION): the package was published less than 24 hours ago, and pnpm 11 refuses freshly-published packages for safety. Add minimumReleaseAge: 0 to your pnpm config (pnpm-workspace.yaml) to opt out, or wait until the 24 hours have passed and retry. ② "untrusted origin" (ERR_PNPM_UNTRUSTED_ORIGIN): a dependency source is not trusted by this machine, usually because plugins were previously installed via github: or a non-official npm registry, so the lockfile records an untrusted source. 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.',
   // Custom install entry channel names (the three cards) — used in error/log traceability
   installChannelNpm: 'NPM package',

package/src/client/logic/failures.ts

@@ -153,6 +153,16 @@ export function removeNotification(id: number): NotificationRecord[] {
 
 export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'repo'
 
+/** Match the pnpm error code, not a generic mention of checksum or integrity. */
+function missingTarballIntegrity(message: string): boolean {
+  return /\bERR_PNPM_MISSING_TARBALL_INTEGRITY\b/.test(message)
+}
+
+/** The same policy subtype selects recovery copy in live and saved failures. */
+export function pnpmPolicyHintOf(message: string): 'failPnpmTarballIntegrityHint' | 'failPnpmPolicyHint' {
+  return missingTarballIntegrity(message) ? 'failPnpmTarballIntegrityHint' : 'failPnpmPolicyHint'
+}
+
 /**
  * 失败归类：把安装输出归到具体成因，供弹窗文案、是否引导提 Issue 与 issue 预填原因使用。
  * 分界是「本机环境问题」（装任何插件都会同样失败 → 不引导提 Issue）与
@@ -183,7 +193,7 @@ export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissi
  * - originRejected：请求的来源没通过本地 hub 服务的校验（服务端 403，正文是裸的
  *   `untrusted origin`）—— 请求在进入安装流程前就被拒，与 pnpm 无关；常见于用非 localhost 的
  *   地址（如局域网 IP）打开市场页面，或宿主页面的 origin 未被识别 → 提示从本机地址打开市场后重试
- * - pnpmPolicy：pnpm 11 的供应链安全策略拒绝安装（`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` /
+ * - pnpmPolicy：pnpm 的供应链安全策略拒绝安装（缺少 tarball integrity、`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` /
  *   `Minimum release age` —— 锁文件里包的发布时间还不满 24 小时被拒；`untrusted origin` ——
  *   依赖来源未被本机 pnpm 信任）→ 提示按子场景给解法（发布未满 24 小时 → `minimumReleaseAge: 0`
  *   豁免或等满 24 小时；untrusted origin → 删除 profile 的 node_modules + pnpm-lock.yaml 清掉
@@ -266,11 +276,11 @@ export function classifyFailure(message: string): FailureKind {
   // 用「整行以它结尾」来区隔 pnpm 的真实报错：pnpm 的形态后面一定跟着 dsh 的上下文
   // （如 `untrusted origin\ndsh: pnpm failed in profile directory …`），不会被本规则命中
   if (/(^|\n)untrusted origin\s*$/.test(message)) return 'originRejected'
-  // pnpm 供应链安全策略拦截（pnpm 11：minimumReleaseAge 拒收「刚发布」的包 /
+  // pnpm 供应链安全策略拦截（缺少 tarball 校验值 / minimumReleaseAge 拒收「刚发布」的包 /
   // untrusted origin 来源不受信任）：pnpm 在、也连得上，纯粹是本机策略不放行 ——
   // 装任何「新发布/非信任来源」的插件都会同样失败。
   // 必须在 pnpmIgnoredBuild 之前 —— 该策略优先于「构建脚本被白名单拦截」，且两者都不引导提 Issue。
-  if (/ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|Minimum release age|untrusted origin/i.test(message)) return 'pnpmPolicy'
+  if (missingTarballIntegrity(message) || /ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|Minimum release age|untrusted origin/i.test(message)) return 'pnpmPolicy'
   // profile 里留着指向旧版本 dsh-plugin 的 patch 声明（ERR_PNPM_UNUSED_PATCH /
   // `The following patches were not used: dsh-plugin@1.4.2`）：本机 pnpm 配置与本次解析到的版本
   // 对不上，pnpm 出于安全直接中止整次安装 —— 任何插件都装不进来 → 提示删条目后重试。

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

@@ -10,6 +10,16 @@
 import type { HubPlugin } from '../types.ts'
 import { githubReleaseTarget } from '../../server/services/install/release-target.ts'
 
+/** Backend attempts are chronological; report the last executed command before a display fallback.
+ * These prefixes are the task queue's recorded command shapes, never commands to execute here.
+ */
+export function executedCommandOf(command?: string, attempts?: string[]): string | undefined {
+  if (attempts === undefined) return command
+  return attempts.slice().reverse().find((attempt) =>
+    /^dsh plugin --profile(?:=| )\S+ (?:add|remove|update) \S/.test(attempt)
+    || /^npm install -g \S/.test(attempt))
+}
+
 /**
  * 安装通道决策（用户无感知）：目录探测到 npm 包名 → 用 npm 包名安装
  * （走 npm registry tarball，更快、与 GitHub 网络无关）；其次用「同仓库」的权威

package/src/client/logic/urls.ts

@@ -9,7 +9,8 @@
  */
 import type { EnvInfo, HubPlugin, LocaleId } from '../types.ts'
 import { GITHUB_URL, PLUGIN_VERSION, SITE_URL } from './constants.ts'
-import { MAX_CORE_CHARS, classifyFailure, coreErrorCode, summarizeError } from './failures.ts'
+import { MAX_CORE_CHARS, classifyFailure, coreErrorCode, pnpmPolicyHintOf, summarizeError } from './failures.ts'
+import { executedCommandOf } from './install-command.ts'
 import type { FailureKind } from './failures.ts'
 
 /** dsh-plugin.org 中文页挂在 /zh/ 前缀下，英文在根路径。 */
@@ -78,6 +79,7 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
   // [packaging]（预检/装后校验拦截）单独列：无论走 npm 还是 git 通道，都是分发物不完整
   // （package.json 声明的入口文件在发布物里缺失），作者照此补齐即可。
   const kind = classifyFailure(message)
+  const executed = executedCommandOf(command, attempts)
   // 标题 = 错误原因（非动作词），让 issue 列表一眼可分流
   const title = `[dsh-plugin.org | dsh-plugin-hub] ${reasonTitleOf(kind)}: ${repo}`
   const reason = /\[packaging\]/i.test(message)
@@ -91,7 +93,9 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
             : kind === 'originRejected'
                 ? 'the request never reached the install flow — the local service rejected its origin (local environment issue)'
                 : kind === 'pnpmPolicy'
-                ? 'the pnpm supply-chain policy on the user machine blocked the install (minimum release age for freshly published packages / untrusted origin)'
+                ? pnpmPolicyHintOf(message) === 'failPnpmTarballIntegrityHint'
+                  ? 'pnpm rejected a lockfile entry without tarball integrity; inspect and back up the profile lockfile before resolving it again, keeping integrity checks enabled'
+                  : 'the pnpm supply-chain policy on the user machine blocked the install (minimum release age for freshly published packages / untrusted origin)'
                 : kind === 'pnpmUnusedPatch'
                   ? 'the profile keeps a pnpm patch entry for an older dsh-plugin version, so pnpm aborted the install (local config issue)'
                   : kind === 'fileLocked'
@@ -112,7 +116,7 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
       // 来源说明：标题（链官网）+ 一句来源（链仓库）+ 实际执行的安装命令（含 --profile）与执行结果，链接由常量动态拼接
       `## [DSH Plugin 插件市场](${SITE_URL}) · 安装 Plugin 失败错误信息`,
       `本错误信息由 [dsh-plugin-hub](${GITHUB_URL}) 插件市场的安装程序自动生成，随本次安装失败一并提交。`,
-      `- 实际执行的安装命令：\`${command ?? `dsh plugin${env?.profile ? ` --profile ${env.profile}` : ''} add git+https://github.com/${repo}.git`}\``,
+      `- 实际执行的安装命令：${executed ? `\`${executed}\`` : 'unknown (no executed command recorded)'}`,
       `- 执行结果：安装失败，未能安装该插件。`,
       // 尝试过的安装方式（npm 反查 + 实际执行命令，按先后顺序）：作者据此反推正确的
       // npm 包名 —— 组织 scope 与 GitHub 用户名不一致时仅凭仓库名猜不到，作者看到我们
@@ -176,4 +180,3 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
   }
   return url
 }
-

package/src/server/http/routes.ts

@@ -17,7 +17,7 @@ import { fetchViaCurl, gitLsRemote, probeUrl, systemProxy } from '../services/pr
 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 { isDshNpmPackageForRepo, resolveNpmPackage } from '../services/install/npm-resolve.ts'
 import { preflightTarget } from '../services/install/preflight.ts'
 import { isDshPlugin, isEntryLoaded } from '../services/loader.ts'
 import { loadSettings, saveSettings, resetSettings, type HubSettings } from '../services/settings.ts'
@@ -804,13 +804,39 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
             sendJson(response, 400, { error: 'unsupported install target' })
             return
           }
+          const attempts: string[] = []
+          // Catalog metadata may outlive a packaging split: one repository can publish both a
+          // CLI/helper package and a dedicated DSH plugin package. Keep the catalog target when
+          // registry metadata confirms it is a DSH package for this repo. Otherwise inspect the
+          // repository root package.json and use its package name only when that exact registry
+          // package also points back to the repo and identifies as a DSH plugin. This avoids
+          // relying on npm search ranking, which is not a repository index and can omit the
+          // correct package even with a large result window.
+          const catalogRepo = source === 'catalog' ? githubRepoOf(displayRepo) : null
+          if (catalogRepo !== null && release === null && repoTarget === null && validPackageName(rawRepo)) {
+            const catalogTargetIsDsh = await isDshNpmPackageForRepo(rawRepo, catalogRepo, settings.npmRegistry)
+            if (catalogTargetIsDsh) {
+              recordResolvedNpmPackage(profile, catalogRepo, rawRepo)
+            } else {
+              const catalogGitTarget = githubTarget(catalogRepo)
+              if (catalogGitTarget !== null) {
+                const root = await preflightTarget(catalogGitTarget)
+                const rootName = root.ok && root.name !== null && validPackageName(root.name) ? root.name : null
+                if (rootName !== null && rootName !== rawRepo
+                    && await isDshNpmPackageForRepo(rootName, catalogRepo, settings.npmRegistry)) {
+                  attempts.push(`catalog npm target: \`${target}\` → repository root DSH package \`${rootName}\``)
+                  target = rootName
+                  recordResolvedNpmPackage(profile, catalogRepo, rootName)
+                }
+              }
+            }
+          }
           // npm 优先：git 目标先反查该仓库的官方 npm 包，命中则改走 npm 通道。
           // git 分发常缺构建产物/子模块，npm 包是作者发布的完整产物；未命中或
           // 查询失败保留 github 直装（不阻塞安装，预检仍会拦截缺入口文件的情况）。
           // 通用机制，不针对具体插件。
           // 反查本身计入「已尝试的安装方式」：组织 scope 与 GitHub 用户名不一致时仅凭
           // 仓库名猜不到包名，失败提 Issue 时作者看到我们查过的命令就能直接指认正确包名。
-          const attempts: string[] = []
           if (repoTarget !== null) {
             // 反查/记录统一用归一化后的 owner/repo（gitRepo），保证「输入完整链接」也走同一套 npm 反查
             const repoIdentity = gitRepo ?? rawRepo

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

@@ -12,6 +12,7 @@
  * 避免同一会话内重复查询 registry。
  */
 import { get } from 'node:https'
+import { githubRepoOf } from '../profile/profile.ts'
 
 /** 反查缓存：repo 小写 → npm 包名（null 表示已确认无对应 npm 包；网络异常不缓存）。 */
 const cache = new Map<string, string | null>()
@@ -45,7 +46,8 @@ type NpmSearchPackage = {
   name?: unknown
   keywords?: unknown
   links?: { repository?: unknown }
-  repository?: { url?: unknown }
+  repository?: unknown
+  dsh?: unknown
 }
 
 type NpmSearchObject = { package?: NpmSearchPackage }
@@ -58,15 +60,57 @@ type NpmSearchResponse = { objects?: NpmSearchObject[] }
  * 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()
+function repositoryUrlOf(pkg: NpmSearchPackage): string {
+  if (typeof pkg.repository === 'string') return pkg.repository
+  if (pkg.repository !== null && typeof pkg.repository === 'object') {
+    const url = (pkg.repository as { url?: unknown }).url
+    if (typeof url === 'string') return url
+  }
+  return String(pkg.links?.repository ?? '')
+}
+
+export function isDshPackageMetadataForRepo(pkg: NpmSearchPackage, repo: string): boolean {
+  if (githubRepoOf(repositoryUrlOf(pkg))?.toLowerCase() !== repo.toLowerCase()) return false
+  const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : []
+  const keywordMarked = keywords.some((keyword) => typeof keyword === 'string' && keyword.toLowerCase() === 'dsh-plugin')
+  const manifestMarked = pkg.dsh !== null && typeof pkg.dsh === 'object'
+  return keywordMarked || manifestMarked
+}
+
+export function isDshNpmPackageForRepo(packageName: string, repo: string, registry = ''): Promise<boolean> {
+  if (packageName === '' || repo === '') return Promise.resolve(false)
+  const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '')
+  const url = `${base}/${encodeURIComponent(packageName)}/latest`
+  return new Promise((resolve) => {
+    const req = get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume()
+        resolve(false)
+        return
+      }
+      let body = ''
+      res.on('data', (chunk: Buffer) => { body += chunk.toString() })
+      res.on('end', () => {
+        try {
+          resolve(isDshPackageMetadataForRepo(JSON.parse(body) as NpmSearchPackage, repo))
+        } catch {
+          resolve(false)
+        }
+      })
+    })
+    req.on('timeout', () => req.destroy())
+    req.on('error', () => resolve(false))
+  })
+}
+
+function matchingPackagesForRepo(objects: NpmSearchObject[], repo: string): Array<{ name: string; isDshPlugin: boolean }> {
   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 repoUrl = repositoryUrlOf(pkg)
+    if (githubRepoOf(repoUrl)?.toLowerCase() !== repo.toLowerCase()) continue
     const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : []
     matches.push({
       name: pkg.name,
@@ -74,6 +118,11 @@ export function selectNpmPackageForRepo(objects: NpmSearchObject[], repo: string
     })
   }
 
+  return matches
+}
+
+export function selectNpmPackageForRepo(objects: NpmSearchObject[], repo: string): string | null {
+  const matches = matchingPackagesForRepo(objects, repo)
   return matches.find((candidate) => candidate.isDshPlugin)?.name ?? matches[0]?.name ?? null
 }
 

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

@@ -59,10 +59,13 @@ export async function preflightTarget(target: string): Promise<PreflightResult>
   try {
     const tar = join(dir, 'pkg.tar.gz')
     await download(`https://codeload.github.com/${owner}/${repo}/tar.gz/${commit}`, tar)
-    const meta = await readTarJson(tar, 'package/package.json')
+    const rootPackage = await rootPackageEntry(tar)
+    if (rootPackage === null) return { ok: true, missing: null, name: null }
+    const rootPrefix = rootPackage.slice(0, -'package.json'.length)
+    const meta = await readTarJson(tar, rootPackage)
     if (meta === null) return { ok: true, missing: null, name: null }
     const entry = resolvePackageEntry(meta)
-    const inTar = await hasTarEntry(tar, `package/${entry}`)
+    const inTar = await hasTarEntry(tar, `${rootPrefix}${entry}`)
     return { ok: inTar, missing: inTar ? null : entry, name: typeof meta.name === 'string' ? meta.name : null }
   } catch {
     return { ok: true, missing: null, name: null }
@@ -96,6 +99,26 @@ function download(url: string, dest: string): Promise<void> {
   })
 }
 
+/** GitHub codeload tarballs use a dynamic top-level directory (`repo-<sha>/`),
+ * not npm's `package/` prefix. Pick only a package.json directly under that
+ * single archive root; nested monorepo package manifests are intentionally
+ * ignored. Exported for a small parser regression test. */
+export function rootPackageEntryOfTarList(listing: string): string | null {
+  const candidates = listing
+    .split(/\r?\n/)
+    .filter((line) => /^[^/]+\/package\.json$/u.test(line))
+  return candidates.length === 1 ? candidates[0] : null
+}
+
+async function rootPackageEntry(tar: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync('tar', ['-tzf', tar], { maxBuffer: 16 * 1024 * 1024 })
+    return rootPackageEntryOfTarList(stdout)
+  } catch {
+    return null
+  }
+}
+
 /** 从 tarball 提取并解析一个 JSON 文件；文件不存在或解析失败返回 null。 */
 async function readTarJson(tar: string, entry: string): Promise<Record<string, unknown> | null> {
   try {