插件开发指南

SillyGirl 的插件系统基于 Goja JavaScript 引擎，完整支持 ECMAScript 5.1。插件以 .js 文件形式存在，通过顶部注释声明元数据，由框架自动加载、匹配和执行。

插件结构

一个最小插件由注释元数据和执行代码组成：

/**
 * @title HelloWorld
 * @rule raw ^你好$
 */

s.reply("Hello World!");

插件文件可以包含多个 @rule，每条规则独立匹配：

/**
 * @title 多功能助手
 * @rule raw ^你好$
 * @rule raw ^再见$
 * @rule 天气 [城市]
 */

const content = s.getContent();
if (content === "你好") {
  s.reply("Hello!");
} else if (content === "再见") {
  s.reply("Goodbye!");
} else {
  const city = s.param("城市");
  s.reply(`${city}今天天气晴朗！`);
}

注释元数据

字段	类型	必填	说明
`title`	string	是	插件标题，显示在管理面板和插件市场
`rule`	string	否	消息匹配规则，支持多行。详见规则匹配语法
`cron`	string	否	定时任务表达式，支持多行，格式为 `平台 cron表达式`
`priority`	number	否	匹配优先级，数字越大越优先，默认 0
`on_start`	boolean	否	`true` 时随系统启动执行一次，常用于初始化服务
`module`	boolean	否	`true` 时表示为模块插件，不响应消息规则
`web`	boolean	否	`true` 时表示为 Web 插件，可声明 HTTP 路由
`version`	string	否	版本号，如 `v1.0.0`
`author`	string	否	作者名
`description`	string	否	插件描述
`icon`	string	否	插件图标 URL
`public`	boolean	否	`true` 时允许发布到插件市场
`disable`	boolean	否	`true` 时禁用插件
`admin`	boolean	否	`true` 时仅管理员可触发
`platform`	string	否	限制平台，如 `qq`、`web`

元数据示例

/**
 * @title 每日早报
 * @rule raw ^早报$
 * @cron qq 0 9 * * *
 * @cron web 0 9 * * *
 * @priority 10
 * @version v1.2.0
 * @author cdle
 * @description 每天早上9点推送新闻早报
 * @icon https://example.com/icon.png
 * @public true
 */

全局对象与 API

sender (s)

当前消息的 Sender 对象，是插件中最核心的交互入口。

用户信息

s.getUserId()       // 获取用户ID（string）
s.getUserName()     // 获取用户昵称（string）
s.getChatId()       // 获取群聊ID，私聊时为空字符串（string）
s.getChatName()     // 获取群聊名称（string）
s.getMessageId()    // 获取消息ID（string）
s.getPlatform()     // 获取平台类型，如 "qq"、"web"（string）
s.getBotId()        // 获取当前机器人ID（string）
s.isAdmin()         // 判断用户是否为管理员（boolean）

内容操作

s.getContent()      // 获取消息原始内容（string）
s.setContent(text)  // 修改当前消息内容（影响后续插件匹配）
s.continue()        // 继续匹配后续规则（默认匹配成功即停止）

回复消息

s.reply("文本")     // 回复文本消息，返回 { message_id, error }
s.reply("文本1", "文本2")  // 多段回复

参数捕获

// 对于规则 "天气 [城市]"
s.param("城市")     // 通过名称获取捕获组
s.param(1)          // 通过索引获取第1个捕获组（从1开始）
s.get(1)            // param 的别名
s.getAllMatch()     // 获取所有匹配组（二维数组）

群管功能

s.kick(userId)          // 踢出群成员
s.unkick(userId)        // 取消踢出
s.ban(userId, duration) // 禁言，duration 为秒数
s.unban(userId)         // 解除禁言
s.recallMessage(messageId)  // 撤回消息

Bucket(name)

持久化键值存储，数据自动持久化到 BoltDB 或 Redis。

const bucket = Bucket("myapp");

// 基础读写
bucket.set("key", "value");
const value = bucket.get("key", "default_value");  // 支持默认值

// 类型自动转换
bucket.set("count", 100);        // 存储为数字
bucket.set("enabled", true);     // 存储为布尔值
bucket.set("data", { a: 1 });    // 存储为对象（自动 JSON 序列化）

// 监听变更
bucket.watch("key", (oldValue, newValue, key) => {
  console.log(`${key} changed: ${oldValue} -> ${newValue}`);
});

// 其他方法
bucket.keys();       // 获取所有键名（string[]）
bucket.getAll();     // 获取所有键值（object）
bucket.delete("key"); // 删除键
bucket.empty();      // 清空 bucket
bucket.len();        // 获取键数量（number）

作用域说明：每个 Bucket 是独立的命名空间，不同插件建议使用不同的 Bucket 名称，避免键冲突。

Cron()

定时任务调度器，支持标准 Cron 表达式。

const task = Cron();

// 添加任务（6字段：秒 分 时 日 月 周）
const { id, error } = task.add("*/5 * * * * *", () => {
  console.log("每5秒执行一次");
});

// 添加任务（5字段：分 时 日 月 周，秒自动补0）
const { id, error } = task.add("0 9 * * *", () => {
  console.log("每天早上9点执行");
});

// 移除任务
task.remove(id);

注意：插件中更推荐通过 @cron 注释声明定时任务，由框架统一管理生命周期。

Express()

HTTP 服务路由注册（基于内置 Web 服务器）。

const app = Express();

app.get("/hello", (req, res) => {
  res.send("Hello World!");
});

app.post("/api/data", (req, res) => {
  const body = req.body();
  res.json({ success: true, data: body });
});

注意：Web 插件需要声明 @web true 元数据，且框架会自动清理已注册的路由。

其他全局函数

sleep(ms)           // 同步阻塞睡眠（毫秒）
md5(str)            // MD5 哈希
uuid()              // 生成 UUID
running()           // 判断当前插件是否仍在运行（boolean）
fmt.Sprintf(format, ...args)  // 格式化字符串
fmt.Printf(format, ...args)   // 格式化输出
time.Now()          // 获取当前时间对象
time.Sleep(ms)      // 睡眠（毫秒）
time.Unix(sec)      // Unix 时间戳转时间对象
time.Parse(str, layout, locale)  // 解析时间字符串

规则匹配语法

规则（@rule）支持多种语法，框架会自动转换为正则表达式进行匹配。

基础规则

/**
 * @rule raw ^你好$      // 原始正则，完全匹配"你好"
 * @rule raw ^/help$     // 原始正则，匹配 "/help"
 * @rule 你好            // 自动转换为 ^你好$，完全匹配
 * @rule ^天气           // 以"天气"开头
 * @rule 帮助$           // 以"帮助"结尾
 */

参数捕获

/**
 * @rule 天气 [城市]              // 匹配"天气 北京"，捕获"北京"
 * @rule [操作:登录,注册,退出]     // 匹配"登录"、"注册"或"退出"
 * @rule 查询 ?                   // ? 匹配任意非空白字符
 * @rule 搜索 *                   // * 匹配任意内容（包括空白）
 */

可选参数

/**
 * @rule 天气 [城市?]             // ? 表示可选，匹配"天气"或"天气 北京"
 */

优先级与冲突

当多条规则可能同时匹配一条消息时，框架按以下顺序决定执行：

监听规则（s.listen 注册的）优先于普通规则
高 priority 优先于低 priority
同一优先级下，先加载的插件优先

使用 s.continue() 可以让当前插件执行完毕后继续匹配后续规则：

/**
 * @title 日志中间件
 * @rule *
 * @priority 999
 */

console.log("收到消息:", s.getContent());
s.continue();  // 继续让其他插件处理

消息监听与会话

s.listen() 是实现对话式交互的核心 API，支持等待用户后续输入并按规则匹配。

基础用法

/**
 * @title 注册流程
 * @rule raw ^注册$
 */

s.reply("请输入你的用户名：");
const result = s.listen({
  rules: ["raw ^(.+)$"],  // 捕获任意输入
  timeout: 30000,          // 30秒超时
  handle: (s2) => {
    const username = s2.param(1);
    s2.reply(`用户名 "${username}" 注册成功！`);
  },
});

if (!result) {
  s.reply("注册超时，请重试。");
}

监听选项

s.listen({
  rules: ["规则1", "规则2"],        // 匹配规则数组
  timeout: 10000,                   // 超时时间（毫秒）
  handle: (s2) => { ... },          // 匹配后的回调函数
  private: true,                    // 允许在私聊中触发
  group: true,                      // 允许在群聊中触发
  require_admin: false,             // 是否要求管理员权限
  allow_platforms: ["qq"],          // 限制平台
  prohibit_platforms: ["web"],      // 禁止平台
  allow_users: ["12345"],           // 仅允许指定用户
  allow_groups: ["67890"],          // 仅允许指定群组
  user_id: s.getUserId(),           // 仅监听当前用户
  chat_id: s.getChatId(),           // 仅监听当前群组
});

持久化监听

添加 "persistent" 参数可创建长期有效的监听器：

/**
 * @title 关键词监控
 * @rule raw ^启动监控$
 */

s.listen({
  rules: ["raw ^(.+)$"],
  timeout: 0,           // 0 表示永不超时
  handle: (s2) => {
    console.log("监控到消息:", s2.getContent());
    // 返回空字符串或 undefined 会继续监听
  },
}, "persistent");

s.reply("监控已启动");

HoldOn 与 GoAgain

/**
 * @title 循环输入
 * @rule raw ^开始$
 */

function ask() {
  s.reply("请输入内容（输入'结束'停止）：");
  const r = s.listen({
    rules: ["raw ^(.+)$"],
    timeout: 30000,
    handle: (s2) => {
      if (s2.param(1) === "结束") {
        s2.reply("已结束");
        return;
      }
      s2.reply("你输入了：" + s2.param(1));
      return s2.holdOn("开始");  // 重新触发当前插件
    },
  });
}
ask();

HTTP 路由

声明 @web true 的插件可以注册 HTTP 路由：

/**
 * @title WebAPI 示例
 * @web true
 */

Express().get("/api/status", (req, res) => {
  res.json({
    status: "ok",
    time: new Date().toISOString(),
    plugin: "WebAPI 示例",
  });
});

Express().post("/api/echo", (req, res) => {
  const body = req.body();
  res.json({ echo: body });
});

Request / Response 对象

req.url()           // 请求 URL
req.method()        // 请求方法
req.header("key")   // 获取请求头
req.body()          // 获取请求体（已解析 JSON）
req.query("key")    // 获取 URL 参数
req.path()          // 请求路径
req.param("key")    // 获取路径参数

res.send("text")    // 发送文本响应
res.json(obj)       // 发送 JSON 响应
res.redirect(url)   // 重定向
res.status(code)    // 设置状态码

定时任务

通过 @cron 注释声明定时任务：

/**
 * @title 每日提醒
 * @cron qq 0 9 * * *       // 每天早上9点（QQ平台）
 * @cron web 0 12 * * *     // 每天中午12点（Web平台）
 */

s.reply("该起床啦！今天是 " + time.Now().Format("2006-01-02"));

Cron 表达式格式（5字段或6字段）：

秒(可选) 分 时 日 月 周

字段	范围	特殊字符
秒	0-59	`, - * /`
分	0-59	`, - * /`
时	0-23	`, - * /`
日	1-31	`, - * /`
月	1-12	`, - * /`
周	0-6（0=周日）	`, - * /`

示例：

表达式	说明
`/5 * * *`	每5分钟
`0 /1 * *`	每小时
`0 9 * * 1-5`	工作日早上9点
`0 0 1 * *`	每月1号零点
`/30 * * * *`	每30秒

完整示例

示例 1：记忆名字

/**
 * @title 记忆名字
 * @rule raw ^我是谁$
 * @rule 我是[姓名]
 * @version v1.0.0
 * @author cdle
 */

const user = Bucket("user_names");
const name = s.param("姓名");

if (!name) {
  const stored = user.get(s.getUserId());
  if (stored) {
    s.reply(`你是 ${stored}`);
  } else {
    s.reply("我还不知道你是谁，告诉我吧：我是[你的名字]");
  }
} else {
  user.set(s.getUserId(), name);
  s.reply(`好的，我记住你了，${name}！`);
}

示例 2：倒计时提醒

/**
 * @title 倒计时
 * @rule 倒计时 [分钟:1,2,3,5,10] 分钟
 * @version v1.0.0
 */

const minutes = parseInt(s.param(1));
s.reply(`好的，${minutes}分钟后提醒你。`);

// 使用 Cron 不太适合一次性延时，这里用 sleep
// 注意：sleep 会阻塞，长时间任务建议用 cron 或其他方式
go(() => {
  sleep(minutes * 60 * 1000);
  s.reply("⏰ 时间到了！");
});

注：实际开发中长时间后台任务建议使用 @cron 或外部调度。

示例 3：简易 HTTP API

/**
 * @title 天气查询 API
 * @web true
 * @version v1.0.0
 */

Express().get("/api/weather", (req, res) => {
  const city = req.query("city") || "北京";
  // 实际场景中这里应调用第三方天气 API
  res.json({
    city: city,
    weather: "晴",
    temperature: "25°C",
    updated_at: time.Now().Format("2006-01-02 15:04:05"),
  });
});

调试技巧

1. 使用终端模式

./sillyGirl -t

终端模式是开发插件的最快方式，修改插件后立即生效，无需重启。

2. 开启调试模式

在 Admin 面板将 sillyGirl.debug 设为 true，或在插件中：

console.log("调试信息:", someVariable);
console.debug("详细调试:", detailedInfo);
console.error("错误:", err);

3. 查看插件状态

在 Admin 面板的"插件"页面，可以查看：

插件加载状态
规则列表
错误日志
性能统计

4. 安全执行

插件运行异常时框架会自动捕获 panic，不会影响其他插件或核心服务。你可以在 Admin 面板查看具体的错误堆栈。

5. 模块复用

将公共逻辑抽取为 @module true 插件，其他插件通过 require 或全局变量复用：

/**
 * @title 工具模块
 * @module true
 */

// 定义全局工具函数
RegistFuncs["utils"] = {
  formatTime: (t) => t.Format("2006-01-02"),
  isWeekend: (t) => t.Weekday() === 0 || t.Weekday() === 6,
};

FilesExpand file tree

plugin-dev.md

Latest commit

History

plugin-dev.md

File metadata and controls

插件开发指南

目录

插件结构

注释元数据

元数据示例

全局对象与 API

sender (s)

用户信息

内容操作

回复消息

参数捕获

群管功能

Bucket(name)

Cron()

Express()

其他全局函数

规则匹配语法

基础规则

参数捕获

可选参数

优先级与冲突

消息监听与会话

基础用法

监听选项

持久化监听

HoldOn 与 GoAgain

HTTP 路由

Request / Response 对象

定时任务

完整示例

示例 1：记忆名字

示例 2：倒计时提醒

示例 3：简易 HTTP API

调试技巧

1. 使用终端模式

2. 开启调试模式

3. 查看插件状态

4. 安全执行

5. 模块复用