脚本插件（JavaScript）

Bngeuit 支持直接用 JavaScript 编写插件：把 .js 文件放进 plugins/ 目录即自动加载，无需编译打包，适合快速原型与热更新。

最小示例

plugins/hello.js：

plugin = {
    name: 'hello',
    version: '1.0',
    description: '最简单的脚本插件'
};

function onEnable() {
    bngeuit.info('脚本插件已启用！');
}

// 监听群 @ 消息（内置事件包可写简名）
bngeuit.on('GroupAtMessageEvent', (e) => {
    Bngeuit.replyGroupText(e.getGroupOpenid(), e.getId(), 1, '你好，' + e.getAuthor().username());
});

// 注册命令 /hello
bngeuit.registerCommand('hello', (sender, args) => {
    sender.sendMessage('Hello from JS!');
});

元信息（plugin 对象）

脚本顶层声明全局 plugin 对象，字段对应 JAR 插件的 plugin.yml：

字段	必填	说明
name	✅	插件名（也用于 plugin load/unload/reload 按名管理）
version	否	版本，默认 1.0
description	否	描述
author	否	作者
depend / softdepend	否	依赖的插件名数组（脚本之间按依赖拓扑排序加载）

生命周期

onLoad()      # 加载（只执行脚本定义，不注册业务）
    ↓
onEnable()    # 启用（此时可注册事件/命令）
    ↓
onActive()    # 机器人上线（两种接入模式统一触发一次）
    ↓
onDisable()   # 卸载（自动注销已注册的事件/命令，释放 JS 上下文）

四个函数均可选，不定义则跳过。onActive 在机器人上线时触发一次（WS 模式全部分片就绪 / Webhook 模式回调服务就绪），适合启动定时任务等「上线初始化」；onDisable 无需手动注销——框架会自动清理该脚本注册的全部事件与命令。

全局 bngeuit 桥接对象（ScriptBridge）

每个脚本注入全局 bngeuit 对象，提供与 Java 插件等价的能力：

API	说明
bngeuit.on(事件, handler[, options])	注册事件监听。事件 可为 Java.type(...) 类 / Java Class / 类名字符串（内置事件包可写简名如 'GroupAtMessageEvent'）；options：{ priority: 'P1'~'P6', ignoreCancelled: true }
bngeuit.registerCommand(名, def)	注册命令。def 为函数（简单形式）或 { description, aliases, handler, subcommands } 对象（完整形式）
bngeuit.api()	获取原始 BotApi（上传、流式消息等高级 API）
bngeuit.info / warn / error(msg)	插件日志（前缀为脚本插件名）
bngeuit.getDataFolder()	插件数据目录 plugins/<插件名>/

全局 Bngeuit 门面

脚本内直接可用全局变量 Bngeuit 调用静态方法（发消息、调度器、事件总线、媒体文件等），等价于 Java 侧 Bngeuit.xxx，用法完全一致。

访问 Java 类

// 推荐：Java.type 拿类对象传给 bngeuit.on
const E = Java.type('cn.org.bukkit.bngeuit.event.receive.GroupAtMessageEvent');
bngeuit.on(E, (e) => { /* ... */ });

// 也可用 Packages.包名.类名；已加载插件 JAR 中的类同样可解析

线程模型

每个脚本拥有独立的 GraalJS 上下文（非线程安全），所有 JS 回调（生命周期、事件、命令）在每脚本锁内串行执行——同一脚本内事件处理有序、无并发竞争。所有脚本共享同一个 Truffle Engine（编译/解析缓存复用，多脚本不重复初始化）。

热管理

• plugin load <插件名> —— 热加载
• plugin unload <插件名> —— 热卸载（执行 onDisable 并释放上下文）
• plugin reload <插件名> —— 热重载（卸载后从源文件重新加载启用）

详见 命令系统。