dsh-plugin 1.3.7 → 1.3.9

package/src/client/locales.ts

@@ -25,7 +25,9 @@ export const zh = {
   fork: 'Fork',
   loading: '正在加载插件数据…',
   failed: '插件数据加载失败',
-  failedDesc: '请稍后重试，或点击右上角按钮在浏览器中打开插件中心。',
+  // 目录拉不出来时的精准提示：按「是否配置了代理」区分，引导排查网络 / 代理
+  failedDescNoProxy: '你的网络似乎不通，无法获取插件目录数据。请检查网络连接后重试；或点击右上角按钮在浏览器中打开插件中心。',
+  failedDescProxy: '你的网络似乎不通，或设置里的 HTTP 代理地址不可达，无法获取插件目录数据。请检查代理设置与网络连接后重试；或点击右上角按钮在浏览器中打开插件中心。',
   retry: '重试',
   install: '安装',
   // AI 识别可能需要命令行辅助的插件（webInstallable=false）：仍可尝试一键安装，失败时复制命令去 dsh 终端
@@ -309,6 +311,14 @@ export const zh = {
   failNetworkTarget: '无法访问 {url} —— 你的网络连接不通',
   // 「去系统诊断」直达按钮：网络不通提示下方的品牌实底按钮，跳到设置 → 系统诊断跑连通性检测
   failNetworkRunDiag: '去系统诊断检测网络',
+  failDshMissingHint: '系统找不到 dsh 命令（dsh 未加入系统 PATH），无法调用安装器执行安装。请确认 DeepSeek Harness 已正确安装、dsh 已加入 PATH（或重新安装），然后重试。这不是插件本身的问题。',
+  failPnpmMissingHint: '安装器找到了 dsh，但系统里没有 pnpm 命令（dsh 用它来管理 profile 插件）。请先安装 pnpm（如 npm install -g pnpm），确认 pnpm 已加入 PATH 后重试。这不是插件本身的问题。',
+  // 自定义安装三卡片入口的渠道名（报错/日志溯源：本次安装从哪个入口发起）
+  installChannelNpm: 'NPM 包',
+  installChannelGit: 'GitHub 源码',
+  installChannelDsh: 'DSH 命令',
+  // 报错/通知中心的入口溯源行：前缀在错误正文顶部，精准指出自定义安装是从哪张卡片发起的
+  installEntryLine: '安装入口：{c}。',
   reportIssue: '去插件仓库提交 Issue',
   detail: '打开详情',
   noResult: '没有找到匹配的插件',
@@ -368,7 +378,9 @@ export const en = {
   fork: 'Fork',
   loading: 'Loading plugin data…',
   failed: 'Failed to load plugin data',
-  failedDesc: 'Please retry, or open the hub in your browser with the button above.',
+  // Precise hints when the catalog cannot load: distinguished by whether a proxy is configured
+  failedDescNoProxy: 'Your network seems unreachable, so the plugin catalog could not be loaded. Please check your connection and retry; or open the hub in your browser with the button above.',
+  failedDescProxy: 'Your network seems unreachable, or the HTTP proxy in Settings is unreachable, so the plugin catalog could not be loaded. Please check the proxy address and your connection, then retry; or open the hub in your browser with the button above.',
   retry: 'Retry',
   install: 'Install',
   // AI-flagged plugins that may need command-line help (webInstallable=false): one-click install still allowed,
@@ -654,6 +666,14 @@ export const en = {
   failNetworkTarget: 'Cannot reach {url} — your network connection is down',
   // Diagnostics shortcut button under the network-down hint: jumps to Settings → System Diagnostics
   failNetworkRunDiag: 'Run a network diagnostic',
+  failDshMissingHint: 'The dsh command could not be found (it is not on the system PATH), so the installer could not run. Please make sure DeepSeek Harness is installed correctly and dsh is on your PATH (or reinstall it), then retry. This is not a problem with the plugin itself.',
+  failPnpmMissingHint: 'The installer found dsh, but pnpm is missing on this machine (dsh uses it to manage profile plugins). Please install pnpm first (e.g. npm install -g pnpm), make sure it is on your PATH, then retry. This is not a problem with the plugin itself.',
+  // Custom install entry channel names (the three cards) — used in error/log traceability
+  installChannelNpm: 'NPM package',
+  installChannelGit: 'GitHub source',
+  installChannelDsh: 'DSH command',
+  // Entry traceability line prefixed at the top of the error text: which card initiated this install
+  installEntryLine: 'Install entry: {c}.',
   reportIssue: 'Report an Issue to the plugin repo',
   detail: 'Open details',
   noResult: 'No plugins match your search',

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/styles/List.module.css

@@ -301,7 +301,6 @@ body[data-ds-dark-theme] .uninstallBtn:hover {
 }
 
 .retryBtn {
-  margin-top: 4px;
   font-size: 12px;
   line-height: 18px;
   color: var(--hub-text-secondary);
@@ -318,6 +317,30 @@ body[data-ds-dark-theme] .uninstallBtn:hover {
   background: var(--hub-bg-hover);
 }
 
+/* 失败态按钮行：重试 + 「去系统诊断检测网络」并排 */
+.stateActions {
+  margin-top: 4px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.diagBtn {
+  font-size: 12px;
+  line-height: 18px;
+  color: #fff;
+  border: none;
+  border-radius: 6px;
+  padding: 4px 12px;
+  background: var(--hub-brand);
+  cursor: pointer;
+  user-select: none;
+}
+
+.diagBtn:hover {
+  background: var(--hub-brand-hover);
+}
+
 /* —— footer —— */
 
 .footer {

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,