dsh-plugin 1.6.10 → 1.6.11

package/lib/services/install/registry-check.js

@@ -0,0 +1,89 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 官方 registry 存在性复核：把「包在 registry 上不存在」这类失败的责任方分开。
+ *
+ * 背景：安装失败日志出现 `ERR_PNPM_FETCH_404` / `Not Found - 404` 时，光看日志分不清三种情形：
+ *   ① 缺的包是 **profile 自己声明的依赖**（历史残留条目，指向一个从未发布的包）—— 用户环境问题：
+ *      pnpm 每次解析依赖都会先卡在它上面，任何插件都装不进来（issue #73），提示删掉该条目即可；
+ *   ② 缺的包来自**插件的依赖树**，且该包在官方 registry 上也不存在 —— 作者侧问题（漏声明依赖、
+ *      依赖被删除或从未发布），应引导用户投插件作者仓库；
+ *   ③ 缺的包来自插件依赖树，但官方 registry 上有 —— 用户本机 registry 指向的镜像/私有源未同步
+ *      该包，属用户环境问题，提示换源即可。
+ * 故本模块先排除 ①（读 profile 的 package.json），再用**官方** registry（registry.npmjs.org，
+ * 绕开本机可能配置的镜像）复查存在性，产出 ② / ③ 的标记行。
+ *
+ * 与 npm-check.ts 同构：本模块只产出「标记行」，由 task-queue 追加到任务输出，前端按标记分类。
+ * fetch 与 profile 目录都可注入，便于单测覆盖全部结论而不依赖网络。
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** pnpm 输出里 scope 包是 URL 编码形态（`@scope%2Fname`）：比较依赖名、拼查询 URL 前先还原成
+ *  `@scope/name`。 */
+function decodePackageName(raw) {
+    return raw.replace(/%40/gi, '@').replace(/%2f/gi, '/');
+}
+/** 从失败输出里提取「registry 上不存在的包名」（含 scope，如 `@scope/name`）：读 404 行的请求路径。
+ *  提取不到返回 null。 */
+export function missingPackageOf(output) {
+    for (const line of output.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 decodePackageName(m[1]);
+    }
+    return null;
+}
+/** 读 profile 自己声明的依赖名（profile 目录下 package.json 的 dependencies 键）。读不到返回空数组。 */
+export function profileDependencyNames(profileDir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'));
+        return Object.keys(raw.dependencies ?? {});
+    }
+    catch {
+        return [];
+    }
+}
+/** 官方 registry 上是否存在该包：明确 404 → false（不存在），2xx → true，其余（限流/网络异常）→ null
+ *  —— 判不了就不判，绝不妄下结论。 */
+async function existsOnOfficialRegistry(name, fetchImpl, timeoutMs) {
+    // scope 包的路径要编码：`@scope/name` → `%40scope%2Fname`
+    const url = `https://registry.npmjs.org/${name.replace('@', '%40').replace('/', '%2F')}`;
+    try {
+        const res = await fetchImpl(url, {
+            headers: { accept: 'application/vnd.npm.install-v1+json' },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (res.status === 404)
+            return false;
+        return res.ok ? true : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 产出「包不存在」失败的责任方标记行；判不了返回 null（前端维持既有提示）。
+ * - `[registry-missing]`     缺的包在官方源上也不存在 → 作者侧问题（前端引导投作者）
+ * - `[registry-mirror-lag]`  官方源上有 → 本机镜像源未同步（前端提示换源，不投任何一方）
+ */
+export async function registryMissingMarker(output, opts) {
+    const name = missingPackageOf(output);
+    if (name === null)
+        return null;
+    // ① profile 自己声明的残留依赖（#73）：用户环境问题，交给既有的 pnpmMissingDep 提示（该提示就是
+    // 教用户删 profile 里那条依赖），这里不再产出标记、不改归属
+    if (profileDependencyNames(opts.profileDir).some((dep) => dep.toLowerCase() === name.toLowerCase()))
+        return null;
+    const exists = await existsOnOfficialRegistry(name, opts.fetchImpl ?? fetch, opts.timeoutMs ?? 8000);
+    if (exists === false) {
+        return `[registry-missing] ${name} is not published on the official npm registry (registry.npmjs.org) — a dependency of this plugin is missing or was removed; author-side issue`;
+    }
+    if (exists === true) {
+        return `[registry-mirror-lag] ${name} exists on the official npm registry — the configured registry or mirror has not synced it; local environment issue`;
+    }
+    return null;
+}

package/lib/services/install/task-queue.js

@@ -13,6 +13,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.js';
 import { npmTooLowMarker } from './npm-check.js';
+import { registryMissingMarker } from './registry-check.js';
 import { backfillOperationLog } from './operation-log.js';
 import { cleanLine, estimateProgress } from '../profile/progress.js';
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.js';
@@ -681,6 +682,22 @@ function annotateNpmTooLow(result, options) {
         pushLine(options.task, line);
     return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
 }
+/** 包在 registry 不存在（404）→ 用官方源复查一次，把「作者依赖缺失/包被删」与「本机镜像源滞后」
+ *  分开（两者的提示与去向不同：前者引导投作者、后者只提示换源）。检测逻辑在独立的
+ *  registry-check.ts；这里之所以是异步，是因为要联网查官方 registry —— 只在安装失败且日志含 404
+ *  时发生，代价可忽略。 */
+async function annotateRegistryMissing(result, options) {
+    if (options.action === 'remove' || result.exitCode === 0 || result.timedOut)
+        return result;
+    const line = await registryMissingMarker(`${result.stderr}\n${result.stdout}`, {
+        profileDir: profileDirectory(options.profile),
+    });
+    if (line === null)
+        return result;
+    if (options.task && options.task.status !== 'cancelled')
+        pushLine(options.task, line);
+    return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
+}
 /**
  * Run a plugin mutation with one recovery path: when `add` fails because
  * pnpm's allowBuilds gate blocks a build script — either the git-hosted
@@ -765,6 +782,8 @@ export async function runPluginMutation(options) {
             result = { ...result, stderr: `${result.stderr}\n${backfilled}` };
         }
     }
+    // 包在 registry 不存在（404）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」
+    result = await annotateRegistryMissing(result, options);
     // npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 追加 [npm-too-low] 标记，前端据此给准确原因
     return annotateNpmTooLow(result, options);
 }

package/lib/types/services/install/registry-check.d.ts

@@ -0,0 +1,15 @@
+/** 从失败输出里提取「registry 上不存在的包名」（含 scope，如 `@scope/name`）：读 404 行的请求路径。
+ *  提取不到返回 null。 */
+export declare function missingPackageOf(output: string): string | null;
+/** 读 profile 自己声明的依赖名（profile 目录下 package.json 的 dependencies 键）。读不到返回空数组。 */
+export declare function profileDependencyNames(profileDir: string): string[];
+/**
+ * 产出「包不存在」失败的责任方标记行；判不了返回 null（前端维持既有提示）。
+ * - `[registry-missing]`     缺的包在官方源上也不存在 → 作者侧问题（前端引导投作者）
+ * - `[registry-mirror-lag]`  官方源上有 → 本机镜像源未同步（前端提示换源，不投任何一方）
+ */
+export declare function registryMissingMarker(output: string, opts: {
+    profileDir: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<string | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "1.6.10",
+  "version": "1.6.11",
   "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, pnpmPolicyHintOf, pnpmPolicyHintParams, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { classifyFailure, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
 import type { PendingRestart, QueueTask } from '../../hooks/useTaskQueue.ts'
 import { pluginIssueUrl, pluginSiteUrl, hubIssueUrl } from '../../logic/urls.ts'
 import { CloseIcon } from '../ui/icons.tsx'
@@ -311,7 +311,24 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       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')),
+                        h('div', { className: styles.failPrepareHint }, t(registryMissingHintOf(r.message))),
+                      ])
+                    }
+                    if (kind === 'pluginMissingDep') {
+                      // 服务端用**官方** registry 复核过：插件依赖树里的包在官方源上也不存在，且不是用户
+                      // profile 的残留依赖 → 作者侧问题（依赖没发布/已被删除），引导到插件作者仓库提 Issue
+                      //（判据是源上的客观存在性，不是我们的启发式判断，故不设「市场误判」次要入口）
+                      const pkg = missingRegistryPackageOf(r.message)
+                      return h('div', null, [
+                        pkg ? h('div', { className: styles.failNetworkTarget }, t('failPluginMissingDepTarget', { pkg })) : null,
+                        h('div', { className: styles.failPrepareHint }, t('failPluginMissingDepHint')),
+                        r.repo && shownRepo ? h('a', {
+                          className: styles.failBigIssue,
+                          href: pluginIssueUrl(shownRepo, r.message, env, r.command, r.attempts),
+                          target: '_blank',
+                          rel: 'noopener noreferrer',
+                          title: t('failIssueHint'),
+                        }, t('failIssueBig')) : null,
                       ])
                     }
                     if (kind === 'registryVersionStale') {

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

@@ -17,7 +17,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, hubIssueUrl } from '../../logic/urls.ts'
-import { classifyFailure, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
+import { classifyFailure, missingRegistryPackageOf, npmTooLowVersion, pnpmPolicyHintOf, pnpmPolicyHintParams, registryMissingHintOf, unreachableTargetOf, registryHostOf } from '../../logic/failures.ts'
 
 /** 完成结果视图：绿色对勾 + 标题/描述；
  *  终态只有两种：
@@ -444,7 +444,25 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
                   const pkg = missingRegistryPackageOf(message)
                   return pkg ? h('div', { className: styles.failNetworkTarget }, t('failPnpmMissingDepTarget', { pkg })) : null
                 })(),
-                h('div', { className: styles.failPrepareHint }, t('failPnpmMissingDepHint')),
+                h('div', { className: styles.failPrepareHint }, t(registryMissingHintOf(message))),
+              ])
+              : failureKind === 'pluginMissingDep'
+              // 服务端用**官方** registry 复核过：插件依赖树里的某个包在官方源上也不存在，且不是用户
+              // profile 的残留依赖 → 作者侧问题（依赖没发布/已被删除）。判据是源上的客观存在性，
+              // 不是我们的启发式判断，故不给「市场误判」次要入口，直接引导到插件作者仓库提 Issue。
+              ? h('div', null, [
+                (() => {
+                  const pkg = missingRegistryPackageOf(message)
+                  return pkg ? h('div', { className: styles.failNetworkTarget }, t('failPluginMissingDepTarget', { pkg })) : null
+                })(),
+                h('div', { className: styles.failPrepareHint }, t('failPluginMissingDepHint')),
+                repo ? h('a', {
+                  className: styles.failBigIssue,
+                  href: pluginIssueUrl(repo, message, env, command, attempts),
+                  target: '_blank',
+                  rel: 'noopener noreferrer',
+                  title: t('failIssueHint'),
+                }, t('failIssueBig')) : null,
               ])
               : failureKind === 'registryVersionStale'
               // 要装的版本在「实际执行安装的那个源」里查不到（ERR_PNPM_NO_MATCHING_VERSION / ETARGET）：

package/src/client/locales.ts

@@ -357,6 +357,9 @@ export const zh = {
   // 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 条目或整个锁文件）后重试。',
+  failRegistryMirrorLagHint: '安装器调用 pnpm 时报「包不存在」（ERR_PNPM_FETCH_404）：该包在官方 npm 源上是有的，但你本机配置的 npm/pnpm 源（registry 或镜像）没有同步到它。请把 npm/pnpm 的 registry 指回官方源 https://registry.npmjs.org（或换一个已同步该包的镜像）后重试。这不是插件本身的问题。',
+  failPluginMissingDepTarget: '{pkg} 在官方 npm 源上不存在',
+  failPluginMissingDepHint: '该插件依赖的包在官方 npm 源上并不存在（已删除或从未发布）：这是插件作者侧的依赖问题，不是你环境的问题。请向插件作者仓库反馈，请作者补上或修正该依赖，或改为随插件一起分发。',
   failRegistryVersionStaleHint: '安装器调用 pnpm 时报「找不到匹配的版本」（ERR_PNPM_NO_MATCHING_VERSION）：要装的这个版本在实际执行安装的 npm 源里查不到。常见原因是你设置的 npmRegistry 与本机 ~/.npmrc 用的不是同一个源——官方源刚发布、镜像还没同步上来（快则几分钟、慢则几小时），也可能只是版本号写错了。这不是插件本身的问题。可在插件市场设置里把 npmRegistry 改成与本机 ~/.npmrc 一致（或反过来），或那一次显式走官方源（https://registry.npmjs.org）、改用离线包后重试；若该版本刚发布不久，等镜像同步后重试即可。',
   failPnpmLinkedDirMissingHint: '安装器调用 pnpm 时报「要安装的目录不存在」（ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND）：你的 profile 里留着一条指向本机不存在目录的本地依赖（link: / file: 形式，例如用 dsh plugin add <本地路径> 装过开发中的插件，之后那个目录被删除或移动了）。pnpm 每次解析 profile 依赖都会先卡在它上面，因此任何插件都装不进来。这不是插件本身的问题——请在 profile 目录（~/.dsh/profiles/<profile>）的 package.json 里删除该本地依赖条目（同时删掉对应的 pnpm-lock.yaml 条目或整个锁文件），或把该目录恢复回原路径后重试。',
   failFileLockedHint: '安装过程中 pnpm 无法替换 profile 里的文件：有程序正占用着它（Windows 常见报错 os error 32「另一个程序正在使用此文件」）。通常是 DeepSeek Harness 自身或杀毒软件的实时扫描持有文件句柄。这不是插件本身的问题——请完全退出 DeepSeek Harness（Windows 可在任务管理器确认进程已结束，必要时临时关闭杀毒软件实时防护）后重试。',
@@ -770,6 +773,9 @@ export const en = {
   // 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.',
+  failRegistryMirrorLagHint: 'pnpm reported that a package does not exist on the npm registry (ERR_PNPM_FETCH_404): that package does exist on the official npm registry, but the npm/pnpm registry (or mirror) configured on your machine has not synced it. Point the npm/pnpm registry back at the official one (https://registry.npmjs.org), or switch to a mirror that has the package, then retry. This is not a problem with the plugin itself.',
+  failPluginMissingDepTarget: '{pkg} does not exist on the official npm registry',
+  failPluginMissingDepHint: 'A package this plugin depends on does not exist on the official npm registry (removed, or never published). This is a dependency problem on the plugin author side, not a problem with your environment. Please report it to the plugin repository so the author can fix that dependency or ship it together with the plugin.',
   failRegistryVersionStaleHint: 'pnpm reported that no matching version was found (ERR_PNPM_NO_MATCHING_VERSION): the version being installed does not exist in the npm registry that actually performs the install. This usually means the npmRegistry configured in the hub differs from the source in your local ~/.npmrc — the official registry has published it but the mirror has not synced yet (it can take minutes to hours) — or the version number was simply mistyped. This is not a problem with the plugin itself. Align the hub\'s npmRegistry with your local ~/.npmrc (or the other way round), or explicitly use the official registry (https://registry.npmjs.org) for that one install, or use an offline package, then retry; if the version was published only recently, waiting for the mirror to sync is enough.',
   failPnpmLinkedDirMissingHint: 'pnpm reported that a directory it needs to install from does not exist (ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND): your profile keeps a local dependency (a link: / file: entry, e.g. from `dsh plugin add <local path>`) whose target directory has since been deleted or moved. pnpm hits it every time it resolves profile dependencies, so no plugin can be installed into that profile. This is not a problem with the plugin itself. Remove that local dependency from package.json inside the profile directory (~/.dsh/profiles/<profile>) — along with its entry in pnpm-lock.yaml, or the lockfile itself — or restore the directory to its original path, 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.',

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' | 'pnpmMissingDep' | 'registryVersionStale' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'hubState' | 'timeout' | 'profileLock' | 'hub'
+export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'pluginMissingDep' | 'registryVersionStale' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'hubState' | 'timeout' | 'profileLock' | 'hub'
 
 /** Match the pnpm error code, not a generic mention of checksum or integrity. */
 function missingTarballIntegrity(message: string): boolean {
@@ -230,6 +230,11 @@ export function classifyFailure(message: string): FailureKind {
   // 装后校验发现入口文件缺失（[packaging]）= git 分发缺构建产物
   if (/\[packaging\]|entry file missing/i.test(message)) return 'pluginPrepare'
   // registry 上不存在的依赖（404），profile 任何安装都会卡在这条。必须在 pluginPrepare 之前判
+  // 官方源复核结论：缺的包在官方 registry 上也不存在，且不是本机 profile 声明的残留依赖 →
+  // 该包来自插件的依赖树，属**作者侧**问题（依赖没发布/已被删除）。标记由服务端联网复查后注入。
+  // 必须排在 pnpmMissingDep 之前 —— 日志里同样含 ERR_PNPM_FETCH_404，靠标记区分「作者的锅」
+  // 与「本机 profile 残留依赖（#73）/ 镜像源滞后」。
+  if (/\[registry-missing\]/i.test(message)) return 'pluginMissingDep'
   if (/ERR_PNPM_FETCH_404|404 Not Found|Not Found - 404/i.test(message)) return 'pnpmMissingDep'
   // 要装的版本在实际安装源里没有（镜像滞后或版本写错）。必须在 pluginPrepare 之前判
   if (/\bERR_PNPM_NO_MATCHING_VERSION\b|\bETARGET\b|No matching version found/i.test(message)) return 'registryVersionStale'
@@ -252,6 +257,12 @@ export function classifyFailure(message: string): FailureKind {
   // dsh 进程或安装任务在写，锁一直没释放。既不是插件问题、也不是用户环境坏了 —— 把并发收掉重试即可。
   // 摆放位置同样在一切错误码分支之后：日志里真有 pnpm 报错时仍以真实报错为准。
   if (/atomic-write: timed out waiting for the writer lock|timed out waiting for the writer lock/i.test(message)) return 'profileLock'
+  // 宿主 DSH 自己的 allowBuilds 摘要行（#210）：新版宿主把 pnpm 报错只写进 diagnostics 日志文件，
+  // 终端里只留这一句「git-hosted plugins build … add the exact key … then re-run」，日志里因此
+  // 一条原始 ERR_PNPM_* 码都没有 —— 只能靠这句话识别为「构建脚本被白名单拦截」。
+  // 摆放位置在一切错误码分支之后：日志里真有 ERR_PNPM_PREPARE_PACKAGE / ERR_PNPM_IGNORED_BUILDS
+  // 时（构建确实跑挂、或不带摘要的旧宿主），仍以原始报错为准，不会被这句摘要改写。
+  if (/git-hosted plugins build on install via their prepare script|add the exact key pnpm printed above under allowBuilds/i.test(message)) return 'pnpmIgnoredBuild'
   // 其余未知失败：引导到插件中心仓库排查
   return 'hub'
 }
@@ -318,13 +329,21 @@ export function coreErrorCode(message: string): string | null {
   return m ? m[0].replace(/^\[|\]$/g, '') : null
 }
 
+/** 「包在 registry 不存在」失败的提示变体：服务端用官方源复核过（会注入 `[registry-mirror-lag]`）
+ *  时，说明包在官方源上存在、是本机镜像源未同步 → 提示换源；否则沿用既有的「profile 残留依赖」
+ *  提示（#73：指向从未发布包的残留条目，任何插件都装不进来）。 */
+export function registryMissingHintOf(message: string): 'failPnpmMissingDepHint' | 'failRegistryMirrorLagHint' {
+  return /\[registry-mirror-lag\]/i.test(message) ? 'failRegistryMirrorLagHint' : 'failPnpmMissingDepHint'
+}
+
 /** 提取「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]
+    // pnpm 输出里 scope 包是 URL 编码形态（`@scope%2Fname`）：还原成 `@scope/name` 再展示
+    if (m) return m[1].replace(/%40/gi, '@').replace(/%2f/gi, '/')
   }
   return null
 }

package/src/client/logic/urls.ts

@@ -66,6 +66,7 @@ function reasonTitleOf(kind: FailureKind): string {
     case 'hubState': return 'stale install state in the plugin hub'
     case 'timeout': return 'install timed out'
     case 'profileLock': return 'DSH profile is locked by another process'
+    case 'pluginMissingDep': return 'a dependency of the plugin is not published on npm'
     case 'hub': return 'install failed (cause unclassified)'
     default: return 'plugin install failed'
   }
@@ -90,6 +91,9 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
   const title = `[dsh-plugin.org | dsh-plugin-hub] ${reasonTitleOf(kind)}: ${repo}`
   const reason = /\[packaging\]/i.test(message)
     ? 'plugin distribution is incomplete — a file the package needs (its entry from main / exports, an entry a bundled patch mounts, or the patch declared by dsh.bundle.patch) is missing from the published package (github tarball or npm package); please commit build output or publish a complete package'
+      : /\[registry-missing\]/i.test(message)
+        // 服务端用官方 registry 复核过：缺的包在官方源上也不存在，且不是用户 profile 的残留依赖
+        ? 'a dependency declared by the plugin is not published on the public npm registry (missing, removed, or never released); please publish or correct that dependency, or ship it with the plugin'
       : kind === 'network'
         ? 'network connectivity issue on the user side (DNS, proxy, firewall, or a blocked connection)'
         : kind === 'pluginPrepare'

package/src/server/services/install/registry-check.ts

@@ -0,0 +1,94 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 官方 registry 存在性复核：把「包在 registry 上不存在」这类失败的责任方分开。
+ *
+ * 背景：安装失败日志出现 `ERR_PNPM_FETCH_404` / `Not Found - 404` 时，光看日志分不清三种情形：
+ *   ① 缺的包是 **profile 自己声明的依赖**（历史残留条目，指向一个从未发布的包）—— 用户环境问题：
+ *      pnpm 每次解析依赖都会先卡在它上面，任何插件都装不进来（issue #73），提示删掉该条目即可；
+ *   ② 缺的包来自**插件的依赖树**，且该包在官方 registry 上也不存在 —— 作者侧问题（漏声明依赖、
+ *      依赖被删除或从未发布），应引导用户投插件作者仓库；
+ *   ③ 缺的包来自插件依赖树，但官方 registry 上有 —— 用户本机 registry 指向的镜像/私有源未同步
+ *      该包，属用户环境问题，提示换源即可。
+ * 故本模块先排除 ①（读 profile 的 package.json），再用**官方** registry（registry.npmjs.org，
+ * 绕开本机可能配置的镜像）复查存在性，产出 ② / ③ 的标记行。
+ *
+ * 与 npm-check.ts 同构：本模块只产出「标记行」，由 task-queue 追加到任务输出，前端按标记分类。
+ * fetch 与 profile 目录都可注入，便于单测覆盖全部结论而不依赖网络。
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** pnpm 输出里 scope 包是 URL 编码形态（`@scope%2Fname`）：比较依赖名、拼查询 URL 前先还原成
+ *  `@scope/name`。 */
+function decodePackageName(raw: string): string {
+  return raw.replace(/%40/gi, '@').replace(/%2f/gi, '/')
+}
+
+/** 从失败输出里提取「registry 上不存在的包名」（含 scope，如 `@scope/name`）：读 404 行的请求路径。
+ *  提取不到返回 null。 */
+export function missingPackageOf(output: string): string | null {
+  for (const line of output.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 decodePackageName(m[1])
+  }
+  return null
+}
+
+/** 读 profile 自己声明的依赖名（profile 目录下 package.json 的 dependencies 键）。读不到返回空数组。 */
+export function profileDependencyNames(profileDir: string): string[] {
+  try {
+    const raw = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8')) as { dependencies?: Record<string, unknown> }
+    return Object.keys(raw.dependencies ?? {})
+  } catch {
+    return []
+  }
+}
+
+/** 官方 registry 上是否存在该包：明确 404 → false（不存在），2xx → true，其余（限流/网络异常）→ null
+ *  —— 判不了就不判，绝不妄下结论。 */
+async function existsOnOfficialRegistry(
+  name: string,
+  fetchImpl: typeof fetch,
+  timeoutMs: number,
+): Promise<boolean | null> {
+  // scope 包的路径要编码：`@scope/name` → `%40scope%2Fname`
+  const url = `https://registry.npmjs.org/${name.replace('@', '%40').replace('/', '%2F')}`
+  try {
+    const res = await fetchImpl(url, {
+      headers: { accept: 'application/vnd.npm.install-v1+json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (res.status === 404) return false
+    return res.ok ? true : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 产出「包不存在」失败的责任方标记行；判不了返回 null（前端维持既有提示）。
+ * - `[registry-missing]`     缺的包在官方源上也不存在 → 作者侧问题（前端引导投作者）
+ * - `[registry-mirror-lag]`  官方源上有 → 本机镜像源未同步（前端提示换源，不投任何一方）
+ */
+export async function registryMissingMarker(
+  output: string,
+  opts: { profileDir: string; fetchImpl?: typeof fetch; timeoutMs?: number },
+): Promise<string | null> {
+  const name = missingPackageOf(output)
+  if (name === null) return null
+  // ① profile 自己声明的残留依赖（#73）：用户环境问题，交给既有的 pnpmMissingDep 提示（该提示就是
+  // 教用户删 profile 里那条依赖），这里不再产出标记、不改归属
+  if (profileDependencyNames(opts.profileDir).some((dep) => dep.toLowerCase() === name.toLowerCase())) return null
+  const exists = await existsOnOfficialRegistry(name, opts.fetchImpl ?? fetch, opts.timeoutMs ?? 8000)
+  if (exists === false) {
+    return `[registry-missing] ${name} is not published on the official npm registry (registry.npmjs.org) — a dependency of this plugin is missing or was removed; author-side issue`
+  }
+  if (exists === true) {
+    return `[registry-mirror-lag] ${name} exists on the official npm registry — the configured registry or mirror has not synced it; local environment issue`
+  }
+  return null
+}

package/src/server/services/install/task-queue.ts

@@ -14,6 +14,7 @@ import { dirname, join, resolve } from 'node:path'
 import type { InstallResult, InstallTask, Invocation, QueueItem } from './install-types.ts'
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.ts'
 import { npmTooLowMarker } from './npm-check.ts'
+import { registryMissingMarker } from './registry-check.ts'
 import { backfillOperationLog } from './operation-log.ts'
 import { cleanLine, estimateProgress } from '../profile/progress.ts'
 import type { LoaderHandle } from '../loader.ts'
@@ -711,6 +712,24 @@ function annotateNpmTooLow(result: InstallResult, options: {
   return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line }
 }
 
+/** 包在 registry 不存在（404）→ 用官方源复查一次，把「作者依赖缺失/包被删」与「本机镜像源滞后」
+ *  分开（两者的提示与去向不同：前者引导投作者、后者只提示换源）。检测逻辑在独立的
+ *  registry-check.ts；这里之所以是异步，是因为要联网查官方 registry —— 只在安装失败且日志含 404
+ *  时发生，代价可忽略。 */
+async function annotateRegistryMissing(result: InstallResult, options: {
+  action: 'add' | 'remove' | 'update'
+  profile: string
+  task?: InstallTask
+}): Promise<InstallResult> {
+  if (options.action === 'remove' || result.exitCode === 0 || result.timedOut) return result
+  const line = await registryMissingMarker(`${result.stderr}\n${result.stdout}`, {
+    profileDir: profileDirectory(options.profile),
+  })
+  if (line === null) return result
+  if (options.task && options.task.status !== 'cancelled') pushLine(options.task, line)
+  return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line }
+}
+
 /**
  * Run a plugin mutation with one recovery path: when `add` fails because
  * pnpm's allowBuilds gate blocks a build script — either the git-hosted
@@ -804,6 +823,8 @@ export async function runPluginMutation(options: {
       result = { ...result, stderr: `${result.stderr}\n${backfilled}` }
     }
   }
+  // 包在 registry 不存在（404）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」
+  result = await annotateRegistryMissing(result, options)
   // npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 追加 [npm-too-low] 标记，前端据此给准确原因
   return annotateNpmTooLow(result, options)
 }