GSTE

简介

群脚本引擎（GSTE）是一个为即时通讯群组设计的脚本执行环境。它允许开发者在安全的沙箱中编写自定义逻辑，实现自动回复、消息过滤、群管功能等。

快速开始

一个最简单的群脚本只需要导出一个事件处理函数。以下是一个自动欢迎新成员的示例：

// 当用户进入群聊时触发
function onEnter(event) {
    // 发送欢迎消息
    sendGroupMessage("欢迎加入本群！请遵守群规~");

    // 显示系统提示（仅自己可见）
    WSystemMsg("新成员已进入");
}

脚本结构

群脚本通过导出特定名称的函数来响应不同事件。引擎会自动识别并调用这些函数：

生命周期

onEnter - 进入群聊

当用户打开群聊窗口时触发，适合初始化群相关数据或发送欢迎信息。

function onEnter(event) {
    // event.contact 包含群基本信息
    const group = getCurrentGroup();
    log("进入群聊:", group.groupName);

    // 读取之前保存的变量
    const count = getVariable("visitCount") || 0;
    setVariable("visitCount", count + 1);
}

onSend - 发送消息前拦截

在消息实际发送前触发，可用于内容审核、自动修正或阻止发送。

function onSend(event) {
    // event.content 是消息文本
    const text = event.content;

    // 检查敏感词
    if (text.includes("广告")) {
        infomsg("消息包含敏感词，已阻止发送");
        return false; // 阻止发送
    }

    // 自动追加签名
    if (!text.endsWith("[自动发送]")) {
        event.rawMessage.text += " [自动发送]";
    }
}

onMessage - 接收消息

当群内有新消息时触发（包括自己发送的消息），可用于自动回复或消息记录。

function onMessage(event) {
    // 简单的关键词回复
    if (event.content === "帮助") {
        sendGroupMessage("可用命令：帮助、状态、规则");
    }

    // 管理员命令
    if (event.content.startsWith("/") && event.sender.isAdmin) {
        handleAdminCommand(event.content);
    }
}

上下文对象

每个事件处理函数都会接收一个 event 对象，包含当前事件的详细信息：

事件对象结构

onSend 事件对象

{
    content: "消息文本内容",           // 消息文本
    messageType: "text",              // 消息类型
    timestamp: 1711882800000,         // 时间戳
    sender: {
        userId: "user_123",
        name: "用户名"
    },
    rawMessage: { ... }               // 原始消息对象，可修改
}

API 参考：消息相关

log("调试信息", someVariable);
warn("警告信息");
error("错误信息");

API 参考：群组信息

{
    groupId: "12345",           // 群ID
    groupName: "技术交流群",    // 群名称
    groupDesc: "群描述...",   // 群描述
    memberCount: 128,          // 成员数量
    isAdmin: true,              // 当前用户是否为管理员
    isOwner: false             // 当前用户是否为群主
}

{
    userId: "user_123",
    name: "我的昵称",
    isAdmin: true,
    isOwner: false
}

API 参考：变量存储

脚本引擎提供键值对存储功能，数据按群隔离，重启后清空（内存存储）。

function onMessage(event) {
    // 获取当前计数
    let count = getVariable("msgCount") || 0;
    count++;

    // 每10条消息提醒一次
    if (count % 10 === 0) {
        sendGroupMessage(`已接收 ${count} 条消息！`);
    }

    // 保存计数
    setVariable("msgCount", count);
}

API 参考：工具函数

async function onEnter(event) {
    await delay(1000);  // 等待1秒
    sendGroupMessage("延迟发送的消息");
}

API 参考：字符串扩展

引擎为 String 原型添加了安全检查的方法：

const text = "这是一段测试文本";

// 检查单个关键词
if (text.checkIfrom("测试")) {
    log("包含关键词");
}

// 检查多个关键词
const keywords = ["广告", "推广", "spam"];
if (text.checkIfrom(keywords)) {
    infomsg("检测到敏感内容");
}

API 参考：正则匹配

if (RegexUxs.run("^帮助$", event.content)) {
    sendGroupMessage("可用命令：帮助、状态");
}

const matches = RegexUxs.check("\\d+", event.content);
if (matches) {
    sendGroupMessage(`提取到数字: ${matches[0]}`);
}

API 参考：HTTP 网络请求

const xhr = HttpNetServer.create();

function onMessage(event) {
    if (event.content.startsWith("天气")) {
        const city = event.content.slice(2).trim();
        if (!city) {
            sendGroupMessage("请指定城市，如：天气 北京");
            return;
        }

        const xhr = HttpNetServer.create();
        HttpNetServer.setTimeout(xhr, 5000);
        HttpNetServer.open(xhr, "GET", `https://api.example.com/weather?city=${encodeURIComponent(city)}`);
        HttpNetServer.setHeader(xhr, "Content-Type", "application/json");
        HttpNetServer.onState(xhr, () => {
            if (HttpNetServer.getReadyState(xhr) === 4) {
                const status = HttpNetServer.getStatus(xhr);
                if (status === 200) {
                    const response = HttpNetServer.getResponse(xhr);
                    try {
                        const data = JSON.parse(response);
                        sendGroupMessage(`${city}天气：${data.weather}，温度 ${data.temp}℃`);
                    } catch (e) {
                        sendGroupMessage("解析天气数据失败");
                    }
                } else {
                    sendGroupMessage(`请求失败，状态码：${status}`);
                }
            }
        });
        
        HttpNetServer.send(xhr);
        WSystemMsg(`正在查询 ${city} 天气...`);
    }
}

安全限制

为了保障系统安全，脚本引擎实施了严格的安全策略：

禁止访问的 API

代码扫描规则

• 检测 while/for 循环（防止死循环）
• 检测 __proto__, constructor, prototype 访问
• 检测 import/export 语句
• 检测 with 语句
• 检测 debugger 语句
• 检测 new Function 和 eval 调用
• 检测危险全局变量访问字符串

字符串内容检查

所有传入 WSystemMsg, infomsg, setVariable 的字符串都会经过危险内容扫描，如果包含以下模式将被拒绝：

• window, document, location 等危险全局变量名
• eval, Function, setTimeout 等可执行方法
• DOM 操作相关字符串

资源限制

完整示例

示例 1：消息审核系统

// 敏感词列表
const sensitiveWords = ["广告", "推广", "加微信", "qq群"];
// 警告阈值
const WARN_LIMIT = 3;

function onSend(event) {
    const text = event.content;

    // 检查敏感词
    if (text.checkIfrom(sensitiveWords)) {
        infomsg("⚠️ 消息包含敏感词，请修改后发送");
        return false; // 阻止发送
    }

    // 检查发送频率
    const user = getCurrentUser();
    const key = `msg_count_${user.userId}`;
    let count = getVariable(key) || 0;
    count++;

    if (count > WARN_LIMIT) {
        infomsg("⚠️ 发送过于频繁，请稍后再试");
        return false;
    }

    setVariable(key, count);

    // 5秒后重置计数
    delay(5000).then(() => {
        const current = getVariable(key) || 0;
        if (current > 0) {
            setVariable(key, current - 1);
        }
    });
}

最佳实践

1. 错误处理

虽然引擎有 try-catch 包装，但建议关键逻辑自行处理异常：

function safeOperation() {
    try {
        // 可能出错的操作
        const data = JSON.parse(getVariable("config") || "{}");
        return data;
    } catch (e) {
        error("解析配置失败:", e.message);
        return {};
    }
}

2. 变量命名

• 使用描述性名称：userWarningCount 优于 cnt
• 添加前缀避免冲突：bot_config, bot_state
• 常量使用大写：MAX_RETRY = 3

3. 性能优化

• 避免在 onMessage 中频繁读写变量，可缓存到局部变量
• 大数据量使用 Slicetion 分批处理
• 复杂计算考虑使用 delay(0) 让出执行权