dsh-modpack

dsh plugin --profile web add dsh-modpack

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](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](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](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 已把「本地链接但

…(truncated)