dsh-plugin 1.3.8 → 1.3.9

package/src/client/logic/failures.ts

@@ -151,15 +151,22 @@ export function removeNotification(id: number): NotificationRecord[] {
   return next
 }
 
-export type FailureKind = 'npmTooOld' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'repo'
+export type FailureKind = 'npmTooOld' | 'dshMissing' | 'pnpmMissing' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'repo'
 
 /**
- * 失败归类，五态。无论底层机制如何（pnpm 白名单拦截 / 构建脚本被忽略 / prepare 失败），
+ * 失败归类，七态。无论底层机制如何（pnpm 白名单拦截 / 构建脚本被忽略 / prepare 失败），
  * 对用户而言结果都一样 —— 当前安装通道（npm 或 git）装不上，就是插件分发/依赖的问题，
- * 一律引导提 Issue；唯一的两个例外是本机环境问题（npm 版本过低 / 网络不通）：
+ * 一律引导提 Issue；唯一的例外是本机环境问题（npm 版本过低 / 找不到 dsh / 找不到 pnpm / 网络不通）：
  * - npmTooOld：失败输出含 npm arborist 的 `edgesOut` 崩溃特征（build-ideal-tree.js 解 peer 依赖时
  *   内部抛错，npm 11.6.0 前必现的已知缺陷，npm/cli#8261、#9787），或服务端已核实本机版本低于
  *   阈值并打了 `[npm-too-low]` 标记 —— 是本机 npm 版本过低/自身缺陷，不是插件问题 → 引导升级 npm
+ * - dshMissing：安装器 spawn 的 `dsh` 命令找不到（Windows cmd「不是内部或外部命令」/ POSIX
+ *   「command not found」/ spawn ENOENT）—— 是本机 DSH 未正确安装或不在 PATH，不是插件问题
+ *   → 提示检查 PATH/重装 DSH，不引导提 Issue
+ * - pnpmMissing：dsh 存在但调用的 `pnpm` 找不到（dsh 报 `pnpm not found on PATH`/POSIX
+ *   「pnpm: command not found」/ spawn ENOENT）—— 本机缺 pnpm（dsh 用 pnpm 管理 profile 插件），
+ *   不是插件问题（dsh-plugin-hub#13：Linux 下 `dsh: pnpm not found on PATH` 被误归插件侧失败）
+ *   → 提示安装/开启 pnpm，不引导提 Issue
  * - network：安装前连通性预检拦截（服务端 `[network]` 标记）或底层连接失败
  *   （ERR_PNPM_GIT_FETCH_FAILED / ETIMEDOUT / DNS 解析 / TLS 握手 / 代理拒绝）——
  *   是本机网络不通/被墙/代理有问题，不是插件问题 → 提示检查网络，不引导提 Issue
@@ -176,6 +183,19 @@ export function classifyFailure(message: string): FailureKind {
   // 不是插件问题 —— 必须最先判，否则该报错会被外层 ERR_PNPM_PREPARE_PACKAGE 吞成
   // 「插件打包分发问题」，误导用户去提 Issue
   if (/\[npm-too-low\]|edgesOut/i.test(message)) return 'npmTooOld'
+  // 找不到 pnpm 命令（dsh 报 `pnpm not found on PATH` —— dsh 用它管理 profile 插件 /
+  // POSIX「pnpm: command not found」/ spawn pnpm ENOENT / Windows cmd 中英文报错）：
+  // 本机缺 pnpm，不是插件问题。必须在 dshMissing 之前 —— dshMissing 正则含裸「command not
+  // found」，会把 `pnpm: command not found` 吞成「dsh 缺失」，误引导用户去装 DSH
+  // （dsh-plugin-hub#13：Linux 下 `dsh: pnpm not found on PATH` 被误归插件侧失败）
+  if (/\[pnpm-missing\]|pnpm not found|pnpm: command not found|spawn pnpm ENOENT|'pnpm' 不是内部或外部命令|"pnpm" 不是内部或外部命令|pnpm['"]?\s*is not recognized/i.test(message)) return 'pnpmMissing'
+  // 找不到 dsh 命令（服务端 [dsh-missing] 标记 —— 乱码免疫：Windows cmd 中文版输出 GBK，
+  // 经 UTF-8 解码成乱码无法匹配原文，故服务端在 spawn 前用 which/where 探测并打 ASCII 标记；
+  // 其余形态：Windows cmd「不是内部或外部命令」/ POSIX「command not found」/
+  // node spawn ENOENT）：是本机 DSH 未正确安装或不在 PATH，不是插件问题 —— 必须先判，
+  // 否则会被外层 "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 白名单（allowBuilds）拦截：插件的 prepare 脚本或依赖里的原生模块构建
   // 被默认拒绝（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED / ERR_PNPM_IGNORED_BUILDS）。
   // 这类错误出现即说明 pnpm 已成功 fetch 到 tarball（网络是通的），主因是插件构建脚本

package/src/client/logic/urls.ts

@@ -40,6 +40,8 @@ export function pluginSiteUrl(repo: string): string {
 function reasonTitleOf(kind: FailureKind): string {
   switch (kind) {
     case 'npmTooOld': return 'npm too old to install'
+    case 'dshMissing': return 'dsh command not found on the user machine'
+    case 'pnpmMissing': return 'pnpm command not found on the user machine'
     case 'pnpmIgnoredBuild': return 'build scripts blocked by pnpm allowlist'
     case 'pluginPrepare': return 'plugin distribution incomplete'
     case 'network': return 'network failure on the user side'

package/src/client/types.ts

@@ -9,6 +9,10 @@
 
 export type LocaleId = 'zh' | 'en'
 
+/** 自定义安装入口渠道：三张卡片（NPM 包 / GitHub 源码 / DSH 命令）。
+ * 客户端提交时显式上报，服务端落日志/报错提示据此溯源「从哪个入口发起」。 */
+export type InstallChannel = 'npm' | 'git' | 'dsh'
+
 /** Translation function signature shared by the host binder and the in-component dictionary. */
 export type Translate = (key: string, params?: Record<string, string | number>) => string
 

package/src/server/http/routes.ts

@@ -646,6 +646,12 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
           const source = typeof body === 'object' && body !== null && typeof (body as { source?: unknown }).source === 'string'
             ? (body as { source: string }).source
             : ''
+          // 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+          // 客户端显式上报，服务端日志/报错据此精准溯源「从哪个入口发起」；目录插件安装不传。
+          const installChannel = (() => {
+            const raw = body !== null && typeof body === 'object' ? (body as { installChannel?: unknown }).installChannel : undefined
+            return raw === 'git' || raw === 'dsh' || raw === 'npm' ? raw : undefined
+          })()
           const settings = loadSettings(profile)
           // 界面语言（客户端随请求携带）：错误消息按用户当前语言提示（中文界面给中文，英文界面给英文）
           const lang = typeof body === 'object' && body !== null && (body as { lang?: unknown }).lang === 'en'
@@ -684,6 +690,8 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
               globalNpm,
               timeoutMs: COMMAND_TIMEOUT_MS,
               env: mutationEnv(settings),
+              // 全局 npm 安装由 NPM 包卡片/官方命令发起：日志体现入口渠道
+              installChannel: installChannel ?? 'npm',
             })
             sendJson(response, 200, { ok: true, task: task.id })
             return
@@ -816,6 +824,8 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
             env: mutationEnv(settings),
             // 覆盖更新：npm 通道命令显式 @latest（pnpm add 无版本对已存在依赖是幂等的，不加版本不会真更新）
             updateNpm: mode === 'update',
+            // 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：日志/报错据此溯源
+            installChannel,
           })
           sendJson(response, 200, { ok: true, task: task.id })
         } catch (error) {

package/src/server/services/install/install-types.ts

@@ -28,6 +28,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
@@ -51,7 +54,7 @@ export interface Invocation {
 /** 排队中的变更任务及其启动参数。 */
 export interface QueueItem {
   task: InstallTask
-  options: { action: 'add' | 'remove' | 'update'; profile: string; target: string; timeoutMs?: number; env?: NodeJS.ProcessEnv; globalNpm?: string[] }
+  options: { action: 'add' | 'remove' | 'update'; profile: string; target: string; timeoutMs?: number; env?: NodeJS.ProcessEnv; globalNpm?: string[]; installChannel?: 'npm' | 'git' | 'dsh' }
 }
 
 /**

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

@@ -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 type { InstallResult, InstallTask, Invocation, QueueItem } from './install-types.ts'
@@ -44,6 +44,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. */
@@ -55,12 +57,12 @@ export function activeTask(): ActiveTaskInfo[] {
   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
@@ -140,6 +142,23 @@ function cliInvocation(): Invocation {
   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?: NodeJS.ProcessEnv): boolean {
+  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: ReturnType<typeof spawn>): void {
   if (process.platform === 'win32' && child.pid !== undefined) {
     const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore' })
@@ -168,6 +187,15 @@ function mutationVerb(action: 'add' | 'remove' | 'update'): string {
   return action === 'remove' ? '开始卸载' : action === 'update' ? '开始更新' : '开始安装'
 }
 
+/** 系统日志入口渠道后缀：自定义安装（带渠道）在日志里体现「从哪张卡片发起」，
+ *  目录插件安装（无渠道）返回空串。日志中文语境，渠道名用中文口语。 */
+function channelLabel(channel: 'npm' | 'git' | 'dsh' | undefined): string {
+  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.
@@ -189,8 +217,11 @@ export function startPluginMutation(options: {
   attempts?: string[]
   /** 更新已安装的 npm 包（mode=update）：命令显式带 @latest，让 pnpm 真正解析最新版本 */
   updateNpm?: boolean
+  /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+   *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装不传 */
+  installChannel?: 'npm' | 'git' | 'dsh'
 }): InstallTask {
-  const task: InstallTask = { 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: InstallTask = { 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) {
@@ -203,14 +234,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
@@ -235,7 +270,7 @@ function pumpQueue(): void {
         level: 'success',
         category,
         event: `${category}.done`,
-        message: `${verb('成功')} ${show}${task.needsRestart ? '（待重启生效）' : ''}`,
+        message: `${verb('成功')} ${show}${channelLabel(options.installChannel)}${task.needsRestart ? '（待重启生效）' : ''}`,
       })
     } else if (task.status === 'failed') {
       appendLog(options.profile, {
@@ -243,7 +278,7 @@ function pumpQueue(): void {
         level: 'error',
         category,
         event: `${category}.fail`,
-        message: `${verb('失败')} ${show}`,
+        message: `${verb('失败')} ${show}${channelLabel(options.installChannel)}`,
       })
     } else if (task.status === 'cancelled') {
       appendLog(options.profile, {
@@ -251,7 +286,7 @@ function pumpQueue(): void {
         level: 'warn',
         category,
         event: 'task.cancel',
-        message: `已取消 ${show}`,
+        message: `已取消 ${show}${channelLabel(options.installChannel)}`,
       })
     }
     // 已终态的任务移出队列：既防 queue 数组无限增长（内存泄漏），也让下一轮 pump 干净
@@ -319,6 +354,20 @@ function spawnMutation(options: {
     let settled = false
     let child: ReturnType<typeof spawn>
     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,