DSH plugin 类型扩展:declare module 补 Context、Events 与配置
类型问题最烦的地方不是报错,而是它只在编辑器里报错。代码能跑、日志正常,只有 ctx.metrics 下面那条红波浪线一直在提醒你「这里用了 any」。这篇从三个具体报错出发,把 declare module 能做什么、不能做什么一次说清。
DSH plugin 的三个报错,同一个原因
DSH plugin 的三类类型报错都来自同一个原因:运行时注册与编译期声明脱节。
先看三种最常见的报错,它们看起来无关,其实是一件事。
第一种:属性不存在。 你写 ctx.metrics.record(...),编辑器提示 Property 'metrics' does not exist on type 'Context'。运行时可能完全正常,因为服务真的注册了,只是类型系统不知道。第二种:事件名不匹配。 你写 ctx.on('stats/report', handler),提示没有这个重载;或者参数类型对不上,count 被推断成 any。
第三种:配置全是 any。 apply(ctx, config) 里的 config 没有类型提示,字段名打错也不报错,直到运行时报 undefined。三种报错的共同点是:运行时与编译期脱节。 运行时靠注册,编译期靠声明;只做了一边,就会出现「能跑但没提示」或「有提示但跑不了」。
declare module 究竟给 DSH plugin 改了什么
它改的不是你的代码,而是 Cordis 已声明接口的类型表。 写法固定:
declare module '@deepseek-ai/cordis' {
interface Context {
metrics: MetricsService
}
}
这段声明告诉 TypeScript:以后所有 Context 上都多了一个 metrics 属性,类型是 MetricsService。它有三个边界必须记住:
- 只作用于编译期,编译后完全消失;
- 不产生任何运行时行为,不会帮你注册服务;
- 只对「参与本次编译」的文件生效,没被 import 到的声明文件等于不存在。
第 3 条是很多人卡住的原因。 声明写在一个没被引用的文件里,编辑器看起来一切正常,换一个包却提示不存在。
DSH plugin 最值得扩展的三处地方
第一处是 Context,用来补服务属性。 这条最适合放在 Service Definition 包里,和抽象类放一起:
import { Service, type Context } from '@deepseek-ai/cordis'
declare module '@deepseek-ai/cordis' {
interface Context { metrics: MetricsService }
}
export abstract class MetricsService extends Service {
constructor(ctx: Context) { super(ctx, 'metrics') }
abstract record(event: string): void
}
属性名必须和服务名一致。写成 metrics 就注册 metrics,不要出现「属性叫 metricsService、注册叫 metrics」这种错位。
第二处是 Events,用来补事件名与监听器签名。 官方示例的写法是给 Events 接口加一个方法签名:
declare module '@deepseek-ai/cordis' {
interface Events {
'stats/report'(name: string, count: number): void
}
}
这样 ctx.emit('stats/report', name, next) 与 ctx.on('stats/report', (name, count) => ...) 都会被校验。事件名建议用 namespace/action 形式,事件多了以后能按前缀分组,也不会和普通属性名混在一起。
第三处是配置类型,这一处不用 declare module。 插件的 Config 是导出同名 schema 来约束的,TypeScript 从 Schema<Config> 推断 apply 第二个参数的类型。配置里出现 any,通常是没导出 Config 类型,或者 schema 与接口对不上。
DSH plugin 类型有了,运行时没有
DSH plugin 的类型声明不负责运行时接线,属性有类型不等于值存在。
这是新手最容易困惑的一类现象:编辑器不报错了,运行起来 ctx.metrics 是 undefined。原因只有一个:声明合并不负责接线。 下面两件事必须由你分别完成:
| 层面 | 要做的事 | 漏了会怎样 |
|---|---|---|
| 运行时 | super(ctx, 'metrics') 注册服务 | 属性存在但值 undefined |
| 运行时 | ctx.emit('stats/report', ...) 发出事件 | 监听器永远不触发 |
| 编译期 | declare module 补类型 | 编辑器报红,但能跑 |
DSH plugin 为什么需要 import type {}
import type {} 的作用是把 DSH plugin 的声明文件拉进编译图,而不引入运行时依赖。
有一种情况很隐蔽:声明写在 stats.ts 里,reporter.ts 只 import 了类型,结果事件名还是没有补全。官方教程给了一个看似多余的写法:
import type {} from './stats'
它不导入任何值,作用是把 stats.ts 拉进编译图,让 TypeScript 看到那里的声明合并。少了这一行,两个文件在类型层面互不相识。这条规则可以推广成一句:声明合并跟着模块可见性走,不跟着目录结构走。 换包、换入口、换 tsconfig 的 include,都可能让声明「突然失效」。
DSH plugin 类型扩展五分钟自检
按这五步自检,能把 DSH plugin 的类型问题与装配问题分开。
按下面五步走一遍,能覆盖大多数类型扩展问题:
- 删掉所有
any,跑一次类型检查,记录报错位置; - 给每个报错补声明,确认同一文件内不再报错;
- 换到另一个包引用服务,确认声明是否仍然生效;
- 在运行时不注册服务,只留声明,确认现象是 undefined 而不是报错;
- 恢复注册,确认值与类型都对上。
第 4 步是有意为之。 它帮你把「类型问题」和「装配问题」彻底分开,之后看到 undefined 就不会先去改声明。
类型扩展的收益是让错误提前到编译期,代价是你要维护两份真相:声明与注册。两份保持一致,编辑器才会变成真正的护栏。想看 Context 与 inject 的运行期规则,读 Cordis 入门;想看事件分发模式的选择,读 DSH plugin 事件怎么写。
常见问题
DSH plugin 的声明合并只影响编译期,不产生任何运行时接线。服务仍需要继承 Service 并用 super(ctx, 'myService') 注册,事件仍需要 ctx.emit 发出;类型写了但没注册,运行时就是空的。
DSH plugin 的事件类型只在参与编译的声明里才会被合并,没进编译图就等于不存在。Consumer 侧需要一行 import type {} from './stats' 把声明文件拉进编译图,这行不产生运行时导入,但能让 ctx.on 与 ctx.emit 拿到事件签名。
DSH plugin 的属性名相同但类型不同会冲突,类型相同则合并成同一个。正确做法是只在 Service Definition 包里声明一次,Provider 与 Consumer 只 import 那个包,不要各自复制一份声明。
DSH plugin 官方示例用 namespace/action 约定,例如 stats/report,让扁平的事件命名空间保持可读与可分组。纯 camelCase 不会报错,但事件多了以后很难看出归属,也容易和属性名混淆。
相关术语
- 声明合并
- 声明合并是 TypeScript 把同名接口的多次声明合并成一个类型的机制,DSH plugin 用它扩展 Cordis 的 Context 与 Events。— DeepSeek Harness 开发文档
- Context 接口
- Context 接口是 Cordis 描述插件上下文的类型,声明合并可以往它上面添加自定义服务属性,让 ctx 获得类型。— DeepSeek Harness 开发文档
- Events 接口
- Events 接口是 Cordis 描述事件名与监听器签名的类型,合并后 ctx.emit 与 ctx.on 会按声明校验参数。— DeepSeek Harness 开发文档
- import type
- import type 是只引入类型、在编译后消失的导入语法,用来把声明合并带入编译图而不引入运行时依赖。— DeepSeek Harness 开发文档
来源
- DeepSeek Harness 开发文档:Cordis 教程· deepseek-harness
- DeepSeek Harness 开发文档:事件· deepseek-harness
- DeepSeek Harness 开发文档:服务与依赖· deepseek-harness