dsh-plugin 1.6.6 → 1.6.8

package/lib/http/install.js

@@ -208,16 +208,15 @@ export function registerInstallRoutes(webServer, profile, loader) {
                             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}` });
@@ -272,17 +271,17 @@ export function registerInstallRoutes(webServer, profile, loader) {
                             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/lib/services/install/operation-log.js

@@ -0,0 +1,49 @@
+/**
+ * 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.js';
+/**
+ * 从 DSH 输出里解析 operation 日志路径（`diagnostics: <path>`）。
+ * 只认 DSH 的 operation 日志：路径含 `.plugin-manager` 且以 `pnpm.log` 结尾；
+ * 不是这种路径（或压根没有该行）返回 null，调用方据此跳过回捞。
+ */
+export function operationLogPathOf(output) {
+    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) {
+    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/lib/services/install/package-entry.js

@@ -1,21 +1,31 @@
 /**
- * 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'];
 /**
- * 解析包的入口文件（相对包根，不带 `./` 前缀）。
+ * 解析作者声明的入口文件（相对包根，不带 `./` 前缀）。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) {
     const dot = meta.exports?.['.'];
@@ -26,8 +36,48 @@ export function resolvePackageEntry(meta) {
             : 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) {
+    const patch = meta.dsh?.bundle?.patch;
+    const declared = typeof patch === 'string' ? [patch] : Array.isArray(patch) ? patch : [];
+    return declared
+        .filter((file) => typeof file === 'string' && file !== '')
+        .map(stripDotSlash);
+}
+/** 分发里必须存在的全部文件：作者声明的入口，加上 bundle 声明的补丁，入口在前。
+ *  manifest 没声明入口时才看补丁：补丁按本包名 mount 自己（下面 mountsItself），
+ *  宿主就会 import 本包，Node 的旧式解析落到 index.js —— 那个入口同样必须有。 */
+export function requiredDistributionFiles(meta, patchTexts = []) {
+    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) {
+    return text
+        .split(/\r?\n/)
+        .map((line) => /^\s*(?:-\s*)?name:\s*(.+?)\s*$/u.exec(line)?.[1])
+        .filter((value) => value !== undefined)
+        .map((value) => value.replace(/^(['"])(.*)\1$/u, '$2'))
+        .filter((value) => value !== '');
+}
+/** 补丁是否把本包自己 mount 进树（dsh 文档里组合包的常规写法），是则宿主会 import 本包。 */
+export function mountsItself(meta, patchTexts) {
+    const name = meta.name;
+    if (typeof name !== 'string' || name === '')
+        return false;
+    return patchTexts.some((text) => patchRowNamesOf(text).includes(name));
 }
 function firstStringOf(conditions) {
     for (const key of EXPORT_CONDITION_KEYS) {
@@ -37,3 +87,4 @@ function firstStringOf(conditions) {
     }
     return undefined;
 }
+const stripDotSlash = (file) => file.replace(/^\.\//u, '');

package/lib/services/install/preflight.js

@@ -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.js';
 import { githubReleaseTarget } from './release-target.js';
-import { resolvePackageEntry } from './package-entry.js';
+import { requiredDistributionFiles, resolveBundlePatchFiles } from './package-entry.js';
 const execFileAsync = promisify(execFile);
 /** 单次网络操作超时（ms）：git ls-remote / codeload 下载。网络不可达时不能无限挂起，
  *  否则 `/install` 请求永远不返回、任务不入队、前端进度卡 0%。超时后放行（交给装后校验）。 */
@@ -49,9 +49,18 @@ export async function preflightTarget(target) {
         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 = [];
+        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 };
@@ -117,32 +126,53 @@ export function rootPackageEntryOfTarList(listing) {
         .filter((line) => /^[^/]+\/package\.json$/u.test(line));
     return candidates.length === 1 ? candidates[0] : null;
 }
+/**
+ * 清单里第一个缺失的必需文件（成员名带包根前缀，由调用方拼好），全部都在则为 null。
+ * 清单不可读（tar 缺失/解压失败）时按第一个必需文件缺失处理：与逐文件查询时
+ * 「查不到就是缺」的判定一致，宁可拦下一次可疑安装，也不放一个空包过去。
+ * Exported for a small parser regression test.
+ */
+export function missingDistributionFileOfTarList(listing, required) {
+    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) {
+    const listing = await tarListing(tar);
+    return listing === null ? null : rootPackageEntryOfTarList(listing);
+}
+/** tar 成员清单；`tar` 执行失败时返回 null（调用方按无法判定处理）。 */
+async function tarListing(tar) {
     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, entry) {
+/** 从 tarball 提取一个文件的内容；文件不存在或提取失败返回 null。 */
+async function readTarText(tar, entry) {
     try {
         const { stdout } = await execFileAsync('tar', ['-xzOf', tar, entry], { maxBuffer: 4 * 1024 * 1024 });
-        return JSON.parse(stdout);
+        return stdout;
     }
     catch {
         return null;
     }
 }
-/** 检查 tarball 内是否存在指定 entry。 */
-async function hasTarEntry(tar, entry) {
+/** 从 tarball 提取并解析一个 JSON 文件；文件不存在或解析失败返回 null。 */
+async function readTarJson(tar, entry) {
+    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);
     }
     catch {
-        return false;
+        return null;
     }
 }

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

@@ -8,11 +8,12 @@
  * 输出流式收集到任务上；卸载成功时尝试从运行中 loader 即时停用（见 loader.ts）。
  */
 import { spawn, spawnSync } from 'node:child_process';
-import { resolvePackageEntry } from './package-entry.js';
+import { requiredDistributionFiles, resolveBundlePatchFiles } from './package-entry.js';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 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 { backfillOperationLog } 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';
@@ -591,10 +592,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, target) {
     let profilePkg = null;
@@ -613,20 +616,33 @@ export function verifyInstalledEntry(profile, target) {
     if (!name)
         return { name: null, missing: null };
     const pkgDir = join(profileDirectory(profile), 'node_modules', name);
-    let entry = null;
+    let required = [];
     try {
         const meta = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
-        entry = resolvePackageEntry(meta);
+        // 补丁按本包名 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，逗号分隔）。 */
 function ignoredBuildKeys(output) {
@@ -702,21 +718,37 @@ 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] 标记，前端据此给准确原因

package/lib/types/services/install/operation-log.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 从 DSH 输出里解析 operation 日志路径（`diagnostics: <path>`）。
+ * 只认 DSH 的 operation 日志：路径含 `.plugin-manager` 且以 `pnpm.log` 结尾；
+ * 不是这种路径（或压根没有该行）返回 null，调用方据此跳过回捞。
+ */
+export declare function operationLogPathOf(output: string): string | null;
+/**
+ * 回捞 operation 日志尾部，作为失败详情返回；拿不到（无路径 / 文件不存在 / 读失败 /
+ * 内容为空）返回 null。尾部截到与子进程输出相同的上限，避免超大日志撑爆内存与消息。
+ */
+export declare function backfillOperationLog(output: string): string | null;

package/lib/types/services/install/package-entry.d.ts

@@ -1,21 +1,53 @@
 /**
- * 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 本包，入口那时必须存在。
+ * 所以只有补丁真的写了自己的包名，才把这个入口算进分发要求。
  */
+/** 解析所需的 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 declare function resolvePackageEntry(meta: {
-    main?: unknown;
-    exports?: unknown;
-}): string;
+export declare function resolvePackageEntry(meta: PackageManifest): string | null;
+/**
+ * 解析 `dsh.bundle.patch` 声明的补丁文件（相对包根，不带 `./` 前缀）。
+ * 形状不合规范（既不是字符串也不是字符串数组）在这里不判定：那是 dsh 启动时
+ * bundlePatchFiles 的报错职责，预检只负责「声明了就要在包里存在」。
+ */
+export declare function resolveBundlePatchFiles(meta: PackageManifest): string[];
+/** 分发里必须存在的全部文件：作者声明的入口，加上 bundle 声明的补丁，入口在前。
+ *  manifest 没声明入口时才看补丁：补丁按本包名 mount 自己（下面 mountsItself），
+ *  宿主就会 import 本包，Node 的旧式解析落到 index.js —— 那个入口同样必须有。 */
+export declare function requiredDistributionFiles(meta: PackageManifest, patchTexts?: string[]): string[];
+/**
+ * 补丁文本里插件行的 `name:` 值（DSH 补丁按行书写：`- name: <pkg>` / `  name: <pkg>`）。
+ * 刻意不做 YAML 解析：只认这一种行形状，认不出来就不判定 —— 漏判只是少一条要求，
+ * 误判会拦下能装的包，两边的代价不对称。
+ */
+export declare function patchRowNamesOf(text: string): string[];
+/** 补丁是否把本包自己 mount 进树（dsh 文档里组合包的常规写法），是则宿主会 import 本包。 */
+export declare function mountsItself(meta: PackageManifest, patchTexts: string[]): boolean;

package/lib/types/services/install/preflight.d.ts

@@ -1,4 +1,5 @@
-/** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径；
+/** 预检结果：ok=false 表示分发改 package.json 声明的文件（入口或 bundle 补丁），
+ *  missing 为该文件在包内的相对路径；
  *  name 为 git 分发包 package.json 声明的包名（非 git 目标/无法确定时为 null），
  *  供安装路由做「包名冲突」检测 —— 同名包名已被其他来源占用时，pnpm 装前必然撞车，
  *  需要把晦涩的 CLI 报错转成明确的拦截。 */
@@ -13,3 +14,10 @@ export declare function preflightTarget(target: string): Promise<PreflightResult
  * single archive root; nested monorepo package manifests are intentionally
  * ignored. Exported for a small parser regression test. */
 export declare function rootPackageEntryOfTarList(listing: string): string | null;
+/**
+ * 清单里第一个缺失的必需文件（成员名带包根前缀，由调用方拼好），全部都在则为 null。
+ * 清单不可读（tar 缺失/解压失败）时按第一个必需文件缺失处理：与逐文件查询时
+ * 「查不到就是缺」的判定一致，宁可拦下一次可疑安装，也不放一个空包过去。
+ * Exported for a small parser regression test.
+ */
+export declare function missingDistributionFileOfTarList(listing: string | null, required: string[]): string | null;

package/lib/types/services/install/task-queue.d.ts

@@ -67,10 +67,12 @@ export declare function startPluginMutation(options: {
     installChannel?: 'npm' | 'git' | 'dsh';
 }): InstallTask;
 /**
- * 安装后校验已装包的入口文件（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 declare function verifyInstalledEntry(profile: string, target: string): {
     name: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin",
-  "version": "1.6.6",
+  "version": "1.6.8",
   "description": "A community plugin marketplace for DeepSeek Harness, built to the official plugin spec — browse, search and install 10000+ human-curated community plugins without leaving the app. · DeepSeek Harness 社区插件市场（遵循官方开发规范）：10000+ 人工精选社区插件，每日更新。",
   "type": "module",
   "main": "lib/index.js",

package/src/client/components/modals/NotificationsModal.tsx

@@ -377,6 +377,12 @@ export function NotificationsModal({ records, tasks, pendingRestarts, t, env, on
                         }, t('failIssueBig')) : null,
                       ])
                     }
+                    if (kind === 'hubState') {
+                      // 插件中心的列表状态已过期（安装器自身守卫消息）：非插件问题、也不是 bug，只给可行动提示，不引导提 Issue
+                      return h('div', null, [
+                        h('div', { className: styles.failPrepareHint }, t('failHubStateHint')),
+                      ])
+                    }
                     // pnpm allowBuilds 拦截与未知失败：不归到插件作者，改为引导到插件中心仓库排查
                     return h('div', null, [
                       kind === 'pnpmIgnoredBuild'

package/src/client/components/modals/modals.tsx

@@ -497,6 +497,11 @@ export function ErrorModal({ message, repo, kind, command, attempts, t, env, onC
                   title: t('failIssueHint'),
                 }, t('failIssueBig')) : null,
               ])
+              : failureKind === 'hubState'
+              ? h('div', null, [
+                // 插件中心的列表状态已过期（安装器自身守卫消息）：不是插件问题、也不是 bug，只给可行动提示，不引导提 Issue
+                h('div', { className: styles.failPrepareHint }, t('failHubStateHint')),
+              ])
               : h('div', null, [
                 // pnpm allowBuilds 拦截与未知失败：不归到插件作者，改为引导到插件中心仓库排查
                 failureKind === 'pnpmIgnoredBuild'

package/src/client/locales.ts

@@ -315,10 +315,12 @@ export const zh = {
   failHubIssueBig: '反馈给插件中心排查',
   // 未知失败兜底：不归到插件作者，引导到插件中心仓库排查
   failUnclassifiedHint: '安装失败，原因未能自动识别。这通常不是插件自身的问题（可能与本机环境或插件中心有关），请将错误信息反馈给插件中心，由维护者排查。',
+  // 插件中心自身状态类消息（插件未安装 / 不在此处卸载 / 已在队列中）：已安装列表与实读快照不同步，非插件问题，不引导提 Issue
+  failHubStateHint: '插件列表状态已过期或与本地不一致：该插件可能已经装过了（无需重复安装，要升级请点「更新」），也可能已不在已安装列表中，或已在队列中。这不是插件本身的问题 —— 请刷新页面后重试。',
   // prepare 构建脚本实际执行失败（git 分发缺子模块/构建产物）：插件打包分发问题，应提 Issue
   failPrepareHint: '该插件安装时的构建脚本执行失败（git 分发常缺失子模块或构建产物），属插件打包分发问题。请向作者仓库提交 Issue 反馈。',
-  // 安装前预检 / 装后校验拦截（[packaging]）：git 分发缺构建产物、入口文件不存在 = 插件未适配官方默认安装方式
-  failPackagingHint: '该插件不支持官方默认安装方式：其 git 分发缺少构建产物（package.json 声明的入口文件在仓库中不存在），说明作者未适配官方安装流程。请到作者仓库提交 Issue 反馈，请其提交构建产物、改用预构建 release `.tgz` 直链（`releases/download/<tag>/<asset>.tgz`），或发布完整的 npm 版。',
+  // 安装前预检 / 装后校验拦截（[packaging]）：git 分发缺插件需要的文件（入口 / 补丁 mount 的入口 / bundle 补丁）= 插件未适配官方默认安装方式
+  failPackagingHint: '该插件不支持官方默认安装方式：其 git 分发缺少它需要的文件（`main` / `exports` 声明的入口、补丁按本包名 mount 的入口，或 `dsh.bundle.patch` 声明的补丁），说明作者未适配官方安装流程。请到作者仓库提交 Issue 反馈，请其提交构建产物、改用预构建 release `.tgz` 直链（`releases/download/<tag>/<asset>.tgz`），或发布完整的 npm 版。',
   // 原生依赖构建脚本被 pnpm 默认拦截（如 node-pty 的 ERR_PNPM_IGNORED_BUILDS）：不单独算插件问题，引导到插件中心仓库排查
   failIgnoredBuild: '该插件或其依赖需要执行构建脚本，被 pnpm 的安全白名单（allowBuilds）默认拦截导致安装失败（如原生模块 node-pty、或 git 安装时插件的 prepare 脚本）。这不一定是插件自身的问题（也可能是插件中心反查失败后回退到 git 安装所致），请先反馈给插件中心排查；若确认为插件依赖问题，可建议作者改用预编译版本（如 node-pty-prebuilt-multiarch）或移除安装期构建。',
   // npm arborist 内部崩溃（edgesOut）＋ 本机 npm 版本过低：npm 自身已知缺陷，不是插件问题，升级 npm 即可
@@ -713,10 +715,12 @@ export const en = {
   failHubIssueBig: 'Report to the Plugin Hub for triage',
   // Unknown-failure fallback: not routed to the plugin author, but to the hub repo for triage
   failUnclassifiedHint: 'The install failed and the cause could not be identified automatically. This is usually not the plugin itself (it may relate to your local environment or the Plugin Hub). Please report the error to the Plugin Hub so the maintainers can triage it.',
+  // The hub's own state-guard messages (plugin not installed / cannot be uninstalled here / already queued / already installed): the installed list is out of sync with the live snapshot — not a plugin issue, no issue prompt
+  failHubStateHint: 'The plugin list is out of date or out of sync: this plugin may already be installed (no need to reinstall — use "Update" to upgrade), or may no longer be in the installed list, or may already be queued. This is not a plugin problem — refresh the page and retry.',
   // prepare script actually failed (git tarball misses submodules/build output): a packaging issue of the plugin itself — file an issue
   failPrepareHint: 'This plugin failed while running its build scripts during install (git tarballs often miss submodules or build output). This is a packaging issue of the plugin itself — please report it to the author repository.',
-  // Pre-install / post-install guard hit ([packaging]): git distribution lacks build output, entry file missing = not adapted to the official default install method
-  failPackagingHint: 'This plugin does not support the official default install method: its git distribution lacks the build output (the entry file declared in package.json is not in the repository), so it has not been adapted to the official install flow. Please file an Issue on the author\'s repo asking for committed build output, a prebuilt release `.tgz` (`releases/download/<tag>/<asset>.tgz`), or a complete npm release.',
+  // Pre-install / post-install guard hit ([packaging]): git distribution lacks a file the package needs (entry / entry a patch mounts / bundle patch) = not adapted to the official default install method
+  failPackagingHint: 'This plugin does not support the official default install method: its git distribution lacks a file the package needs (the entry from `main` / `exports`, an entry its own patch mounts by name, or the patch declared by `dsh.bundle.patch`), so it has not been adapted to the official install flow. Please file an Issue on the author\'s repo asking for committed build output, a prebuilt release `.tgz` (`releases/download/<tag>/<asset>.tgz`), or a complete npm release.',
   // native-module build scripts ignored by pnpm by default (e.g. node-pty, ERR_PNPM_IGNORED_BUILDS): not a plugin-side issue on its own, route to the hub repo for triage
   failIgnoredBuild: 'This plugin (or its dependencies) needs to run build scripts, which pnpm blocks by default via its allowBuilds allowlist, so the install fails (e.g. native modules like node-pty, or the plugin\'s own prepare script on git installs). This is not necessarily the plugin itself (it may be caused by the hub falling back to a git install after npm lookup failed). Please report it to the Plugin Hub first; if it turns out to be a plugin dependency issue, the author can ship a prebuilt variant (e.g. node-pty-prebuilt-multiarch) or drop install-time builds.',
   failNpmTooLow: 'Your local npm may be too old: npm crashed internally while resolving the plugin\'s dependencies (a known npm bug — not a plugin issue). Please upgrade npm and retry: npm install -g npm@latest',