DeepSeek Harness 照 Cookbook 新增包:拆包边界、导出面与依赖位置
新增 package 不是「多建一个目录」,而是给一段代码划定发布与依赖边界。 官方 Cookbook 把这件事拆成三步:先判断该不该拆,再定导出面,最后放依赖(来源)。顺序反了,最常见的结果是「包建出来了,profile 却装不进去」或「装进去了,版本互相打架」。
DeepSeek Harness 什么时候该拆包
拆包的第一判据是「是否需要独立发布」,不是「文件是不是太多」。 下面三条任意一条成立,才值得新增 package(来源):
- 独立发布节奏 — 这部分需要单独发版,不想带着整个插件一起升级;
- 独立依赖面 — 它依赖一组别的包不需要的库,混在一起会让安装变重;
- 明确复用边界 — 多个插件要共用它,且不希望复制代码。
三条都不成立时,继续在现有包里加文件更便宜。拆包会增加 package.json、构建配置、版本约束和 profile 依赖图,这些都是长期成本。
反过来,三种情况不该拆:只是文件多、只是想让目录好看、只是「以后可能会复用」。前者是组织问题,后两者是猜测,不是边界。
拆包前先画一张依赖图:谁依赖谁、哪些是宿主提供、哪些是插件自带。图画不出来,说明边界还没想清楚,先别拆。
DeepSeek Harness package.json 的三个关键字段
新增包时,先看三个字段:name、exports、dsh。 它们分别决定「叫什么」「对外暴露什么」「在 Harness 里是什么角色」(来源)。
- name — 包名要稳定,避免以后重命名;被 profile 与依赖图引用后,改名成本很高;
- exports — 只暴露消费者真正需要的入口,不要把所有内部文件都导出去;
- dsh — 声明包的角色,例如组合包的 patch 文件位置;没有这个字段,Harness 可能不知道如何加载它。
三个字段里,exports 最容易被写宽。把所有子路径都导出,短期方便,长期会把内部实现变成事实上的公共 API;一旦别人 import 了,你就不能随便改。
一个实用原则:先只导出根入口,等确有第二个消费者时再加子路径。导出面越小,重构越自由。
dsh 字段则要与包的职责一致。普通插件、组合包、客户端半侧的声明不同,写错不会立刻报错,但会在加载或挂载时表现为「包在,能力不在」。
DeepSeek Harness 导出面最小化
导出面是承诺,不是便利:每多一个导出,就多一个不能随意改的接口。 最小化导出面有三条做法(来源):
- 根入口只导出公共 API — 类型、注册函数、必要的常量;
- 内部模块不导出 — 通过相对路径 import 的内部文件,不要出现在 exports 里;
- 客户端半单独导出 — 浏览器半用
./client之类的明确入口,不和 Host 半混在一起。
导出面写宽以后,最典型的症状是「改一个内部函数,外部消费者挂了」。这不是消费者的问题,而是导出面把内部实现变成了公共契约。
还要注意类型导出。只导出运行时值、不导出类型,会让 TypeScript 消费者无法正确推导;只导出类型、不导出运行时入口,又会让运行时 import 失败。两者要成对设计。
如果包有多个入口,建议在 README 里写清每个入口的用途与稳定性等级。没有说明的入口,默认视为内部。
DeepSeek Harness 依赖放哪:peer、dependencies 还是 devDependencies
依赖位置错了,表现通常不是编译失败,而是运行时出现两份不同版本。 三类依赖的判断如下(来源):
| 依赖类型 | 放哪 | 判断标准 |
|---|---|---|
| 宿主提供的核心包 | peerDependencies | 必须与宿主同版本,不能自带一份 |
| 插件运行必需的库 | dependencies | 宿主不提供,插件自己需要 |
| 构建、测试、类型工具 | devDependencies | 只在开发期使用,不进运行时 |
核心包放 dependencies 是最常见的错误。它会让插件自带一份核心包,与宿主的那份冲突;表现可能是「服务注册了但找不到」,或「类型对、运行时不对」。
反过来,把运行时必需的库放 devDependencies,本地开发能跑,安装到 profile 后就缺依赖。判断方法很简单:这个 import 在用户机器上会不会执行?会,就不能只放 dev。
peerDependencies 还要写清版本范围。范围太宽,可能装到不兼容版本;范围太窄,又会阻止合理升级。范围应与宿主实际支持的版本对齐。
DeepSeek Harness 与组合包的关系
package 是代码单元,组合包是加载单元,两者不是一回事。 官方把组合包描述为 Cordis 配置项及其挂载代码的分发格式,通过 dsh.bundle 指向 patch 文件(来源)。
这意味着:
- 新增 package 不一定新增组合包 — 一个组合包可以挂载多个 package;
- 组合包决定「装什么」 — profile 通过组合包把能力装进树里;
- package 决定「怎么复用」 — 代码边界与依赖面在 package 层解决。
把两者混在一起,常见结果是「package 建好了,但 profile 没有加载它」。你需要在组合包的 patch 里把它挂上,或在 profile 的依赖里声明它。
如果只是给现有组合包加一个能力,优先在现有包里加,而不是新建 package 再新建组合包。每多一层,安装和排查都多一步。
DeepSeek Harness 验证:从引用到安装
验证新增包,要覆盖「能 import、能装进 profile、能注册能力」三段。 推荐四步(来源):
- 能 import — 在测试或示例里从导出面 import,确认运行时与类型都能解析;
- 能构建 — 跑包的构建,确认
exports指向的产物真实存在; - 能装进 profile — 在目标 profile 的依赖或组合包里出现,
pnpm install不报冲突; - 能注册能力 — 启动后能看到该包提供的服务、工具或设置项。
只过第一步,是「代码能复用但没进运行时」;只过前三步,是「装进去了但没挂载」;四步都过,才算新增包完成。
旧文 develop-workspace-package 讲新包目录与验证,develop-plugin-bundle 讲组合包结构;本篇补的是官方 Cookbook 的拆包判据、导出面与依赖位置。三件事想清楚,包才不会越拆越乱。
拆包不是一次性的决定,新增前先问「不拆会怎样」;如果答案只是「文件多一点」,就先不拆。
常见问题
DeepSeek Harness 里,当代码有独立发布节奏、独立依赖面或明确复用边界时再拆包。DeepSeek Harness 的插件包会进入 profile 与依赖图,拆得太早会增加安装与版本负担,拆得太晚会让一个包承担多种职责。
DeepSeek Harness 里,exports 决定外部能 import 哪些入口,dsh 字段声明这个包在 Harness 里的角色,例如组合包的 patch 文件。两者职责不同,不能用一个替代另一个。
DeepSeek Harness 里,宿主提供的包放 peerDependencies,避免重复安装与版本冲突;插件自己运行必需的库放 dependencies;只在构建和测试时用的工具放 devDependencies。
DeepSeek Harness 里,看三处:包能被目标入口 import,组合包或 profile 的依赖图里出现它,运行时注册的能力可见。只完成 pnpm install 不等于 profile 已经加载它。
相关术语
- package 边界
- package 边界是 DeepSeek Harness 插件代码的发布与依赖单元;一个包应有单一职责、稳定导出面和明确依赖范围。— DeepSeek Harness 官方文档 - 新增 Package
- exports
- exports 是 package.json 中声明外部可导入入口的字段,决定哪些文件与子路径对消费者可见。— DeepSeek Harness 官方文档 - 新增 Package
- dsh 字段
- dsh 字段是 DeepSeek Harness 识别包角色的声明,例如组合包通过它指向自己的 patch 文件。— DeepSeek Harness 官方文档 - 插件配置目录
- peerDependencies
- peerDependencies 是要求由宿主提供的依赖声明,用于避免同一个核心包被重复安装成多个版本。— DeepSeek Harness 官方文档 - 新增 Package
来源
- DeepSeek Harness 官方文档 - 新增 Package· deepseek-harness
- DeepSeek Harness 官方文档 - 插件配置目录· deepseek-harness