dsh-plugin 1.6.6 → 1.6.8

package/src/client/logic/failures.ts

@@ -151,7 +151,7 @@ export function removeNotification(id: number): NotificationRecord[] {
   return next
 }
 
-export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'registryVersionStale' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'hub'
+export type FailureKind = 'npmTooOld' | 'dshMissing' | 'gitMissing' | 'pnpmMissing' | 'npmMissing' | 'pnpmStore' | 'pnpmWorkspace' | 'originRejected' | 'pnpmPolicy' | 'pnpmUnusedPatch' | 'pnpmMissingDep' | 'registryVersionStale' | 'pnpmLinkedDirMissing' | 'fileLocked' | 'accessDenied' | 'fsUnavailable' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'network' | 'hubState' | 'hub'
 
 /** Match the pnpm error code, not a generic mention of checksum or integrity. */
 function missingTarballIntegrity(message: string): boolean {
@@ -238,6 +238,12 @@ export function classifyFailure(message: string): FailureKind {
   // 构建脚本真的跑挂了才算插件问题。Command failed 区分大小写：只匹配 pnpm 的包装，
   // 不匹配宿主那句小写 dsh: plugin command failed
   if (/ERR_PNPM_PREPARE_PACKAGE|ELIFECYCLE|prepare-guard/i.test(message) || /Command failed/.test(message)) return 'pluginPrepare'
+  // 安装器自身产生的状态类消息（未安装 / 不在此处卸载 / 已在队列中 / 已安装）：这几句由本服务的
+  // 守卫发出，不是 CLI 输出、也不是插件问题，而是插件中心的已安装列表与实读快照不同步。
+  // 单独归类，让前端给「刷新后重试」这类可行动提示，而不是当作未知失败引导去提 Issue。
+  // already installed 只认「整行就是它」的短形态（旧版本守卫留下的历史记录）；带「——」说明的
+  // 包名冲突另有处置，不能按状态不同步提示。
+  if (/plugin is not installed|plugin cannot be uninstalled here|already queued:|^already installed: \S+$/im.test(message)) return 'hubState'
   // 其余未知失败：引导到插件中心仓库排查
   return 'hub'
 }

package/src/client/logic/urls.ts

@@ -63,6 +63,7 @@ function reasonTitleOf(kind: FailureKind): string {
     case 'pnpmIgnoredBuild': return 'build scripts blocked by pnpm allowlist'
     case 'pluginPrepare': return 'plugin distribution incomplete'
     case 'network': return 'network failure on the user side'
+    case 'hubState': return 'stale install state in the plugin hub'
     case 'hub': return 'install failed (cause unclassified)'
     default: return 'plugin install failed'
   }
@@ -80,13 +81,13 @@ function reasonTitleOf(kind: FailureKind): string {
 export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | null, command?: string, attempts?: string[]): string {
   // 原因判定：按失败类型归类，便于作者判断问题是否出在插件侧。
   // [packaging]（预检/装后校验拦截）单独列：无论走 npm 还是 git 通道，都是分发物不完整
-  // （package.json 声明的入口文件在发布物里缺失），作者照此补齐即可。
+  // （package.json 声明的文件在发布物里缺失），作者照此补齐即可。
   const kind = classifyFailure(message)
   const executed = executedCommandOf(command, attempts)
   // 标题 = 错误原因（非动作词），让 issue 列表一眼可分流
   const title = `[dsh-plugin.org | dsh-plugin-hub] ${reasonTitleOf(kind)}: ${repo}`
   const reason = /\[packaging\]/i.test(message)
-    ? 'plugin distribution is incomplete — the entry file declared in package.json is missing from the published package (github tarball or npm package); please commit build output or publish a complete package'
+    ? 'plugin distribution is incomplete — a file the package needs (its entry from main / exports, an entry a bundled patch mounts, or the patch declared by dsh.bundle.patch) is missing from the published package (github tarball or npm package); please commit build output or publish a complete package'
       : kind === 'network'
         ? 'network connectivity issue on the user side (DNS, proxy, firewall, or a blocked connection)'
         : kind === 'pluginPrepare'
@@ -132,7 +133,7 @@ export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | nu
         ? [
           '',
           '## 安装方式说明',
-          'DSH 插件支持三种官方安装通道：`dsh plugin add <npm-package>`（npm 分发，需发布完整构建产物）、`dsh plugin add git+https://github.com/owner/repo.git`（Git 直装，仓库需提交构建产物），以及预构建 release 包 `dsh plugin add https://github.com/owner/repo/releases/download/<tag>/<asset>.tgz`（仓库不便提交构建产物时的推荐方式）。注意：pnpm ≥10 默认拦截依赖构建脚本，Git 直装不会执行包内 `prepare`，请勿依赖它生成产物。当前插件的分发物缺少 package.json 声明的入口文件，请提交构建产物、改用 release `.tgz` 直链，或发布完整的 npm 包。',
+          'DSH 插件支持三种官方安装通道：`dsh plugin add <npm-package>`（npm 分发，需发布完整构建产物）、`dsh plugin add git+https://github.com/owner/repo.git`（Git 直装，仓库需提交构建产物），以及预构建 release 包 `dsh plugin add https://github.com/owner/repo/releases/download/<tag>/<asset>.tgz`（仓库不便提交构建产物时的推荐方式）。注意：pnpm ≥10 默认拦截依赖构建脚本，Git 直装不会执行包内 `prepare`，请勿依赖它生成产物。当前插件的分发物缺少它需要的文件（`main` / `exports` 声明的入口、补丁按本包名 mount 的入口，或 `dsh.bundle.patch` 声明的补丁），请提交构建产物、改用 release `.tgz` 直链，或发布完整的 npm 包。',
         ]
         : []),
       '',

package/src/server/http/install.ts

@@ -206,16 +206,14 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
               return
             }
           }
-          // 重复安装防护：非更新请求命中已安装目标时直接拒绝，不重复跑 CLI
-          // （否则 CLI 会因「已存在」失败，且用户看到的是莫名其妙的报错）；
-          // 更新请求（mode: 'update'）放行，CLI 的 add 对已存在依赖是 pnpm 原位覆盖重装。
-          // 命中判定双通道：npm 包名按 dependencies 键直接命中，GitHub 目标按仓库身份匹配。
+          // 命中已安装目标时一律按「更新」语义执行（pnpm add 对已存在依赖本就是原位覆盖重装），
+          // 不再抛 409：客户端的已装列表与服务端实读可能不同步（如页面列表滞后），此时用户点
+          // 「安装」会撞上重复安装守卫，直接覆盖重装比让用户看到一句看不懂的 already installed
+          // 报错友好，最终状态也一致（都是已安装）。命中判定双通道：npm 包名按 dependencies
+          // 键直接命中，GitHub 目标按仓库身份匹配。
           const installed = readInstalled(profile)
           const already = installedByRepo(installed, target) ?? (installed[target] !== undefined ? target : null)
-          if (already !== null && mode !== 'update') {
-            sendJson(response, 409, { error: `already installed: ${already}` })
-            return
-          }
+          if (already !== null) mode = 'update'
           // 队列级去重：同一目标已在排队/执行中时拒绝，避免客户端防重竞态导致重复入队
           if (hasQueuedTarget(target)) {
             sendJson(response, 409, { error: `already queued: ${target}` })
@@ -268,17 +266,17 @@ export function registerInstallRoutes(webServer: WebServerService, profile: stri
               return
             }
           }
-          // 安装前预检：仅新安装走预检（github 源分发改入口文件缺失时直接拦截）。
+          // 安装前预检：仅新安装走预检（github 源分发缺 package.json 声明的文件时直接拦截）。
           // 更新是已信任目标的覆盖重装，跳过预检避免重复下载 tarball。
           // npm 包信任 registry 直接放行；github 源拦截时标记 [packaging] 前缀，
           // 供客户端归类为「插件分发不完整」并引导去仓库提 Issue
           if (already === null) {
             const preflight = await preflightTarget(target)
             if (!preflight.ok) {
-              // 预检拦截（git 分发缺入口文件）：同步 400 返回，附上已尝试的安装方式，
+              // 预检拦截（git 分发缺作者声明的文件）：同步 400 返回，附上已尝试的安装方式，
               // 客户端失败弹窗提 Issue 时一并贴给作者
               sendJson(response, 400, {
-                error: `[packaging] ${target}: plugin distribution is incomplete — the entry file ${preflight.missing ?? '?'} declared in package.json is not present in the git distribution (build output not committed). Report to the author.`,
+                error: `[packaging] ${target}: plugin distribution is incomplete — the file ${preflight.missing ?? '?'} the package needs (its declared entry, an entry a bundled patch mounts, or the patch itself) is not present in the git distribution (build output not committed). Report to the author.`,
                 attempts,
               })
               return

package/src/server/services/install/operation-log.ts

@@ -0,0 +1,46 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * 失败回捞：DSH 有时只把一行摘要（`dsh: plugin command failed; diagnostics: <path>`）
+ * 回显到控制台，真正的 pnpm 报错写进该路径的 operation 日志。这里从输出里解析出该路径
+ * 并读取其尾部，补进失败信息 —— 否则前端拿不到任何错误特征，只能把失败归为「未知」。
+ * 只允许读 DSH 自己的 operation 日志（路径含 .plugin-manager 且以 pnpm.log 结尾），
+ * 防止插件把任意路径打印进日志造成越权读取；任何异常都静默降级（返回 null），
+ * 不改变原有失败处理。
+ */
+import { readFileSync } from 'node:fs'
+import { CAPTURE_LIMIT_BYTES } from './install-types.ts'
+
+/**
+ * 从 DSH 输出里解析 operation 日志路径（`diagnostics: <path>`）。
+ * 只认 DSH 的 operation 日志：路径含 `.plugin-manager` 且以 `pnpm.log` 结尾；
+ * 不是这种路径（或压根没有该行）返回 null，调用方据此跳过回捞。
+ */
+export function operationLogPathOf(output: string): string | null {
+  for (const raw of output.split(/\r?\n/)) {
+    const m = /diagnostics:\s*"?(.+?)"?\s*$/i.exec(raw.trim())
+    if (m === null) continue
+    const path = m[1].trim()
+    if (!path.includes('.plugin-manager') || !path.toLowerCase().endsWith('pnpm.log')) continue
+    return path
+  }
+  return null
+}
+
+/**
+ * 回捞 operation 日志尾部，作为失败详情返回；拿不到（无路径 / 文件不存在 / 读失败 /
+ * 内容为空）返回 null。尾部截到与子进程输出相同的上限，避免超大日志撑爆内存与消息。
+ */
+export function backfillOperationLog(output: string): string | null {
+  const path = operationLogPathOf(output)
+  if (path === null) return null
+  try {
+    const text = readFileSync(path, 'utf8').trim()
+    if (text === '') return null
+    return text.length > CAPTURE_LIMIT_BYTES ? text.slice(-CAPTURE_LIMIT_BYTES) : text
+  } catch {
+    return null
+  }
+}

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

@@ -1,25 +1,43 @@
 /**
- * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 包入口解析：从 package.json 的 exports["."] / main 推出用于校验的入口文件。
- * git 通道（tar 预检）与 npm 通道（装后 statSync 校验）共用，保证两条通道
- * 对同一个包判定一致。
+ * 分发文件解析：从 package.json 推出装完后必须真实存在的文件 —— 作者声明的入口
+ * （exports["."] / main）与 bundle 声明的补丁（dsh.bundle.patch）。git 通道（tar 预检）
+ * 与 npm 通道（装后 statSync 校验）共用，保证两条通道对同一个包判定一致。
+ *
+ * 这里不替作者补一个 index.js：宿主加载一个 bundle 读的是它的 package.json 和它声明的
+ * 补丁文件（官方 bundleManifest 的注释即「Read bundle metadata without loading its
+ * JavaScript」），从不 import 包本身。凭空要求一个作者没声明的入口，只会把完整的
+ * 技能包判成分发残缺，并把一条假缺陷推到作者仓库（见 QingYunA/answer-me-with-html#209）。
+ *
+ * 例外是补丁自己 mount 了本包：dsh 的《打包与安装插件》里组合包的常规写法就是
+ * `- insert: - name: <本包名>`，宿主随后按包名 import 本包，入口那时必须存在。
+ * 所以只有补丁真的写了自己的包名，才把这个入口算进分发要求。
  */
 
 /** exports 条件对象里按优先级尝试的键；Node 语义下 default 最宽，import/require 次之。 */
 const EXPORT_CONDITION_KEYS = ['default', 'import', 'require'] as const
 
+/** 解析所需的 manifest 字段；其余字段不读。 */
+export interface PackageManifest {
+  name?: unknown
+  main?: unknown
+  exports?: unknown
+  dsh?: unknown
+}
+
 /**
- * 解析包的入口文件（相对包根，不带 `./` 前缀）。
+ * 解析作者声明的入口文件（相对包根，不带 `./` 前缀）。manifest 未声明入口时返回 null：
+ * 没有声明就没有可缺失的入口，是否可 import 交给真实安装与宿主加载去暴露。
  *
  * Node 的 exports 规范要求字符串 target 以 `./` 开头（如 `"./lib/index.js"`），
  * 而 tar 成员名与磁盘路径都不带该前缀，因此统一剥掉；条件对象
  * （`{ "import": ..., "require": ... }`）按 default → import → require 取第一
- * 个字符串值。无 exports 时回退 main，再回退 index.js。
+ * 个字符串值。无 exports 时回退 main；两者都没有则没有入口。
  */
-export function resolvePackageEntry(meta: { main?: unknown; exports?: unknown }): string {
+export function resolvePackageEntry(meta: PackageManifest): string | null {
   const dot = (meta.exports as Record<string, unknown> | undefined)?.['.']
   const fromExports = typeof dot === 'string'
     ? dot
@@ -28,8 +46,51 @@ export function resolvePackageEntry(meta: { main?: unknown; exports?: unknown })
       : undefined
   const candidate = typeof fromExports === 'string' ? fromExports
     : typeof meta.main === 'string' ? meta.main
-      : 'index.js'
-  return candidate.replace(/^\.\//u, '')
+      : null
+  return candidate === null ? null : stripDotSlash(candidate)
+}
+
+/**
+ * 解析 `dsh.bundle.patch` 声明的补丁文件（相对包根，不带 `./` 前缀）。
+ * 形状不合规范（既不是字符串也不是字符串数组）在这里不判定：那是 dsh 启动时
+ * bundlePatchFiles 的报错职责，预检只负责「声明了就要在包里存在」。
+ */
+export function resolveBundlePatchFiles(meta: PackageManifest): string[] {
+  const patch = (meta.dsh as { bundle?: { patch?: unknown } } | undefined)?.bundle?.patch
+  const declared = typeof patch === 'string' ? [patch] : Array.isArray(patch) ? patch : []
+  return declared
+    .filter((file): file is string => typeof file === 'string' && file !== '')
+    .map(stripDotSlash)
+}
+
+/** 分发里必须存在的全部文件：作者声明的入口，加上 bundle 声明的补丁，入口在前。
+ *  manifest 没声明入口时才看补丁：补丁按本包名 mount 自己（下面 mountsItself），
+ *  宿主就会 import 本包，Node 的旧式解析落到 index.js —— 那个入口同样必须有。 */
+export function requiredDistributionFiles(meta: PackageManifest, patchTexts: string[] = []): string[] {
+  const declared = resolvePackageEntry(meta)
+  const entry = declared ?? (mountsItself(meta, patchTexts) ? 'index.js' : null)
+  return [...(entry === null ? [] : [entry]), ...resolveBundlePatchFiles(meta)]
+}
+
+/**
+ * 补丁文本里插件行的 `name:` 值（DSH 补丁按行书写：`- name: <pkg>` / `  name: <pkg>`）。
+ * 刻意不做 YAML 解析：只认这一种行形状，认不出来就不判定 —— 漏判只是少一条要求，
+ * 误判会拦下能装的包，两边的代价不对称。
+ */
+export function patchRowNamesOf(text: string): string[] {
+  return text
+    .split(/\r?\n/)
+    .map((line) => /^\s*(?:-\s*)?name:\s*(.+?)\s*$/u.exec(line)?.[1])
+    .filter((value): value is string => value !== undefined)
+    .map((value) => value.replace(/^(['"])(.*)\1$/u, '$2'))
+    .filter((value) => value !== '')
+}
+
+/** 补丁是否把本包自己 mount 进树（dsh 文档里组合包的常规写法），是则宿主会 import 本包。 */
+export function mountsItself(meta: PackageManifest, patchTexts: string[]): boolean {
+  const name = meta.name
+  if (typeof name !== 'string' || name === '') return false
+  return patchTexts.some((text) => patchRowNamesOf(text).includes(name))
 }
 
 function firstStringOf(conditions: Record<string, unknown>): string | undefined {
@@ -39,3 +100,5 @@ function firstStringOf(conditions: Record<string, unknown>): string | undefined
   }
   return undefined
 }
+
+const stripDotSlash = (file: string): string => file.replace(/^\.\//u, '')

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

@@ -3,10 +3,10 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 安装前预检：对 GitHub 源的插件，检查其分发（codeload tarball）里是否
- * 真的包含 package.json 声明的入口文件（main / exports["."].default）。
- * git 分发常不提交构建产物（lib/ 等），这类残缺包装完会让宿主重启加载插件树时
- * ERR_MODULE_NOT_FOUND 直接崩溃 —— 预检在动手安装前就把它们拦下，避免白装一次。
+ * 安装前预检：对 GitHub 源的插件，检查其分发（codeload tarball）里是否真的包含
+ * package.json 声明的文件（main / exports["."] / dsh.bundle.patch）。git 分发常不提交
+ * 构建产物（lib/ 等），这类残缺包装完会让宿主重启加载插件树时 ERR_MODULE_NOT_FOUND
+ * 直接崩溃 —— 预检在动手安装前就把它们拦下，避免白装一次。
  * npm 包信任 registry 的完整性，直接放行；任何无法预检的情况也放行，交给装后
  * 校验（verifyInstalledEntry）兜底，保证预检自身失败不会卡死安装流程。
  */
@@ -19,7 +19,7 @@ import { pipeline } from 'node:stream/promises'
 import { promisify } from 'node:util'
 import { githubRefOf, githubRepoOf } from '../profile/profile.ts'
 import { githubReleaseTarget } from './release-target.ts'
-import { resolvePackageEntry } from './package-entry.ts'
+import { requiredDistributionFiles, resolveBundlePatchFiles } from './package-entry.ts'
 
 const execFileAsync = promisify(execFile)
 
@@ -27,7 +27,8 @@ const execFileAsync = promisify(execFile)
  *  否则 `/install` 请求永远不返回、任务不入队、前端进度卡 0%。超时后放行（交给装后校验）。 */
 const PREFLIGHT_TIMEOUT_MS = 15_000
 
-/** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径；
+/** 预检结果：ok=false 表示分发改 package.json 声明的文件（入口或 bundle 补丁），
+ *  missing 为该文件在包内的相对路径；
  *  name 为 git 分发包 package.json 声明的包名（非 git 目标/无法确定时为 null），
  *  供安装路由做「包名冲突」检测 —— 同名包名已被其他来源占用时，pnpm 装前必然撞车，
  *  需要把晦涩的 CLI 报错转成明确的拦截。 */
@@ -57,9 +58,17 @@ export async function preflightTarget(target: string): Promise<PreflightResult>
     const rootPrefix = rootPackage.slice(0, -'package.json'.length)
     const meta = await readTarJson(tar, rootPackage)
     if (meta === null) return { ok: true, missing: null, name: null }
-    const entry = resolvePackageEntry(meta)
-    const inTar = await hasTarEntry(tar, `${rootPrefix}${entry}`)
-    return { ok: inTar, missing: inTar ? null : entry, name: typeof meta.name === 'string' ? meta.name : null }
+    // 只校验作者声明过的文件：没声明入口的包（只挂技能的 bundle）没有可缺失的入口，
+    // 它的分发是否完整由 dsh.bundle.patch 是否在包里决定；补丁若按本包名 mount 自己，
+    // 入口又变成必须的（宿主会 import 本包）—— 所以判入口前先把补丁读出来。
+    const patchTexts: string[] = []
+    for (const file of resolveBundlePatchFiles(meta)) {
+      const text = await readTarText(tar, `${rootPrefix}${file}`)
+      if (text !== null) patchTexts.push(text)
+    }
+    const required = requiredDistributionFiles(meta, patchTexts).map((file) => `${rootPrefix}${file}`)
+    const missing = missingDistributionFileOfTarList(await tarListing(tar), required)
+    return { ok: missing === null, missing, name: typeof meta.name === 'string' ? meta.name : null }
   } catch {
     return { ok: true, missing: null, name: null }
   } finally {
@@ -125,31 +134,51 @@ export function rootPackageEntryOfTarList(listing: string): string | null {
   return candidates.length === 1 ? candidates[0] : null
 }
 
+/**
+ * 清单里第一个缺失的必需文件（成员名带包根前缀，由调用方拼好），全部都在则为 null。
+ * 清单不可读（tar 缺失/解压失败）时按第一个必需文件缺失处理：与逐文件查询时
+ * 「查不到就是缺」的判定一致，宁可拦下一次可疑安装，也不放一个空包过去。
+ * Exported for a small parser regression test.
+ */
+export function missingDistributionFileOfTarList(listing: string | null, required: string[]): string | null {
+  if (required.length === 0) return null
+  if (listing === null) return required[0]
+  const present = new Set(listing.split(/\r?\n/))
+  return required.find((file) => !present.has(file)) ?? null
+}
+
 async function rootPackageEntry(tar: string): Promise<string | null> {
+  const listing = await tarListing(tar)
+  return listing === null ? null : rootPackageEntryOfTarList(listing)
+}
+
+/** tar 成员清单；`tar` 执行失败时返回 null（调用方按无法判定处理）。 */
+async function tarListing(tar: string): Promise<string | null> {
   try {
     const { stdout } = await execFileAsync('tar', ['-tzf', tar], { maxBuffer: 16 * 1024 * 1024 })
-    return rootPackageEntryOfTarList(stdout)
+    return stdout
   } catch {
     return null
   }
 }
 
-/** 从 tarball 提取并解析一个 JSON 文件；文件不存在或解析失败返回 null。 */
-async function readTarJson(tar: string, entry: string): Promise<Record<string, unknown> | null> {
+/** 从 tarball 提取一个文件的内容；文件不存在或提取失败返回 null。 */
+async function readTarText(tar: string, entry: string): Promise<string | null> {
   try {
     const { stdout } = await execFileAsync('tar', ['-xzOf', tar, entry], { maxBuffer: 4 * 1024 * 1024 })
-    return JSON.parse(stdout) as Record<string, unknown>
+    return stdout
   } catch {
     return null
   }
 }
 
-/** 检查 tarball 内是否存在指定 entry。 */
-async function hasTarEntry(tar: string, entry: string): Promise<boolean> {
+/** 从 tarball 提取并解析一个 JSON 文件；文件不存在或解析失败返回 null。 */
+async function readTarJson(tar: string, entry: string): Promise<Record<string, unknown> | null> {
+  const text = await readTarText(tar, entry)
+  if (text === null) return null
   try {
-    const { stdout } = await execFileAsync('tar', ['-tzf', tar, entry], { maxBuffer: 1024 * 1024 })
-    return stdout.split(/\r?\n/).some((line) => line === entry)
+    return JSON.parse(text) as Record<string, unknown>
   } catch {
-    return false
+    return null
   }
 }

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

@@ -8,12 +8,13 @@
  * 输出流式收集到任务上；卸载成功时尝试从运行中 loader 即时停用（见 loader.ts）。
  */
 import { spawn, spawnSync } from 'node:child_process'
-import { resolvePackageEntry } from './package-entry.ts'
+import { requiredDistributionFiles, resolveBundlePatchFiles, type PackageManifest } from './package-entry.ts'
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import type { InstallResult, InstallTask, Invocation, QueueItem } from './install-types.ts'
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.ts'
 import { npmTooLowMarker } from './npm-check.ts'
+import { backfillOperationLog } from './operation-log.ts'
 import { cleanLine, estimateProgress } from '../profile/progress.ts'
 import type { LoaderHandle } from '../loader.ts'
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.ts'
@@ -625,10 +626,12 @@ function spawnMutation(options: {
 }
 
 /**
- * 安装后校验已装包的入口文件（package.json 的 main / exports["."].default）是否真实存在。
- * git: 分发常不提交构建产物（lib/ 等），pnpm 装完没有报错，但宿主重启加载插件树时会
- * ERR_MODULE_NOT_FOUND 直接崩溃、网页打不开 —— 这里在登记「待重启」前就把这类残缺包拦下。
- * 返回 { name, missing }：name 为空表示无法定位目标包（跳过校验）；missing 为缺失的入口路径。
+ * 安装后校验已装包里 package.json 声明的文件（main / exports["."].default 与
+ * dsh.bundle.patch）是否真实存在。git: 分发常不提交构建产物（lib/ 等），pnpm 装完没有
+ * 报错，但宿主重启加载插件树时会 ERR_MODULE_NOT_FOUND 直接崩溃、网页打不开 —— 这里在
+ * 登记「待重启」前就把这类残缺包拦下。没有声明过的文件不在这里追究：没声明入口的
+ * bundle 包（只挂技能）本来就不需要入口，宿主读的是它的 package.json 与声明的补丁。
+ * 返回 { name, missing }：name 为空表示无法定位目标包（跳过校验）；missing 为缺失文件的路径。
  */
 export function verifyInstalledEntry(profile: string, target: string): { name: string | null; missing: string | null } {
   let profilePkg: Record<string, unknown> | null = null
@@ -645,21 +648,29 @@ export function verifyInstalledEntry(profile: string, target: string): { name: s
     : deps[target] !== undefined ? target : Object.keys(deps).find((k) => deps[k] === target)
   if (!name) return { name: null, missing: null }
   const pkgDir = join(profileDirectory(profile), 'node_modules', name)
-  let entry: string | null = null
+  let required: string[] = []
   try {
-    const meta = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8')) as {
-      main?: unknown
-      exports?: unknown
-    }
-    entry = resolvePackageEntry(meta)
+    const meta = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8')) as PackageManifest
+    // 补丁按本包名 mount 自己时入口也是必须的，所以先读已装包里的补丁（读不到就当没有）。
+    const patchTexts = resolveBundlePatchFiles(meta).flatMap((file) => {
+      try {
+        return [readFileSync(join(pkgDir, file), 'utf8')]
+      } catch {
+        return []
+      }
+    })
+    required = requiredDistributionFiles(meta, patchTexts)
   } catch {
     return { name, missing: null }
   }
-  try {
-    return { name, missing: statSync(join(pkgDir, entry)).isFile() ? null : entry }
-  } catch {
-    return { name, missing: entry }
+  for (const file of required) {
+    try {
+      if (!statSync(join(pkgDir, file)).isFile()) return { name, missing: file }
+    } catch {
+      return { name, missing: file }
+    }
   }
+  return { name, missing: null }
 }
 
 /** 从 pnpm `Ignored build scripts:` 提示行解析被拦截的构建脚本 key（name@version，逗号分隔）。 */
@@ -749,21 +760,35 @@ export async function runPluginMutation(options: {
       }
     }
   }
-  // pnpm 安装本身成功，但目标包入口文件缺失（git 分发缺构建产物）→ 判为失败：
+  // pnpm 安装本身成功，但目标包声明分发的文件缺失（git 分发缺构建产物 / 缺声明的补丁）→ 判为失败：
   // 撤销刚登记的待重启，避免用户重启时宿主加载残缺包直接崩溃。
   // 全局 npm 安装不进 profile（profile deps 里没有这些包），跳过入口校验
   if (options.action !== 'remove' && result.exitCode === 0 && !result.timedOut && (options.globalNpm ?? []).length === 0) {
     const verified = verifyInstalledEntry(options.profile, options.target)
     if (verified.name !== null && verified.missing !== null) {
       clearPendingRestart(options.displayTarget ?? options.target)
-      const detail = `[packaging] ${verified.name}: entry file missing: ${verified.missing} (git distribution lacks build output — install the npm version or report to the author)`
+      const detail = `[packaging] ${verified.name}: declared file missing: ${verified.missing} (git distribution lacks build output — install the npm version or report to the author)`
       if (options.task && options.task.status !== 'cancelled') {
         options.task.status = 'failed'
         options.task.exitCode = null
         options.task.progress = 0
         pushLine(options.task, detail)
       }
-      return { exitCode: 1, timedOut: false, error: `entry file missing: ${verified.missing}`, stdout: result.stdout, stderr: `${result.stderr}\n${detail}` }
+      return { exitCode: 1, timedOut: false, error: `declared file missing: ${verified.missing}`, stdout: result.stdout, stderr: `${result.stderr}\n${detail}` }
+    }
+  }
+  // DSH 只把一行摘要（`dsh: plugin command failed; diagnostics: <path>`）回显到控制台时，
+  // 控制台里没有任何错误特征，前端只能把失败归为「未知」（issue #192）。这里按该路径回捞
+  // operation 日志尾部补进失败信息：用户直接看到真实报错，自动归类也有据可依。
+  // 只在本就不含任何错误码时回捞 —— pnpm 已把报错回显出来时无需多读一次文件。
+  if (result.exitCode !== 0 && !result.timedOut && !/\bERR_[A-Z0-9_]+\b/.test(`${result.stderr}\n${result.stdout}`)) {
+    const backfilled = backfillOperationLog(`${result.stderr}\n${result.stdout}`)
+    if (backfilled !== null) {
+      if (options.task && options.task.status !== 'cancelled') {
+        pushLine(options.task, '[pnpm log] DSH did not echo pnpm output — recovered the operation log from disk')
+        for (const line of backfilled.split(/\r?\n/)) if (line.trim() !== '') pushLine(options.task, line.trimEnd())
+      }
+      result = { ...result, stderr: `${result.stderr}\n${backfilled}` }
     }
   }
   // npm arborist edgesOut 崩溃 + 本机 npm 版本过低 → 追加 [npm-too-low] 标记，前端据此给准确原因