ARTICLE · 1359142
Cordis 入门:构建你的第一个插件
目录
环境准备 1.1 安装 Node.js 与包管理器 1.2 创建模板项目 插件的基本形态 2.1 三种合法形态 2.2 ctx.plugin() 的四种等价写法 模块化与嵌套 3.1 导出约定与默认导出优先级 3.2 嵌套插件与独立热重载 用 Schema 约束配置 4.1 基本示例 4.2 类型描述与链式调用 在配置文件中加载插件 进阶:实现一个 sleep参考文献
本文是 Cordis 插件开发的入门教程,对应官方文档的「起步」与「认识插件」「插件配置」章节,涵盖从环境搭建、插件的三种形态、模块化组织,到配置约束与副作用管理的完整链路。Cordis 框架的整体介绍见 [[Cordis:一个 TypeScript 插件框架]]。
1. 环境准备
在动手写插件之前,先搭好开发环境。Cordis 是 ESM 优先的框架,脚手架要求 Node 22 或更高版本。
1.1 安装 Node.js 与包管理器
安装当前 LTS 版本的 Node.js 即可满足要求,包管理器任选 yarn、npm 或 pnpm 之一。需要注意上游文档中「安装 Node.js」一节尚未完成,按照常规方式安装即可。
1.2 创建模板项目
打开命令行,进入你想要创建 Cordis 项目的目录,执行脚手架命令:
1 2 3 4 5 6
# yarnyarn create cordis# npmnpm init cordis# pnpmpnpm init cordis
一个实践建议:项目目录不宜过深,路径中避免中文和空格。推荐的目录如下:
Windows: C:\dev或D:\dev(不要直接在盘根创建项目,至少建一层目录)其他操作系统: ~/dev
2. 插件的基本形态
Cordis 的一切都从插件开始。先看一个最小可运行的插件:
1 2 3 4 5 6 7 8 9
import { Context } from'cordis'exportconst name = 'example'exportinterfaceConfig {}exportfunctionapply(ctx: Context, config: Config) {ctx.logger.success('Hello World')}
这个文件由四部分组成:模块导出的插件函数 apply、插件名 name、配置类型 Config,以及函数体内对上下文 ctx 的操作。
2.1 三种合法形态
一个插件必须是以下三种基本形式之一:
一个接受两个参数的函数:第一个参数是所在的上下文,第二个参数是传入的配置 一个接受两个参数的类:构造参数同样是上下文和配置 一个对象:其中的 apply方法是第一种形式中所说的函数
2.2 ctx.plugin() 的四种等价写法
使用 ctx.plugin() 加载插件,相当于把 ctx 传入插件的函数或类中。因此下面四种写法基本等价:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
// 直接对 ctx 进行操作ctx.logger.success('Hello World')// 使用函数形式的插件ctx.plugin(ctx => ctx.logger.success('Hello World'))// 使用对象形式的插件ctx.plugin({apply: ctx => ctx.logger.success('Hello World'),})// 使用类形式的插件ctx.plugin(class {constructor(ctx: Context) {ctx.logger.success('Hello World')}})
插件化不只是换一种函数调用的写法:它把多个逻辑组合成可模块化的单元,并让插件内部能够初始化自己所需的选项,显著提升可维护性。
3. 模块化与嵌套
插件化最大的好处是把不同功能写进不同模块,插件作为模块的导出存在。
3.1 导出约定与默认导出优先级
对于对象形式的插件,可以额外提供 name 属性作为插件名;函数和类形式则直接以函数名、类名为插件名。具名插件有助于描述功能并被用于插件关系可视化,但不影响运行时行为。
1 2 3 4 5
// foo.ts:整体导出对象形式的插件import { Context } from'cordis'exportinterfaceConfig {}exportconst name = 'Foo'exportfunctionapply(ctx: Context, config?: Config) {}
1 2 3 4 5 6 7 8 9
// bar.ts:默认导出类形式的插件import { Context } from'cordis'classBar {constructor(ctx: Context, config?: Bar.Config) {}}namespaceBar {exportinterfaceConfig {}}exportdefaultBar
注意:默认导出的优先级更高。只要插件模块提供了默认导出,Cordis 加载器就只会加载默认导出,而不是导出整体。
3.2 嵌套插件与独立热重载
插件可以嵌套:把复杂功能解耦成多个子模块,再由一个入口插件依次加载它们。
1 2 3 4 5 6 7 8 9
// 入口文件 index.ts,从各模块分别加载插件import { Context } from'cordis'import * asFoofrom'./foo'importBarfrom'./bar'exportfunctionapply(ctx: Context) {ctx.plugin(Foo)ctx.plugin(Bar)}
加载 index.ts 就相当于同时加载了 foo 和 bar。除了减轻心智负担,解耦出的模块还享受独立的热重载——修改其中一个模块的代码,不会影响另一个模块的运行。许多大型插件都采用这种组织方式。
4. 用 Schema 约束配置
仅仅是接受任意格式的输入是不够的,还需要对配置项进行约束,以确保插件能正常运行。Cordis 集成了 schemastery 工具来验证配置合法性、为可缺省项提供默认值,并支持在控制台通过表单在线配置。
4.1 基本示例
插件同时导出一个 Config 类型和一个同名的 Schema 对象,前者提供类型,后者生成约束:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
import { Context, Schema } from'cordis'exportconst name = 'example'exportinterfaceConfig {foo: stringbar?: number}exportconstConfig: Schema<Config> = Schema.object({foo: Schema.string().required(),bar: Schema.number().default(1),})exportfunctionapply(ctx: Context, config: Config) {ctx.logger.info(`foo: ${config.foo}, bar: ${config.bar}`)}
foo 是必需项,不填写则插件启动时报错;bar 是可选项,不填写会被赋予默认值 1。
4.2 类型描述与链式调用
除了 string、number、boolean 等基础类型,还支持 array、dict、object 等复合类型,可以组合出复杂配置:
1 2 3 4 5 6 7
Schema.object({foo: Schema.array(Schema.string()),bar: Schema.dict(Schema.number()),baz: Schema.object({quz: Schema.boolean(),}),})
对已创建的类型可以链式调用添加更多信息:
1 2 3 4 5
Schema.number().min(0).max(100).step(1) // 限制取值范围.default(50) // 设置默认值.role('slider') // 以滑动条形式显示.description('这是一个介于 0 和 100 之间的整数。')
高级类型中,intersect 用于类型分组显示,union 可以创造联合类型;恰当组合甚至能构造出上下关联的配置项。
形如 name 和 Config 这样与插件入口函数同级导出的属性称为元属性。常用的还有 usage(使用方法说明)、reusable、using、filter 等。使用默认导出时,推荐把配置声明放进 namespace:
1 2 3 4 5 6 7 8 9 10 11 12
classExample {constructor(ctx: Context, config: Example.Config) {// 插件实现}}namespaceExample {exportinterfaceConfig {}exportconstConfig: Schema<Config> = Schema.object({})}exportdefaultExample
5. 在配置文件中加载插件
在配置文件中,用插件的 npm 包名(即 package.json 的 name 字段)添加插件。打开 cordis.yml,加入一行:
1
-name:cordis-plugin-example6. 进阶:实现一个 sleep
最后用一个进阶示例收尾:实现一个可被插件停用打断的 sleep。核心是 ctx.effect()——立即执行回调并收集其产生的副作用,插件停用时这些副作用会被自动回收:
1 2 3 4 5 6 7 8 9 10 11
import { Context } from'cordis'importtype {} from'@cordisjs/plugin-timer'functionsleep(ctx: Context, delay: number) {const { promise, resolve, reject } = Promise.withResolvers<void>()const dispose = ctx.effect(function* () {yield ctx.setTimeout(resolve, delay)yield () => reject(newError('effect is disposed'))}, 'sleep()')return promise.finally(dispose)}
生成器中每个 yield 返回一个清理函数:定时器到点时 resolve 兑现 promise;而如果插件先被停用,第二个清理函数会 reject,调用方因此感知到中断而不是永远挂起。
参考文献
[1] 环境搭建(Cordis 官方文档):https://github.com/cordiverse/docs/blob/main/zh-CN/guide/starter/setup.md
[2] 认识插件(Cordis 官方文档):https://github.com/cordiverse/docs/blob/main/zh-CN/guide/essential/index.md
[3] 插件配置(Cordis 官方文档):https://github.com/cordiverse/docs/blob/main/zh-CN/guide/essential/config.md
[4] schemastery 项目主页:https://github.com/shigma/schemastery















































































