ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 照 Cookbook 新增包:拆包边界、导出面与依赖位置

插件开发发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH plugin新增 package拆包依赖管理
官方 Cookbook 的新增 package 不是多建一个目录,而是决定拆包边界、导出面和依赖位置。本文给三条拆包判据、package.json 的关键字段,以及依赖放 peer、dependencies 还是 devDependencies 的判断。

新增 package 不是「多建一个目录」,而是给一段代码划定发布与依赖边界。 官方 Cookbook 把这件事拆成三步:先判断该不该拆,再定导出面,最后放依赖(来源)。顺序反了,最常见的结果是「包建出来了,profile 却装不进去」或「装进去了,版本互相打架」。

DeepSeek Harness 什么时候该拆包

拆包的第一判据是「是否需要独立发布」,不是「文件是不是太多」。 下面三条任意一条成立,才值得新增 package(来源):

  1. 独立发布节奏 — 这部分需要单独发版,不想带着整个插件一起升级;
  2. 独立依赖面 — 它依赖一组别的包不需要的库,混在一起会让安装变重;
  3. 明确复用边界 — 多个插件要共用它,且不希望复制代码。

三条都不成立时,继续在现有包里加文件更便宜。拆包会增加 package.json、构建配置、版本约束和 profile 依赖图,这些都是长期成本。

反过来,三种情况不该拆:只是文件多、只是想让目录好看、只是「以后可能会复用」。前者是组织问题,后两者是猜测,不是边界。

拆包前先画一张依赖图:谁依赖谁、哪些是宿主提供、哪些是插件自带。图画不出来,说明边界还没想清楚,先别拆。

DeepSeek Harness package.json 的三个关键字段

新增包时,先看三个字段:name、exports、dsh。 它们分别决定「叫什么」「对外暴露什么」「在 Harness 里是什么角色」(来源)。

  • name — 包名要稳定,避免以后重命名;被 profile 与依赖图引用后,改名成本很高;
  • exports — 只暴露消费者真正需要的入口,不要把所有内部文件都导出去;
  • dsh — 声明包的角色,例如组合包的 patch 文件位置;没有这个字段,Harness 可能不知道如何加载它。

三个字段里,exports 最容易被写宽。把所有子路径都导出,短期方便,长期会把内部实现变成事实上的公共 API;一旦别人 import 了,你就不能随便改。

一个实用原则:先只导出根入口,等确有第二个消费者时再加子路径。导出面越小,重构越自由。

dsh 字段则要与包的职责一致。普通插件、组合包、客户端半侧的声明不同,写错不会立刻报错,但会在加载或挂载时表现为「包在,能力不在」。

DeepSeek Harness 导出面最小化

导出面是承诺,不是便利:每多一个导出,就多一个不能随意改的接口。 最小化导出面有三条做法(来源):

  1. 根入口只导出公共 API — 类型、注册函数、必要的常量;
  2. 内部模块不导出 — 通过相对路径 import 的内部文件,不要出现在 exports 里;
  3. 客户端半单独导出 — 浏览器半用 ./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、能注册能力」三段。 推荐四步(来源):

  1. 能 import — 在测试或示例里从导出面 import,确认运行时与类型都能解析;
  2. 能构建 — 跑包的构建,确认 exports 指向的产物真实存在;
  3. 能装进 profile — 在目标 profile 的依赖或组合包里出现,pnpm install 不报冲突;
  4. 能注册能力 — 启动后能看到该包提供的服务、工具或设置项。

只过第一步,是「代码能复用但没进运行时」;只过前三步,是「装进去了但没挂载」;四步都过,才算新增包完成。

旧文 develop-workspace-package 讲新包目录与验证,develop-plugin-bundle 讲组合包结构;本篇补的是官方 Cookbook 的拆包判据、导出面与依赖位置。三件事想清楚,包才不会越拆越乱。

拆包不是一次性的决定,新增前先问「不拆会怎样」;如果答案只是「文件多一点」,就先不拆。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 插件开发到什么时候应该新增一个 package,而不是继续加文件?

DeepSeek Harness 里,当代码有独立发布节奏、独立依赖面或明确复用边界时再拆包。DeepSeek Harness 的插件包会进入 profile 与依赖图,拆得太早会增加安装与版本负担,拆得太晚会让一个包承担多种职责。

DeepSeek Harness 的 package.json 里 exports 和 dsh 字段各管什么?

DeepSeek Harness 里,exports 决定外部能 import 哪些入口,dsh 字段声明这个包在 Harness 里的角色,例如组合包的 patch 文件。两者职责不同,不能用一个替代另一个。

DeepSeek Harness 插件依赖应该放 peerDependencies 还是 dependencies?

DeepSeek Harness 里,宿主提供的包放 peerDependencies,避免重复安装与版本冲突;插件自己运行必需的库放 dependencies;只在构建和测试时用的工具放 devDependencies。

DeepSeek Harness 新增包后,怎么确认它真的被 profile 用上了?

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

来源