dsh-plugin 1.4.0 → 1.4.2

package/lib/http/routes.js

@@ -121,6 +121,20 @@ export function readInstalled(profile) {
         return {};
     }
 }
+/** 读已装依赖实际落在磁盘上的仓库身份（`owner/repo`）：解析 node_modules/<name>/package.json
+ *  的 repository 字段。已装 spec 可能是纯版本号（丢了仓库身份），但真实包元数据仍指向来源仓库，
+ *  据此可区分「同名依赖其实是同一仓库的残留（应转 update）」还是「跨仓库包名冲突（应报错）」。
+ *  读不到 / 解析不出返回 null（交给调用方按冲突处理）。 */
+function installedRepoOf(profile, name) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(profileDirectory(profile), 'node_modules', name, 'package.json'), 'utf8'));
+        const repo = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+        return repo ? githubRepoOf(repo) : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** 宿主 dsh CLI 版本：优先直接跑 `dsh --version`（与 pnpm/npm/git 同款同步探测，1500ms 超时兜底，
  *  绝不挂起）—— 原先从 process.argv[1] 向上找 package.json 猜版本在部分宿主加载方式下取不到，
  *  导致 issue 环境快照 DSH: unknown；拿不到再退回入口 package.json 查找（dsh 不在 PATH 时兜底）。 */
@@ -655,8 +669,9 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                 // 任务自动入队：即使已有插件操作在跑也接受请求（FIFO 串行执行），不再 409 拒绝
                 try {
                     const body = await readJsonBody(request);
-                    // mode: 'update' = 已安装目标的覆盖更新（放行 add，pnpm 对已存在依赖原位覆盖重装）
-                    const mode = body !== null && typeof body === 'object' && body.mode === 'update'
+                    // mode: 'update' = 已安装目标的覆盖更新（放行 add，pnpm 对已存在依赖原位覆盖重装）。
+                    // 后续「同仓库残留」检测可能把 install 就地升级为 update（见包名冲突检测），故用 let。
+                    let mode = body !== null && typeof body === 'object' && body.mode === 'update'
                         ? 'update'
                         : 'install';
                     // installTargetOf 先把完整 DSH 命令（`dsh plugin [--profile <p>] add <target>`）剥成裸目标，
@@ -829,6 +844,32 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                             });
                             return;
                         }
+                        // 包名冲突检测（仅 git 通道）：git 目标包内声明的 name 若与 profile 已装依赖同名，
+                        // pnpm 会以该 name 做依赖键撞车，抛出的 CLI 报错晦涩难懂（issue #25：sandbase-harness
+                        // 声明 managed-agents，但该包名在 registry 上被另一仓库占用，npm 反查搜不到 → git 直装
+                        // 撞已装同名依赖）。到这里已装依赖要么来源不同仓库、要么 spec 是版本号解析不出仓库身份。
+                        // 读 node_modules 里已装包的真实 repository 区分两种情况：
+                        //  - 指向同一仓库 → 是「同仓库残留」（spec 丢了仓库身份），就地转 update 覆盖重装（幂等）；
+                        //  - 指向别的仓库 / 读不到 → 跨仓库包名冲突，入队前转成明确 409，指导用户先卸载或改装。
+                        if (preflight.name !== null && repoTarget !== null && target === repoTarget) {
+                            const declared = preflight.name;
+                            if (installed[declared] !== undefined) {
+                                const installedRepo = installedRepoOf(profile, declared);
+                                if (installedRepo !== null && gitRepo !== null && installedRepo.toLowerCase() === gitRepo.toLowerCase()) {
+                                    // 同名且同源：已装 spec 丢了仓库身份导致的残留，直接按 update 覆盖重装，不打扰用户
+                                    attempts.push(`same-repo residual: \`${declared}\` resolves to \`${installedRepo}\` → reinstall as update`);
+                                    mode = 'update';
+                                }
+                                else {
+                                    attempts.push(`package name conflict: \`${gitRepo}\` declares npm name \`${declared}\`, which is already present in the profile and cannot be matched to this repo (that npm name is likely registered by another repository)`);
+                                    const error = lang === 'zh'
+                                        ? `already installed: ${declared} —— ${gitRepo} 声明的 npm 包名「${declared}」已存在于当前 profile，且无法匹配到本仓库（该包名在 npm 上可能被其他仓库占用）。请先移除现有的 ${declared}（dsh plugin remove ${declared}），再重新安装；或改装该包名对应的官方 npm 包。`
+                                        : `already installed: ${declared} — ${gitRepo} declares the npm package name "${declared}", which is already present in the profile and cannot be matched to this repo (that npm name is likely registered by another repository). Remove the existing ${declared} dependency (dsh plugin remove ${declared}) first, then retry; or install the official npm package under that name.`;
+                                    sendJson(response, 409, { error, attempts });
+                                    return;
+                                }
+                            }
+                        }
                     }
                     // 入队前复检（与上方检查同语义，但必须在同步块内）：preflight 的 await 期间并发请求
                     // 可能已通过上方检查、任务却尚未入队——此处检查与 startPluginMutation 之间无 await，

package/lib/services/install/preflight.js

@@ -25,7 +25,7 @@ const PREFLIGHT_TIMEOUT_MS = 15_000;
 export async function preflightTarget(target) {
     const source = githubRepoOf(target);
     if (source === null)
-        return { ok: true, missing: null };
+        return { ok: true, missing: null, name: null };
     const [owner, repo] = source.split('/');
     let commit = '';
     try {
@@ -36,17 +36,17 @@ export async function preflightTarget(target) {
         commit = stdout.split(/\s+/)[0] ?? '';
     }
     catch {
-        return { ok: true, missing: null };
+        return { ok: true, missing: null, name: null };
     }
     if (!commit)
-        return { ok: true, missing: null };
+        return { ok: true, missing: null, name: null };
     const dir = mkdtempSync(join(tmpdir(), 'dsh-preflight-'));
     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');
         if (meta === null)
-            return { ok: true, missing: null };
+            return { ok: true, missing: null, name: null };
         const dot = meta.exports?.['.'];
         const resolved = typeof dot === 'string'
             ? dot
@@ -55,10 +55,10 @@ export async function preflightTarget(target) {
                 : undefined;
         const entry = typeof resolved === 'string' ? resolved : typeof meta.main === 'string' ? meta.main : 'index.js';
         const inTar = await hasTarEntry(tar, `package/${entry}`);
-        return { ok: inTar, missing: inTar ? null : entry };
+        return { ok: inTar, missing: inTar ? null : entry, name: typeof meta.name === 'string' ? meta.name : null };
     }
     catch {
-        return { ok: true, missing: null };
+        return { ok: true, missing: null, name: null };
     }
     finally {
         rmSync(dir, { recursive: true, force: true });

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

@@ -1,6 +1,10 @@
-/** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径。 */
+/** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径；
+ *  name 为 git 分发包 package.json 声明的包名（非 git 目标/无法确定时为 null），
+ *  供安装路由做「包名冲突」检测 —— 同名包名已被其他来源占用时，pnpm 装前必然撞车，
+ *  需要把晦涩的 CLI 报错转成明确的拦截。 */
 export interface PreflightResult {
     ok: boolean;
     missing: string | null;
+    name: string | null;
 }
 export declare function preflightTarget(target: string): Promise<PreflightResult>;

package/package.json

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

package/src/client/components/catalog/CatalogList.tsx

@@ -11,7 +11,7 @@
 import { createElement as h, useEffect, useRef } from 'react'
 import styles from '../../styles/List.module.css'
 import type { HubPlugin, LocaleId, Translate } from '../../types.ts'
-import { SITE_URL } from '../../logic/constants.ts'
+import { siteUrl } from '../../logic/urls.ts'
 import { useIncrementalList } from '../../hooks/useIncrementalList.ts'
 import { PluginCard } from './PluginCard.tsx'
 
@@ -82,7 +82,7 @@ export function CatalogList({ plugins, failed, visible, total, t, langPath, relo
     plugins !== null && !failed && h('div', { className: styles.footer },
       h('a', {
         className: styles.footLink,
-        href: `${SITE_URL}${langPath}`,
+        href: siteUrl(langPath),
         target: '_blank',
         rel: 'noopener noreferrer',
       }, t('browseAll', { n: total })),

package/src/client/components/layout/CatalogHeader.tsx

@@ -9,7 +9,8 @@
 import { createElement as h, Fragment } from 'react'
 import styles from '../../styles/Header.module.css'
 import type { Translate } from '../../types.ts'
-import { GITHUB_URL, PLUGIN_VERSION, SITE_URL } from '../../logic/constants.ts'
+import { GITHUB_URL, PLUGIN_VERSION } from '../../logic/constants.ts'
+import { siteUrl } from '../../logic/urls.ts'
 import { GitHubIcon, LogoIcon } from '../ui/icons.tsx'
 
 export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggleLang, hubUpdate, onVersionClick, onAboutClick }: {
@@ -31,7 +32,7 @@ export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggle
       h('div', { className: styles.headerTitleRow },
         h('a', {
           className: styles.brandTitle,
-          href: `${SITE_URL}${langPath}`,
+          href: siteUrl(langPath),
           target: '_blank',
           rel: 'noopener noreferrer',
           title: t('openHint'),
@@ -86,7 +87,7 @@ export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggle
       // 第二行：副标题仍是官网链接，点击跳 dsh-plugin.org
       h('a', {
         className: styles.taglineLink,
-        href: `${SITE_URL}${langPath}`,
+        href: siteUrl(langPath),
         target: '_blank',
         rel: 'noopener noreferrer',
         title: t('openHint'),
@@ -96,7 +97,7 @@ export function CatalogHeader({ t, langPath, statsTotal, statsVerified, onToggle
     ),
     h('a', {
       className: styles.adBanner,
-      href: `${SITE_URL}${langPath}`,
+      href: siteUrl(langPath),
       target: '_blank',
       rel: 'noopener noreferrer',
     },

package/src/client/logic/failures.ts

@@ -178,10 +178,12 @@ export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissi
  *   本机 npm 未安装或不在 PATH，不是插件问题。dshMissing 的通用「not recognized」模式会把
  *   `'npm' is not recognized` 吞成 dsh 缺失，所以必须在 dshMissing 之前判断
  *   → 提示安装 npm（Node.js 自带）/加入 PATH，不引导提 Issue
- * - pnpmStore：pnpm 存在但报 store 位置不匹配（`ERR_PNPM_UNEXPECTED_STORE` / `Unexpected store
- *   location`）—— profile 目录的 node_modules 是用不同大版本的 pnpm 生成的，当前 pnpm 不认，
- *   任何插件装进该 profile 都会失败；不是插件问题（dsh-plugin-hub#14：macOS 下
- *   `ERR_PNPM_UNEXPECTED_STORE` 被误归插件侧失败）→ 提示清理 profile 依赖目录重建，不引导提 Issue
+ * - pnpmStore：pnpm 存在但报 store / virtual store 位置不匹配（`ERR_PNPM_UNEXPECTED_STORE` /
+ *   `ERR_PNPM_UNEXPECTED_VIRTUAL_STORE` / `Unexpected store location`）—— profile 目录的 node_modules
+ *   是用不同大版本的 pnpm 生成的（或 profile 目录被复制/移动、virtual-store-dir 配置变化），
+ *   当前 pnpm 不认，任何插件装进该 profile 都会失败；不是插件问题（dsh-plugin-hub#14：macOS 下
+ *   `ERR_PNPM_UNEXPECTED_STORE` 被误归插件侧失败；dsh-plugin-hub#30：`ERR_PNPM_UNEXPECTED_VIRTUAL_STORE`
+ *   漏判被误归插件侧失败）→ 提示清理 profile 依赖目录重建，不引导提 Issue
  * - pnpmPolicy：pnpm 11 的供应链安全策略拒绝安装（`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` /
  *   `Minimum release age` —— 锁文件里包的发布时间还不满 24 小时被拒；`untrusted origin` —— 依赖来源未被
  *   本机 pnpm 信任）。拦的是「刚发布的新包」与「未被信任的来源」，装任何新插件都会撞墙，不是
@@ -229,12 +231,15 @@ export function classifyFailure(message: string): FailureKind {
   // 否则会被外层 "Command failed" 吞成「插件打包问题」，误导用户去提 Issue
   // （dsh-plugin-hub#12：Win 下 'dsh' 不在 PATH，cmd 报「不是内部或外部命令」被误归插件侧失败）
   if (/\[dsh-missing\]|不是内部或外部命令|is not recognized as an internal or external command|command not found|spawn dsh ENOENT/i.test(message)) return 'dshMissing'
-  // pnpm 大版本不一致（ERR_PNPM_UNEXPECTED_STORE / Unexpected store location）：profile 目录里
-  // 旧依赖是另一个大版本 pnpm 生成的，当前 pnpm 出于安全不认旧 store —— 本机环境问题，
-  // 任何插件装进该 profile 都会同样失败，不是插件问题（dsh-plugin-hub#14：macOS 下
-  // `ERR_PNPM_UNEXPECTED_STORE` 被误归插件侧失败）；提示清理依赖目录用当前 pnpm 重建，
-  // 不引导提 Issue。必须在 pnpmMissing 之后 —— pnpm 在（能跑起来报错），不是「找不到命令」。
-  if (/ERR_PNPM_UNEXPECTED_STORE|Unexpected store location/i.test(message)) return 'pnpmStore'
+  // pnpm 大版本/虚拟 store 位置不一致（ERR_PNPM_UNEXPECTED_STORE / ERR_PNPM_UNEXPECTED_VIRTUAL_STORE /
+  // Unexpected store location）：profile 目录里旧依赖是另一个大版本 pnpm 生成的（或 profile 目录
+  // 被复制/移动、virtual-store-dir 配置变化导致 virtual store 位置不匹配），当前 pnpm 出于安全
+  // 不认旧 store —— 本机环境问题，任何插件装进该 profile 都会同样失败，不是插件问题
+  // （dsh-plugin-hub#14：macOS 下 ERR_PNPM_UNEXPECTED_STORE 被误归插件侧失败；
+  //  dsh-plugin-hub#30：ERR_PNPM_UNEXPECTED_VIRTUAL_STORE 漏判被误归插件侧失败）；
+  // 提示清理依赖目录用当前 pnpm 重建，不引导提 Issue。必须在 pnpmMissing 之后 ——
+  // pnpm 在（能跑起来报错），不是「找不到命令」。
+  if (/ERR_PNPM_UNEXPECTED_(VIRTUAL_)?STORE|Unexpected (virtual )?store location/i.test(message)) return 'pnpmStore'
   // pnpm 供应链安全策略拦截（pnpm 11：minimumReleaseAge 拒收「刚发布」的包 /
   // untrusted origin 来源不受信任）：pnpm 在、也连得上，纯粹是本机策略不放行 ——
   // 装任何「新发布/非信任来源」的插件都会同样失败，不是插件问题（dsh-plugin-hub#15/#16）。
@@ -271,6 +276,14 @@ export function npmTooLowVersion(message: string): string | null {
 
 /** 核心行特征：错误代码 / 生命周期脚本失败 / prepare 失败 / 描述性报错（子模块缺失、找不到等）/ 退出与宿主提示信息。 */
 const CORE_LINE_RE = /ERR_[A-Z_]+|ELIFECYCLE|Command failed|prepare-guard|Failed to prepare|exit code|\bprepare\b|pnpm failed in profile|git-hosted plugins build|submodule|not found|cannot find|no such|unable to|fatal|missing|error/i
+/** pnpm 的 peer 依赖告警行（`missing peer …` / `Issues with peer dependencies found` /
+ *  `Peer dependencies that should be installed`）：宿主提供的 peer（@deepseek-ai/*、react、
+ *  dsh-client-* 等，DSH profile 用 autoInstallPeers:false 不自动装）缺失是无害噪音，与插件本身
+ *  无关 —— 抓核心错误时必须跳过，否则会被 CORE_LINE_RE 的 `missing` 分支误抓、淹没真正的
+ *  错误码（如 git 源的 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED），让 issue 正文只剩一堆 peer WARN
+ *  （dsh-plugin-hub#28：anime-find 的 auto-issue 核心错误全是 missing-peer WARN 树，真正的
+ *  prepare 错误被盖住）。 */
+const PEER_WARN_RE = /missing peer|issues with peer dependencies|peer dependencies that should be installed/i
 /** 提交 issue 时正文里错误摘要的上限字符数。GitHub 请求行上限 8192 字节，
  * 固定模板与 URL 编码开销约 1~2K，核心错误（以 ASCII 日志为主）可安全带到 ~5K；
  * 仍超长时 pluginIssueUrl 会逐档缩小核心预算，最终 URL 不会超限。 */
@@ -289,7 +302,7 @@ export function summarizeError(message: string, maxChars: number = MAX_CORE_CHAR
   const core: string[] = []
   for (const raw of message.split(/\r?\n/)) {
     const line = raw.trim()
-    if (!line || !CORE_LINE_RE.test(line)) continue
+    if (!line || PEER_WARN_RE.test(line) || !CORE_LINE_RE.test(line)) continue
     const short = line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}…` : line
     if (!seen.has(short)) {
       seen.add(short)

package/src/client/logic/urls.ts

@@ -17,13 +17,19 @@ export function langPathOf(lang: LocaleId): string {
   return lang === 'zh' ? 'zh/' : ''
 }
 
+/** 官网链接统一携带 `?ref=hub` 来源参数：统计有多少访问是从插件商城跳转而来。
+ *  所有「从商城跳官网」的链接（详情页/首页）都应经由此函数拼接，避免来源参数散落各处。 */
+export function siteUrl(path: string): string {
+  return `${SITE_URL}${path}?ref=hub`
+}
+
 /**
  * 官网详情页两级路径：/plugins/{ownerSlug}/{slug}；
  * 缺 ownerSlug 时从 repo 推导（卡片详情按钮与弹窗来源行共用）。
  */
 export function pluginDetailUrl(plugin: HubPlugin, langPath: string): string {
   const repo = plugin.source?.repo ?? ''
-  return `${SITE_URL}${langPath}plugins/${plugin.ownerSlug ?? repo.split('/')[0]?.toLowerCase() ?? ''}/${plugin.slug}`
+  return siteUrl(`${langPath}plugins/${plugin.ownerSlug ?? repo.split('/')[0]?.toLowerCase() ?? ''}/${plugin.slug}`)
 }
 
 /**
@@ -31,7 +37,7 @@ export function pluginDetailUrl(plugin: HubPlugin, langPath: string): string {
  * 与 issue 正文的 Catalog 链接同一形式（单级 /plugins/{repo}）。
  */
 export function pluginSiteUrl(repo: string): string {
-  return `${SITE_URL}plugins/${repo}`
+  return siteUrl(`plugins/${repo}`)
 }
 
 /** 按失败类型给出简洁的错误原因标题（对外用英文）：

package/src/server/http/routes.ts

@@ -149,6 +149,22 @@ export function readInstalled(profile: string): Record<string, string> {
   }
 }
 
+/** 读已装依赖实际落在磁盘上的仓库身份（`owner/repo`）：解析 node_modules/<name>/package.json
+ *  的 repository 字段。已装 spec 可能是纯版本号（丢了仓库身份），但真实包元数据仍指向来源仓库，
+ *  据此可区分「同名依赖其实是同一仓库的残留（应转 update）」还是「跨仓库包名冲突（应报错）」。
+ *  读不到 / 解析不出返回 null（交给调用方按冲突处理）。 */
+function installedRepoOf(profile: string, name: string): string | null {
+  try {
+    const pkg = JSON.parse(readFileSync(join(profileDirectory(profile), 'node_modules', name, 'package.json'), 'utf8')) as {
+      repository?: string | { url?: string }
+    }
+    const repo = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url
+    return repo ? githubRepoOf(repo) : null
+  } catch {
+    return null
+  }
+}
+
 /** 宿主 dsh CLI 版本：优先直接跑 `dsh --version`（与 pnpm/npm/git 同款同步探测，1500ms 超时兜底，
  *  绝不挂起）—— 原先从 process.argv[1] 向上找 package.json 猜版本在部分宿主加载方式下取不到，
  *  导致 issue 环境快照 DSH: unknown；拿不到再退回入口 package.json 查找（dsh 不在 PATH 时兜底）。 */
@@ -649,8 +665,9 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
         // 任务自动入队：即使已有插件操作在跑也接受请求（FIFO 串行执行），不再 409 拒绝
         try {
           const body = await readJsonBody(request)
-          // mode: 'update' = 已安装目标的覆盖更新（放行 add，pnpm 对已存在依赖原位覆盖重装）
-          const mode = body !== null && typeof body === 'object' && (body as { mode?: unknown }).mode === 'update'
+          // mode: 'update' = 已安装目标的覆盖更新（放行 add，pnpm 对已存在依赖原位覆盖重装）。
+          // 后续「同仓库残留」检测可能把 install 就地升级为 update（见包名冲突检测），故用 let。
+          let mode = body !== null && typeof body === 'object' && (body as { mode?: unknown }).mode === 'update'
             ? 'update'
             : 'install'
           // installTargetOf 先把完整 DSH 命令（`dsh plugin [--profile <p>] add <target>`）剥成裸目标，
@@ -822,6 +839,31 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
               })
               return
             }
+            // 包名冲突检测（仅 git 通道）：git 目标包内声明的 name 若与 profile 已装依赖同名，
+            // pnpm 会以该 name 做依赖键撞车，抛出的 CLI 报错晦涩难懂（issue #25：sandbase-harness
+            // 声明 managed-agents，但该包名在 registry 上被另一仓库占用，npm 反查搜不到 → git 直装
+            // 撞已装同名依赖）。到这里已装依赖要么来源不同仓库、要么 spec 是版本号解析不出仓库身份。
+            // 读 node_modules 里已装包的真实 repository 区分两种情况：
+            //  - 指向同一仓库 → 是「同仓库残留」（spec 丢了仓库身份），就地转 update 覆盖重装（幂等）；
+            //  - 指向别的仓库 / 读不到 → 跨仓库包名冲突，入队前转成明确 409，指导用户先卸载或改装。
+            if (preflight.name !== null && repoTarget !== null && target === repoTarget) {
+              const declared = preflight.name
+              if (installed[declared] !== undefined) {
+                const installedRepo = installedRepoOf(profile, declared)
+                if (installedRepo !== null && gitRepo !== null && installedRepo.toLowerCase() === gitRepo.toLowerCase()) {
+                  // 同名且同源：已装 spec 丢了仓库身份导致的残留，直接按 update 覆盖重装，不打扰用户
+                  attempts.push(`same-repo residual: \`${declared}\` resolves to \`${installedRepo}\` → reinstall as update`)
+                  mode = 'update'
+                } else {
+                  attempts.push(`package name conflict: \`${gitRepo}\` declares npm name \`${declared}\`, which is already present in the profile and cannot be matched to this repo (that npm name is likely registered by another repository)`)
+                  const error = lang === 'zh'
+                    ? `already installed: ${declared} —— ${gitRepo} 声明的 npm 包名「${declared}」已存在于当前 profile，且无法匹配到本仓库（该包名在 npm 上可能被其他仓库占用）。请先移除现有的 ${declared}（dsh plugin remove ${declared}），再重新安装；或改装该包名对应的官方 npm 包。`
+                    : `already installed: ${declared} — ${gitRepo} declares the npm package name "${declared}", which is already present in the profile and cannot be matched to this repo (that npm name is likely registered by another repository). Remove the existing ${declared} dependency (dsh plugin remove ${declared}) first, then retry; or install the official npm package under that name.`
+                  sendJson(response, 409, { error, attempts })
+                  return
+                }
+              }
+            }
           }
           // 入队前复检（与上方检查同语义，但必须在同步块内）：preflight 的 await 期间并发请求
           // 可能已通过上方检查、任务却尚未入队——此处检查与 startPluginMutation 之间无 await，

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

@@ -25,15 +25,19 @@ const execFileAsync = promisify(execFile)
  *  否则 `/install` 请求永远不返回、任务不入队、前端进度卡 0%。超时后放行（交给装后校验）。 */
 const PREFLIGHT_TIMEOUT_MS = 15_000
 
-/** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径。 */
+/** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径；
+ *  name 为 git 分发包 package.json 声明的包名（非 git 目标/无法确定时为 null），
+ *  供安装路由做「包名冲突」检测 —— 同名包名已被其他来源占用时，pnpm 装前必然撞车，
+ *  需要把晦涩的 CLI 报错转成明确的拦截。 */
 export interface PreflightResult {
   ok: boolean
   missing: string | null
+  name: string | null
 }
 
 export async function preflightTarget(target: string): Promise<PreflightResult> {
   const source = githubRepoOf(target)
-  if (source === null) return { ok: true, missing: null }
+  if (source === null) return { ok: true, missing: null, name: null }
   const [owner, repo] = source.split('/')
   let commit = ''
   try {
@@ -43,15 +47,15 @@ export async function preflightTarget(target: string): Promise<PreflightResult>
     })
     commit = stdout.split(/\s+/)[0] ?? ''
   } catch {
-    return { ok: true, missing: null }
+    return { ok: true, missing: null, name: null }
   }
-  if (!commit) return { ok: true, missing: null }
+  if (!commit) return { ok: true, missing: null, name: null }
   const dir = mkdtempSync(join(tmpdir(), 'dsh-preflight-'))
   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')
-    if (meta === null) return { ok: true, missing: null }
+    if (meta === null) return { ok: true, missing: null, name: null }
     const dot = (meta.exports as Record<string, unknown> | undefined)?.['.']
     const resolved = typeof dot === 'string'
       ? dot
@@ -60,9 +64,9 @@ export async function preflightTarget(target: string): Promise<PreflightResult>
         : undefined
     const entry = typeof resolved === 'string' ? resolved : typeof meta.main === 'string' ? meta.main : 'index.js'
     const inTar = await hasTarEntry(tar, `package/${entry}`)
-    return { ok: inTar, missing: inTar ? null : entry }
+    return { ok: inTar, missing: inTar ? null : entry, name: typeof meta.name === 'string' ? meta.name : null }
   } catch {
-    return { ok: true, missing: null }
+    return { ok: true, missing: null, name: null }
   } finally {
     rmSync(dir, { recursive: true, force: true })
   }