dsh-plugin-pack 0.0.0-stage → 1.0.2

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# dsh-plugin-pack bundle patch
+#
+# 只插一行：插件本体。
+#   - 宿主侧：工具 plugin_pack_*、/pack 命令、/plugin-pack/* HTTP 路由（lib/index.js + lib/server.js）
+#   - 客户端：插件页顶部「导入 / 导出」两个标签页 + 插件行详情 + 设置页（client.js）
+#   - 热加载：hotload.js，改完 client 代码或 package.json 不必重启（/pack hotload 或界面按钮）
+- insert:
+    - id: dsh-plugin-pack
+      name: dsh-plugin-pack
+      config:
+        enabled: true
+        # 空字符串 = $DSH_HOME/exports
+        exportDir: ''
+        # 默认不打包插件自己的数据目录（可能含 token）
+        includeData: false
+        # 默认剔除 .env / *.pem / credentials.json 之类
+        includeSecrets: false
+        # 体积上限，按**未压缩**字节算（压缩比约 1:3）。
+        # 默认 2 GiB 原始 ≈ 600~700 MiB 成品，够全量备份；界面里也能改，0 = 不限制。
+        maxBytes: 2147483648
+        # 导入时是否覆盖已存在的同 id patch 行
+        overwritePatchConfig: false
+        # 启动时自动把自己的客户端半身热加载一次（失败只记日志，不阻断）
+        selfHotload: true

package/hotload.js

@@ -0,0 +1,230 @@
+/**
+ * 客户端 bundle 热加载。
+ *
+ * 背景（读宿主 dsh-client-modules 源码得出的事实）：
+ *
+ *   1. 宿主启动时扫描 Loader 行 → 读 package.json → 判定 `dsh.client.platform === 'web'`
+ *      且 `exports["./client"]` 存在 → 才把包入表，之后 `/plugins/??<id>/client.js&rev=<hash>` 才有内容。
+ *   2. 判定结果（包括"不是客户端包"这种否定结论）缓存在 `pkgMeta: Map<sourceKey, meta|null>` 里，
+ *      **没有任何失效机制** —— `resolveMeta()` 命中缓存就直接返回，从不重读 package.json。
+ *      这就是为什么改了 package.json 也看不到界面，必须重启。
+ *   3. 唯一能把改动送进图表的是 `rebuilt(id)`，但它只在 `table` 里已有这个包时才有效。
+ *   4. `dirty: Set<entryName>` + `flush(onError)` 是重扫入口，`processOne` → `resolveSource`
+ *      → `resolveMeta` 会**再走一次**判定 —— 只要把缓存删掉，重扫就会读到新值。
+ *
+ * 所以热加载 = 删缓存 + 标记 dirty + flush，再对已入表的包走 rebuilt。
+ * 全部从宿主进程内部做，不需要重启。
+ *
+ * @module dsh-plugin-pack/hotload
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 宿主服务名。 */
+const SERVICE = 'clientModules';
+
+/**
+ * 从 ctx 里取出 clientModules 服务实例。
+ *
+ * 优先 ctx.get()，其次直接取属性 —— 不同 cordis 版本暴露方式略有差别。
+ *
+ * @param {object} ctx
+ * @returns {object|null}
+ */
+export function getRegistry(ctx) {
+  if (!ctx) return null;
+  try {
+    const viaGet = typeof ctx.get === 'function' ? ctx.get(SERVICE) : undefined;
+    if (viaGet) return viaGet;
+  } catch {
+    /* 服务不存在时 cordis 会抛 */
+  }
+  try {
+    const direct = ctx[SERVICE];
+    if (direct) return direct;
+  } catch {
+    /* 需要 inject 才能取属性 */
+  }
+  return null;
+}
+
+/** 一个 Loader 行的 name 是否属于这个包。 */
+function isRowOf(loaderName, packageName, packageDir) {
+  if (loaderName === packageName) return true;
+  // 路径形态的行（patch 里写死绝对路径的插件）
+  const normalized = String(loaderName).replace(/\\/g, '/');
+  const lowered = normalized.toLowerCase();
+  const dir = String(packageDir).replace(/\\/g, '/').toLowerCase();
+  if (!lowered.includes('/') && !lowered.includes(':')) return false;
+  return lowered === dir || lowered.startsWith(`${dir}/`);
+}
+
+/**
+ * 收集 registry 里所有和这个包相关的 sourceKey。
+ *
+ * pkgMeta 的 key 形如 `<baseUrl>\0<loaderName>`，所以要按 loaderName 匹配。
+ *
+ * @param {object} registry
+ * @param {string} packageName
+ * @param {string} packageDir
+ * @returns {{ sourceKeys: string[], loaderNames: string[] }}
+ */
+export function keysForPackage(registry, packageName, packageDir) {
+  const sourceKeys = [];
+  const loaderNames = new Set();
+  const meta = registry?.pkgMeta;
+  if (!(meta instanceof Map)) return { sourceKeys, loaderNames };
+
+  for (const key of meta.keys()) {
+    const raw = String(key);
+    const at = raw.indexOf('\0');
+    const loaderName = at >= 0 ? raw.slice(at + 1) : raw;
+    if (isRowOf(loaderName, packageName, packageDir)) {
+      sourceKeys.push(key);
+      loaderNames.add(loaderName);
+    }
+  }
+  return { sourceKeys, loaderNames: [...loaderNames] };
+}
+
+/**
+ * 让宿主重新扫描一个包，把改动送进客户端图表。
+ *
+ * @param {object} ctx cordis 上下文
+ * @param {object} options
+ * @param {string} options.packageName 包名（Loader 行 name 常见取值）
+ * @param {string} options.packageDir 包目录绝对路径（用于匹配路径形态的 Loader 行）
+ * @param {(msg: string) => void} [options.log]
+ * @returns {object} 结果
+ */
+export function reloadClientPackage(ctx, options = {}) {
+  const log = typeof options.log === 'function' ? options.log : () => {};
+  const packageName = String(options.packageName ?? '').trim();
+  const packageDir = String(options.packageDir ?? '').trim();
+  if (!packageName) return { ok: false, error: '需要 packageName' };
+
+  const registry = getRegistry(ctx);
+  if (!registry) {
+    return {
+      ok: false,
+      error: `宿主没有 ${SERVICE} 服务（可能不是 Web/桌面端，或版本不支持）`,
+    };
+  }
+
+  const steps = [];
+  const { sourceKeys, loaderNames } = keysForPackage(registry, packageName, packageDir);
+  steps.push(`匹配到 ${sourceKeys.length} 条缓存 / ${loaderNames.length} 个 Loader 行`);
+
+  // 1) 删掉否定缓存，让 resolveMeta 重读 package.json
+  if (registry.pkgMeta instanceof Map) {
+    for (const key of sourceKeys) registry.pkgMeta.delete(key);
+    steps.push(`已清除 pkgMeta 缓存 ${sourceKeys.length} 条`);
+  }
+
+  // 2) 标记 dirty：processOne 会重新走 resolveSource → resolveMeta
+  const names = loaderNames.length ? loaderNames : [packageName];
+  if (!(registry.dirty instanceof Set)) {
+    return { ok: false, error: 'registry.dirty 不是 Set，宿主版本不兼容' };
+  }
+  for (const name of names) registry.dirty.add(name);
+  steps.push(`已标记 dirty: ${names.join(', ')}`);
+
+  // 3) 触发重扫
+  const failures = [];
+  if (typeof registry.flush !== 'function') {
+    return { ok: false, error: 'registry.flush 不可用，宿主版本不兼容' };
+  }
+  registry.flush((error) => failures.push(String(error?.message ?? error)));
+  steps.push(`flush 完成，失败 ${failures.length} 条`);
+
+  // 4) 若已入表，走 rebuilt 让浏览器拿到新 rev
+  const inTable = registry.table instanceof Map ? registry.table.has(packageName) : false;
+  let rev = null;
+  if (inTable && typeof registry.rebuilt === 'function') {
+    rev = registry.rebuilt(packageName) ?? null;
+    steps.push(`rebuilt → rev=${rev}`);
+  } else {
+    steps.push('未入表（重扫可能失败，或 Loader 行不属于本包）');
+  }
+
+  for (const step of steps) log(step);
+
+  return {
+    ok: inTable,
+    packageName,
+    inTable,
+    rev,
+    clearedCaches: sourceKeys.length,
+    loaderNames: names,
+    failures,
+    steps,
+    error: inTable ? null : '重扫后仍不在图表里：检查 dsh.client.platform 是否为 web、exports["./client"] 是否存在、Loader 行 name 是否为包名',
+  };
+}
+
+/**
+ * 只读检查：这个包现在在宿主的客户端图表里吗？
+ *
+ * @param {object} ctx
+ * @param {string} packageName
+ * @returns {object}
+ */
+export function clientStatus(ctx, packageName) {
+  const registry = getRegistry(ctx);
+  if (!registry) return { available: false, reason: `没有 ${SERVICE} 服务` };
+  const inTable = registry.table instanceof Map ? registry.table.has(packageName) : false;
+  const record = inTable ? registry.table.get(packageName) : null;
+  const composed = registry.composed ?? null;
+  const rows = Array.isArray(composed?.entries) ? composed.entries : [];
+  const row = rows.find((item) => item.id === packageName) ?? null;
+  return {
+    available: true,
+    inTable,
+    rev: record?.entry?.rev ?? row?.rev ?? null,
+    clientPath: record?.meta?.clientPath ?? null,
+    inject: record?.meta?.inject ?? null,
+    immediately: record?.meta?.immediately ?? null,
+    bootstrapIds: composed?.bootstrapIds ?? [],
+    entries: rows.map((item) => item.id),
+  };
+}
+
+/**
+ * 直接读包自己的声明，判断"该不该"被宿主接受（不依赖宿主）。
+ *
+ * @param {string} packageDir
+ * @returns {object}
+ */
+export function localVerdict(packageDir) {
+  const pkgFile = path.join(packageDir, 'package.json');
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+  } catch (error) {
+    return { ok: false, error: `读 package.json 失败: ${error?.message ?? error}` };
+  }
+  const decl = pkg.dsh?.client;
+  if (!decl) return { ok: false, error: '没有 dsh.client 声明', name: pkg.name, version: pkg.version };
+  if (decl.platform !== 'web') return { ok: false, error: `platform=${decl.platform}，需要 web`, name: pkg.name };
+
+  let rel = pkg.exports?.['./client'];
+  if (rel && typeof rel === 'object') rel = rel.default ?? rel.import ?? rel.require;
+  if (typeof rel !== 'string') {
+    return { ok: false, error: 'exports 里没有 "./client"', name: pkg.name };
+  }
+  const clientPath = path.join(packageDir, rel.replace(/^\.\//, ''));
+  if (!fs.existsSync(clientPath)) {
+    return { ok: false, error: `client bundle 不存在: ${clientPath}`, name: pkg.name };
+  }
+  const stat = fs.statSync(clientPath);
+  return {
+    ok: true,
+    name: pkg.name,
+    version: pkg.version,
+    clientPath,
+    bytes: stat.size,
+    mtimeMs: stat.mtimeMs,
+    inject: decl.inject ?? [],
+    immediately: decl.immediately === true,
+  };
+}

package/lib/export.js

@@ -0,0 +1,444 @@
+/**
+ * 导出：把扫描到的插件连依赖打成 zip 整合包。
+ *
+ * 包内布局：
+ *   manifest.json
+ *   README.txt
+ *   packages/<插件名>/...                  插件本体
+ *   packages/<插件名>/node_modules/<依赖>/  扁平化的运行时依赖
+ *   data/<插件名>/<目录>/...                可选：插件数据
+ *
+ * @module dsh-plugin-pack/export
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { scanProfile } from './scan.js';
+import { writeZipStream } from './zip-stream.js';
+import { writeTgzStream } from './tar.js';
+import { dshHome as resolveDshHome, profileDir as resolveProfileDir, profileName as resolveProfileName, packSegment, stamp, humanBytes } from './home.js';
+import { walkTree, walkTreeAsync, SKIP_DIRS, fileFilter, ensureDir, removeTree } from './util.js';
+
+/** 新整合包格式：内部每个插件是一个 .tgz。 */
+export const PACK_FORMAT_V2 = 'dsh-plugin-pack@2';
+/** 旧格式：内部是散文件。 */
+export const PACK_FORMAT_V1 = 'dsh-plugin-pack@1';
+/** 写出的格式用 v2；导入端同时认 v1 和 v2。 */
+export const PACK_FORMAT = PACK_FORMAT_V2;
+export const GENERATOR = { name: 'dsh-plugin-pack', version: '1.0.0' };
+
+/**
+ * 生成整合包。
+ *
+ * @param {object} [options]
+ * @param {string} [options.out] 输出文件；目录则自动命名
+ * @param {string[]|null} [options.include]
+ * @param {string[]} [options.exclude]
+ * @param {boolean} [options.includeData]
+ * @param {boolean} [options.includeSecrets]
+ * @param {number} [options.maxBytes]
+ * @param {boolean} [options.dryRun]
+ * @param {(message: string) => void} [options.onProgress]
+ * @returns {Promise<object>} 导出报告
+ */
+export async function exportBundle(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.dshHome ? path.resolve(options.dshHome) : resolveDshHome(env);
+  const profile = options.profileDir ? path.resolve(options.profileDir) : resolveProfileDir(env);
+  const profileLabel = options.profileName ?? resolveProfileName(env);
+  const includeSecrets = Boolean(options.includeSecrets);
+  // maxBytes：显式传 0 = 不限制；没传才用默认值。
+  //
+  // 注意这个上限是按**未压缩**字节算的（写入时才知道真实压缩比），
+  // 而典型压缩比约 1:3 —— 实测 479 MiB 原始内容产出 166 MiB 的 zip。
+  // 所以默认给 2 GiB 原始体积（约 600~700 MiB 成品），
+  // 默认 512 MiB 会把正常的全量备份直接挡掉。
+  const maxBytes =
+    options.maxBytes === 0
+      ? Number.POSITIVE_INFINITY
+      : Number.isFinite(options.maxBytes) && options.maxBytes > 0
+        ? Math.floor(options.maxBytes)
+        : 2 * 1024 * 1024 * 1024;
+  const onProgress = typeof options.onProgress === 'function' ? options.onProgress : () => {};
+  const warnings = [];
+
+  const scan = await scanProfile({
+    env,
+    dshHome: home,
+    profileDir: profile,
+    profileName: profileLabel,
+    include: options.include ?? null,
+    exclude: options.exclude ?? [],
+    includeData: Boolean(options.includeData),
+    includeSecrets,
+    maxBytes,
+    // 导出要精确体积，不能用可能过期的缓存
+    fresh: true,
+  });
+  warnings.push(...scan.warnings);
+
+  const selected = scan.selected;
+  if (!selected.length) {
+    const error = new Error('没有可导出的插件：当前 profile 里没扫到第三方插件，或者 include/exclude 把它们全过滤掉了');
+    error.code = 'NO_PLUGINS';
+    throw error;
+  }
+
+  const createdAt = new Date();
+  const stampText = stamp(createdAt);
+  const manifest = {
+    format: PACK_FORMAT,
+    createdAt: createdAt.toISOString(),
+    generator: GENERATOR,
+    // v2：packages/ 下每个插件是一个独立 .tgz
+    layout: 'tarballs',
+    source: {
+      profile: profileLabel,
+      profileDir: profile,
+      dshHome: home,
+      dshVersion: readDshVersion(home),
+      platform: process.platform,
+      arch: process.arch,
+      node: process.version,
+    },
+    plugins: selected.map((plugin) => ({
+      name: plugin.name,
+      version: plugin.version,
+      // 打包完成后会回填成 packages/<包名>-<版本>.tgz
+      tgz: null,
+      description: plugin.description,
+      kind: plugin.kind,
+      sources: plugin.sources,
+      declaredName: plugin.declaredName,
+      link: plugin.link,
+      inBundles: plugin.inBundles,
+      bundleIndex: plugin.bundleIndex,
+      hasPatch: plugin.hasPatch,
+      patchRel: plugin.patchRel,
+      client: plugin.client,
+      entry: plugin.entry,
+      deps: plugin.deps.map((dep) => ({ name: dep.name, version: dep.version, bytes: dep.bytes })),
+      patchRows: plugin.patchRows,
+      insertRows: plugin.insertRows,
+      dataDirs: plugin.dataDirs.map((data) => ({ name: data.name, bytes: data.bytes, files: data.files })),
+      bytes: plugin.bytes,
+      fileCount: plugin.fileCount,
+      warnings: plugin.warnings,
+    })),
+    profile: {
+      bundles: scan.profile.bundles,
+      dependencies: scan.profile.dependencies,
+    },
+    warnings,
+  };
+
+  /** @type {Array<{name: string, file?: string, data?: Buffer|string}>} */
+  const entries = [];
+  let planned = 0;
+  const report = [];
+
+  /**
+   * 把一个插件打成 npm tarball 的 Buffer（异步）。
+   *
+   * 单个插件导出直接用这个结果；整合包则把它当成 zip 里的一个条目。
+   * 两者共用同一段逻辑，保证"单导出的 tgz"和"整合包里的 tgz"完全一致。
+   *
+   * @param {object} plugin scan 结果里的一个插件
+   * @returns {Promise<{ buffer: Buffer, bytes: number, files: number, deps: number, tgzName: string }>}
+   */
+  const buildPluginTarball = async (plugin) => {
+    const keepFile = fileFilter({ includeSecrets });
+    const skipDirs = new Set([...SKIP_DIRS, 'node_modules']);
+    /** @type {Array<{name: string}>} */
+    const tgzEntries = [];
+
+    const addToTgz = async (prefix, root) => {
+      let files = 0;
+      let bytes = 0;
+      for await (const item of walkTreeAsync(root, { skipDirs, keepFile })) {
+        planned += item.size;
+        if (planned > maxBytes) {
+          const error = new Error(
+            `整合包超过体积上限 ${humanBytes(maxBytes)}（已到 ${humanBytes(planned)}）。` +
+              `在导出页把「体积上限」调大、点「按当前选择自动调大」，或改成「不限制」；也可以只勾选部分插件。`,
+          );
+          error.code = 'TOO_LARGE';
+          throw error;
+        }
+        // npm tarball 的路径一律在 package/ 下
+        tgzEntries.push({ name: `package/${prefix ? `${prefix}/` : ''}${item.rel}`, file: item.path });
+        files += 1;
+        bytes += item.size;
+      }
+      return { files, bytes };
+    };
+
+    const main = await addToTgz('', plugin.dir);
+    for (const dep of plugin.deps) {
+      // 依赖目录必须用**真实包名结构**：@electron/get 要落成 node_modules/@electron/get/，
+      // 不能压成 @electron__get —— 那样 Node 的模块解析找不到它（ERR_MODULE_NOT_FOUND）。
+      // packSegment 只适合做"单层目录名"（如 local-plugins 下的插件目录），不能用在 node_modules。
+      await addToTgz(`node_modules/${dep.name}`, dep.dir);
+    }
+
+    // 写进临时文件再读回 —— writeTgzStream 是写盘接口，这里借一次
+    const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'dsh-pack-tgz-'));
+    const tmpFile = path.join(tmpDir, 'plugin.tgz');
+    try {
+      const result = await writeTgzStream(tgzEntries, tmpFile, { maxBytes: maxBytes * 4 });
+      const buffer = await fs.promises.readFile(tmpFile);
+      return {
+        buffer,
+        bytes: result.bytes,
+        files: main.files,
+        deps: plugin.deps.length,
+        tgzName: `${packSegment(plugin.name)}-${plugin.version}.tgz`,
+      };
+    } finally {
+      removeTree(tmpDir);
+    }
+  };
+
+  for (let index = 0; index < selected.length; index += 1) {
+    const plugin = selected[index];
+    const pluginSegment = packSegment(plugin.name);
+    const tarball = await buildPluginTarball(plugin);
+    onProgress(`已打包 ${plugin.name} → ${tarball.tgzName}（${humanBytes(tarball.bytes)}）`);
+
+    // 整合包内每个插件是一个独立的 .tgz，放在 packages/ 下
+    const tgzPath = `packages/${tarball.tgzName}`;
+    entries.push({ name: tgzPath, data: tarball.buffer });
+    // 回填 manifest 里的路径，导入端据此定位
+    manifest.plugins[index].tgz = tgzPath;
+    manifest.plugins[index].tgzBytes = tarball.bytes;
+
+    for (const data of plugin.dataDirs) {
+      const keepFile = fileFilter({ includeSecrets });
+      const skipDirs = new Set([...SKIP_DIRS, 'node_modules']);
+      for await (const item of walkTreeAsync(data.path, { skipDirs, keepFile })) {
+        planned += item.size;
+        if (planned > maxBytes) {
+          const error = new Error(`整合包超过体积上限 ${humanBytes(maxBytes)}（已到 ${humanBytes(planned)}）。`);
+          error.code = 'TOO_LARGE';
+          throw error;
+        }
+        entries.push({ name: `data/${pluginSegment}/${packSegment(data.name)}/${item.rel}`, file: item.path });
+      }
+    }
+
+    report.push({
+      name: plugin.name,
+      version: plugin.version,
+      kind: plugin.kind,
+      files: tarball.files,
+      bytes: tarball.bytes,
+      deps: tarball.deps,
+      patchRows: plugin.patchRows.length,
+      insertRows: plugin.insertRows.length,
+      dataDirs: plugin.dataDirs.length,
+      tgz: `packages/${tarball.tgzName}`,
+    });
+
+    // 单个插件导出：直接把这个 tarball 当成品
+    if (selected.length === 1) {
+      const outFile = resolveOutFile(options.out, home, profileLabel, stampText, {
+        kind: 'plugin',
+        pluginName: plugin.name,
+      });
+      if (options.dryRun) {
+        return {
+          ok: true,
+          dryRun: true,
+          kind: 'plugin',
+          file: outFile,
+          bytes: tarball.bytes,
+          entries: tarball.files,
+          plugins: report,
+          warnings,
+          manifest,
+        };
+      }
+      ensureDir(path.dirname(outFile));
+      await fs.promises.writeFile(outFile, tarball.buffer);
+      onProgress(`已写出 ${outFile}（${humanBytes(tarball.bytes)}）`);
+      return {
+        ok: true,
+        kind: 'plugin',
+        file: outFile,
+        bytes: tarball.bytes,
+        rawBytes: planned,
+        entries: tarball.files,
+        plugins: report,
+        warnings,
+        manifest,
+      };
+    }
+  }
+
+  /* 走到这里一定是多个插件 → 整合包（.zip）。
+   * 单个插件已在上面循环里直接返回 .tgz 了。
+   *
+   * 整合包里的每个插件是一个独立的 .tgz（packages/<包名>-<版本>.tgz），
+   * 这样：
+   *   - 包内结构对人是可读的（一眼看出有哪些插件、各自多大）
+   *   - 导入时可以只解自己要的那几个
+   *   - 单个 tgz 抽出来就能直接 npm i，与单独导出的文件完全等价
+   */
+  const outFile = resolveOutFile(options.out, home, profileLabel, stampText, { kind: 'bundle' });
+
+  const readme = renderReadme(manifest, report, createdAt);
+  const head = [
+    { name: 'manifest.json', data: `${JSON.stringify(manifest, null, 2)}\n` },
+    { name: 'README.txt', data: readme },
+  ];
+
+  if (options.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      kind: 'bundle',
+      file: outFile,
+      bytes: head.reduce((sum, entry) => sum + Buffer.byteLength(entry.data), 0) + planned,
+      entries: entries.length + head.length,
+      plugins: report,
+      warnings,
+      manifest,
+    };
+  }
+
+  ensureDir(path.dirname(outFile));
+
+  let progressBytes = 0;
+  const result = await writeZipStream([...head, ...entries], outFile, {
+    maxBytes: maxBytes * 4, // 压缩前的原始总量上限
+    onEntry: (name, bytes) => {
+      progressBytes += bytes;
+      if (progressBytes > 0 && progressBytes % (32 * 1024 * 1024) < bytes) {
+        onProgress(`已写入 ${humanBytes(progressBytes)} / ${humanBytes(planned)}`);
+      }
+    },
+  });
+  onProgress(`已写出 ${outFile}（${humanBytes(result.bytes)}）`);
+
+  return {
+    ok: true,
+    kind: 'bundle',
+    file: outFile,
+    bytes: result.bytes,
+    rawBytes: planned,
+    entries: result.entries,
+    plugins: report,
+    warnings,
+    manifest,
+  };
+}
+
+/**
+ * 解析输出路径；传目录时自动生成文件名。
+ *
+ * 三条规则按顺序：
+ *   1. 空 → $DSH_HOME/exports/<默认名>
+ *   2. 是已存在的目录，或字符串以分隔符结尾 → 当成目录，拼默认文件名
+ *   3. 已带正确扩展名 → 原样；否则补扩展名
+ *
+ * 扩展名跟着导出类型走：
+ *   - 单个插件 → .tgz（npm tarball，包名化文件名）
+ *   - 多个插件 → .zip（整合包）
+ *
+ * @param {string} raw
+ * @param {string} home
+ * @param {string} profileLabel
+ * @param {string} stampText
+ * @param {{ kind?: 'plugin'|'bundle', pluginName?: string }} [options]
+ */
+export function resolveOutFile(raw, home, profileLabel, stampText, options = {}) {
+  const kind = options.kind === 'plugin' ? 'plugin' : 'bundle';
+  const ext = kind === 'plugin' ? '.tgz' : '.zip';
+  const fallbackName =
+    kind === 'plugin'
+      ? // npm tarball 惯例用「包名-版本」或「包名-时间戳」，这里用包名 + 时间戳便于区分
+        `${slugForFile(options.pluginName ?? 'plugin')}-${stampText}.tgz`
+      : `dsh-plugin-pack-${profileLabel}-${stampText}.zip`;
+
+  if (!raw || !String(raw).trim()) {
+    return path.join(home, 'exports', fallbackName);
+  }
+  const text = String(raw).trim();
+  const target = path.resolve(text);
+  let stat = null;
+  try {
+    stat = fs.statSync(target);
+  } catch {
+    stat = null;
+  }
+  if (stat?.isDirectory()) return path.join(target, fallbackName);
+  // 末尾带分隔符：用户明确指了"这个目录"，即使它还不存在
+  if (/[\\/]$/.test(text)) return path.join(target, fallbackName);
+  if (stat?.isFile()) return target;
+  // 已经带了本类型该有的扩展名就原样；否则补上
+  if (target.toLowerCase().endsWith(ext)) return target;
+  // 用户明确写成了另一种扩展名（比如单插件却写了 .zip）→ 尊重用户选择
+  if (kind === 'plugin' && target.toLowerCase().endsWith('.zip')) return target;
+  if (kind === 'bundle' && target.toLowerCase().endsWith('.tgz')) return target;
+  return `${target}${ext}`;
+}
+
+/** 文件名里安全的包名（scoped 包把 / 换成 --）。 */
+function slugForFile(name) {
+  return (
+    String(name ?? '')
+      .replace(/^@/, '')
+      .replace(/[\\/:*?"<>|\u0000-\u001f]/g, '-')
+      .replace(/\s+/g, '-')
+      .slice(0, 80) || 'plugin'
+  );
+}
+
+/** 读 dsh 版本（有就读，没有就空）。 */
+function readDshVersion(home) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(home, 'version.json'), 'utf8'));
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** 包内 README。 */
+function renderReadme(manifest, report, createdAt) {
+  const lines = [
+    'dsh-plugin-pack 整合包（v2 布局）',
+    '===============================',
+    '',
+    `生成时间: ${createdAt.toISOString()}`,
+    `来源 profile: ${manifest.source.profile}`,
+    `来源目录: ${manifest.source.profileDir}`,
+    `插件数量: ${report.length}`,
+    '',
+    '包内结构:',
+    '  manifest.json            插件清单与配置',
+    '  packages/<包名>-<版本>.tgz  每个插件一个 npm tarball',
+    '  data/...                 可选，插件数据目录',
+    '',
+    '每个 .tgz 都是标准的 npm 包（package/ 前缀），可以单独取出来用：',
+    '  npm i ./packages/<包名>-<版本>.tgz',
+    '',
+    '插件清单:',
+    ...report.map(
+      (item) =>
+        `  - ${item.name}@${item.version}  ${humanBytes(item.bytes)} / 依赖 ${item.deps} 个${item.tgz ? `  → ${item.tgz}` : ''}`,
+    ),
+    '',
+    '导入方式（任选一种）:',
+    '  1. dsh 里拖进「插件 → 导入」的框',
+    '  2. 命令行:      dsh-plugin-pack import <这个 zip 的路径>',
+    '  3. 让 agent 调用: plugin_pack_import({ file: "<路径>" })',
+    '',
+    '整包和单个 .tgz 都能导入：拖 zip 是装整批，拖 tgz 是只装那一个。',
+    '导入会先把 package.json 和 cordis.patch.yml 备份到 profile 的 .plugin-backups/ 下，',
+    '然后把插件落到 local-plugins/ 并写回 profile 配置。导入完成后重启 dsh 生效。',
+    '',
+  ];
+  return `${lines.join('\n')}\n`;
+}