4 · DSH插件管理(打包 _ 安装 _ 层叠)

当前时间： 2026-08-28 00:00:05 分类：办公文件评论(0)

4 · DSH插件管理(打包 _ 安装 _ 层叠)

到上一篇为止，你的插件还只是本地一个用 --patch 挂进去的源码。真要让别人也能用，得把它打包成一个能 install 的东西。这一篇就干三件事：怎么打包、怎么装进 profile、装进去之后配置是怎么一层层叠起来的。

1. 先分清两个词：组合包 vs 档案

这俩名字第一次听很容易混，其实分工特别清楚——一个是你写的东西，一个是用户启动的东西：

概念	是什么	回答的问题
组合包 bundle	附带一个配置层的 npm 包	「这个包贡献什么插件？」
profile 档案	`DSH_HOME/cordis.patch.yml` （所有 profile 共享的机器偏好）每个 `--patch <path>` overlay（按命令行里出现的顺序） ⚠️ 两个推论，写 patch 时务必刻在脑子里：后应用的层按行胜出；而且 patch 是替换目标行的整个 `config` 值，不是深合并各键。所以你想覆盖某一行，必须把那一行需要的每个 key 都重述一遍，不能只写要改的那一个。 5. 从 GitHub 装：构建这道坎 `dsh plugin --profile demo add github:you/hello-plugin` 这条命令看着省事，其实有个坑：git 装拉的是源码，不是构建产物。整个流程里没有任何一步会跑你的 `build`，所以 TypeScript 写的包到手时没有 `lib/`，加载直接失败。要让它跑起来，作者和用户各做一件事： `allowBuilds: dsh-hello-plugin: true` 然后再跑一次 `add` 就行。 🔴 说句实在话，这条授权你得想清楚：`allowBuilds` 等于允许这个包的代码在你机器上、且不在 agent 沙箱里执行。所以只对源码信得过的包授权，并且锁 commit（`github:you/hello-plugin#<sha>`），免得别人之后悄悄 push 改了内容。不想让用户做这个授权，就发构建产物，两种方式都不需要构建权限：本篇小结下一篇：05-六个核心接口-v2 bundle 回答「贡献什么插件」，profile 回答「由哪些 bundle 组成」——一个你写，一个用户启动。装 / 卸都用 `dsh plugin --profile <name> add/remove`，本质是转发给 pnpm；`--dump-config` 用来验层。层叠顺序：bundles → profile patch → home → overlay；patch 是整行替换，不是深合并。 GitHub 安装的 `allowBuilds` 是「本机执行代码」授权，务必锁 commit；嫌麻烦就发 npm / tarball。发 npm ：`pnpm publish` 时把 `lib/` 构建好，用户 `dsh plugin add your-package` 装的就是预构建代码。发 tarball ：`pnpm pack` 打包，用户 `dsh plugin add ./hello-plugin-0.1.0.tgz`。作者：提供一个 `prepare` 脚本——pnpm 在 git 装完后会运行它，用它从源码构建出发布入口。注意要自包含，别假设旁边有一份 monorepo checkout（那种只有你开发机上有）。用户：给构建授权。pnpm ≥10 默认拒绝跑 git 依赖的 `prepare` 脚本，所以第一次 `add` 会失败。`dsh` 会告诉你怎么修——把 pnpm 打印的确切包键抄进该 profile 的 `pnpm-workspace.yaml`：