Mioku

Appearance

插件上下文：插件 setup(ctx) 收到的对象。 事件监听、定时任务、配置、日志、Bot 操作与工具函数都挂在上面， 同时混入了 utils 中的常用工具（dayjs、fs、path、randomInt 等）。

Extends ​

  • CtxUtils

Properties ​

base64Decode ​

readonly base64Decode: (str, type) => string | Buffer<ArrayBufferLike> = utilsExports.base64Decode

Parameters ​

str ​

string

type? ​

"buffer" | BufferEncoding

Returns ​

string | Buffer<ArrayBufferLike>

base64Encode ​

readonly base64Encode: (str) => string = utilsExports.base64Encode

Parameters ​

str ​

string | number | Buffer<ArrayBufferLike>

Returns ​

string

clamp ​

readonly clamp: (n, min, max) => number = utilsExports.clamp

Parameters ​

n ​

number

min ​

number

max ​

number

Returns ​

number

colors ​

readonly colors: any = utilsExports.colors

dayjs ​

readonly dayjs: any = utilsExports.dayjs

filesize ​

readonly filesize: any = utilsExports.filesize

filter ​

readonly filter: <T>(source, type) => T[] = utilsExports.filter

Type Parameters ​

T ​

T extends MessageSegment

Parameters ​

source ​

Message | HasMessage

type ​

string

Returns ​

T[]

find ​

readonly find: <T>(source, type) => T | undefined = utilsExports.find

Type Parameters ​

T ​

T extends MessageSegment

Parameters ​

source ​

Message | HasMessage

type ​

string

Returns ​

T | undefined

formatDuration ​

readonly formatDuration: (ms) => string = utilsExports.formatDuration

Parameters ​

ms ​

number

Returns ​

string

fs ​

readonly fs: __module = utilsExports.fs

getTerminalInput ​

readonly getTerminalInput: (inputTip) => Promise<string> = utilsExports.getTerminalInput

Parameters ​

inputTip? ​

string = "请输入"

Returns ​

Promise<string>

isBoolean ​

readonly isBoolean: (val) => val is boolean = utilsExports.isBoolean

Parameters ​

val ​

unknown

Returns ​

val is boolean

isDefined ​

readonly isDefined: <T>(val?) => val is T = utilsExports.isDefined

Type Parameters ​

T ​

T = unknown

Parameters ​

val? ​

T

Returns ​

val is T

isFunction ​

readonly isFunction: <T>(val) => val is T = utilsExports.isFunction

Type Parameters ​

T ​

T extends AnyFunc = AnyFunc

Parameters ​

val ​

unknown

Returns ​

val is T

isNumber ​

readonly isNumber: (val) => val is number = utilsExports.isNumber

Parameters ​

val ​

unknown

Returns ​

val is number

isObject ​

readonly isObject: (val) => val is Record<string, unknown> = utilsExports.isObject

Parameters ​

val ​

unknown

Returns ​

val is Record<string, unknown>

isString ​

readonly isString: (val) => val is string = utilsExports.isString

Parameters ​

val ​

unknown

Returns ​

val is string

localeDate ​

readonly localeDate: (ts, options) => string = utilsExports.localeDate

Parameters ​

ts? ​

string | number | Date

options? ​
locale? ​

string

timeZone? ​

string

Returns ​

string

localeTime ​

readonly localeTime: (ts, options) => string = utilsExports.localeTime

Parameters ​

ts? ​

string | number | Date

options? ​
locale? ​

string

seconds? ​

boolean

timeZone? ​

string

Returns ​

string

localNum ​

readonly localNum: (num, locale) => string = utilsExports.localNum

Parameters ​

num ​

number

locale? ​

string = "zh-CN"

Returns ​

string

md5 ​

readonly md5: (text, encoding) => string | Buffer<ArrayBufferLike> = utilsExports.md5

Parameters ​

text ​

BinaryLike

encoding? ​

BinaryToTextEncoding | "buffer"

Returns ​

string | Buffer<ArrayBufferLike>

noNullish ​

readonly noNullish: <T>(val) => val is T = utilsExports.noNullish

Type Parameters ​

T ​

T

Parameters ​

val ​

T | null | undefined

Returns ​

val is T

path ​

readonly path: typeof path = utilsExports.path

prettyMs ​

readonly prettyMs: any = utilsExports.prettyMs

qs ​

readonly qs: (obj) => string = utilsExports.qs

Parameters ​

obj ​

Record<number | string, unknown>

Returns ​

string

randomId ​

readonly randomId: () => string = utilsExports.randomId

Returns ​

string

randomInt ​

readonly randomInt: (min, max, ...hashArgs) => number = utilsExports.randomInt

Parameters ​

min ​

number

max ​

number

hashArgs ​

...unknown[]

Returns ​

number

randomItem ​

readonly randomItem: <T>(array, ...hashArgs) => T = utilsExports.randomItem

Type Parameters ​

T ​

T

Parameters ​

array ​

readonly T[]

hashArgs ​

...unknown[]

Returns ​

T

randomItems ​

readonly randomItems: <T>(array, count, ...hashArgs) => T[] = utilsExports.randomItems

Type Parameters ​

T ​

T

Parameters ​

array ​

readonly T[]

count ​

number

hashArgs ​

...unknown[]

Returns ​

T[]

stringifyError ​

readonly stringifyError: (error) => string = utilsExports.stringifyError

Parameters ​

error ​

unknown

Returns ​

string

toArray ​

readonly toArray: <T>(value) => T[] = utilsExports.toArray

Type Parameters ​

T ​

T

Parameters ​

value ​

T | T[]

Returns ​

T[]

unique ​

readonly unique: <T>(array) => T[] = utilsExports.unique

Type Parameters ​

T ​

T

Parameters ​

array ​

T[]

Returns ​

T[]

uuid ​

readonly uuid: () => string = utilsExports.uuid

Returns ​

string

wait ​

readonly wait: (ms) => Promise<void> = utilsExports.wait

Parameters ​

ms ​

number

Returns ​

Promise<void>

Accessors ​

adapters ​

Get Signature ​

get adapters(): readonly Adapter[]

所有已加载的适配器实例（含当前没有 bot 连接的）

Returns ​

readonly Adapter[]

bot ​

Get Signature ​

get bot(): BotBase | undefined

第一个已连接的 bot（多数单 bot 场景直接用这个）

Returns ​

BotBase | undefined

bots ​

Get Signature ​

get bots(): readonly BotBase[]

所有已连接的 bot

Returns ​

readonly BotBase[]

buses ​

Get Signature ​

get buses(): EventBus

Returns ​

EventBus

capabilities ​

Get Signature ​

get capabilities(): CapabilityRegistry

Returns ​

CapabilityRegistry

commands ​

Get Signature ​

get commands(): CommandManager

当前运行时的命令管理器

Returns ​

CommandManager

config ​

Get Signature ​

get config(): Readonly<MiokuConfig>

当前框架配置（只读）

Returns ​

Readonly<MiokuConfig>

logger ​

Get Signature ​

get logger(): Logger

Returns ​

Logger

pluginId ​

Get Signature ​

get pluginId(): string

Returns ​

string

pluginName ​

Get Signature ​

get pluginName(): string

Returns ​

string

plugins ​

Get Signature ​

get plugins(): PluginManager

Returns ​

PluginManager

segment ​

Get Signature ​

get segment(): object

Returns ​
at() ​

readonly at(target): MessageSegment

Parameters ​
target ​

PlatformId

Returns ​

MessageSegment

button() ​

readonly button(options): MessageSegment

Parameters ​
options ​

ButtonOptions

Returns ​

MessageSegment

face() ​

readonly face(id): MessageSegment

Parameters ​
id ​

string | number

Returns ​

MessageSegment

file() ​

readonly file(file, options?): MessageSegment

Parameters ​
file ​

string | Buffer<ArrayBufferLike>

options? ​
local? ​

boolean

name? ​

string

Returns ​

MessageSegment

forward() ​

readonly forward(id): MessageSegment

Parameters ​
id ​

string

Returns ​

MessageSegment

image() ​

readonly image(file, options?): MessageSegment

file 为 URL 或本地路径；传 Buffer 会转成 base64 发送

Parameters ​
file ​

string | Buffer<ArrayBufferLike>

options? ​

object & Attachment = {}

Returns ​

MessageSegment

json() ​

readonly json(data): MessageSegment

Parameters ​
data ​

string | Record<string, unknown>

Returns ​

MessageSegment

markdown() ​

readonly markdown(content): MessageSegment

Parameters ​
content ​

string

Returns ​

MessageSegment

node() ​

readonly node(options): MessageSegment

Parameters ​
options ​
content ​

MessageInput

nickname ​

string

user_id ​

PlatformId

Returns ​

MessageSegment

raw() ​

readonly raw(type, data, attachment?): MessageSegment

Parameters ​
type ​

string

data ​

Record<string, unknown>

attachment? ​

Attachment

Returns ​

MessageSegment

record() ​

readonly record(file, options?): MessageSegment

Parameters ​
file ​

string | Buffer<ArrayBufferLike>

options? ​
local? ​

boolean

Returns ​

MessageSegment

reply() ​

readonly reply(messageId): MessageSegment

Parameters ​
messageId ​

PlatformId

Returns ​

MessageSegment

text() ​

readonly text(text): MessageSegment

Parameters ​
text ​

string

Returns ​

MessageSegment

video() ​

readonly video(file, options?): MessageSegment

Parameters ​
file ​

string | Buffer<ArrayBufferLike>

options? ​
local? ​

boolean

Returns ​

MessageSegment

self_id ​

Get Signature ​

get self_id(): string | undefined

Returns ​

string | undefined

services ​

Get Signature ​

get services(): MiokuServices

Returns ​

MiokuServices

Methods ​

addService() ​

addService<T>(name, value, cover?): () => void

注册一个运行时服务供其他插件取用，返回注销函数

Type Parameters ​

T ​

T = unknown

Parameters ​

name ​

string

value ​

T

cover? ​

boolean

Returns ​

() => void

botsForEvent() ​

botsForEvent(event): BotBase[]

观察到该事件的全部已连接 bot（首个即 primary）。 跨适配器去重后，被标记为重复的投递不会进入普通 handler， 但这里依然能看到全部参与方。

Parameters ​

event ​

Event

Returns ​

BotBase[]

command() ​

Call Signature ​

command(definition): () => void

注册消息命令；默认自动匹配框架前缀并在命中后消费消息

Parameters ​
definition ​

CommandDefinition

Returns ​

() => void

Call Signature ​

command(matcher, handler, options?): () => void

注册消息命令；默认自动匹配框架前缀并在命中后消费消息

Parameters ​
matcher ​

CommandMatcher

handler ​

CommandHandler

options? ​

CommandShortcutOptions

Returns ​

() => void

correlation() ​

correlation(event): CorrelationRecord | undefined

取事件所属的跨适配器关联记录。 同一条逻辑消息被多个适配器/bot 投递时，可从这里读到全部参与方。

Parameters ​

event ​

Event

Returns ​

CorrelationRecord | undefined

correlationStats() ​

correlationStats(): CorrelationStats | undefined

事件关联/去重的运行统计

Returns ​

CorrelationStats | undefined

createCmd() ​

createCmd(cmdStr, options?): object

解析命令行字符串为 命令 + 参数 + 选项

Parameters ​

cmdStr ​

string

options? ​

CreateCmdOptions = {}

Returns ​

object

cmd ​

cmd: string | undefined

options ​

options: Record<string, unknown>

params ​

params: string[]

createDB() ​

createDB<T>(filename, options?): Promise<Low<T>>

在指定路径创建一个 lowdb 数据库文件

Type Parameters ​

T ​

T extends object = object

Parameters ​

filename ​

string

options? ​
compress? ​

boolean

defaultData? ​

T

Returns ​

Promise<Low<T>>

createStore() ​

createStore<T>(defaultData, options?): Promise<Low<T>>

在插件目录下创建一个 JSON 数据存储

Type Parameters ​

T ​

T extends object = object

Parameters ​

defaultData ​

T

options? ​
__dirname? ​

string

compress? ​

boolean

filename? ​

string

importMeta? ​

ImportMeta

Returns ​

Promise<Low<T>>

cron() ​

cron(expression, handler): any

注册 cron 定时任务，插件卸载时自动停止

Parameters ​

expression ​

string

handler ​

CronHandler

Returns ​

any

dispose() ​

dispose(): Promise<void>

Returns ​

Promise<void>

getAdapter() ​

getAdapter<T>(name): T | undefined

按名称取适配器实例

Type Parameters ​

T ​

T extends Adapter = Adapter

Parameters ​

name ​

string

Returns ​

T | undefined

getDriver() ​

getDriver(): Driver

Returns ​

Driver

getQuoteMsg() ​

getQuoteMsg(event): Promise<MessageGetResult | null>

获取事件引用回复的消息内容。 返回 null 表示没有引用、拿不到对应 bot 或消息已失效。

Parameters ​

event ​
bot? ​

BotBase

quote_id? ​

string | null

self_id? ​

string

Returns ​

Promise<MessageGetResult | null>

handle() ​

handle<R>(route, handler): () => void

注册事件监听。route 支持层级路由，如 message、message.group、 onebotv11:message；返回取消监听函数。

Type Parameters ​

R ​

R extends string | readonly string[]

Parameters ​

route ​

R

handler ​

(event) => void | Promise<void>

Returns ​

() => void

hasRight() ​

hasRight(event): boolean

同 isAdmin，别名

Parameters ​

event ​

unknown

Returns ​

boolean

isAdmin() ​

isAdmin(event): boolean

事件发送者是否为 bot 主人、配置管理员、当前群群主或群管理员；等价于 permission: "admin"

Parameters ​

event ​

unknown

Returns ​

boolean

isGroupMsg() ​

isGroupMsg(event): boolean

Parameters ​

event ​

unknown

Returns ​

boolean

isMaster() ​

isMaster(event): boolean

事件发送者是否为 bot 主人（仅看 owners 名单，不识别群身份）

Parameters ​

event ​

unknown

Returns ​

boolean

isOwner() ​

isOwner(event): boolean

事件发送者是否为 bot 主人或当前群群主；等价于 permission: "owner"

Parameters ​

event ​

unknown

Returns ​

boolean

isOwnerOrAdmin() ​

isOwnerOrAdmin(event): boolean

同 isAdmin，保留旧名称

Parameters ​

event ​

unknown

Returns ​

boolean

isPrivateMsg() ​

isPrivateMsg(event): boolean

Parameters ​

event ​

unknown

Returns ​

boolean

match() ​

match<T>(event, pattern, quote?): Promise<{ message_id: string; } | null>

按模式匹配消息文本（支持正则/字符串/关键词数组）

Type Parameters ​

T ​

T extends HasMessage

Parameters ​

event ​

T

pattern ​

Record<string, MatchValue | MatchHandler<HasMessage>>

quote? ​

boolean

Returns ​

Promise<{ message_id: string; } | null>

mentionedBots() ​

mentionedBots(event): BotBase[]

事件里被 @ 到的、且本运行时已连接的 bot

Parameters ​

event ​

Event

Returns ​

BotBase[]

noticeAdmins() ​

noticeAdmins(message, options?): Promise<void>

向所有管理员发送消息

Parameters ​

message ​

MessageInput

options? ​

NoticeOptions

Returns ​

Promise<void>

noticeFriends() ​

noticeFriends(userIds, message, options?): Promise<void>

向多个好友发送消息

Parameters ​

userIds ​

readonly string[]

message ​

MessageInput

options? ​

NoticeOptions

Returns ​

Promise<void>

noticeGroups() ​

noticeGroups(groupIds, message, options?): Promise<void>

向多个群发送消息

Parameters ​

groupIds ​

readonly string[]

message ​

MessageInput

options? ​

NoticeOptions

Returns ​

Promise<void>

noticeOwners() ​

noticeOwners(message, options?): Promise<void>

向所有主人发送消息

Parameters ​

message ​

MessageInput

options? ​

NoticeOptions

Returns ​

Promise<void>

onBot() ​

onBot<K>(type, handler): () => void

监听 bot 连接 / 断开

Type Parameters ​

K ​

K extends "connected" | "disconnected"

Parameters ​

type ​

K

handler ​

(event) => void | Promise<void>

Returns ​

() => void

pickBot() ​

pickBot<T>(bot_id): T | undefined

按 bot_id 取指定 bot

Type Parameters ​

T ​

T extends BotBase = BotBase

Parameters ​

bot_id ​

string | number

Returns ​

T | undefined

pickReplyBot() ​

pickReplyBot(event): BotBase | undefined

这条消息应当由哪个 bot 回应：优先「被 @ 的 bot」，其次是关联组里首个到达的 bot。 插件可用它替代隐式的 event.bot，从而不受适配器到达顺序影响。

Parameters ​

event ​

Event

Returns ​

BotBase | undefined

text() ​

text(source, options?): string

提取事件消息的纯文本

Parameters ​

source ​

Message | HasMessage

options? ​
trim? ​

boolean | "whole" | "each"

Returns ​

string

updateConfig() ​

updateConfig(updater): Promise<void>

修改框架配置（owners、admins、plugins 等）

Parameters ​

updater ​

(config) => void | Promise<void>

Returns ​

Promise<void>

Released under the MIT License with love.

Copyright © 2026 Jerryplusy