dsh-plugin 1.3.8 → 1.3.10

package/lib/http/routes.js

@@ -11,7 +11,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir, release } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fetchViaCurl, gitLsRemote, probeUrl, systemProxy } from '../services/probe.js';
 import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubRepoOf, githubTarget, globalNpmPackagesOf, hasQueuedTarget, installTargetOf, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName } from '../services/install/install.js';
 import { recordInstalledVersion, recordResolvedNpmPackage, readInstalledVersions, removeInstalledVersion } from '../services/profile/installed-versions.js';
@@ -145,11 +145,29 @@ function hostDshVersion() {
     }
     return null;
 }
+/** 探测命令行工具的版本号（pnpm --version / npm --version / git --version）：
+ *  未安装 / 不在 PATH / 超时一律返回 null —— issue 环境快照如实写 unknown，绝不挂起。
+ *  （同步探测仅用于启动期/请求期的低频率 /env 快照，安装通道不经过这里。） */
+function toolVersion(cmd, args) {
+    try {
+        const r = spawnSync(cmd, args, { timeout: 1500, encoding: 'utf8' });
+        if (r.error || r.status !== 0)
+            return null;
+        const v = (r.stdout ?? '').trim().split(/\r?\n/)[0];
+        return v || null;
+    }
+    catch {
+        return null;
+    }
+}
 /** 宿主环境快照：提交 bug 时随 issue 附上，便于作者复现（前端 /env 端点返回）。 */
 function hostEnv(profile) {
     return {
         dshVersion: hostDshVersion(),
         nodeVersion: process.version,
+        pnpmVersion: toolVersion('pnpm', ['--version']),
+        npmVersion: toolVersion('npm', ['--version']),
+        gitVersion: toolVersion('git', ['--version']),
         platform: process.platform,
         arch: process.arch,
         release: release(),
@@ -650,6 +668,12 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                     const source = typeof body === 'object' && body !== null && typeof body.source === 'string'
                         ? body.source
                         : '';
+                    // 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+                    // 客户端显式上报，服务端日志/报错据此精准溯源「从哪个入口发起」；目录插件安装不传。
+                    const installChannel = (() => {
+                        const raw = body !== null && typeof body === 'object' ? body.installChannel : undefined;
+                        return raw === 'git' || raw === 'dsh' || raw === 'npm' ? raw : undefined;
+                    })();
                     const settings = loadSettings(profile);
                     // 界面语言（客户端随请求携带）：错误消息按用户当前语言提示（中文界面给中文，英文界面给英文）
                     const lang = typeof body === 'object' && body !== null && body.lang === 'en'
@@ -688,6 +712,8 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                             globalNpm,
                             timeoutMs: COMMAND_TIMEOUT_MS,
                             env: mutationEnv(settings),
+                            // 全局 npm 安装由 NPM 包卡片/官方命令发起：日志体现入口渠道
+                            installChannel: installChannel ?? 'npm',
                         });
                         sendJson(response, 200, { ok: true, task: task.id });
                         return;
@@ -821,6 +847,8 @@ export function mountPluginHubRoutes(webServer, profile, loader) {
                         env: mutationEnv(settings),
                         // 覆盖更新：npm 通道命令显式 @latest（pnpm add 无版本对已存在依赖是幂等的，不加版本不会真更新）
                         updateNpm: mode === 'update',
+                        // 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：日志/报错据此溯源
+                        installChannel,
                     });
                     sendJson(response, 200, { ok: true, task: task.id });
                 }

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

@@ -7,7 +7,7 @@
  * 每个任务一次 `dsh plugin --profile <profile> <action> <target>` 子进程，
  * 输出流式收集到任务上；卸载成功时尝试从运行中 loader 即时停用（见 loader.ts）。
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { 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';
@@ -40,12 +40,12 @@ export function activeTask() {
     for (const item of queue) {
         const task = item.task;
         if (task.status === 'pending') {
-            found.push({ id: task.id, target: show(task), action: task.action, status: 'pending', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES), attempts: task.attempts });
+            found.push({ id: task.id, target: show(task), action: task.action, status: 'pending', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES), attempts: task.attempts, installChannel: task.installChannel });
         }
     }
     tasks.forEach((task) => {
         if (task.status === 'running') {
-            found.unshift({ id: task.id, target: show(task), action: task.action, status: 'running', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES), attempts: task.attempts });
+            found.unshift({ id: task.id, target: show(task), action: task.action, status: 'running', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES), attempts: task.attempts, installChannel: task.installChannel });
         }
     });
     return found;
@@ -124,6 +124,23 @@ function cliInvocation() {
     }
     return { file: 'dsh', prefixArgs: [], cwd: process.cwd(), useShell: process.platform === 'win32' };
 }
+/**
+ * dsh 命令存在性探测：which/where 找 PATH 里的 dsh。
+ * Windows shell 模式命令缺失时 cmd 只输出 GBK 乱码「不是内部或外部命令」（UTF-8 解码后
+ * 无法匹配），POSIX 非 shell 模式才会抛 spawn dsh ENOENT —— 两种形态都不可靠，统一在
+ * spawn 前用 which/where 探测，命令不存在则直接失败并打 ASCII 标记 [dsh-missing]（乱码免疫）。
+ * 探测自身异常（which/where 不可用等）不拦截安装，交给装后校验兜底。
+ */
+function dshOnPath(env) {
+    try {
+        const probe = process.platform === 'win32' ? 'where' : 'which';
+        const res = spawnSync(probe, ['dsh'], { env, encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'pipe'] });
+        return res.status === 0 && (res.stdout ?? '').trim().length > 0;
+    }
+    catch {
+        return true;
+    }
+}
 function stopChild(child) {
     if (process.platform === 'win32' && child.pid !== undefined) {
         const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore' });
@@ -150,13 +167,24 @@ function mutationCategory(action) {
 function mutationVerb(action) {
     return action === 'remove' ? '开始卸载' : action === 'update' ? '开始更新' : '开始安装';
 }
+/** 系统日志入口渠道后缀：自定义安装（带渠道）在日志里体现「从哪张卡片发起」，
+ *  目录插件安装（无渠道）返回空串。日志中文语境，渠道名用中文口语。 */
+function channelLabel(channel) {
+    if (channel === 'git')
+        return '（GitHub 源码入口）';
+    if (channel === 'dsh')
+        return '（DSH 命令入口）';
+    if (channel === 'npm')
+        return '（NPM 包入口）';
+    return '';
+}
 /**
  * Enqueue a plugin mutation and return its task. Tasks run strictly serially:
  * the queue worker starts the next one only after the previous finishes.
  * Progress is visible through `getTask(id)` / `activeTask()` until done.
  */
 export function startPluginMutation(options) {
-    const task = { id: nextTaskId, target: options.target, displayTarget: options.displayTarget, globalNpm: options.globalNpm, action: options.action, status: 'pending', timedOut: false, exitCode: null, progress: 0, lines: [], attempts: options.attempts ?? [], needsRestart: false };
+    const task = { id: nextTaskId, target: options.target, displayTarget: options.displayTarget, globalNpm: options.globalNpm, action: options.action, status: 'pending', timedOut: false, exitCode: null, progress: 0, lines: [], attempts: options.attempts ?? [], needsRestart: false, installChannel: options.installChannel };
     nextTaskId = nextTaskId >= Number.MAX_SAFE_INTEGER ? 1 : nextTaskId + 1;
     tasks.set(task.id, task);
     if (tasks.size > MAX_TASKS) {
@@ -169,14 +197,18 @@ export function startPluginMutation(options) {
         });
     }
     queue.push({ task, options: { ...options } });
-    // 系统日志：记录任务入队（安装/卸载/更新开始）
+    // 任务输出首行标记入口渠道（ASCII 标记，乱码免疫）：进度面板/失败明细里能溯源「从哪张卡片发起」
+    if (options.installChannel !== undefined) {
+        pushLine(task, `[install-channel] ${options.installChannel}`);
+    }
+    // 系统日志：记录任务入队（安装/卸载/更新开始），自定义安装带入口渠道后缀
     const category = mutationCategory(options.action);
     appendLog(options.profile, {
         at: Date.now(),
         level: 'info',
         category,
         event: `${category}.start`,
-        message: `${mutationVerb(options.action)} ${options.displayTarget ?? options.target}`,
+        message: `${mutationVerb(options.action)} ${options.displayTarget ?? options.target}${channelLabel(options.installChannel)}`,
     });
     pumpQueue();
     return task;
@@ -202,7 +234,7 @@ function pumpQueue() {
                 level: 'success',
                 category,
                 event: `${category}.done`,
-                message: `${verb('成功')} ${show}${task.needsRestart ? '（待重启生效）' : ''}`,
+                message: `${verb('成功')} ${show}${channelLabel(options.installChannel)}${task.needsRestart ? '（待重启生效）' : ''}`,
             });
         }
         else if (task.status === 'failed') {
@@ -211,7 +243,7 @@ function pumpQueue() {
                 level: 'error',
                 category,
                 event: `${category}.fail`,
-                message: `${verb('失败')} ${show}`,
+                message: `${verb('失败')} ${show}${channelLabel(options.installChannel)}`,
             });
         }
         else if (task.status === 'cancelled') {
@@ -220,7 +252,7 @@ function pumpQueue() {
                 level: 'warn',
                 category,
                 event: 'task.cancel',
-                message: `已取消 ${show}`,
+                message: `已取消 ${show}${channelLabel(options.installChannel)}`,
             });
         }
         // 已终态的任务移出队列：既防 queue 数组无限增长（内存泄漏），也让下一轮 pump 干净
@@ -273,6 +305,20 @@ function spawnMutation(options) {
         let settled = false;
         let child;
         try {
+            // 独立 CLI 场景（file: 'dsh'，宿主加载器走 node bin 不经过这里）：先探测 dsh 是否在 PATH。
+            // 命令不存在时 Windows shell 模式只回传 GBK 乱码、POSIX 才抛 spawn dsh ENOENT —— 统一前置
+            // 拦截并打 ASCII 标记 [dsh-missing]，前端据此精准提示「dsh 未加入 PATH」而不是笼统的插件失败。
+            if (invocation.file === 'dsh' && !dshOnPath(env)) {
+                const detail = '[dsh-missing] the dsh CLI was not found on this machine (DeepSeek Harness not installed, or dsh not on the PATH)';
+                if (task) {
+                    task.status = 'failed';
+                    task.exitCode = null;
+                    task.progress = 0;
+                    pushLine(task, detail);
+                }
+                resolveOnce({ exitCode: 1, timedOut: false, error: detail, stdout: '', stderr: detail });
+                return;
+            }
             child = spawn(invocation.file, attemptArgs, {
                 cwd: invocation.cwd,
                 env,

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

@@ -26,6 +26,9 @@ export interface InstallTask {
     /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时任务执行全局 npm 安装，不进任何 profile */
     globalNpm?: string[];
     action: 'add' | 'remove' | 'update';
+    /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+     *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装无此字段。 */
+    installChannel?: 'npm' | 'git' | 'dsh';
     /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
     status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled';
     timedOut: boolean;
@@ -54,6 +57,7 @@ export interface QueueItem {
         timeoutMs?: number;
         env?: NodeJS.ProcessEnv;
         globalNpm?: string[];
+        installChannel?: 'npm' | 'git' | 'dsh';
     };
 }
 /**

package/lib/types/services/install/task-queue.d.ts

@@ -11,6 +11,8 @@ export interface ActiveTaskInfo {
     lines: string[];
     /** 尝试过的安装方式（npm 反查 + 实际执行命令）：失败时前端 issue 预填需要 */
     attempts: string[];
+    /** 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：前端刷新恢复后仍能精准溯源 */
+    installChannel?: 'npm' | 'git' | 'dsh';
 }
 /** All non-terminal tasks in queue order (running first, then pending). Lets the client resume a queue after a page reload. */
 export declare function activeTask(): ActiveTaskInfo[];
@@ -52,6 +54,9 @@ export declare function startPluginMutation(options: {
     attempts?: string[];
     /** 更新已安装的 npm 包（mode=update）：命令显式带 @latest，让 pnpm 真正解析最新版本 */
     updateNpm?: boolean;
+    /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+     *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装不传 */
+    installChannel?: 'npm' | 'git' | 'dsh';
 }): InstallTask;
 /**
  * 安装后校验已装包的入口文件（package.json 的 main / exports["."].default）是否真实存在。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "1.3.8",
+  "version": "1.3.10",
   "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/PluginHubSection.tsx

@@ -12,7 +12,7 @@ import { createElement as h, useEffect, useRef, useState } from 'react'
 import type { MouseEvent } from 'react'
 import styles from '../styles/Header.module.css'
 import modalStyles from '../styles/Modal.module.css'
-import type { EnvInfo, HubPlugin, SectionProps, ToastState } from '../types.ts'
+import type { EnvInfo, HubPlugin, InstallChannel, SectionProps, ToastState } from '../types.ts'
 import { installCommandOf, repoFromInstallTarget } from '../logic/install-command.ts'
 import { PLUGIN_VERSION } from '../logic/constants.ts'
 import { ensurePluginCss } from '../logic/ensure-plugin-css.ts'
@@ -81,6 +81,9 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
   /** 命令行安装确认弹窗：记录待安装的裸目标（npm 包名 / GitHub 地址，DSH 命令已剥成裸目标）——
    *  与应用商店同一套确认/进度/结果弹窗，提供时 plugin 传 null 走 customTarget 模式 */
   const [confirmCustomTarget, setConfirmCustomTarget] = useState<string | null>(null)
+  /** 自定义安装入口渠道（三张卡片之一）：随确认弹窗记录，提交时上报服务端，
+   *  报错/日志据此精准溯源「从哪个入口发起」（npm 全局安装固定为 'npm'） */
+  const [confirmCustomChannel, setConfirmCustomChannel] = useState<InstallChannel | null>(null)
   /** 全局 npm 安装确认弹窗（官方 `npm install -g <pkgs>`）：记录原始命令 + 解析出的包列表，
    *  走与应用商店同一套确认/进度/结果弹窗（plugin 传 null，InstallModal 走 globalNpm 模式） */
   const [confirmGlobalNpm, setConfirmGlobalNpm] = useState<{ raw: string; pkgs: string[] } | null>(null)
@@ -212,6 +215,7 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
       if (e.key === 'Escape') {
         setConfirmPlugin(null)
         setConfirmCustomTarget(null)
+        setConfirmCustomChannel(null)
         setConfirmGlobalNpm(null)
         setUninstallPlugin(null)
         setUninstallItem(null)
@@ -471,11 +475,14 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
                 // 不进插件列表，不做「已安装→更新」判定 —— npm install -g 对已装包是原位覆盖更新，天然幂等）
                 if (opts?.globalNpm && opts.globalNpm.length > 0) {
                   setConfirmCustomTarget(null)
+                  setConfirmCustomChannel(null)
                   setConfirmIsUpdate(false)
                   setConfirmGlobalNpm({ raw, pkgs: opts.globalNpm })
                   return
                 }
                 setConfirmGlobalNpm(null)
+                // 记录入口渠道：报错/日志据此精准提示「从哪张卡片发起的安装」（NPM 包 / GitHub 源码 / DSH 命令）
+                setConfirmCustomChannel(opts.installChannel)
                 setConfirmIsUpdate(customTargetInstalled(target))
                 setConfirmCustomTarget(target)
               },
@@ -635,12 +642,17 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
       onClose: () => {
         setInstallDone(false)
         setConfirmCustomTarget(null)
+        setConfirmCustomChannel(null)
       },
       onCopy: () => {
         doCopy(`pnpm add ${confirmCustomTarget}`)
         setToast({ id: Date.now(), kind: 'copied' })
       },
-      onInstall: () => void queue.installCustom(confirmCustomTarget, confirmIsUpdate ? { update: true } : undefined),
+      onInstall: () => void queue.installCustom(confirmCustomTarget, {
+        update: confirmIsUpdate,
+        // 入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：上报服务端，报错/日志据此溯源
+        channel: confirmCustomChannel ?? 'npm',
+      }),
       onRestart: () => setShowRestartConfirm(true),
     }),
     // 全局 npm 安装确认弹窗（官方 `npm install -g <pkgs>`）：与应用商店同一套确认/进度/结果流程。
@@ -661,12 +673,13 @@ export function PluginHubSection({ t: _hostT, locale }: SectionProps) {
       onClose: () => {
         setInstallDone(false)
         setConfirmGlobalNpm(null)
+        setConfirmCustomChannel(null)
       },
       onCopy: () => {
         doCopy(`npm install -g ${confirmGlobalNpm.pkgs.join(' ')}`)
         setToast({ id: Date.now(), kind: 'copied' })
       },
-      onInstall: () => void queue.installGlobalNpm(confirmGlobalNpm.pkgs),
+      onInstall: () => void queue.installGlobalNpm(confirmGlobalNpm.pkgs, { channel: 'npm' }),
       onRestart: () => setShowRestartConfirm(true),
     }),
     // 卸载确认弹窗：确认/进度/结果视图逻辑收敛在 modals.tsx。

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

@@ -266,6 +266,22 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                       return h('div', { className: styles.failPrepareHint },
                         t(v ? 'failNpmTooLowV' : 'failNpmTooLow', v ? { v } : undefined))
                     }
+                    if (kind === 'dshMissing') {
+                      // 找不到 dsh 命令（Win「不是内部或外部命令」/ POSIX「command not found」/ spawn ENOENT）：
+                      // 本机 DeepSeek Harness 未正确安装或 dsh 不在 PATH，不是插件问题 —— 直接给环境修复指引，不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failDshMissingHint'))
+                    }
+                    if (kind === 'pnpmMissing') {
+                      // 找到了 dsh 但缺 pnpm（dsh 用它管理 profile 插件；dsh 报 pnpm not found on PATH）：
+                      // 本机缺 pnpm，不是插件问题 —— 给安装指引，不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failPnpmMissingHint'))
+                    }
+                    if (kind === 'pnpmStore') {
+                      // pnpm 存在但 store 大版本不匹配（ERR_PNPM_UNEXPECTED_STORE）：profile 目录旧依赖是
+                      // 另一大版本 pnpm 装的，当前 pnpm 不认，任何插件装进该 profile 都会失败 ——
+                      // 给清理重建指引，不引导提 Issue
+                      return h('div', { className: styles.failPrepareHint }, t('failPnpmStoreHint'))
+                    }
                     if (kind === 'network') {
                       // 安装前预检 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
                       // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，

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

@@ -387,7 +387,20 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
           failureKind === 'npmTooOld'
             ? h('div', { className: styles.failPrepareHint },
               t(npmVersion ? 'failNpmTooLowV' : 'failNpmTooLow', npmVersion ? { v: npmVersion } : undefined))
-            : failureKind === 'network'
+            : failureKind === 'dshMissing'
+              // 找不到 dsh 命令（Win「不是内部或外部命令」/ POSIX「command not found」/ spawn ENOENT）：
+              // 本机 DeepSeek Harness 未正确安装或 dsh 不在 PATH，不是插件问题 —— 直接给环境修复指引，不引导提 Issue
+              ? h('div', { className: styles.failPrepareHint }, t('failDshMissingHint'))
+              : failureKind === 'pnpmMissing'
+              // 找到了 dsh 但缺 pnpm（dsh 用它管理 profile 插件；dsh 报 pnpm not found on PATH）：
+              // 本机缺 pnpm，不是插件问题 —— 给安装指引，不引导提 Issue
+              ? h('div', { className: styles.failPrepareHint }, t('failPnpmMissingHint'))
+              : failureKind === 'pnpmStore'
+              // pnpm 存在但 store 大版本不匹配（ERR_PNPM_UNEXPECTED_STORE）：profile 目录旧依赖是
+              // 另一大版本 pnpm 装的，当前 pnpm 不认，任何插件装进该 profile 都会失败 ——
+              // 给清理重建指引，不引导提 Issue
+              ? h('div', { className: styles.failPrepareHint }, t('failPnpmStoreHint'))
+              : failureKind === 'network'
               // 安装前预检 / 安装日志里的连接失败（[network] / git fetch 超时 / DNS / TLS）：
               // 是本机网络不通或代理有问题，不是插件问题 —— 提示检查网络 + 直达「系统诊断」，
               // 不引导提 Issue

package/src/client/components/views/CustomInstallView.tsx

@@ -20,7 +20,7 @@ import { createElement as h, useState } from 'react'
 import type { FormEvent, MouseEvent } from 'react'
 import styles from '../../styles/CustomInstallView.module.css'
 import modal from '../../styles/Modal.module.css'
-import type { Translate } from '../../types.ts'
+import type { InstallChannel, Translate } from '../../types.ts'
 import { CloseIcon, HelpIcon } from '../ui/icons.tsx'
 
 /* —— 自定义安装输入预检 ——
@@ -113,8 +113,10 @@ type HelpTarget = keyof typeof HELP_CARDS
 export function CustomInstallView({ t, onInstallCustom, enableNpm, enableGit, enableDsh, onOpenSettings, profile }: {
   t: Translate
   /** 命令行安装：输入 npm 包名 / npm、pnpm 安装命令 / GitHub 地址 / dsh plugin 命令即装
-   *  （custom 源，受安全设置开关控制）；opts.globalNpm 表示官方 npm 全局安装命令（npm install -g），附带解析出的包列表 */
-  onInstallCustom: (raw: string, opts?: { globalNpm?: string[] }) => void
+   *  （custom 源，受安全设置开关控制）。installChannel 必填 = 入口渠道（三张卡片之一）：
+   *  服务端日志/报错提示据此溯源「从哪个入口发起」；opts.globalNpm 表示官方 npm 全局安装
+   *  命令（npm install -g），附带解析出的包列表（仍属 NPM 包入口）。 */
+  onInstallCustom: (raw: string, opts: { installChannel: InstallChannel; globalNpm?: string[] }) => void
   /** 安全信任三通道开关：关掉后对应输入卡片禁用（不提交），并引导去设置打开 */
   enableNpm: boolean
   enableGit: boolean
@@ -155,9 +157,9 @@ export function CustomInstallView({ t, onInstallCustom, enableNpm, enableGit, en
     const parsed = parseNpmInput(raw)
     if (parsed === null) { setNpmError(t('npmInstallInvalid')); return }
     if (parsed.kind === 'global') {
-      onInstallCustom(raw, { globalNpm: parsed.pkgs })
+      onInstallCustom(raw, { installChannel: 'npm', globalNpm: parsed.pkgs })
     } else {
-      onInstallCustom(parsed.target)
+      onInstallCustom(parsed.target, { installChannel: 'npm' })
     }
     setNpmQuery('')
     setNpmError('')
@@ -166,7 +168,7 @@ export function CustomInstallView({ t, onInstallCustom, enableNpm, enableGit, en
     const target = gitQuery.trim()
     if (!target) return
     if (!isGitHubInput(target)) { setGitError(t('gitInstallInvalid')); return }
-    onInstallCustom(target)
+    onInstallCustom(target, { installChannel: 'git' })
     setGitQuery('')
     setGitError('')
   }
@@ -177,7 +179,7 @@ export function CustomInstallView({ t, onInstallCustom, enableNpm, enableGit, en
     if (parsed === null) { setCmdError(t('dshCmdInvalid')); return }
     // add / update 统一走安装流程：目标已安装时弹窗自动转「更新」覆盖重装（服务端 mode=update 放行），
     // 未安装时即为普通安装 —— 粘贴 `dsh plugin --profile web update dsh-plugin` 这类命令即可更新到最新
-    onInstallCustom(parsed.target)
+    onInstallCustom(parsed.target, { installChannel: 'dsh' })
     setCmdQuery('')
     setCmdError('')
   }

package/src/client/hooks/useTaskQueue.ts

@@ -10,7 +10,7 @@
  * uninstall, cancel) plus the modal task lookups used by the dialogs.
  */
 import { useEffect, useRef, useState } from 'react'
-import type { HubPlugin, LocaleId, Translate } from '../types.ts'
+import type { HubPlugin, InstallChannel, LocaleId, Translate } from '../types.ts'
 import { installCommandOf, installTargetOf, repoFromInstallTarget } from '../logic/install-command.ts'
 import type { InstalledItem } from '../logic/installed.ts'
 
@@ -28,6 +28,9 @@ export interface QueueTask {
   desc?: string
   /** 所属插件仓库（owner/repo）：失败时错误弹窗据此提供「去仓库反馈」入口；卸载为 null */
   repo: string | null
+  /** 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令三张卡片）：失败时错误/通知精准
+   *  溯源「从哪个入口发起」；目录插件安装无此字段（非自定义入口）。 */
+  channel?: InstallChannel
   /** 实际动作（add/update/remove）：成功通知据此区分「安装成功」与「更新成功」。
    *  服务端 /active 带回真实动作；本地乐观入队按 update 标记推断。 */
   action?: 'add' | 'update' | 'remove'
@@ -89,6 +92,15 @@ export interface TaskQueueOptions {
   resolvePending: (repo: string) => { desc?: string; version?: string } | null
 }
 
+/** 入口渠道的 i18n key：NPM 包 / GitHub 源码 / DSH 命令。 */
+const channelKeyOf = (channel: InstallChannel): string =>
+  channel === 'git' ? 'installChannelGit' : channel === 'dsh' ? 'installChannelDsh' : 'installChannelNpm'
+
+/** 失败消息的入口溯源前缀：自定义安装（带渠道）在错误正文顶部精准指出从哪张卡片发起；
+ *  目录插件安装（无渠道）返回 null，错误正文保持原样。 */
+const entryLineOf = (t: Translate, channel: InstallChannel | undefined): string | null =>
+  channel ? t('installEntryLine', { c: t(channelKeyOf(channel)) }) : null
+
 export function useTaskQueue(opts: TaskQueueOptions) {
   const {
     t, langKey, refreshInstalled, onInstallDone, onUninstallDone, onError,
@@ -205,10 +217,12 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       }
     } else {
       // 失败：完整展示全部输出行（最新在前，逆序为日志阅读顺序），不裁剪
-      const detail = lines.length > 0
+      const rawDetail = lines.length > 0
         ? [...lines].reverse().join('\n')
         : q.kind === 'uninstall' ? t('uninstallFail') : t('installFail')
-      onError(detail, q.repo, q.kind, q.command, q.attempts, q.action === 'update')
+      // 自定义安装（带入口渠道）：错误正文顶部精准提示「从哪张卡片发起」，目录安装保持原样
+      const entry = entryLineOf(t, q.channel)
+      onError(entry ? `${entry}\n${rawDetail}` : rawDetail, q.repo, q.kind, q.command, q.attempts, q.action === 'update')
     }
     maybeStopPoll()
   }
@@ -283,7 +297,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
         const res = await fetch('/dsh-plugin-hub/active', { cache: 'no-store' })
         if (!res.ok) throw new Error(`active ${res.status}`)
         const data = await res.json() as {
-          tasks?: { id?: unknown; action?: unknown; target?: unknown; status?: unknown; progress?: unknown; lines?: unknown; attempts?: unknown; needsRestart?: unknown }[]
+          tasks?: { id?: unknown; action?: unknown; target?: unknown; status?: unknown; progress?: unknown; lines?: unknown; attempts?: unknown; needsRestart?: unknown; installChannel?: unknown }[]
           pendingRestarts?: unknown
         }
         const active = (data.tasks ?? []).filter((a) => typeof a.id === 'number')
@@ -313,6 +327,10 @@ export function useTaskQueue(opts: TaskQueueOptions) {
                 lines: Array.isArray(a.lines) ? (a.lines as string[]) : (prevTask?.lines ?? []),
                 attempts: Array.isArray(a.attempts) ? (a.attempts as string[]) : (prevTask?.attempts ?? []),
                 needsRestart: typeof a.needsRestart === 'boolean' ? a.needsRestart : (prevTask?.needsRestart ?? true),
+                // 入口渠道：本地乐观入队已带；服务端 /active 也带回（刷新恢复用），服务端优先
+                channel: (a.installChannel === 'npm' || a.installChannel === 'git' || a.installChannel === 'dsh')
+                  ? a.installChannel
+                  : prevTask?.channel,
               })
             }
             // 保留乐观条目：服务端尚未登记（preflight 中），无真实 id，不能因 active 缺它就被合并吞掉
@@ -353,7 +371,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
         const res = await fetch('/dsh-plugin-hub/active', { cache: 'no-store' })
         if (!res.ok) return
         const data = await res.json() as {
-          tasks?: { id?: unknown; action?: unknown; target?: unknown; status?: unknown; progress?: unknown; lines?: unknown; attempts?: unknown; needsRestart?: unknown }[]
+          tasks?: { id?: unknown; action?: unknown; target?: unknown; status?: unknown; progress?: unknown; lines?: unknown; attempts?: unknown; needsRestart?: unknown; displayTarget?: unknown; installChannel?: unknown }[]
           pendingRestarts?: unknown
         }
         if (cancelled) return
@@ -379,6 +397,8 @@ export function useTaskQueue(opts: TaskQueueOptions) {
               lines: Array.isArray(a.lines) ? (a.lines as string[]) : [],
               attempts: Array.isArray((a as { attempts?: unknown }).attempts) ? ((a as { attempts: string[] }).attempts) : [],
               needsRestart: typeof (a as { needsRestart?: unknown }).needsRestart === 'boolean' ? (a as { needsRestart: boolean }).needsRestart : true,
+              // 服务端登记的入口渠道：自定义安装刷新后也能精准溯源（目录安装无此字段）
+              channel: (a.installChannel === 'npm' || a.installChannel === 'git' || a.installChannel === 'dsh') ? a.installChannel : undefined,
             }
           })
         if (items.length > 0 || pendingRef.current.length > 0) {
@@ -410,6 +430,9 @@ export function useTaskQueue(opts: TaskQueueOptions) {
     update?: boolean
     /** 全局 npm 安装包列表（`npm install -g <pkgs>`）：非空时服务端执行全局安装，不进任何 profile */
     globalNpm?: string[]
+    /** 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：随请求上报服务端落日志，
+     *  失败弹窗/通知据此精准溯源「从哪个入口发起」；目录安装不传。 */
+    channel?: InstallChannel
   }) => {
     // 防重复入队：同一目标已在排队/执行中则忽略
     if (queueRef.current.some((q) => q.kind === 'install' && q.target === input.repo)) return
@@ -428,6 +451,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       version: input.version, updatedAt: input.updatedAt,
       status: 'running', progress: 0, lines: [], optimistic: true,
       command: input.command,
+      channel: input.channel,
       action: input.update ? 'update' : 'add',
       // 服务端登记后 /active 会带回真实尝试记录（npm 反查 + 执行命令），先占位空列表
       attempts: [], needsRestart: true,
@@ -446,6 +470,8 @@ export function useTaskQueue(opts: TaskQueueOptions) {
           mode: input.update ? 'update' : undefined,
           // 界面语言带给服务端：网络预检等错误消息按用户当前语言返回（中文界面给中文，英文界面给英文）
           ...(langKey ? { lang: langKey } : {}),
+          // 自定义安装入口渠道（三张卡片之一）：服务端日志/报错提示据此溯源
+          ...(input.channel ? { installChannel: input.channel } : {}),
           ...(input.globalNpm && input.globalNpm.length > 0 ? { globalNpm: input.globalNpm } : {}),
         }),
         signal: controller.signal,
@@ -455,8 +481,11 @@ export function useTaskQueue(opts: TaskQueueOptions) {
         // 请求层失败（重复安装 409 / 参数错误 / 安全开关 403 等）：移除乐观条目 + 完整错误弹窗
         applyQueue((prev) => prev.filter((x) => x.id !== tempId))
         // 同步 400（如预检拦截）服务端会附上已尝试的安装方式，issue 预填一并展示；
-        // 用 || 而非 ?? ：error 为空字符串时回退 HTTP 状态，避免复制出来是空白
-        onError(data.error || `HTTP ${res.status}`, input.repo, 'install', input.command, data.attempts)
+        // 用 || 而非 ?? ：error 为空字符串时回退 HTTP 状态，避免复制出来是空白。
+        // 自定义安装（带入口渠道）：错误正文顶部精准提示「从哪张卡片发起」
+        const entry = entryLineOf(t, input.channel)
+        const msg = data.error || `HTTP ${res.status}`
+        onError(entry ? `${entry}\n${msg}` : msg, input.repo, 'install', input.command, data.attempts)
         return
       }
       const taskId = data.task
@@ -476,7 +505,10 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       const reason = aborted
         ? t('requestTimeout')
         : err instanceof Error && err.message ? err.message : String(err ?? '')
-      onError(reason ? `${t('installFail')} — ${reason}` : t('installFail'), input.repo, 'install', input.command)
+      // 自定义安装（带入口渠道）：错误正文顶部精准提示「从哪张卡片发起」
+      const entry = entryLineOf(t, input.channel)
+      const msg = reason ? `${t('installFail')} — ${reason}` : t('installFail')
+      onError(entry ? `${entry}\n${msg}` : msg, input.repo, 'install', input.command)
     } finally {
       window.clearTimeout(timeout)
       submittingRef.current.delete(input.repo)
@@ -505,9 +537,11 @@ export function useTaskQueue(opts: TaskQueueOptions) {
 
   /** 命令行安装：用户手输 npm 包名或 GitHub 地址，走 custom 源（受安全开关控制）。
    *  update=true 时对已安装目标放行覆盖重装（与目录插件「更新」同一语义）。
+   *  channel=入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：上报服务端落日志，
+   *  失败弹窗/通知据此精准溯源。
    *  队列展示/防重一律用归一化身份（owner/repo 或 npm 包名）：与服务端 /active 合并、
    *  弹窗目标匹配同口径，npm 包名透传不受影响。 */
-  const installCustom = async (raw: string, opts?: { update?: boolean }) => {
+  const installCustom = async (raw: string, opts?: { update?: boolean; channel?: InstallChannel }) => {
     const target = raw.trim()
     if (!target) return
     const repo = repoFromInstallTarget(target)
@@ -517,12 +551,13 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       command: `pnpm add ${target}`,
       source: 'custom',
       update: opts?.update,
+      channel: opts?.channel,
     })
   }
 
   /** 全局 npm 安装（官方 README 的 `npm install -g <pkgs>`）：不进任何 profile、无需宿主重启。
-   *  队列展示/防重用包列表空格拼接的身份（与服务端 target 同口径）。 */
-  const installGlobalNpm = async (pkgs: string[], opts?: { update?: boolean }) => {
+   *  队列展示/防重用包列表空格拼接的身份（与服务端 target 同口径）；入口渠道固定为 npm（NPM 包卡片）。 */
+  const installGlobalNpm = async (pkgs: string[], opts?: { update?: boolean; channel?: InstallChannel }) => {
     const list = (pkgs ?? []).map((p) => p.trim()).filter((p) => p !== '')
     if (list.length === 0) return
     const identity = list.join(' ')
@@ -533,6 +568,7 @@ export function useTaskQueue(opts: TaskQueueOptions) {
       source: 'custom',
       globalNpm: list,
       update: opts?.update,
+      channel: opts?.channel ?? 'npm',
     })
   }