dsh-plugin 1.4.0 → 1.4.1

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.1",
   "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/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 })
   }