DeepSeek Harness 插件继承到的接口面:哪些由框架给、哪些必须自己声明的清单
插件作者最容易忽略的一件事:Context 不是「什么都有」,它只给你框架级的公共接口。 生命周期、事件、日志、插件挂载这些是继承来的;你自己的服务、事件与配置,仍然要显式注册并扩展类型(来源)。分清这两层,能避免一半「类型对、运行时错」的问题。
DeepSeek Harness 继承面是什么:Context 给你的公共接口
继承接口面是框架与插件之间的公共契约,不是插件能力的全集。 Cordis 把一组通用能力挂在 Context 上,插件在 apply(ctx) 里直接使用,不需要自己创建。(来源)
这组能力的共同点是「所有插件都可能需要」:监听事件、注册副作用、挂子插件、写日志、声明依赖。它们由框架统一实现,插件只负责调用。
继承面的价值是减少重复:每个插件都自己实现一套生命周期或日志,既浪费又容易不一致。框架把它们收上来,插件只写业务。
继承面的边界也很明确:它不包含你的业务服务。ctx 上有没有 myService,取决于有没有插件注册过,而不是取决于 Context 类型本身。
DeepSeek Harness 框架给的清单
框架给的是「机制」,不是「业务」。 可以按四类记(来源):
- 生命周期 — 插件加载、卸载、副作用注册与清理;
- 事件 — 监听、触发、按作用域订阅;
- 依赖与挂载 — 声明 inject、挂载子插件、访问父上下文;
- 基础设施 — 日志、作用域、插件管理等通用能力。
这四类的具体方法名以官方继承接口面文档为准,不要凭记忆写。名称写错时,TypeScript 可能不报错(如果用了 any),运行时才失败。
框架给的清单还有一个特点:它们对「所有插件」都成立。如果你的能力只对某类插件有意义,它就不该进继承面,而应该做成 Service 或 Registry。
一个判断方法:把能力从 Context 上拿掉,是否所有插件都会受影响?会,才是继承面;只有部分插件受影响,就是业务能力。
继承面还会随框架版本变化。升级 Cordis 或 DeepSeek Harness 后,新增的继承接口可能改变推荐写法;不要因为「以前能跑」就假设继承面没变,升级说明与官方文档要一起看。
DeepSeek Harness 必须自己声明的清单
插件自己的东西,三样必须显式处理:服务、事件、配置。 它们都不会自动出现在 Context 上。(来源)
- 服务 — 通过注册贡献到上下文,消费方按名称注入;不注册,消费方拿不到。
- 事件 — 通过
SessionEventMap或事件域扩展声明;不声明,类型系统不认识,运行时也可能被拒绝。 - 配置 — 通过 Config schema 声明字段与默认值;不声明,设置页与 patch 都不知道该写什么。
三者的共同点是「声明与注册成对」:只声明类型不注册,类型有、运行时没有;只注册不声明,运行时有、类型没有。
一个实用习惯:每加一个服务或事件,同时写三处——运行时注册、类型扩展、README 说明。三处齐全,消费方才不会踩空。
配置还要注意默认值与可选性。没有默认值的必填字段,会让部署必须显式提供;可选字段则要给消费方明确的缺省行为。
配置 schema 不是文档的替代品。字段描述、默认值、取值范围写进 schema,设置页和 patch 才能生成正确的表单与校验;只写文档,消费方仍可能填错。
DeepSeek Harness 类型与运行时错位的两个症状
错位有两个方向,表现不同,排查方法也不同。 先看是哪一种(来源):
| 症状 | 常见原因 | 排查 |
|---|---|---|
| 类型有、运行时没有 | 只写了 declare module,没有注册 | 查 apply 里是否真的注册 |
| 运行时有一、类型没有 | 注册了但没扩展类型 | 查 Context/Events 的类型声明 |
| 类型和运行时都有,但名字不一致 | 注册名与声明名不同 | 对齐字符串常量 |
第一种最危险,因为编译能过、运行时才炸。它通常发生在「先写类型、后写实现」的过程中,类型写完了,实现忘了。
第二种不会立刻报错,但消费方只能用 any 或字符串访问,失去了类型安全。长期看,它会变成「这个能力大家都知道有,但没人敢改」。
第三种最常见,也最容易修:把注册名与声明名抽成同一个常量,双方引用它,而不是各写一遍字符串。
DeepSeek Harness 三个自检问题
写完插件,用三个问题检查继承面是否用对。 三问都过,基本不会出现错位(来源):
- 这个能力是所有插件都要的吗? 是,才放继承面;不是,做成 Service 或 Registry。
- 这个能力注册了吗? 类型声明不算注册,必须在 apply 里真正贡献。
- 消费方怎么找到它? 名称、类型、文档三处是否一致?不一致,就会有人写错。
三问的顺序是从设计到实现:先判断归属,再确认注册,最后确认消费方视角。顺序反了,容易在实现细节里迷失。
如果三问里有任何一问答不上来,先不要加新能力。把已有的服务与事件整理清楚,比继续堆接口更有价值。
DeepSeek Harness 验证:从消费方角度看继承面
验证继承面,不要只看提供方代码,要从消费方写一段最小调用。 三步(来源):
- 类型检查 — 消费方能否在不使用 any 的情况下访问该能力;
- 运行时调用 — 调用是否真的执行,而不是落到空实现;
- 卸载验证 — 提供方卸载后,消费方是否得到明确的不可用,而不是旧对象。
三步都过,说明继承面、注册与类型扩展是对齐的。只过前两步,可能是注册句柄泄漏;只过第一步,可能是只有类型没有实现。
旧文 develop-cordis-primer 讲 Cordis 入门,develop-plugin-typescript-augment 讲类型扩展,develop-plugin-events 讲事件;本篇补的是继承面清单。先分清框架给的与自己的,再谈注册。
继承面越清楚,插件越少「看起来能编译、跑起来找不到」的问题。
类型是承诺,注册是兑现,两者缺一不可。
常见问题
DeepSeek Harness 插件从 Context 继承到框架提供的公共能力,例如生命周期、事件监听、日志、插件挂载与依赖注入;具体清单以 Cordis 的继承接口面文档为准。
DeepSeek Harness 里,需要自己声明。DeepSeek Harness 的 Context 只提供框架级接口,插件自己的服务、事件与配置要通过注册与类型扩展补上,否则消费方看不到。
DeepSeek Harness 里,通常是只做了 declare module 类型扩展,没有真正注册服务或事件。DeepSeek Harness 的 TypeScript 类型不会替你在运行时创建能力,声明与注册必须成对。
DeepSeek Harness 里,消费方无法通过类型安全地使用该能力,容易写错名称或参数。DeepSeek Harness 的插件应在扩展类型的同时导出清晰的接口,避免运行时有、文档与类型都没有。
相关术语
- 继承接口面
- 继承接口面是 Cordis 的 Context 向插件提供的框架级公共接口集合,包括生命周期、事件、日志与插件管理等能力。— DeepSeek Harness 官方文档 - 继承接口面
- Context
- Context 是 Cordis 传给插件的共享上下文,插件通过它注册服务、监听事件、挂载子插件并访问框架能力。— DeepSeek Harness 官方文档 - Cordis 入门
- declare module
- declare module 是 TypeScript 的模块扩展语法,DeepSeek Harness 插件用它把自定义服务与事件补进 Context 与 Events 的类型。— DeepSeek Harness 官方文档 - 继承接口面
- 类型与运行时错位
- 类型与运行时错位是指 TypeScript 声明了某项能力,但运行时没有注册,或运行时注册了却没有类型声明。— DeepSeek Harness 官方文档 - 继承接口面
来源
- DeepSeek Harness 官方文档 - 继承接口面· deepseek-harness
- DeepSeek Harness 官方文档 - Cordis 入门· deepseek-harness