dsh-plugin 1.6.11 → 2.0.0

package/lib/services/install/npm-check.js

@@ -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/lib/services/install/npm-resolve.js

@@ -3,57 +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.js';
 import { finalUrl } from '../probe.js';
-/** 反查缓存：repo 小写 → npm 包名（null 表示已确认无对应 npm 包；网络异常不缓存）。 */
-const cache = new Map();
-/** 单次 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, registry = '', proxy = '') {
-    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;
-}
-/**
- * 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) {
     if (typeof pkg.repository === 'string')
         return pkg.repository;
@@ -72,6 +33,10 @@ export function isDshPackageMetadataForRepo(pkg, repo) {
     const manifestMarked = pkg.dsh !== null && typeof pkg.dsh === 'object';
     return keywordMarked || manifestMarked;
 }
+/**
+ * 校验包名对应的 npm 包确实属于该仓库且声明为 DSH 插件：取 registry 上的 `latest`
+ * 元数据比对 repository 与插件标记。网络异常、超时、非 200 一律返回 false，不阻塞调用方。
+ */
 export function isDshNpmPackageForRepo(packageName, repo, registry = '', proxy = '') {
     if (packageName === '' || repo === '')
         return Promise.resolve(false);
@@ -121,55 +86,3 @@ async function canonicalRepo(repo, proxy) {
     const canonical = final === null ? null : githubRepoOf(final);
     return canonical !== null && canonical.toLowerCase() !== key ? canonical : '';
 }
-function matchingPackagesForRepo(objects, repo) {
-    const matches = [];
-    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, repo) {
-    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, registry) {
-    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) => { body += chunk.toString(); });
-            res.on('end', () => {
-                try {
-                    const data = JSON.parse(body);
-                    resolve(selectNpmPackageForRepo(data.objects ?? [], `${owner}/${name}`));
-                }
-                catch {
-                    resolve(undefined);
-                }
-            });
-        });
-        req.on('timeout', () => req.destroy());
-        req.on('error', () => resolve(undefined));
-    });
-}

package/lib/services/install/package-entry.js

@@ -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 次之。 */
 const EXPORT_CONDITION_KEYS = ['default', 'import', 'require'];
@@ -42,7 +37,7 @@ export function resolvePackageEntry(meta) {
 /**
  * 解析 `dsh.bundle.patch` 声明的补丁文件（相对包根，不带 `./` 前缀）。
  * 形状不合规范（既不是字符串也不是字符串数组）在这里不判定：那是 dsh 启动时
- * bundlePatchFiles 的报错职责，预检只负责「声明了就要在包里存在」。
+ * bundlePatchFiles 的报错职责，装后校验只负责「声明了就要在包里存在」。
  */
 export function resolveBundlePatchFiles(meta) {
     const patch = meta.dsh?.bundle?.patch;

package/lib/services/install/registry-check.js

@@ -3,20 +3,9 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 官方 registry 存在性复核：把「包在 registry 上不存在」这类失败的责任方分开。
- *
- * 背景：安装失败日志出现 `ERR_PNPM_FETCH_404` / `Not Found - 404` 时，光看日志分不清三种情形：
- *   ① 缺的包是 **profile 自己声明的依赖**（历史残留条目，指向一个从未发布的包）—— 用户环境问题：
- *      pnpm 每次解析依赖都会先卡在它上面，任何插件都装不进来（issue #73），提示删掉该条目即可；
- *   ② 缺的包来自**插件的依赖树**，且该包在官方 registry 上也不存在 —— 作者侧问题（漏声明依赖、
- *      依赖被删除或从未发布），应引导用户投插件作者仓库；
- *   ③ 缺的包来自插件依赖树，但官方 registry 上有 —— 用户本机 registry 指向的镜像/私有源未同步
- *      该包，属用户环境问题，提示换源即可。
- * 故本模块先排除 ①（读 profile 的 package.json），再用**官方** registry（registry.npmjs.org，
- * 绕开本机可能配置的镜像）复查存在性，产出 ② / ③ 的标记行。
- *
- * 与 npm-check.ts 同构：本模块只产出「标记行」，由 task-queue 追加到任务输出，前端按标记分类。
- * fetch 与 profile 目录都可注入，便于单测覆盖全部结论而不依赖网络。
+ * 官方 registry 存在性复核：用官方源（绕开本机镜像）复查 404 的包，产出标记行区分
+ * 「profile 残留依赖」「插件依赖在官方源也不存在（作者侧）」「本机镜像未同步」三种情形；
+ * 标记由 task-queue 追加到任务输出，前端按标记归类。fetch 与 profile 目录可注入，便于单测。
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -74,8 +63,8 @@ export async function registryMissingMarker(output, opts) {
     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);

package/lib/services/install/release-target.js

@@ -3,23 +3,22 @@
  * 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 片段一律拒绝。
  */
-/** 目录权威命令：`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) {

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

@@ -14,31 +14,31 @@ import { dirname, join, resolve } from 'node:path';
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.js';
 import { npmTooLowMarker } from './npm-check.js';
 import { registryMissingMarker } from './registry-check.js';
-import { backfillOperationLog } from './operation-log.js';
+import { backfillOperationLog, operationLogPathOf } from './operation-log.js';
 import { cleanLine, estimateProgress } from '../profile/progress.js';
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.js';
 import { addPendingRestart, clearPendingRestart } from '../profile/pending-restart.js';
 import { addAllowBuildsKey, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.js';
 import { appendLog } from '../log.js';
-/** In-memory task registry, keyed by task id. */
+/** 内存任务注册表，按任务 id 索引。 */
 const tasks = new Map();
 let nextTaskId = 1;
-/** Pending tasks awaiting their turn (FIFO). The queue worker runs at most one mutation at a time. */
+/** 等待轮到的排队任务（FIFO）。队列 worker 同一时刻最多跑一个变更。 */
 const queue = [];
-/** Child processes of currently running tasks (for cancel). */
+/** 当前运行任务的子进程（用于取消）。 */
 const runningChildren = new Map();
-/** Snapshot of a task (keeps the live object untouched by consumers). */
+/** 任务快照（避免消费方改动实时对象）。 */
 export function getTask(id) {
     const task = tasks.get(id);
     if (!task)
         return undefined;
     return { ...task, lines: task.lines.slice(0, MAX_TASK_LINES) };
 }
-/** 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() {
     const found = [];
-    // 展示目标用 displayTarget（owner/repo）：安装 target 可能被服务端切成 npm 包名
-    // （npm 反查命中），队列恢复/待重启展示对用户保持仓库名无感知
+    // 展示目标用 displayTarget（owner/repo）：安装 target 是 npm 包名，
+    // 队列恢复/待重启展示对用户保持仓库名无感知
     const show = (task) => task.displayTarget ?? task.target;
     for (const item of queue) {
         const task = item.task;
@@ -72,24 +72,22 @@ export function activeTask() {
     return found;
 }
 /**
- * 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() {
     return runningChildren.size > 0;
 }
-/** Whether the target already has a non-terminal task in the queue (install/uninstall dedupe). */
+/** 目标在队列里是否已有未终态任务（安装/卸载去重）。 */
 export function hasQueuedTarget(target) {
     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) {
     const task = tasks.get(id);
@@ -132,6 +130,12 @@ function pushLine(task, line) {
         task.progress = Math.max(task.progress, 6 + Math.min(79, task.lines.length * 2));
     }
 }
+/** spawn 的 cwd：profile 目录（asar 路径不能作 cwd）；目录不存在时回退进程工作目录，
+ *  否则 Node 报的是 `spawn <file> ENOENT`，与「可执行文件不存在」无法区分。 */
+function spawnCwdFor(profile) {
+    const dir = profileDirectory(profile);
+    return existsSync(dir) ? dir : process.cwd();
+}
 function cliInvocation(profile) {
     const entry = process.argv[1];
     if (entry !== undefined) {
@@ -145,8 +149,8 @@ function cliInvocation(profile) {
             return {
                 file: process.execPath,
                 prefixArgs: ['--expose-internals', bootstrap],
-                // 工作目录用 profile 目录（真实存在的目录）：asar 内的路径不能作为 spawn 的 cwd
-                cwd: profileDirectory(profile),
+                // cwd 用 profile 目录（asar 路径不能作 cwd），不存在时由 spawnCwdFor 回退
+                cwd: spawnCwdFor(profile),
                 useShell: false,
                 // Electron 可执行文件只有带这个变量才按 Node 运行引导脚本
                 env: { ELECTRON_RUN_AS_NODE: '1' },
@@ -235,18 +239,13 @@ function mutationVerb(action) {
 /** 系统日志入口渠道后缀：自定义安装（带渠道）在日志里体现「从哪张卡片发起」，
  *  目录插件安装（无渠道）返回空串。日志中文语境，渠道名用中文口语。 */
 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.
+ * 插件变更入队并返回其任务。任务严格串行：队列 worker 只在上一个结束后才启动下一个。
+ * 完成前可通过 `getTask(id)` / `activeTask()` 查看进度。
  */
 export function startPluginMutation(options) {
     // 卸载入队时先快照「该包是否带客户端 UI」：卸载完成后包已从磁盘删除，读不到 package.json，
@@ -296,7 +295,7 @@ export function startPluginMutation(options) {
     pumpQueue();
     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() {
     if (hasRunningTask())
         return;
@@ -358,9 +357,8 @@ function pumpQueue() {
     });
 }
 /**
- * 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) {
     const { action, profile, target, timeoutMs = 5 * 60 * 1000, env, task, displayTarget, loader, globalNpm, updateNpm } = options;
@@ -382,8 +380,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}`;
@@ -427,15 +424,20 @@ function spawnMutation(options) {
             });
         }
         catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            // 宿主自身入口起不来 → 补标记，前端据此归因
+            const marker = hostSpawnMarker(invocation, error);
             if (task) {
                 task.status = 'failed';
                 task.exitCode = null;
-                pushLine(task, `[error] ${error instanceof Error ? error.message : String(error)}`);
+                pushLine(task, `[error] ${detail}`);
+                if (marker !== null)
+                    pushLine(task, marker);
             }
             resolveOnce({
                 exitCode: null,
                 timedOut: false,
-                error: error instanceof Error ? error.message : String(error),
+                error: marker === null ? detail : `${detail}\n${marker}`,
                 stdout,
                 stderr,
             });
@@ -515,12 +517,16 @@ function spawnMutation(options) {
             }, 3_000);
         });
         child.once('error', (error) => {
+            // 同同步抛出那条路径：宿主自身入口起不来 → 补标记
+            const marker = hostSpawnMarker(invocation, error);
             if (task && task.status !== 'cancelled') {
                 task.status = 'failed';
                 task.exitCode = null;
                 pushLine(task, `[error] ${error.message}`);
+                if (marker !== null)
+                    pushLine(task, marker);
             }
-            settleOnce({ exitCode: null, timedOut: false, error: error.message, stdout, stderr });
+            settleOnce({ exitCode: null, timedOut: false, error: marker === null ? error.message : `${error.message}\n${marker}`, stdout, stderr });
         });
         child.once('close', (code) => {
             settleOnce({ exitCode: code, timedOut, error: null, stdout, stderr });
@@ -608,7 +614,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 与声明的补丁。
@@ -682,10 +688,8 @@ function annotateNpmTooLow(result, options) {
         pushLine(options.task, line);
     return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
 }
-/** 包在 registry 不存在（404）→ 用官方源复查一次，把「作者依赖缺失/包被删」与「本机镜像源滞后」
- *  分开（两者的提示与去向不同：前者引导投作者、后者只提示换源）。检测逻辑在独立的
- *  registry-check.ts；这里之所以是异步，是因为要联网查官方 registry —— 只在安装失败且日志含 404
- *  时发生，代价可忽略。 */
+/** 安装失败且日志含 404 时，用官方源复查一次并注入标记（逻辑见 registry-check.ts）。
+ *  异步是因为要联网；只在失败路径上发生。 */
 async function annotateRegistryMissing(result, options) {
     if (options.action === 'remove' || result.exitCode === 0 || result.timedOut)
         return result;
@@ -699,13 +703,23 @@ async function annotateRegistryMissing(result, options) {
     return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line };
 }
 /**
- * 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.
+ * 宿主自身 CLI 调不起来时的 ASCII 标记行：spawn 我们解析出的宿主入口报 ENOENT 时返回
+ * `[host-spawn]`，供前端单独归因、不引导提 Issue。PATH 上的 dsh/npm 各有自己的标记，返回 null。
+ * 导出供单测覆盖判据。
+ */
+export function hostSpawnMarker(invocation, error) {
+    if (error?.code !== 'ENOENT')
+        return null;
+    if (invocation.file === 'dsh' || invocation.file === 'npm')
+        return null;
+    return `[host-spawn] the DSH host could not be launched (${invocation.file}: ENOENT)`;
+}
+/**
+ * 执行插件变更，带一条恢复路径：当 `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) {
     let result = await spawnMutation(options);
@@ -719,8 +733,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}`);
@@ -749,14 +762,14 @@ export async function runPluginMutation(options) {
             }
         }
     }
-    // pnpm 安装本身成功，但目标包声明分发的文件缺失（git 分发缺构建产物 / 缺声明的补丁）→ 判为失败：
+    // 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;
@@ -766,12 +779,12 @@ 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 = 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');
@@ -781,6 +794,10 @@ export async function runPluginMutation(options) {
             }
             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）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」
     result = await annotateRegistryMissing(result, options);