【DeepSeek Harness 插件开发入门】从一行 cordis.yml 到可发布的能力(开发篇)

点击蓝字|关注我们

在 dsh 中扩展功能的唯一方式就是写插件。插件有两种导出形态：函数插件具名导出 name、inject、Config 与 apply，且没有默认导出；服务插件（Cordis Service 子类）默认导出服务类。两种形态混用会让加载器丢弃函数插件的命名空间，必须二选一。

函数插件的 apply(ctx, config) 是唯一的执行入口，inject 声明对既有服务的依赖，Config 是可验证的配置类型；服务插件则用类承载服务实现并注册到上下文。所有包的 npm scope 统一为 @deepseek-ai/dsh-*。

以下是一个示意性的最小函数插件（向既有能力接缝注册本地提供方）：

注：以上为结构示意；实际的服务方法、事件与配置以对应服务定义的 JSDoc 与子系统文档为准。

挂载它只需要在 cordis.yml 中加一行。配置字段中的表达式用 !!js 标记（不是 !js），入口可以用 disabled 关闭；其余元数据保持字面量，条件组合使用叠加层实现。

（1）注册即 effect

每个贡献都通过 ctx.effect() 或 ctx.on() 完成；注册表的 register() 返回 disposer，插件卸载时自动回收。这是热替换安全（HMR）的基础：释放 fiber 之后必须能观察到注册被移除。

（2）瀑布监听必须调用 next()

ctx.waterfall() 链条中的监听器只有调用 next() 才委托给下一环节；返回而不调用会短路整条链。

（3）开关判断使用判别标签

闭合联合以 assertNever 收尾；可扩展联合则在文档化的默认分支中落空。

新增能力遵循接缝模式，而不是把功能焊死在某个插件里：服务定义声明契约，提供方给出实现，消费者把它变成模型可见的工具、命令或界面。三者分离之后，本地文件系统可以换成 E2B 沙箱，模型面前的工具却一个都不用改。

依赖方向不可逆：扩展插件依赖服务定义，绝不依赖具体提供方；界面、钩子与工具插件依赖 dsh-agent 抽象，因此代理循环可以整体替换。组合 bundle 可以依赖脊梁插件。

包位于 packages/<组>/<包>/，沿用仓库统一约束：

src/types.ts 只放类型，不放运行时代码；测试放在包级 tests/ 目录。

tsconfig 继承 tsconfig.base.json，使用 rootDir: src、outDir: lib/types，并引用全部工作区依赖。

README 与 JSDoc 属于变更的一部分：配置键、默认值、错误码、线缆字段的变化必须同提交更新。

每个包自带 ./invariant 运行时不变量检查；模型可见插件的 README 记录 Model Experience（令牌与 KV 缓存影响）。

裸插件必须出现在其解析器 manifest 的 dependencies 中，verify-cordis-config 会强制检查。

一条完整的开发路径是：声明插件身份 → 实现 apply → 挂载到组合 → 验证与发布。

图2 插件开发四步骤

验证方面，产品可见插件必须有非单元的真实组合测试：经 Loader 启动测试专用 cordis.yml，只 mock 外部服务或不确定输入，并断言模型可见、持久或用户可见的输出；模型可见行为还需快照或端到端覆盖。发布后为仓库添加 dsh-plugin 话题以便被发现；bundle 是"可安装补丁层"的发行格式，适合把一组插件作为整体分发。

模型可见 ⟺ 已记录：新的模型可见输入必须伴随新的会话事件。

不做硬编码可调参数：部署差异必须是 cordis.yml 可改的 Config 字段。

配置错误要响亮失败：自包含时在加载期报错，否则在最早可解析点报错，绝不静默跳过缺失的引用。

显式优于隐式：跨包边界的默认值是拥有方实现的显式 resolve 步骤，而不是藏在 run() 里的隐式兜底。

往期回顾