Wblist - 黑白名单

wblist 模块提供了黑白名单管理功能，包含 blacklist 和 whitelist 两个命名空间，分别用于管理服务器的黑名单和白名单。

版本要求

Wblist API 在 SDK v0.3.2 中引入。需要 EasyBot 2.1.0-dev.6 或更高版本。

Blacklist - 黑名单

blacklist 命名空间提供了黑名单的查询、添加和移除功能。

API 参考

declare namespace blacklist {
    function InBlackList(accountId: string): boolean;
    function RemoveBlackList(userId: string, opAccount: string, opName: string, opGroupId: string): Promise;
    function AddBlackList(userId: string, opAccount: string, opName: string, opGroupId: string, banReason: string): Promise;
}

InBlackList()

功能描述：检查指定账号是否在黑名单中。

语法：

blacklist.InBlackList(accountId: string): boolean

参数：

• accountId：要检查的账号 ID

返回值：true 在黑名单中，false 不在

使用示例：

if (blacklist.InBlackList("123456789")) {
    logger.info("该账号已被封禁");
}

AddBlackList()

功能描述：将账号添加到黑名单。

语法：

blacklist.AddBlackList(userId: string, opAccount: string, opName: string, opGroupId: string, banReason: string): Promise

参数：

• userId：被封禁的账号 ID
• opAccount：操作者账号 ID
• opName：操作者名称
• opGroupId：所属群号
• banReason：封禁原因

使用示例：

await blacklist.AddBlackList(
    "123456789",        // 被封禁账号
    "admin_001",        // 操作者ID
    "管理员",            // 操作者名称
    "987654321",        // 群号
    "发布违规内容"       // 原因
);
logger.info("已添加到黑名单");

RemoveBlackList()

功能描述：将账号从黑名单中移除。

语法：

blacklist.RemoveBlackList(userId: string, opAccount: string, opName: string, opGroupId: string): Promise

参数：

• userId：要解封的账号 ID
• opAccount：操作者账号 ID
• opName：操作者名称
• opGroupId：所属群号

使用示例：

await blacklist.RemoveBlackList(
    "123456789",
    "admin_001",
    "管理员",
    "987654321"
);
logger.info("已从黑名单移除");

---

Whitelist - 白名单

whitelist 命名空间提供了白名单的查询、添加和移除功能。

API 参考

declare namespace whitelist {
    function InWhiteList(accountId: string): boolean;
    function IsServerWhiteListEnabled(serverToken: string): boolean;
    function IsGroupWhiteListEnabled(groupId: string, platform?: string | null): boolean;
    function RemoveWhiteList(accountId: string, opId: string, opName: string, groupId: string): Promise;
    function AddWhiteList(accountId: string, opId: string, opName: string, groupId: string, reason: string | null): Promise;
}

InWhiteList()

功能描述：检查指定账号是否在白名单中。

语法：

whitelist.InWhiteList(accountId: string): boolean

参数：

• accountId：要检查的账号 ID

返回值：true 在白名单中，false 不在

IsServerWhiteListEnabled()

功能描述：检查指定服务器是否启用了 EasyBot 白名单。

语法：

whitelist.IsServerWhiteListEnabled(serverToken: string): boolean

参数：

• serverToken：服务器 Token

IsGroupWhiteListEnabled()

功能描述：检查指定群是否开启了白名单。

语法：

whitelist.IsGroupWhiteListEnabled(groupId: string, platform?: string | null): boolean

参数：

• groupId：群号
• platform：平台（默认为 QQ，可传 null）

AddWhiteList()

功能描述：将账号添加到白名单。

语法：

whitelist.AddWhiteList(accountId: string, opId: string, opName: string, groupId: string, reason: string | null): Promise

参数：

• accountId：账号 ID
• opId：操作者 ID
• opName：操作者名称
• groupId：群号
• reason：原因（可为 null）

RemoveWhiteList()

功能描述：将账号从白名单中移除。

语法：

whitelist.RemoveWhiteList(accountId: string, opId: string, opName: string, groupId: string): Promise

---

实战示例

自动封禁违规用户

bus.on("group_message_event", (event) => {
    const message = event.RawMessage;
    const senderId = event.SenderId;

    // 检查是否已经在黑名单
    if (blacklist.InBlackList(senderId)) {
        event.Context.Reply(new MessageChain().Text("您已被封禁，无法使用此功能"));
        event.IsCanceled = true;
        return;
    }

    // 检测违规关键词
    const bannedWords = ["违规词1", "违规词2", "违规词3"];
    for (const word of bannedWords) {
        if (message.includes(word)) {
            // 加入黑名单
            blacklist.AddBlackList(
                senderId,
                event.SelfId,
                "自动封禁系统",
                event.PeerId,
                `发送违规内容: ${word}`
            );

            event.Context.Reply(new MessageChain().Text("您因发送违规内容已被封禁"));
            event.IsCanceled = true;
            return;
        }
    }
});

白名单验证

bus.on("player_login", (server, playerName, playerUuid) => {
    // 检查服务器是否开启了白名单
    const serverToken = server.Session.Info.CachedServerToken;
    if (!whitelist.IsServerWhiteListEnabled(serverToken)) {
        return; // 未开启白名单，放行
    }

    // 获取玩家绑定的社交账号
    const player = db.GetPlayerByName(playerName);
    if (!player || !player.SocialAccount) {
        return {
            kicked: true,
            reason: "本服务器开启了白名单，请先绑定账号"
        };
    }

    // 检查是否在白名单中
    if (!whitelist.InWhiteList(player.SocialAccount.Uuid)) {
        return {
            kicked: true,
            reason: "您不在本服务器的白名单中"
        };
    }

    logger.info(`白名单验证通过: ${playerName}`);
});

管理命令：封禁/解封

bus.on("group_message_event", (event) => {
    const message = event.RawMessage;
    const senderId = event.SenderId;

    // 检查是否有管理员权限（此处简化处理）
    if (!isAdmin(senderId)) return;

    // 封禁命令: /ban @用户 原因
    const banMatch = message.match(/^\/ban\s+(\d+)\s+(.+)/);
    if (banMatch) {
        const targetId = banMatch[1];
        const reason = banMatch[2];

        blacklist.AddBlackList(targetId, senderId, event.SenderName, event.PeerId, reason);
        event.Context.Reply(new MessageChain().Text(`已将 ${targetId} 加入黑名单，原因: ${reason}`));
        return;
    }

    // 解封命令: /unban @用户
    const unbanMatch = message.match(/^\/unban\s+(\d+)/);
    if (unbanMatch) {
        const targetId = unbanMatch[1];

        if (!blacklist.InBlackList(targetId)) {
            event.Context.Reply(new MessageChain().Text(`${targetId} 不在黑名单中`));
            return;
        }

        blacklist.RemoveBlackList(targetId, senderId, event.SenderName, event.PeerId);
        event.Context.Reply(new MessageChain().Text(`已将 ${targetId} 从黑名单移除`));
        return;
    }
});

注意事项

• 黑白名单操作均为异步方法，需要使用 await 或 .then()
• 白名单功能依赖 EasyBot 的服务器白名单设置
• 操作者信息会被记录，用于审计日志
• 封禁原因建议填写详细说明，方便后续查询