ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 类型扩展:declare module 补 Context、Events 与配置

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH pluginTypeScriptdeclare moduleContext类型声明
ctx.myService 报红、事件名没有补全、配置全是 any,根因都是没做声明合并。本文从三个真实报错出发,讲清 declare module 改了什么、放哪、以及为什么类型有了运行时还是没有。

类型问题最烦的地方不是报错,而是它只在编辑器里报错。代码能跑、日志正常,只有 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 已声明接口的类型表。 写法固定:

ts
declare module '@deepseek-ai/cordis' {
  interface Context {
    metrics: MetricsService
  }
}

这段声明告诉 TypeScript:以后所有 Context 上都多了一个 metrics 属性,类型是 MetricsService。它有三个边界必须记住:

  1. 只作用于编译期,编译后完全消失;
  2. 不产生任何运行时行为,不会帮你注册服务;
  3. 只对「参与本次编译」的文件生效,没被 import 到的声明文件等于不存在。

第 3 条是很多人卡住的原因。 声明写在一个没被引用的文件里,编辑器看起来一切正常,换一个包却提示不存在。

DSH plugin 最值得扩展的三处地方

第一处是 Context,用来补服务属性。 这条最适合放在 Service Definition 包里,和抽象类放一起:

ts
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 接口加一个方法签名:

ts
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 了类型,结果事件名还是没有补全。官方教程给了一个看似多余的写法:

ts
import type {} from './stats'

它不导入任何值,作用是把 stats.ts 拉进编译图,让 TypeScript 看到那里的声明合并。少了这一行,两个文件在类型层面互不相识。这条规则可以推广成一句:声明合并跟着模块可见性走,不跟着目录结构走。 换包、换入口、换 tsconfig 的 include,都可能让声明「突然失效」。

DSH plugin 类型扩展五分钟自检

按这五步自检,能把 DSH plugin 的类型问题与装配问题分开。

按下面五步走一遍,能覆盖大多数类型扩展问题:

  1. 删掉所有 any,跑一次类型检查,记录报错位置;
  2. 给每个报错补声明,确认同一文件内不再报错;
  3. 换到另一个包引用服务,确认声明是否仍然生效;
  4. 在运行时不注册服务,只留声明,确认现象是 undefined 而不是报错;
  5. 恢复注册,确认值与类型都对上。

第 4 步是有意为之。 它帮你把「类型问题」和「装配问题」彻底分开,之后看到 undefined 就不会先去改声明。

类型扩展的收益是让错误提前到编译期,代价是你要维护两份真相:声明与注册。两份保持一致,编辑器才会变成真正的护栏。想看 Context 与 inject 的运行期规则,读 Cordis 入门;想看事件分发模式的选择,读 DSH plugin 事件怎么写。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 给 Context 加了类型,为何运行时仍然是 undefined?

DSH plugin 的声明合并只影响编译期,不产生任何运行时接线。服务仍需要继承 Service 并用 super(ctx, 'myService') 注册,事件仍需要 ctx.emit 发出;类型写了但没注册,运行时就是空的。

只写 import type 的声明文件,为什么别的插件看不到我扩展的事件类型?

DSH plugin 的事件类型只在参与编译的声明里才会被合并,没进编译图就等于不存在。Consumer 侧需要一行 import type {} from './stats' 把声明文件拉进编译图,这行不产生运行时导入,但能让 ctx.on 与 ctx.emit 拿到事件签名。

DSH plugin 同一个服务名在两个包里各声明 Context,会冲突吗?

DSH plugin 的属性名相同但类型不同会冲突,类型相同则合并成同一个。正确做法是只在 Service Definition 包里声明一次,Provider 与 Consumer 只 import 那个包,不要各自复制一份声明。

DSH plugin 的自定义事件名应该怎么起,直接用 camelCase 可以吗?

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 开发文档

来源