dsh-plugin 1.6.12 → 2.0.1

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

@@ -17,27 +17,26 @@ export interface InstallResult {
 
 export interface InstallTask {
   id: number
-  /** 操作目标：显式 HTTPS Git URL（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
+  /** 操作目标：npm 包名（安装、更新、卸载一致），冲突/恢复时需要展示给用户 */
   target: string
   /** 展示用目标（owner/repo）：npm 安装时 target 是包名，前端恢复用此字段显示仓库名，保持用户无感知 */
   displayTarget?: string
-  /** 尝试过的安装方式（npm registry 反查 + 实际执行的 CLI 命令，按先后顺序）：
-   *  失败提 Issue 时如实贴给作者，作者据此反推正确的 npm 包名（组织 scope 与 GitHub 用户名不一致时
-   *  仅凭仓库名猜不到，作者看到我们查过/试过的命令就能直接指认）。 */
+  /** 尝试过的安装方式（实际执行过的 CLI 命令，按先后顺序）：
+   *  失败提 Issue 时如实贴给作者，作者据此判断我们真正执行了什么。 */
   attempts: string[]
   /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时任务执行全局 npm 安装，不进任何 profile */
   globalNpm?: string[]
   action: 'add' | 'remove' | 'update'
-  /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+  /** 自定义安装入口渠道（NPM 包卡片）：
    *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装无此字段。 */
-  installChannel?: 'npm' | 'git' | 'dsh'
+  installChannel?: 'npm'
   /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
   status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled'
   timedOut: boolean
   exitCode: number | null
   /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出，阶段行兜底 */
   progress: number
-  /** Newest output lines first (consumer shows the tail). */
+  /** 输出行最新在前（消费方展示尾部）。 */
   lines: string[]
   /** 完成后是否仍需宿主重启才生效：仅「热挂载失败 / 非 dsh 插件 / 更新（ESM 缓存取不到新代码）/
    *  无 loader」等刷新解决不了的兜底场景为 true（弹窗给「立即重启」）；其余一律 false。 */
@@ -70,7 +69,7 @@ export interface QueueItem {
     timeoutMs?: number
     env?: NodeJS.ProcessEnv
     globalNpm?: string[]
-    installChannel?: 'npm' | 'git' | 'dsh'
+    installChannel?: 'npm'
   }
 }
 
@@ -79,7 +78,7 @@ export interface QueueItem {
  * 它自然清空，正好等于「重启后提醒消失」的语义，无需任何重启探测。
  */
 export interface PendingRestart {
-  /** Git 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
+  /** 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
   target: string
   /** 待重启语义：install 装完等挂载生效 / uninstall 卸完等清理 loader 残留 */
   kind: 'install' | 'uninstall'
@@ -87,13 +86,13 @@ export interface PendingRestart {
   at: number
 }
 
-/** Grammar of a catalog GitHub repository identity (`owner/repo`). */
+/** 目录 GitHub 仓库身份（`owner/repo`）的语法。 */
 export const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/
-/** Grammar of an npm package name (used for uninstall targets). */
+/** npm 包名的语法（用于卸载目标）。 */
 export const PACKAGE_RE = /^(?:@[a-z0-9._-]+\/)?[A-Za-z0-9._-]+$/
 /** 捕获输出上限：stdout/stderr 各保留尾部 N 字节。 */
 export const CAPTURE_LIMIT_BYTES = 64 * 1024
-/** Max output lines kept per task (newest wins). */
+/** 每个任务保留的最大输出行数（最新优先）。 */
 export const MAX_TASK_LINES = 200
-/** Max tracked tasks; oldest finished tasks are dropped first. */
+/** 最多跟踪的任务数；超出时先丢弃最早结束的任务。 */
 export const MAX_TASKS = 50

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

@@ -20,7 +20,6 @@ export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.ts'
 export {
   addAllowBuildsKey,
-  githubRefOf,
   githubRepoOf,
   githubTarget,
   globalNpmPackagesOf,

package/src/server/services/install/npm-check.ts

@@ -5,8 +5,9 @@
  *
  * 本机 npm 环境检测：判断一次安装失败是否源于「本机 npm 版本过低」。
  *
- * 背景：pnpm 在 git 源插件的 prepare 阶段会调 npm 装依赖，npm arborist 在解 peer 依赖时有
- * 已知内部崩溃 —— `Cannot read properties of null (reading 'edgesOut')`。这是 npm 自身缺陷，
+ * 背景：pnpm 在带 `prepare` 构建脚本的依赖上会调 npm 装依赖（npm 包同样可能带原生
+ * 依赖或 git 依赖），npm arborist 在解 peer 依赖时有已知内部崩溃 ——
+ * `Cannot read properties of null (reading 'edgesOut')`。这是 npm 自身缺陷，
  * 该报错会被 pnpm 包进 ERR_PNPM_PREPARE_PACKAGE 输出，不能按插件打包问题引导用户提 Issue。
  *
  * 这里的 `npmTooLowMarker` 是纯函数（输出文本 + 环境 → 标记行或 null），不触碰任务/队列，

package/src/server/services/install/npm-resolve.ts

@@ -3,50 +3,18 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * npm 包反查：git 分发不完整（缺构建产物/子模块）导致安装失败时，用 npm
- * registry 的搜索接口按 repository 地址反查该仓库对应的官方 npm 包。
+ * npm 包校验：确认某个 npm 包确实属于该 GitHub 仓库、且声明为 DSH 插件
+ * （包元数据里的 repository 指向该仓库，并带 `dsh-plugin` 关键词或 `dsh` manifest）。
  *
  * 这是通用机制，不针对任何具体插件：只要作者发布了 repository 指向该
- * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中，
- * 从而把 git 分发不完整的插件切换到 npm 通道安装。命中结果带内存缓存，
- * 避免同一会话内重复查询 registry。
+ * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中。
  */
 import { get } from 'node:https'
 import { githubRepoOf } from '../profile/profile.ts'
 import { finalUrl } from '../probe.ts'
 
-/** 反查缓存：repo 小写 → npm 包名（null 表示已确认无对应 npm 包；网络异常不缓存）。 */
-const cache = new Map<string, string | null>()
-
-/** 单次 registry 查询超时（ms）：慢网络下失败返回 null，不阻塞安装流程。 */
+/** 单次 registry 查询超时（ms）：慢网络下失败返回 false，不阻塞安装流程。 */
 const REQUEST_TIMEOUT_MS = 8000
-/** npm search 是相关性搜索而非 repository 精确索引；拉满单页结果后再本地做严格 repo 过滤。 */
-const SEARCH_RESULT_LIMIT = 250
-
-/**
- * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
- * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
- * 原有错误路径，反查只是额外的一次尝试。只有「已确认」的结果（包名，或 200
- * 响应下确认无匹配）会进缓存；网络异常/超时/解析失败不缓存，同一会话内下次
- * 安装仍会重试反查，避免一次瞬时故障把整个会话锁死在 git 通道。
- * registry 参数：npm 镜像源地址，空串 = 官方源；与安装通道吃同一 registry，
- * 保证「配置了镜像」时反查和安装走同一个源（镜像节点同步完整时结果一致）。
- * proxy 参数：GitHub 改名跳转探测走的代理（与安装/诊断同一口径）。
- * 慢网络下失败不阻塞安装。
- */
-export async function resolveNpmPackage(repo: string, registry = '', proxy = ''): Promise<string | null> {
-  const key = repo.toLowerCase()
-  if (cache.has(key)) return cache.get(key) ?? null
-  let found = await searchRepo(repo, registry)
-  // 仓库改名后 npm 包的 repository 已指向新名，按旧名反查不到：跟随一次 GitHub 的
-  // 改名跳转拿到规范名再查一遍（旧地址本身仍可用，只是仓库名变了）。
-  if (found === null) {
-    const canonical = await canonicalRepo(repo, proxy)
-    if (canonical !== '' && canonical.toLowerCase() !== key) found = await searchRepo(canonical, registry)
-  }
-  if (found !== undefined) cache.set(key, found)
-  return found ?? null
-}
 
 type NpmSearchPackage = {
   name?: unknown
@@ -56,16 +24,7 @@ type NpmSearchPackage = {
   dsh?: unknown
 }
 
-type NpmSearchObject = { package?: NpmSearchPackage }
-type NpmSearchResponse = { objects?: NpmSearchObject[] }
-
-/**
- * Pick the installable npm package for one GitHub repository. npm search is a
- * relevance-ranked text search, not an exact repository index, so first filter
- * by repository URL. If a monorepo publishes both a CLI/helper package and a
- * DSH plugin, prefer the package that explicitly advertises the `dsh-plugin`
- * keyword instead of whichever result npm happened to rank first.
- */
+/** 从包元数据取 repository 地址：字符串或 `{ url }` 对象，缺省回退 search 结果的 links.repository。 */
 function repositoryUrlOf(pkg: NpmSearchPackage): string {
   if (typeof pkg.repository === 'string') return pkg.repository
   if (pkg.repository !== null && typeof pkg.repository === 'object') {
@@ -83,6 +42,10 @@ export function isDshPackageMetadataForRepo(pkg: NpmSearchPackage, repo: string)
   return keywordMarked || manifestMarked
 }
 
+/**
+ * 校验包名对应的 npm 包确实属于该仓库且声明为 DSH 插件：取 registry 上的 `latest`
+ * 元数据比对 repository 与插件标记。网络异常、超时、非 200 一律返回 false，不阻塞调用方。
+ */
 export function isDshNpmPackageForRepo(packageName: string, repo: string, registry = '', proxy = ''): Promise<boolean> {
   if (packageName === '' || repo === '') return Promise.resolve(false)
   const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '')
@@ -130,56 +93,3 @@ async function canonicalRepo(repo: string, proxy: string): Promise<string> {
   const canonical = final === null ? null : githubRepoOf(final)
   return canonical !== null && canonical.toLowerCase() !== key ? canonical : ''
 }
-
-function matchingPackagesForRepo(objects: NpmSearchObject[], repo: string): Array<{ name: string; isDshPlugin: boolean }> {
-  const matches: Array<{ name: string; isDshPlugin: boolean }> = []
-
-  for (const obj of objects) {
-    const pkg = obj.package
-    if (typeof pkg?.name !== 'string' || pkg.name === '') continue
-    const repoUrl = repositoryUrlOf(pkg)
-    if (githubRepoOf(repoUrl)?.toLowerCase() !== repo.toLowerCase()) continue
-    const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : []
-    matches.push({
-      name: pkg.name,
-      isDshPlugin: keywords.some((keyword) => typeof keyword === 'string' && keyword.toLowerCase() === 'dsh-plugin'),
-    })
-  }
-
-  return matches
-}
-
-export function selectNpmPackageForRepo(objects: NpmSearchObject[], repo: string): string | null {
-  const matches = matchingPackagesForRepo(objects, repo)
-  return matches.find((candidate) => candidate.isDshPlugin)?.name ?? matches[0]?.name ?? null
-}
-
-/** 用 npm search 接口按 repository 地址反查，并做铁证校验（包元数据必须指向该仓库）。
- * 返回：包名 = 命中；null = 200 响应下确认无匹配；undefined = 本次未能确认（网络/超时/解析失败）。 */
-function searchRepo(repo: string, registry: string): Promise<string | null | undefined> {
-  const [owner, name] = repo.split('/')
-  if (owner === undefined || name === undefined || name === '') return Promise.resolve(null)
-  const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '')
-  const url = `${base}/-/v1/search?text=${encodeURIComponent(`repository:${owner}/${name}`)}&size=${SEARCH_RESULT_LIMIT}`
-  return new Promise((resolve) => {
-    const req = get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
-      if (res.statusCode !== 200) {
-        res.resume()
-        resolve(undefined)
-        return
-      }
-      let body = ''
-      res.on('data', (chunk: Buffer) => { body += chunk.toString() })
-      res.on('end', () => {
-        try {
-          const data = JSON.parse(body) as NpmSearchResponse
-          resolve(selectNpmPackageForRepo(data.objects ?? [], `${owner}/${name}`))
-        } catch {
-          resolve(undefined)
-        }
-      })
-    })
-    req.on('timeout', () => req.destroy())
-    req.on('error', () => resolve(undefined))
-  })
-}

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

@@ -10,7 +10,8 @@
  * 防止插件把任意路径打印进日志造成越权读取；任何异常都静默降级（返回 null），
  * 不改变原有失败处理。
  */
-import { readFileSync } from 'node:fs'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
 import { CAPTURE_LIMIT_BYTES } from './install-types.ts'
 
 /**
@@ -44,3 +45,48 @@ export function backfillOperationLog(output: string): string | null {
     return null
   }
 }
+
+/**
+ * 运行期抓取：宿主的 operation 日志只在命令运行期间存在，结束后可能被清理，
+ * 退出后再按路径读往往已经拿不到。这里在安装过程中轮询 profile 下最新的
+ * `.plugin-manager/logs/<operation>/pnpm.log`，用抓到的内容兜底。
+ * 只认本次运行产生的新文件（mtime 晚于启动基线），避免复述上一次安装的日志。
+ */
+export function createOperationLogTap(profileDir: string): { stop: () => string } {
+  const logsDir = join(profileDir, '.plugin-manager', 'logs')
+  const newestLog = (): { file: string; mtimeMs: number } | null => {
+    let newest: { file: string; mtimeMs: number } | null = null
+    for (const entry of readdirSync(logsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const file = join(logsDir, entry.name, 'pnpm.log')
+      try {
+        const mtimeMs = statSync(file).mtimeMs
+        if (newest === null || mtimeMs > newest.mtimeMs) newest = { file, mtimeMs }
+      } catch { /* 该 operation 还没有 pnpm.log */ }
+    }
+    return newest
+  }
+  let baselineMs = 0
+  try {
+    baselineMs = newestLog()?.mtimeMs ?? 0
+  } catch { /* logs 目录还不存在 */ }
+  let captured = ''
+  const tick = (): void => {
+    try {
+      const newest = newestLog()
+      if (newest === null || newest.mtimeMs <= baselineMs) return
+      const text = readFileSync(newest.file, 'utf8')
+      if (text.length > captured.length) captured = text
+    } catch { /* 读不到就放弃这一轮 */ }
+  }
+  const timer = setInterval(tick, 700)
+  timer.unref()
+  tick()
+  return {
+    stop: (): string => {
+      clearInterval(timer)
+      tick()
+      return captured.length > CAPTURE_LIMIT_BYTES ? captured.slice(-CAPTURE_LIMIT_BYTES) : captured
+    },
+  }
+}

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

@@ -4,17 +4,12 @@
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
  * 分发文件解析：从 package.json 推出装完后必须真实存在的文件 —— 作者声明的入口
- * （exports["."] / main）与 bundle 声明的补丁（dsh.bundle.patch）。git 通道（tar 预检）
- * 与 npm 通道（装后 statSync 校验）共用，保证两条通道对同一个包判定一致。
+ * （exports["."] / main）与 bundle 声明的补丁（dsh.bundle.patch），供装后校验使用。
  *
- * 这里不替作者补一个 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 本包，入口那时必须存在。
- * 所以只有补丁真的写了自己的包名，才把这个入口算进分发要求。
+ * 只在包自己声明了入口时才要求它存在：宿主加载 bundle 读的是它的 package.json 与声明的补丁，
+ * 从不 import 包本身。硬要一个作者没声明过的 index.js，会把完整的包判成分发残缺、把一条假缺陷
+ * 推到作者仓库。例外是补丁自己 mount 了本包（组合包的常规写法）—— 那时宿主按包名 import 本包，
+ * 入口必须存在，所以只有补丁真的写了自己的包名才把这个入口算进分发要求。
  */
 
 /** exports 条件对象里按优先级尝试的键；Node 语义下 default 最宽，import/require 次之。 */
@@ -53,7 +48,7 @@ export function resolvePackageEntry(meta: PackageManifest): string | null {
 /**
  * 解析 `dsh.bundle.patch` 声明的补丁文件（相对包根，不带 `./` 前缀）。
  * 形状不合规范（既不是字符串也不是字符串数组）在这里不判定：那是 dsh 启动时
- * bundlePatchFiles 的报错职责，预检只负责「声明了就要在包里存在」。
+ * bundlePatchFiles 的报错职责，装后校验只负责「声明了就要在包里存在」。
  */
 export function resolveBundlePatchFiles(meta: PackageManifest): string[] {
   const patch = (meta.dsh as { bundle?: { patch?: unknown } } | undefined)?.bundle?.patch

package/src/server/services/install/registry-check.ts

@@ -69,8 +69,8 @@ export async function registryMissingMarker(
 ): Promise<string | null> {
   const name = missingPackageOf(output)
   if (name === null) return null
-  // ① profile 自己声明的残留依赖（#73）：用户环境问题，交给既有的 pnpmMissingDep 提示（该提示就是
-  // 教用户删 profile 里那条依赖），这里不再产出标记、不改归属
+  // 该包是 profile 自己声明的依赖（用户环境里留下的条目）→ 用户环境问题，交给既有的 pnpmMissingDep
+  // 提示处理（那条提示就是教用户删掉它），不产出标记、不改归属
   if (profileDependencyNames(opts.profileDir).some((dep) => dep.toLowerCase() === name.toLowerCase())) return null
   const exists = await existsOnOfficialRegistry(name, opts.fetchImpl ?? fetch, opts.timeoutMs ?? 8000)
   if (exists === false) {

package/src/server/services/install/release-target.ts

@@ -3,14 +3,13 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 预构建 GitHub release 安装目标（目录权威命令 → 可安装直链）。
- * 部分插件（如 loopx）把构建产物发布成 GitHub release 的 .tgz，仓库 HEAD 反而是
- * monorepo 根、走 git 直装会因缺入口文件失败；目录下发的权威安装命令直接指向该
- * release 包。这里把「目录命令」解析成安全的 release 目标，供客户端选路与服务端
- * 校验共用（单一事实来源，避免两端口径漂移）。
+ * 预构建 release 直链的仓库身份解析。部分插件（如 loopx）当初以 GitHub release 的 .tgz
+ * 安装过，仓库 HEAD 反而是 monorepo 根、走 git 直装会因缺入口文件失败；老安装记录里留的
+ * 就是这种 release 直链。这里把「历史安装目标」还原成所属仓库身份，供已装态读回、队列
+ * 去重与展示复用（单一事实来源，避免两端口径漂移）。
  *
  * 只接受固定形态的 HTTPS `github.com/<owner>/<repo>/releases/download/<tag>/<asset>.tgz`：
- * 目录命令是展示数据、绝非 shell 代码，绝不执行命令文本；跨仓跳转、外部主机、凭据、
+ * 输入是记录/展示数据、绝非 shell 代码，绝不执行其文本；跨仓跳转、外部主机、凭据、
  * 移动的 latest 链接、query/fragment、多余 CLI 参数与 shell 片段一律拒绝。
  */
 
@@ -22,15 +21,15 @@ export interface GithubReleaseTarget {
   repo: string
 }
 
-/** 目录权威命令：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同口径）。 */
+/** 完整命令前缀：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同口径）。 */
 const DSH_PLUGIN_CMD_RE = /^dsh[ \t]+plugin[ \t]+--profile(?:[ \t]+|=)[A-Za-z0-9_-]+[ \t]+(?:add|update)[ \t]+(.+)$/i
 
 /** 固定形态的 release .tgz 直链：主机、路径段与扩展名全部锁死。 */
 const RELEASE_URL_RE = /^https:\/\/github\.com\/([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)\/releases\/download\/([A-Za-z0-9._+-]+)\/([A-Za-z0-9._+-]+\.tgz)$/
 
 /**
- * 解析一个 release 安装目标。
- * @param value - 目录命令（`dsh plugin --profile web add <url>`）或裸直链。
+ * 解析一个历史安装目标里的 release 直链。
+ * @param value - 完整命令（`dsh plugin --profile web add <url>`）或裸直链。
  * @returns 命中返回 `{ target, repo }`，否则 null。
  */
 export function githubReleaseTarget(value: string): GithubReleaseTarget | null {

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

@@ -15,7 +15,7 @@ import type { InstallResult, InstallTask, Invocation, QueueItem } from './instal
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.ts'
 import { npmTooLowMarker } from './npm-check.ts'
 import { registryMissingMarker } from './registry-check.ts'
-import { backfillOperationLog } from './operation-log.ts'
+import { backfillOperationLog, createOperationLogTap, operationLogPathOf } 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'
@@ -23,15 +23,15 @@ import { addPendingRestart, clearPendingRestart } from '../profile/pending-resta
 import { addAllowBuildsKey, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.ts'
 import { appendLog } from '../log.ts'
 
-/** In-memory task registry, keyed by task id. */
+/** 内存任务注册表，按任务 id 索引。 */
 const tasks = new Map<number, InstallTask>()
 let nextTaskId = 1
-/** Pending tasks awaiting their turn (FIFO). The queue worker runs at most one mutation at a time. */
+/** 等待轮到的排队任务（FIFO）。队列 worker 同一时刻最多跑一个变更。 */
 const queue: QueueItem[] = []
-/** Child processes of currently running tasks (for cancel). */
+/** 当前运行任务的子进程（用于取消）。 */
 const runningChildren = new Map<number, ReturnType<typeof spawn>>()
 
-/** Snapshot of a task (keeps the live object untouched by consumers). */
+/** 任务快照（避免消费方改动实时对象）。 */
 export function getTask(id: number): InstallTask | undefined {
   const task = tasks.get(id)
   if (!task) return undefined
@@ -45,17 +45,17 @@ export interface ActiveTaskInfo {
   status: 'pending' | 'running'
   progress: number
   lines: string[]
-  /** 尝试过的安装方式（npm 反查 + 实际执行命令）：失败时前端 issue 预填需要 */
+  /** 尝试过的安装方式（实际执行过的命令）：失败时前端 issue 预填需要 */
   attempts: string[]
-  /** 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：前端刷新恢复后仍能精准溯源 */
-  installChannel?: 'npm' | 'git' | 'dsh'
+  /** 自定义安装入口渠道（NPM 包卡片）：前端刷新恢复后仍能精准溯源 */
+  installChannel?: 'npm'
 }
 
-/** All non-terminal tasks in queue order (running first, then pending). Lets the client resume a queue after a page reload. */
+/** 全部未终态任务，按队列顺序（running 在前、pending 在后）。供客户端刷新页面后恢复队列。 */
 export function activeTask(): ActiveTaskInfo[] {
   const found: ActiveTaskInfo[] = []
-  // 展示目标用 displayTarget（owner/repo）：安装 target 可能被服务端切成 npm 包名
-  // （npm 反查命中），队列恢复/待重启展示对用户保持仓库名无感知
+  // 展示目标用 displayTarget（owner/repo）：安装 target 是 npm 包名，
+  // 队列恢复/待重启展示对用户保持仓库名无感知
   const show = (task: InstallTask): string => task.displayTarget ?? task.target
   for (const item of queue) {
     const task = item.task
@@ -90,26 +90,24 @@ export function activeTask(): ActiveTaskInfo[] {
 }
 
 /**
- * True while a mutation child process is still alive. The concurrent slot is
- * keyed off the live child set rather than task.status: cancelling a running
- * task flips its status immediately, but the child may still be shutting down
- * (the close event lands later) — the slot must stay held until then, otherwise
- * a new task would start while the old pnpm still runs in the same profile dir.
+ * 变更子进程仍存活时为 true。并发占位以存活子进程集合为准，而非 task.status：
+ * 取消运行中任务会立即翻转其状态，但子进程可能仍在退出中（close 事件稍后才到）——
+ * 占位必须维持到那时，否则旧 pnpm 还在同一 profile 目录跑，新任务就开始了。
  */
 export function hasRunningTask(): boolean {
   return runningChildren.size > 0
 }
 
-/** Whether the target already has a non-terminal task in the queue (install/uninstall dedupe). */
+/** 目标在队列里是否已有未终态任务（安装/卸载去重）。 */
 export function hasQueuedTarget(target: string): boolean {
   return queue.some((it) => it.task.target === target && (it.task.status === 'pending' || it.task.status === 'running'))
 }
 
 /**
- * Cancel a queued or running task.
- * - pending: removed from the queue immediately (never spawned).
- * - running: kills the child process; the queue worker then picks the next one.
- * Returns false when the task is unknown or already finished.
+ * 取消排队中或运行中的任务。
+ * - pending：立即移出队列（从未 spawn）。
+ * - running：杀掉子进程；队列 worker 随后取下一个。
+ * 任务不存在或已结束时返回 false。
  */
 export function cancelTask(id: number): boolean {
   const task = tasks.get(id)
@@ -260,17 +258,14 @@ function mutationVerb(action: 'add' | 'remove' | 'update'): string {
 
 /** 系统日志入口渠道后缀：自定义安装（带渠道）在日志里体现「从哪张卡片发起」，
  *  目录插件安装（无渠道）返回空串。日志中文语境，渠道名用中文口语。 */
-function channelLabel(channel: 'npm' | 'git' | 'dsh' | undefined): string {
-  if (channel === 'git') return '（GitHub 源码入口）'
-  if (channel === 'dsh') return '（DSH 命令入口）'
+function channelLabel(channel: 'npm' | undefined): string {
   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.
+ * 插件变更入队并返回其任务。任务严格串行：队列 worker 只在上一个结束后才启动下一个。
+ * 完成前可通过 `getTask(id)` / `activeTask()` 查看进度。
  */
 export function startPluginMutation(options: {
   action: 'add' | 'remove' | 'update'
@@ -285,13 +280,13 @@ export function startPluginMutation(options: {
   /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目，两类操作都尽量立即生效
    *  （缺失时安装/卸载仍需重启） */
   loader?: LoaderHandle
-  /** 入队前已尝试的安装方式（npm registry 反查等）：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
+  /** 入队前已尝试的安装方式：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
   attempts?: string[]
   /** 更新已安装的 npm 包（mode=update）：命令显式带 @latest，让 pnpm 真正解析最新版本 */
   updateNpm?: boolean
-  /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
-   *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装不传 */
-  installChannel?: 'npm' | 'git' | 'dsh'
+  /** 自定义安装入口渠道（NPM 包卡片）：任务输出行与系统日志据此溯源「从哪个入口发起」；
+   *  目录插件安装不传 */
+  installChannel?: 'npm'
 }): InstallTask {
   // 卸载入队时先快照「该包是否带客户端 UI」：卸载完成后包已从磁盘删除，读不到 package.json，
   // 只能在此刻取；卸载成功且曾存活时据此决定是否要刷新页面摘除插件面板
@@ -341,7 +336,7 @@ export function startPluginMutation(options: {
   return task
 }
 
-/** Queue worker: at most one mutation runs at a time; pick the next pending task when the slot frees up. */
+/** 队列 worker：同一时刻最多跑一个变更；占位空出时取下一个 pending 任务。 */
 function pumpQueue(): void {
   if (hasRunningTask()) return
   const item = queue.find((it) => it.task.status === 'pending')
@@ -399,9 +394,8 @@ function pumpQueue(): void {
 }
 
 /**
- * Run one `dsh plugin --profile <profile> <action> <target>` spawn, stream
- * its output onto the tracked task and resolve with the captured result.
- * Never rejects; failures surface through the result / task state.
+ * 执行一次 `dsh plugin --profile <profile> <action> <target>` spawn，把输出流式写到
+ * 跟踪的任务上，并以捕获结果 resolve。绝不 reject；失败通过结果/任务状态体现。
  */
 function spawnMutation(options: {
   action: 'add' | 'remove' | 'update'
@@ -438,8 +432,7 @@ function spawnMutation(options: {
   const args = isGlobalNpm
     ? ['install', '-g', ...(globalNpm ?? [])]
     : [...invocation.prefixArgs, 'plugin', '--profile', profile, cliAction, npmUpdateTarget]
-  // 记录实际执行的命令（npm 通道显示包名，git 通道显示 HTTPS 源），
-  // 失败提 Issue 时作为「已尝试的安装方式」随附
+  // 记录实际执行的命令（显示包名），失败提 Issue 时作为「已尝试的安装方式」随附
   const executed = isGlobalNpm
     ? `npm install -g ${(globalNpm ?? []).join(' ')}`
     : `dsh plugin --profile ${profile} ${cliAction} ${npmUpdateTarget}`
@@ -655,7 +648,7 @@ function spawnMutation(options: {
 
 /**
  * 安装后校验已装包里 package.json 声明的文件（main / exports["."].default 与
- * dsh.bundle.patch）是否真实存在。git: 分发常不提交构建产物（lib/ 等），pnpm 装完没有
+ * dsh.bundle.patch）是否真实存在。npm 包也可能漏发构建产物（lib/ 等），pnpm 装完没有
  * 报错，但宿主重启加载插件树时会 ERR_MODULE_NOT_FOUND 直接崩溃、网页打不开 —— 这里在
  * 登记「待重启」前就把这类残缺包拦下。没有声明过的文件不在这里追究：没声明入口的
  * bundle 包（只挂技能）本来就不需要入口，宿主读的是它的 package.json 与声明的补丁。
@@ -754,13 +747,11 @@ export function hostSpawnMarker(invocation: Invocation, error: unknown): string
 }
 
 /**
- * Run a plugin mutation with one recovery path: when `add` fails because
- * pnpm's allowBuilds gate blocks a build script — either the git-hosted
- * package's own `prepare` (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, key from
- * the printed key@url hint) or a dependency's native build
- * (`ERR_PNPM_IGNORED_BUILDS`, key = the listed name@version) — write the
- * exact keys into the profile's pnpm-workspace.yaml and retry once.
- * Other failures fall through to the single-spawn result.
+ * 执行插件变更，带一条恢复路径：当 `add` 因 pnpm 的 allowBuilds 门禁拦下构建脚本而失败 ——
+ * 或是 git 源包自己的 `prepare`（`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，key 取自打印的
+ * key@url 提示），或是某依赖的原生构建（`ERR_PNPM_IGNORED_BUILDS`，key = 列出的 name@version）——
+ * 就把确切的 key 写进 profile 的 pnpm-workspace.yaml 并重试一次。
+ * 其它失败一律落到单次 spawn 的结果。
  */
 export async function runPluginMutation(options: {
   action: 'add' | 'remove' | 'update'
@@ -776,6 +767,8 @@ export async function runPluginMutation(options: {
   /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时执行全局安装，不进任何 profile、无需宿主重启 */
   globalNpm?: string[]
 }): Promise<InstallResult> {
+  // operation 日志只在运行期存在（宿主结束后可能清掉），先开抓取，退出后按路径读作兜底
+  const logTap = createOperationLogTap(profileDirectory(options.profile))
   let result = await spawnMutation(options)
   // allowBuilds 放行 / 装后入口校验都是 profile 专属（pnpm 装进 profile 的场景）；
   // 全局 npm 安装直接走 npm，无 pnpm allowBuilds 拦截、也不进 profile，跳过这两类恢复
@@ -787,8 +780,7 @@ export async function runPluginMutation(options: {
       const key = parseAllowBuildsKey(output)
       if (key !== null) {
         if (options.task) {
-          // First attempt already marked the task failed; reset it so the
-          // retry streams progress as a running task again.
+          // 首次尝试已把任务标为失败；重置它，让重试重新以 running 任务形式流式输出进度。
           options.task.status = 'running'
           options.task.exitCode = null
           pushLine(options.task, `[allow build] ${key}`)
@@ -815,14 +807,16 @@ export async function runPluginMutation(options: {
       }
     }
   }
-  // pnpm 安装本身成功，但目标包声明分发的文件缺失（git 分发缺构建产物 / 缺声明的补丁）→ 判为失败：
+  // 重试会产生新的 operation 日志，运行期抓取到此为止
+  const tappedLog = logTap.stop()
+  // pnpm 安装本身成功，但目标包声明分发的文件缺失（分发物缺构建产物 / 缺声明的补丁）→ 判为失败：
   // 撤销刚登记的待重启，避免用户重启时宿主加载残缺包直接崩溃。
   // 全局 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}: declared 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} (the published package is missing this file — report it to the author)`
       if (options.task && options.task.status !== 'cancelled') {
         options.task.status = 'failed'
         options.task.exitCode = null
@@ -832,18 +826,21 @@ export async function runPluginMutation(options: {
       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 已把报错回显出来时无需多读一次文件。
+  // 宿主只把一行摘要（`dsh: plugin command failed; diagnostics: <path>`）回显到控制台、真正的报错
+  // 写进该日志文件时，前端拿不到任何错误特征、只能归为「未知」。按该路径回捞日志尾部补进失败信息。
+  // 只在输出本就不含错误码时回捞 —— 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}`)
+    const output = `${result.stderr}\n${result.stdout}`
+    const backfilled = tappedLog !== '' ? tappedLog : backfillOperationLog(output)
     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}` }
+    } else if (options.task && options.task.status !== 'cancelled' && operationLogPathOf(output) !== null) {
+      // 诊断路径在、日志却取不到：留一行证据，否则下一次同类上报又只剩宿主那句摘要、看不出根因
+      pushLine(options.task, '[pnpm log] the host-reported diagnostics log could not be read from disk (missing, empty, or unreadable)')
     }
   }
   // 包在 registry 不存在（404）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」