koishi-plugin-microcommands

通过指令输入 JavaScript 代码来定义指令！

用法介绍

微指令允许管理员使用指令microcommand来定义指令。

• microcommand define <name> <code...>

  定义一个微指令。name是指令名，code是指令的 JavaScript 代码。指令定义的 API 见下文。默认需要 4 级权限。

• microcommand remove <name>

  删除指定的微指令。默认需要 4 级权限。

• microcommand show <name>

  显示指定微指令的源代码。默认不要求权限。

• microcommand list

  显示当前注册的微指令列表。默认不要求权限。

每个注册的微指令默认都是microcommand的层级式子指令（除非它已经是某个指令的派生式子指令）。建议用官方插件commands提供的command <name> -p <parentName>来更改微指令所属的父级指令（或command <name> -P来将其修改为顶级指令），或者在控制台的“指令管理”中操作。

微指令 API

在微指令定义的代码中，存在以下局部变量（尽管是变量，但除了可以将ctx赋值为添加了过滤器的ctx〔如ctx = ctx.platform("onebot")〕之外，不要给这些变量赋值）：

• name：当前微指令的名称。
• ctx：当前插件上下文。在整段定义代码运行完之后，会被替换成一个内层插件上下文，以实现服务依赖的注入。
• require(moduleSpec)：用来导入 Node.js 模块。
• inject(services)：注入服务依赖，相当于一般插件的export const inject = services。
• signature(def, desc?, config?)：设置指令的基本信息。除了第一个参数的开头不写指令名称（如果指令没有参数则传入空字符串即可）以外与ctx.command()的参数相同。
• option(name, desc?, config?)：定义指令选项。同cmd.option()。
• alias(name, config?)：定义指令别名。同cmd.alias()。
• usage(text)：定义指令使用说明。同cmd.usage()。
• example(example)：定义指令使用示例。同cmd.example()。
• userFields(fields)：定义指令需要用到的用户数据字段。同cmd.userFields()。
• channelFields(fields)：定义指令需要用到的频道数据字段。同cmd.channelFields()。
• before(checker, append?)：定义指令的检测函数。同cmd.before()。
• action(action, prepend?)：定义指令的执行函数。同cmd.action()。
• locale(locale, dict)：定义指令的本地化字符串。同ctx.i18n.define(locale, { commands: { [name]: dict } })。

此外，koishi 包导出的所有函数和对象都在微指令定义环境中成为了局部变量，可以直接使用。

示例

下面是一个简单的微指令示例：

//microcommand define greet
signature("[name:text]", "打招呼", { checkUnknown: true })
option("count", "-c <count:number>", "打招呼次数", { fallback: 1 })
action(async ({ session, options: { count } }, name) => {
  for (let i = 0; i < count; i++) {
    await session.send("你好，" + h.escape(name || "世界") + "！")
  }
})

下面是包含国际化支持的微指令示例：

//microcommand define greet
signature("[name:text]", { checkUnknown: true })
option("count", "-c <count:number>", { fallback: 1 })
action(async ({ session, options: { count } }, name) => {
  for (let i = 0; i < count; i++) {
    await session.send(session.i18n(".greeting", [name || session.i18n(".default-name")]))
  }
})
locale("zh-CN", {
  description: "打招呼",
  options: {
    count: "打招呼次数",
  },
  messages: {
    greeting: "你好，{0}！",
    "default-name": "世界",
  },
})
locale("en-US", {
  description: "Send greetings",
  options: {
    count: "Repeat count",
  },
  messages: {
    greeting: "Hello, {0}!",
    "default-name": "world",
  },
})