dsh-plugin 1.6.5 → 1.6.7

package/lib/http/settings.js

@@ -0,0 +1,77 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Settings routes: read/write the hub settings and reset them to defaults.
+ */
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadSettings, saveSettings, resetSettings } from '../services/settings.js';
+import { appendLog, customLogFile } from '../services/log.js';
+import { readJsonBody, requireTrustedPost, sendJson } from './shared.js';
+export function registerSettingsRoutes(webServer, profile) {
+    return [
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/settings',
+            // GET 读 / POST 写：webServer.register 按 (kind, path) 唯一，多方法必须合并到同一个 handler 按 method 分派
+            handler: async (request, response) => {
+                if (request.method === 'GET') {
+                    sendJson(response, 200, loadSettings(profile));
+                    return;
+                }
+                if (!requireTrustedPost(request, response))
+                    return;
+                try {
+                    const body = await readJsonBody(request);
+                    // 白名单字段：只接受已知设置项，防客户端把任意键写进文件
+                    const patch = {};
+                    const source = typeof body === 'object' && body !== null ? body : {};
+                    for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'enableGitInstall', 'enableDshInstall', 'npmRegistry', 'proxy', 'logPath']) {
+                        if (source[key] !== undefined)
+                            patch[key] = source[key];
+                    }
+                    // 日志位置：非空时预建目录验证可写，失败直接 400 拦截（默认位置永远合法，空串 = 回默认）
+                    if (typeof patch.logPath === 'string' && patch.logPath.trim() !== '') {
+                        try {
+                            mkdirSync(dirname(customLogFile(patch.logPath)), { recursive: true });
+                        }
+                        catch {
+                            sendJson(response, 400, { error: 'log path is not writable' });
+                            return;
+                        }
+                    }
+                    sendJson(response, 200, saveSettings(profile, patch));
+                    // 系统日志：设置项变更
+                    appendLog(profile, {
+                        at: Date.now(),
+                        level: 'info',
+                        category: 'settings',
+                        event: 'settings.update',
+                        message: `更新设置：${Object.keys(patch).join(', ')}`,
+                    });
+                }
+                catch (error) {
+                    sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/settings/reset',
+            handler: async (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                sendJson(response, 200, resetSettings(profile));
+                appendLog(profile, {
+                    at: Date.now(),
+                    level: 'warn',
+                    category: 'settings',
+                    event: 'settings.reset',
+                    message: '恢复全部默认设置',
+                });
+            },
+        },
+    ];
+}

package/lib/http/shared.js

@@ -0,0 +1,169 @@
+/**
+ * 跨平台宿主重启脚本（以 `node -e` 运行，独立于宿主进程）。
+ * 不用 `/bin/sh -c`：Windows 无 /bin/sh，且 lsof/nohup 仅 POSIX 存在。
+ * 由 `spawn(process.execPath, ['-e', SCRIPT, port], { detached, stdio:'ignore' })` 孵化，
+ * 宿主进程被 kill 后仍能完成「停旧 → 等端口释放 → 拉起新 dsh web」。
+ * 端口探测不到监听进程时不再假装重启（记一行日志后退出，见脚本内注释）。
+ */
+export const HOST_RESTART_SCRIPT = String.raw `const C = require('node:child_process')
+const F = require('node:fs')
+const P = require('node:path')
+const O = require('node:os')
+const win = process.platform === 'win32'
+const port = Number(process.argv[1])
+
+function findPids() {
+  if (win) {
+    const out = C.spawnSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf8' })
+    const found = []
+    for (const line of String(out.stdout || '').split(/\r?\n/)) {
+      if (!/LISTENING/i.test(line)) continue
+      const parts = line.trim().split(/\s+/)
+      const addr = parts[1] || ''
+      if (!addr.endsWith(':' + port)) continue
+      const pid = parts[parts.length - 1]
+      if (pid && /\d+/.test(pid)) found.push(pid)
+    }
+    return found
+  }
+  const out = C.spawnSync('lsof', ['-ti', 'tcp:' + port, '-sTCP:LISTEN'], { encoding: 'utf8' })
+  return String(out.stdout || '').split(/\s+/).filter(Boolean)
+}
+
+const targets = findPids()
+// 一个监听进程都没找到 = 端口探测本身就失败了（netstat 输出格式 / 本地化差异），
+// 旧宿主仍占着端口。此时再拉一个 dsh web 只会在日志里以 EADDRINUSE 静默退出，
+// 用户却看到「重启完成」——不制造这种假象，留一行可诊断的记录后退出。
+if (targets.length === 0) {
+  logLine('restart aborted: no listener found on port ' + port)
+  process.exit(0)
+}
+
+for (const pid of targets) {
+  try {
+    if (win) C.spawnSync('taskkill', ['/pid', pid, '/t', '/f'])
+    else process.kill(Number(pid), 'SIGTERM')
+  } catch {}
+}
+
+let tries = 0
+;(function waitForStop() {
+  if (findPids().length === 0 || ++tries > 20) return startHost()
+  setTimeout(waitForStop, 250)
+})()
+
+function logLine(msg) {
+  try {
+    const dir = P.join(O.homedir(), '.dsh', 'logs')
+    F.mkdirSync(dir, { recursive: true })
+    F.appendFileSync(P.join(dir, 'dsh-web-' + port + '.log'), '[' + new Date().toISOString() + '] ' + msg + '\n')
+  } catch {}
+}
+
+function startHost() {
+  const dir = P.join(O.homedir(), '.dsh', 'logs')
+  F.mkdirSync(dir, { recursive: true })
+  const fd = F.openSync(P.join(dir, 'dsh-web-' + port + '.log'), 'a')
+  const child = C.spawn('dsh', ['web', '--port', String(port)], {
+    detached: true,
+    shell: win,
+    stdio: ['ignore', fd, fd],
+  })
+  child.unref()
+}`;
+/**
+ * 宿主是否由桌面应用壳托管（`ELECTRON_RUN_AS_NODE=1`：壳用 Electron 二进制以 Node 模式跑宿主）。
+ * 桌面端的宿主归应用壳管，插件重启不了它，也不该去 kill —— 详见 /restart 路由。
+ */
+export function isDesktopHost() {
+    return process.env.ELECTRON_RUN_AS_NODE === '1';
+}
+export const PROFILE_RE = /^[A-Za-z0-9_-]+$/;
+const BODY_LIMIT_BYTES = 4 * 1024;
+export const COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
+/** 目录/统计数据代理的本地缓存时长：1 小时内重复打开插件市场直接读盘，
+ *  不重复走 curl 拉远程 —— 重启宿主后首次打开同样秒开（缓存跨重启存活）。 */
+export const CATALOG_CACHE_TTL_MS = 60 * 60 * 1000;
+export function sendJson(response, status, value) {
+    response.writeHead(status, {
+        'cache-control': 'no-store',
+        'content-type': 'application/json; charset=utf-8',
+    });
+    response.end(JSON.stringify(value));
+}
+/** 本机回环主机名：`localhost` / `127.0.0.1` / `[::1]` 指向同一台机器的同一个端口，
+ *  字符串不同但同源，必须按同一来源比较。 */
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** 把 `host[:port]` 形式的 authority 归一化成 `loopback:端口` —— 三个回环别名
+ *  映射成同一个身份，端口缺省按 http 的 80 补齐；非回环主机名、以及解析不出来的值
+ *  都返回 null。 */
+function loopbackAuthority(authority) {
+    try {
+        const parsed = new URL(`http://${authority}`);
+        if (!LOOPBACK_HOSTNAMES.has(parsed.hostname.toLowerCase()))
+            return null;
+        return `loopback:${parsed.port === '' ? '80' : parsed.port}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** POST mutations are only accepted from the local web server origin or the desktop host page.
+ *  Exported for tests (tests/routes.test.ts) — the origin check is the whole CSRF defence. */
+export function isSameOrigin(request) {
+    // 服务只绑定本机回环地址：Host 不是回环（局域网 IP、被改写的域名）一律拒绝，
+    // 顺带挡掉 DNS rebinding（Host 是攻击者域名，即便解析到 127.0.0.1）。
+    const host = request.headers.host;
+    const hostKey = host === undefined ? null : loopbackAuthority(host);
+    if (hostKey === null)
+        return false;
+    const origin = request.headers.origin;
+    // 桌面端宿主把 `/dsh-plugin-hub/*` 转发给本地 http server 时可能不带 Origin 头，
+    // 此时所有 POST 都会被判成 untrusted origin。浏览器对 POST 请求
+    // 必定携带 Origin（含同源 POST 与跨站表单），能省略该头的只有本机原生客户端，
+    // 而它们本来就能伪造任意 Origin，因此放行不扩大 CSRF 面。
+    if (origin === undefined || origin === '')
+        return true;
+    try {
+        const url = new URL(origin);
+        // 桌面端（Electron 宿主）的页面跑在宿主自定义协议下，origin 形如 `dsh-app://app`，
+        // 与 Host（如 localhost:3081）必然不等，因此必须显式放行该协议，否则桌面端全部 POST
+        // 都会被判成 untrusted origin。该协议只有宿主自身能产生，外部网页无法把 Origin
+        // 伪造成 `dsh-app://…`，放行不扩大 CSRF 面。
+        if (url.protocol === 'dsh-app:')
+            return true;
+        // 按归一化后的「主机名:端口」比较：`localhost` / `127.0.0.1` / `[::1]` 不再互相拒绝，
+        // 端口仍然必须一致（另一个本机进程不能被当成同一来源）。
+        return loopbackAuthority(url.host) === hostKey;
+    }
+    catch {
+        return false;
+    }
+}
+export function requireMethod(request, response, method) {
+    if (request.method === method)
+        return true;
+    response.writeHead(405, { allow: method });
+    response.end();
+    return false;
+}
+export function requireTrustedPost(request, response) {
+    if (!requireMethod(request, response, 'POST'))
+        return false;
+    if (isSameOrigin(request))
+        return true;
+    sendJson(response, 403, { error: 'untrusted origin' });
+    return false;
+}
+export async function readJsonBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > BODY_LIMIT_BYTES)
+            throw new Error('request body too large');
+        chunks.push(buffer);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}

package/lib/http/task.js

@@ -0,0 +1,208 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Task/misc routes: task polling, host restart, loader-entry debugging, and
+ * the installed-plugin inventory the client uses to reconcile its list.
+ */
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubTarget, listPendingRestarts, validPackageName } from '../services/install/install.js';
+import { readInstalledVersions, recordInstalledVersion, removeInstalledVersion } from '../services/profile/installed-versions.js';
+import { isDshPlugin, isEntryLoaded } from '../services/loader.js';
+import { profileDirectory, readInstalled } from './catalog.js';
+import { hostEnv } from './diagnostics.js';
+import { HOST_RESTART_SCRIPT, isDesktopHost, readJsonBody, requireMethod, requireTrustedPost, sendJson } from './shared.js';
+export function registerTaskRoutes(webServer, profile, loader) {
+    return [
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/debug/loader-entries',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                sendJson(response, 200, { entries: dumpLoaderEntries(loader) });
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/status',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                const url = new URL(request.url ?? '/', 'http://localhost');
+                const id = Number(url.searchParams.get('task'));
+                const task = Number.isInteger(id) ? getTask(id) : undefined;
+                if (!task) {
+                    sendJson(response, 404, { error: 'task not found' });
+                    return;
+                }
+                sendJson(response, 200, { task });
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/active',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                // 整个任务队列（running 在前、pending 在后）+ 待重启列表：客户端刷新后据此恢复
+                // 进行中/排队任务与「装完没重启」的持久提醒
+                sendJson(response, 200, { tasks: activeTask(), pendingRestarts: listPendingRestarts() });
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/env',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                // 宿主机器环境快照：提交 bug 的 issue 正文会带上，便于作者复现
+                sendJson(response, 200, hostEnv(profile));
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/cancel',
+            handler: async (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                try {
+                    const body = await readJsonBody(request);
+                    const id = typeof body === 'object' && body !== null && typeof body.id === 'number'
+                        ? body.id
+                        : NaN;
+                    const ok = Number.isInteger(id) && cancelTask(id);
+                    sendJson(response, 200, { ok });
+                }
+                catch (error) {
+                    sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/restart',
+            handler: (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                // 桌面端：宿主由应用壳托管，插件重启不了它。Windows 上 `taskkill /T` 会把发起
+                // 重启的助手一起结束（助手是宿主的子进程），壳再把这次外部 kill 判成宿主崩溃
+                // 弹「应用无法启动或已意外停止」；退一步说，脱离壳拉起的 `dsh web` 也服务不了
+                // 桌面 UI（缺壳注入的 desktop:boot）。故不 kill、不拉新宿主，由客户端改提示
+                // 用户从菜单/托盘退出后重新打开。
+                if (isDesktopHost()) {
+                    sendJson(response, 200, { ok: false, desktop: true });
+                    return;
+                }
+                // 当前宿主监听端口来自请求 Host 头（localhost:7923），解析失败回退 7923
+                const host = request.headers.host ?? '';
+                const portMatch = host.match(/:(\d+)$/);
+                const port = portMatch ? Number(portMatch[1]) : 7923;
+                // detached 子进程完成「停旧进程 → 等端口释放 → 后台拉起 dsh web」，
+                // 即使当前宿主（即本插件所在进程）被 kill，重启仍会继续执行。
+                // 不用 /bin/sh：Windows 无此路径，且 lsof/nohup 等仅 POSIX 存在，
+                // 故孵化 node(process.execPath) 跑跨平台脚本 —— Windows 用
+                // netstat + taskkill + shell:true 解析 dsh.cmd，POSIX 用 lsof + SIGTERM。
+                spawn(process.execPath, ['-e', HOST_RESTART_SCRIPT, String(port)], { detached: true, stdio: 'ignore' }).unref();
+                sendJson(response, 200, { ok: true, port });
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/installed-version',
+            handler: async (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                try {
+                    const body = await readJsonBody(request);
+                    const repo = typeof body === 'object' && body !== null && typeof body.repo === 'string'
+                        ? body.repo
+                        : '';
+                    if (githubTarget(repo) === null) {
+                        sendJson(response, 400, { error: 'invalid install target' });
+                        return;
+                    }
+                    // version 为空 = 卸载清理记录；否则记录安装时的目录信号（最新版本 + 仓库更新时间），
+                    // 供「有更新」比对：有版本比版本，无版本比更新时间
+                    const version = body !== null && typeof body.version === 'string'
+                        ? body.version
+                        : null;
+                    if (version === null) {
+                        removeInstalledVersion(profile, repo);
+                    }
+                    else {
+                        const updatedAt = body !== null && typeof body.updatedAt === 'string'
+                            ? body.updatedAt
+                            : '';
+                        recordInstalledVersion(profile, repo, version, updatedAt);
+                    }
+                    sendJson(response, 200, { ok: true });
+                }
+                catch (error) {
+                    sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/open-path',
+            handler: async (request, response) => {
+                if (!requireTrustedPost(request, response))
+                    return;
+                // 在系统文件管理器里定位并打开已安装插件目录（详情视图「在文件夹中显示」）。
+                // 只接受已安装依赖的包名、服务端自行拼接路径——杜绝任意路径注入
+                try {
+                    const body = await readJsonBody(request);
+                    const name = typeof body === 'object' && body !== null && typeof body.name === 'string'
+                        ? body.name
+                        : '';
+                    if (!validPackageName(name) || readInstalled(profile)[name] === undefined) {
+                        sendJson(response, 400, { error: 'plugin is not installed' });
+                        return;
+                    }
+                    const dir = join(profileDirectory(profile), 'node_modules', name);
+                    // macOS Finder 用 -R 定位选中；Windows explorer 用 /select,；Linux 打开目录（xdg-open）
+                    const bin = process.platform === 'darwin' ? 'open'
+                        : process.platform === 'win32' ? 'explorer'
+                            : 'xdg-open';
+                    const args = process.platform === 'darwin' ? ['-R', dir]
+                        : process.platform === 'win32' ? ['/select,', dir]
+                            : [dir];
+                    spawn(bin, args, { detached: true, stdio: 'ignore' }).unref();
+                    sendJson(response, 200, { ok: true });
+                }
+                catch (error) {
+                    sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: '/dsh-plugin-hub/installed',
+            handler: (request, response) => {
+                if (!requireMethod(request, response, 'GET'))
+                    return;
+                // installed：依赖表（包名 → spec）；versions：安装时记录的目录版本（repo → 版本）；
+                // paths：每个依赖在系统上的安装目录（profile/node_modules/<包名>），详情视图展示用；
+                // loaded：已加载进运行中 loader 的包名（官方 ctx.loader.entries()，未重启装的新插件不在其中）；
+                // dshCapable：真正的 dsh 插件（包内声明 dsh 配置 / 在 profile bundles 清单）——
+                //   非 dsh 插件（如 GitHub 官方示例仓库）装上也不会被宿主加载，客户端据此不再提示「待重启」。
+                // 客户端合并这些判断「是否有更新」「运行状态」并展示安装路径/时间等运行时信息。
+                const installed = readInstalled(profile);
+                const paths = {};
+                const loaded = [];
+                const dshCapable = [];
+                for (const name of Object.keys(installed)) {
+                    paths[name] = join(profileDirectory(profile), 'node_modules', name);
+                    if (isEntryLoaded(loader, name))
+                        loaded.push(name);
+                    if (isDshPlugin(profile, name))
+                        dshCapable.push(name);
+                }
+                sendJson(response, 200, { profile, installed, versions: readInstalledVersions(profile), paths, loaded, dshCapable });
+            },
+        },
+    ];
+}

package/lib/services/install/install.js

@@ -1,4 +1,4 @@
 export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../profile/pending-restart.js';
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.js';
-export { addAllowBuildsKey, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName } from '../profile/profile.js';
+export { addAllowBuildsKey, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName, } from '../profile/profile.js';
 export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.js';

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;
     }
 }