diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 3495ea50..50102852 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -18,6 +18,7 @@ export default defineConfig({ { text: '主页', link: '/' }, { text: '快速开始', link: '/start' }, { text: '事件', link: '/event/message' }, + { text: '开发工具', link: '/develop/tools' }, { text: '插件编写', link: '/develop/plugin' }, ] } diff --git a/docs/develop/index.md b/docs/develop/index.md index db714cbf..e981d309 100644 --- a/docs/develop/index.md +++ b/docs/develop/index.md @@ -12,6 +12,7 @@ - [命名规范](#命名规范) - [温馨提示](#温馨提示) - [插件包目录参考结构](#插件包目录参考结构) + - [#karin](#karin) > 推荐使用 VSCode 进行开发 > 推荐安装 `pnpm` 进行包管理 @@ -43,3 +44,17 @@ kritor-plugin-hello-world └── package.json ``` +## #karin + +在模板仓库下，有这么一段代码 +```js +import { plugin, segment } from '#Karin' +``` + +`#Karin` 是一个别名，指向 `./lib/index.js` 文件。 +此文件为入口文件，开发者无需像以下这样引入模块： +```js +import segment from './lib/bot/segment.js' +import plugin from './lib/plugins/plugin.js' +``` +详情请查看 [开发工具](./tools.md/#karin) 文档 \ No newline at end of file diff --git a/docs/develop/plugin.md b/docs/develop/plugin.md index fcbf8a4f..5f992250 100644 --- a/docs/develop/plugin.md +++ b/docs/develop/plugin.md @@ -27,22 +27,41 @@ ## 插件示例 +::: warning 温馨提示 +未标注必选的参数，可选键入。 +::: + 1. 打开`plugins/karin-plugin-example`目录，在此新建一个`hello.js`文件。 2. 打开`hello.js`文件，输入以下代码： ### 方法1 + ```js import { App } from '#Karin' -// 插件名称为 hello -const app = App.init({ name: 'hello' }) + +const app = App.init({ + /** 必选 插件名称 */ + name: 'hello', + /** 插件描述 */ + dsc: '发送你好回复hello', + /** 监听事件 默认message */ + event: 'message', + /** 插件优先级 */ + priority: 5000 +}) app.reg({ - // 使用正则匹配消息 你好 + /** 命令匹配正则 */ reg: '你好$', + /** 命令执行方法名称 */ fnc: 'hello', + /** 是否显示操作日志 true=是 false=否 */ + log: true, + /** 权限 master,owner,admin,all */ + permission: 'all', + /** 调用 this.reply 方法回复 hello 关于参数2，请看下文 */ async hello () { - // 调用 this.reply 方法回复 hello - this.reply('hello') + this.reply('hello', { at: false, recallMsg: 0, reply: true, button: false }) } }) @@ -60,24 +79,32 @@ import { plugin } from '#Karin' export class hello extends plugin { constructor () { super({ - // 插件名称 + // 必选 插件名称 name: 'hello', // 插件描述 dsc: '发送你好回复hello', + // 监听消息事件 默认message + event: 'message', + // 优先级 + priority: 5000, rule: [ { /** 命令正则匹配 */ - reg: '^你好$', + reg: '^#你好$', /** 执行方法 */ - fnc: 'hello' + fnc: 'hello', + // 是否显示操作日志 true=是 false=否 + log: true, + // 权限 master,owner,admin,all + permission: 'all' } - ] + ], }) } async hello () { - // 调用 this.reply 方法回复 hello - this.reply('hello') + // 调用 this.reply 方法回复 hello 关于参数2，请看下文 + this.reply('hello', { at: false, recallMsg: 0, reply: true, button: false }) } } diff --git a/docs/develop/tools.md b/docs/develop/tools.md new file mode 100644 index 00000000..a1d8b473 --- /dev/null +++ b/docs/develop/tools.md @@ -0,0 +1,175 @@ +## #karin + +`./lib/index.js` + +```js +import Bot from './bot/bot.js' +import App from './plugins/app.js' +import Cfg from './config/config.js' +import logger from './config/log.js' +import redis from './config/redis.js' +import segment from './bot/segment.js' +import common from './common/common.js' +import plugin from './plugins/plugin.js' +import Renderer from './Renderer/Renderer.js' +import { kritor } from './adapter/kritor/protos/compiled.js' + +export { App, Bot, Cfg, common, logger, plugin, redis, segment, Renderer, kritor } + +``` + +### 简介 + +可以看到，`#Karin` 是一个别名，指向 `./lib/index.js` 文件。 + +此文件为入口文件，开发者无需像以下这样引入模块： + +```js +import segment from './lib/bot/segment.js' +import plugin from './lib/plugins/plugin.js' +``` + +### 使用 + +- `APP` + ```js + import { App } from '#Karin' + // ... + ``` +- `Bot` + ```js + import { Bot } from '#Karin' + // ... + ``` +- `Cfg` + ```js + import { Cfg } from '#Karin' + // ... + ``` +- `common` + ```js + import { common } from '#Karin' + + /** 休眠函数 延迟5秒 */ + await common.sleep(5 * 1000) + + /** 下载文件 参数1为下载地址，参数2为保存到本地的路径 */ + await common.downFile('https://example.com/1.jpg', './temp/test/1.jpg') + + /** 递归创建文件夹 */ + common.mkdir('./temp/test') + + /** 快速构建淡紫色的bot前缀日志 */ + common.logger('qq', '这是一条来自QQ的消息') + // 输出：[Bot:qq] 这是一条来自QQ的消息 + + /** 获取绝对路径，支持file://前缀 */ + common.absPath('file://./temp/test') + // 输出：/home/karin/temp/test + + /** 将文件转换为不带前缀的base64字符串 */ + await common.base64('./temp/test/1.jpg') + // 输出：'/9j/4AAQSkZJRgABAQEAYABgAADg...' + + /** 将数据流对象转换为Buffer对象 */ + const Buffer = await common.stream(fs.createReadStream('./temp/test/1.jpg')) + // 输出：Buffer + + /** 将文件转换为Buffer对象 支持file:// base64:// 可读流等... */ + const buffer = await common.buffer(buffer) + // 输出 buffer + + ``` +- `logger` + ```js + import { logger } from '#Karin' + + /** 打印trace日志 */ + logger.trace('这是一条trace日志') + /** 打印debug日志 */ + logger.debug('这是一条debug日志') + /** 打印info日志 */ + logger.info('这是一条info日志') + /** 打印warn日志 */ + logger.warn('这是一条warn日志') + /** 打印mark日志 */ + logger.mark('这是一条mark日志') + /** 打印error日志 */ + logger.error('这是一条error日志') + /** 打印fatal日志 */ + logger.fatal('这是一条fatal日志') + + // 其中 logger还提供了打印不同颜色日志的方法 + + /** 打印红色日志 */ + logger.info(logger.red('这是一条红色的info日志')) + /** 打印绿色日志 */ + logger.info(logger.green('这是一条绿色的info日志')) + /** 打印黄色日志 */ + logger.info(logger.yellow('这是一条黄色的info日志')) + /** 打印蓝色日志 */ + logger.info(logger.blue('这是一条蓝色的info日志')) + /** 打印品红色日志 */ + logger.info(logger.magenta('这是一条品红色的info日志')) + /** 打印青色日志 */ + logger.info(logger.cyan('这是一条青色的info日志')) + /** 打印白色日志 */ + logger.info(logger.white('这是一条白色的info日志')) + /** 打印灰色日志 */ + logger.info(logger.chalk.gray('这是一条灰色的info日志')) + /** 打印淡紫色日志 */ + logger.info(logger.violet('这是一条淡紫色的info日志')) + + // 当以上方法无法满足你的需求时，你可以使用 chalk 库来自定义颜色 + logger.info(logger.chalk.hex('#FF0000')('这是一条自定义颜色的info日志')) + + ``` +- `plugin` + ```js + import { plugin } from '#Karin' + // ... + ``` +- `redis` + ```js + import { redis } from '#Karin' + + /** 存储一个键值对 */ + await redis.set('key', 'value') + + /** 存储一个键值对 60秒后过期 */ + await redis.set('key', 'value', { EX: 60 }) + + /** 获取指定键的值 */ + const value = await redis.get('key') + console.log(value) + + /** 删除指定键 */ + await redis.del('key') + + /** 获取所有键 慎用... 返回数组 */ + const all = await redis.keys('*') + console.log(all) + + /** 模糊获取以k开头的所有键列表 返回数组 */ + const keys = await redis.keys('k*') + /** 打印所有键的值 */ + for (const key of keys) { + const value = await redis.get(key) + console.log(value) + } + ``` +- `segment` + ```js + import { segment } from '#Karin' + // ... + ``` +- `Renderer` + ```js + import { Renderer } from '#Karin' + // ... + ``` +- `kritor` + ```js + import { kritor } from '#Karin' + // 内部方法，若无特殊需求，不建议使用 + ```