dsh-modpack · DSH 整合包

npm：https://www.npmjs.com/package/dsh-modpack · 仓库：https://github.com/M1r0er/dsh-modpack · MIT · DSH 插件（bundle）

像 Minecraft 的 PCL / HMCL 整合包那样管理 DSH 的第三方插件：

• 导出：勾选本机已安装的第三方插件 → 生成一个只有清单和版本的小体积 .dshpack.zip（不含插件代码、不含 node_modules），同时给出一整串可直接复制执行的安装命令。
• 导入：选择 .dshpack.zip 或直接粘贴命令串 → 先预览（已装同版本 / 版本不同 / 待安装 / 本地链接）→ 确认后再按 spec 重新下载安装；apply 前自动写 JSON 还原点。
• 发布：把几十 KB 的 zip 发给别人，对方在「设置 → 整合包 → 导入」里预览后一键装齐。
• 本地开发也能分享：本地 link: 插件只要已按同名同版本发布到 npm，导出时会自动转成 name@version；未发布的仍标记为不可分享。

导出的命令形如（示例，不会自动执行）：

dsh plugin --profile desktop add dsh-ops@0.3.0
dsh plugin --profile desktop add dsh-better-sidebar@0.28.0
dsh plugin --profile desktop add github:owner/repo#v1.0.0

为什么不是"备份插件"

DSH 已有若干备份/迁移工具（见 docs/RELATED.md），它们通常打包配置、凭据或本地插件目录，体积大、偏向"整机搬家"。 整合包的定位相反：只记录"装哪些插件、哪个版本"，插件本体在导入时从 npm / git 重新下载。这与 PCL 整合包"只有 mods 清单、不含游戏本体"是同一种取舍：

	备份 / 迁移工具	dsh-modpack
包内容	配置文件、凭据、可能含本地插件源码	清单 + 版本 + 安装命令（可选脱敏配置）
体积	几百 KB ~ 数 MB	通常几 KB ~ 几十 KB
适合	换电脑、回滚	发布、分享、复现一套插件组合
导入	覆盖配置	按 spec 重新下载插件，先预览再应用

同赛道还有一个更重的项目：@dsh-packforge/dsh-pack-plugin（.dspack）。它默认把 profile 配置与 pnpm-lock.yaml 一起打包，导入时用 pnpm 重建依赖，并绑定官方桌面端；其 README 自述 export / install 端到端仍需真实 pnpm 环境验证。dsh-modpack 选的是更轻的形态：只记录"装哪些插件、哪个版本"，并直接给出可复制的 dsh plugin add 命令串。完整对比见 docs/RELATED.md。

安装

在 DSH 里用插件管理器安装本目录（或发布后的 npm 包）：

dsh plugin add dsh-modpack

安装后：

• 设置 → 整合包：图形界面，勾选 / 导出 / 导入；
• 模型工具：modpack_list、modpack_export、modpack_inspect、modpack_import，也可以让 Agent 代劳。

本插件依赖 DSH 内置的 pluginManager 与 configEditor 服务。老版本 DSH 若没有 pluginManager，导出命令串仍可用，自动安装会报"服务不可用"。

图形界面

设置页分两块：

1. 导出
   • 列出当前 profile 的第三方 bundle（含版本、是否本地链接）；
   • 本地链接（link: / 本地路径）会按 name@version 查询 npm registry：已发布的自动升级为可分享项（标注「本机链接 · npm 已发布」），未发布的仍标注「不可分享」；
   • 未发布的本地插件可勾选**「内置」**：对该插件执行 npm pack，把插件代码以 tarball 写进整合包（见下文）；
   • 默认全选可安装项；
   • 可填名称 / 版本 / 作者 / 描述；
   • 可选"包含配置"：只收选中插件的 config override，疑似密钥默认替换为 ${REDACTED}；
   • 导出后显示 zip 路径与命令块，可一键复制。
2. 导入
   • 拖入 .dshpack.zip，或粘贴命令串；
   • 预览表逐条列出 spec 与状态 installed-same / installed-different / missing / local / unknown，内置条目带「内置」标记；
   • 点"应用安装"需二次确认；含内置插件时会额外提示"将执行包内第三方代码"；执行完显示每一步结果、还原点路径；需要重启的改动会单独提示。

命令行 / Agent 工具

// 列出可导出的插件
{ "tool": "modpack_list" }

// 导出（不写 zip，只拿命令串）
{ "tool": "modpack_export", "writeArchive": false, "include": ["dsh-ops", "dsh-context"] }

// 导出为 zip（默认写到 ~/.dsh/modpacks）
{ "tool": "modpack_export", "name": "我的整合包", "version": "1.0.0" }

// 把未发布 npm 的本地插件“内置”进包（对每个插件执行 npm pack）
{ "tool": "modpack_export", "include": ["dsh-local-x", "dsh-ops"], "embed": ["dsh-local-x"] }

// 导入预览（默认 apply=false，绝不安装）
{ "tool": "modpack_import", "path": "D:/packs/我的整合包-1.0.0.dshpack.zip" }

// 确认后应用；包里含内置插件时必须显式 allowEmbedded
{ "tool": "modpack_import", "path": "…", "apply": true, "allowEmbedded": true }

modpack_import 的安装动作走 pluginManager.installBundle(spec, { saveExact: true })，不执行 shell，也不执行粘贴文本里的任何命令——命令串只被解析成 spec。

内置插件（随包代码，可选）

有些插件只在本机开发、不打算发布 npm，仍想分享给朋友。此时可在导出面板勾选该插件的**「内置」**：

1. 对插件的本机目录执行 pnpm pack（尊重 package.json 的 files / .npmignore，排除 node_modules）；
2. 扫描包内文件名，含 .env、config.toml、credentials.*、私钥等疑似凭据时拒绝内置；
3. 把 tarball 写入 zip 的 embedded/<name>-<version>.tgz，并在 dshpack.json 记录 sha256 与 size；
4. 导入时校验 sha256/size 后落到 ~/.dsh/modpacks/embedded/，再交给 pluginManager.installBundle(tarball) 安装（走 DSH 自己的 pnpm 通道）。

⚠️ 内置 = 把第三方代码装进 profile。只分享/导入你信任的来源；导入应用前会再次确认，且必须显式 allowEmbedded: true（界面已在确认框里代填）。

内置插件若还有未发布的 npm 依赖，导入时 pnpm 会解析失败；v1 只保证“依赖都能从 registry 解析”的插件可内置。

.dshpack.zip 是一个普通 zip，内含：

文件	作用
dshpack.json	清单：format/version、插件列表（name、version、spec、kind、bundle 行）、安装命令、可选 config、内置 tarball 的 sha256/size
embedded/*.tgz	仅在选择“内置”时出现：随包携带的插件 tarball
install.ps1 / install.sh	与清单一致的安装命令脚本（内置插件不产生命令）
README.md	人类可读的说明

dshpack.json 关键字段见 API.md；format 固定为 dsh-modpack，当前 formatVersion 为 2（1 为无内置的旧格式，仍可导入）。导入时会校验格式版本，未来格式升级会给出明确提示。

安全

• 导出默认从不安装任何东西；列表会为本地链接插件向 npm registry 做一次只读版本查询（2s 超时，失败按未发布处理），可用 DSH_MODPACK_REGISTRY_CHECK=off 关闭。
• 导入默认只预览；apply:true 前会写 <outDir>/backups/before-import-<时间>.json。
• 默认包内不写插件代码；只有显式“内置”才会写入 tarball，并记录 sha256/size，导入时校验后才安装。
• config 默认不导出，导出时会剔除密钥键与 sk- / ghp_ / xoxb- 等明文 token。
• 本地链接插件（link: / 本地路径）只有同名同版本已发布到 npm 时才按 name@version 导出；否则可显式内置或标记不可分享，不会把别人的本地路径当成可下载 spec。
• 本插件的 HTTP 路由与 GUI 同源（/modpack/*），没有额外的跨域入口。

已知限制

• 只处理 bundle（dsh.profile.bundles / package.json 依赖）；随 DSH 发行的 installation 内置 bundle 不导出。
• 安装依赖目标机器能访问 npm / git，企业内网需要自行配置 registry。
• 版本对比是字符串精确比较；name@latest 这类浮动 spec 只能判断"已安装/未安装"。
• 不支持 zip64 / 加密 zip；整合包超过 32 MiB 会被拒绝（正常只有几 KB）。
• 配置导入（withConfig / 界面勾选）目前按 patchId 匹配本机行；行 id 被上游插件改名时会跳过并给出 reason。
• 内置插件版本随包冻结、不会自动更新；升级需重新导出/导入。内置依赖若未发布到 registry，pnpm 安装会失败。
• 内置 tarball 上限：单个 12 MiB、整体 24 MiB；超过会拒绝导出。

开发

node --check index.js
node tests/zip.test.mjs
node tests/pack.test.mjs
node tests/host.test.mjs   # 用 mock Cordis 服务跑导出→预览→apply 全链路

• lib/zip.mjs：零依赖 zip 读写（store/deflate、CRC32、UTF-8 文件名）。
• lib/pack.mjs：清单构建/校验、spec 分类、命令解析、密钥剔除、diff。
• index.js：Host 半，接 pluginManager / configEditor，注册工具与 /modpack/* 路由。
• client.js：设置页，注册到 settings.section。

验证状态

• 2026-10-20 v0.2.0 内置插件：真实 pnpm pack 冒烟通过——把 dsh-workspace-gate 目录打成 41.9 KiB tarball 写入 zip，清单为 formatVersion: 2、记录 sha256/size；导入端 mock 验证了 sha256 不符会拒绝、未带 allowEmbedded 会拒绝、内置 tarball 落到稳定目录后调用 installBundle(tarball)。
• 2026-10-20 v0.1.2 修复：Host 已把「本地链接但 npm 同版本已发布」的插件升级为可分享项，但 Client 的勾选判定仍残留 local === true → 不可选，导致这类插件显示「本机链接 · npm 已发布」却无法勾选。现已改为以 installable / published 为准，并补了回归测试（dsh-workspace-gate、dsh-inkvault 这类插件可直接勾选导出）。
• 2026-10-19 真机（DSH 0.2.1-rc.2 / Windows）：重启后设置页已注册（settings.section，id=modpack，order 45，active）；modpack_list 读到 15 个第三方插件；modpack_export 生成 5.0 KiB 整合包 / 13 条安装命令（2 个本地链接自动跳过）；modpack_inspect 预览结果为 13 已装同版本 + 2 本地链接跳过。
• 离线：22 项测试通过（zip 往返/CRC、命令解析、密钥剔除、本地链接升级、内置清单校验、mock Cordis 全链路、client 勾选判定），详见 docs/VERIFICATION.md。

License

MIT