如果你对本插件有任何的意见建议,欢迎开启 issue 进行说明,或者你也可以直接贡献代码。
由于 pics 设计为可插拔式的框架,当前仓库仅实现了发送图片的功能,而获取图源的能力则完全由其他插件所实现(下称图源插件)。因此你可以选择向 pics(即本仓库)贡献代码,也可以开发新的图源插件,或向现有的图源插件贡献代码。
本仓库采用了 koishi-thirdeye 进行开发,思路与理念与传统的 koishi 插件并不相同,在贡献代码之前请先了解双方的异同。
图源是一类 koishi-plugin-pics
的附属插件,由其他 Koishi 插件提供。这些插件需要实现 PicSource
类,并使用 ctx.pics.addSource(picSource, ctx)
进行注入。
图源插件推荐在 package.json
的 keywords
内写上 required:pics
以保证正确被 Koishi 插件市场搜索。
export interface PicResult {
// 图片 URL
url: string;
// 图片介绍,会一并出现在底部
description?: string;
}
export class PicSource {
// 构造函数传入 ctx 对象
constructor(ctx: Context);
// 图源的标签列表,使用 -s 参数匹配。
tags: string[];
// 图源权重,权重越大随机到的概率越大,默认 1
weight: number;
// 图源名称。
name: string;
// 图源介绍
description: string;
// 是否为默认图源。用户未指定参数时使用默认图源。
isDefault: boolean;
// 获取随机图片。 picTags 可能是空数组。
randomPic(picTags: string[]): PicResult | Promise<PicResult>;
// 图源启动时运行,可选
onStartup(): Awaitable<void>;
// 图源卸载时运行,可选
onShutdown(): Awaitable<void>;
}
对于单图源的插件,我们提供了 PicSourcePlugin
基类工厂函数,只需要继承该类即可快速开发单图源插件。
import { Context } from "koishi";
import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
import { PicSourcePlugin, PicsContainer } from "koishi-plugin-pics";
@RegisterSchema()
export class Config {
@SchemaProperty({ default: 'my-source' }) // 推荐覆盖该属性以提供默认值
name: string;
@SchemaProperty({ default: 10000 })
code: number;
}
@DefinePlugin()
export default class MyPicSource extends PicSourcePlugin(Config) {
async randomPic(tags: string[]) {
return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
}
}
// 加载图源插件
ctx.plugin(MyPicSource, {
code: 10000,
name: 'my-picsource',
description: 'my-picsource'
});
使用 koishi-thirdeye 提供的 MultiInstancePlugin
方法创建多图源插件。该插件的配置具有 instances
数组属性,每一项都是一个图源的配置。
import { Context } from "koishi";
import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
import { PicSourcePlugin, PicsContainer } from "koishi-plugin-pics";
@RegisterSchema()
export class Config {
@SchemaProperty({ default: 'my-source' }) // 推荐覆盖该属性以提供默认值
name: string;
@SchemaProperty({ default: 10000 })
code: number;
}
// 不 default
@DefinePlugin()
export class MyPicSource extends PicSourcePlugin(Config) {
async randomPic(tags: string[]) {
return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
}
}
// 在这里 default 加载插件
export default class MyMultiPicSource extends MultiInstancePlugin(MyPicSource) {}
// 加载图源插件
ctx.plugin(MyMultiPicSource, {
instances: [
{
code: 10000,
name: 'my-picsource1',
description: 'my-picsource1',
},
{
code: 10001,
name: 'my-picsource2',
description: 'my-picsource2',
},
].
});
图源配置会自动注入到图源插件的配置类中。
export class PicSourceConfig {
@SchemaProperty({ type: 'string', default: [], desc: '图源标签' })
tags: string[];
@SchemaProperty({ default: 1, desc: '图源权重' })
weight: number;
@SchemaProperty({ default: 1, desc: '图源名称', required: true })
name: string;
@SchemaProperty({ desc: '图源描述' })
description?: string;
@SchemaProperty({ desc: '是否为默认图源' })
isDefault?: boolean;
// 给目标对象注入上述对象。
applyTo(target: PicSourceInfo) {
target.tags ||= this.tags;
target.weight ||= this.weight;
target.name ||= this.name;
target.description ||= this.description;
target.isDefault = this.isDefault;
}
}
和图源类似,图像中间件是 koishi-plugin-pics
的另一类附属插件,可以对图源获取的随机 URL 在发送给用户之前进行一定的变换。
图像中间件系统使用洋葱模型的方式进行处理。每一层处理的过程中,可以使用 next(url?: string)
函数进行后续的操作,并得到后续结果的返回值,再进行进一步的处理。
next
函数中的 url
参数可以对进行后续操作的初始 URL 值进行控制。若不填写,则与本中间件的传入 URL 值相同。
图像中间件插件需要使用 koishi-thirdeye 进行开发。请在开发之前阅读相关相关文档。推荐在 package.json
的 keywords
内写上 required:pics
以保证正确被 Koishi 插件市场搜索。
图源中间件插件需要继承 PicMiddlewareBase<Config>
类,覆盖 use
方法,并使用 @DefinePlugin()
进行修饰。
该基类具有这些预定义属性,可以直接使用。
-
pics
:koishi-plugin-pics
服务本身,并已标记为using
依赖。 -
logger
: 日志记录器。
配置基类定义如下。定义插件时该类的属性会自动注入到配置类内。
export class PicMiddlewareConfig {
constructor(config: PicMiddlewareInfo) {}
@SchemaProperty({ description: '中间件名称。' })
name: string;
@SchemaProperty({ description: '是否在首位插入中间件。', default: false })
prepend: boolean;
applyTo(target: PicMiddleware) {
target.name = this.name;
target.prepend = this.prepend;
}
}
下例图像中间件插件会将所有 URL 进行预先下载,并使用 download
方法转换为 base64://
形式的 URL,即为 koishi-plugin-pics
中 useBase64
选项的功能。事实上,koishi-plugin-pics
中的 useAssets
和 useBase64
这两个选项的功能,都是由内置图像中间件实现的。
export class Config {
@SchemaProperty({ type: Schema.object() })
axiosConfig: AxiosRequestConfig;
}
@DefinePlugin()
export default class PicDownloaderMiddleware extends PicMiddlewarePlugin(Config) {
override async use(url: string, next: PicNext) {
const downloadedUrl = await this.pics.download(url, config.axiosConfig);
return next(downloadedUrl);
}
}