CoolQ HTTP API 事件过滤器深度解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00057/article/details/148944306

CoolQ HTTP API 事件过滤器深度解析

coolq-http-api 项目地址: https://gitcode.com/gh_mirrors/coo/coolq-http-api

什么是事件过滤器

CoolQ HTTP API 的事件过滤器是一种强大的消息筛选机制，允许开发者通过定义规则来精确控制哪些事件需要上报到HTTP服务。通过合理配置过滤器，可以显著减少不必要的网络传输和处理开销，提升机器人响应效率。

过滤器基本配置

要启用事件过滤器，需要在配置文件中设置event_filter参数，指定过滤规则文件的路径。例如：

event_filter = filter.json

配置文件应当放置在插件数据目录中，采用JSON格式编写。如果文件不存在或语法错误，插件将暂停所有事件上报。

过滤器规则示例详解

基础过滤示例

场景1：仅处理特定前缀消息

{
    "raw_message": {
        ".regex": "^!!"
    }
}

此规则使用正则表达式匹配，只上报以"!!"开头的原始消息内容。

场景2：过滤群组匿名消息

{
    "message_type": "group",
    "anonymous": {
        ".eq": null
    }
}

该规则确保只接收群组消息，且排除所有匿名消息（匿名消息的anonymous字段不为null）。

复合逻辑过滤

场景3：组合条件过滤

{
    ".or": [
        {"message_type": "private"},
        {
            "message_type": "group",
            "group_id": {"in": [123456]},
            "anonymous": {"eq": null}
        }
    ]
}

这个例子展示了逻辑或(.or)的使用，匹配以下任一情况：

所有私聊消息
指定群组(123456)的非匿名消息

高级过滤技巧

场景4：复杂条件组合

{
    ".or": [
        {
            "message_type": "private",
            "user_id": {
                ".not": {"in": [11111, 22222, 33333]},
                ".neq": 44444
            }
        },
        {
            "message_type": {"regex": "group|discuss"},
            ".or": [
                {"group_id": 12345},
                {"raw_message": {"contains": "通知"}}
            ]
        }
    ]
}

这个复杂规则实现了：

私聊消息中，排除特定用户(11111-33333)和用户44444的消息
群组或讨论组消息中，仅接收：
- 来自群12345的所有消息
- 包含"通知"关键词的消息

过滤器运算符详解

CoolQ HTTP API 提供了丰富的运算符来实现各种过滤需求：

| 运算符 | 功能描述 | 参数类型 | 适用数据类型 | |------------|----------------------------|--------------|------------| | .not | 逻辑非运算 | 对象 | 任意 | | .and | 逻辑与运算 | 对象 | 任意/对象 | | .or | 逻辑或运算 | 对象数组 | 任意 | | .eq | 等于比较 | 任意值 | 任意 | | .neq | 不等于比较 | 任意值 | 任意 | | .in | 包含于检查 | 字符串/数组 | 字符串/任意 | | .contains| 包含子字符串 | 字符串 | 字符串 | | .regex | 正则表达式匹配 | 字符串 | 字符串 |

过滤处理流程说明

初始化阶段：插件启动时加载并验证过滤规则，任何语法错误将导致上报功能暂停。
运行时处理：
- 事件数据对象构建完成后应用过滤规则
- 按层级逐项检查过滤条件
- 所有条件必须同时满足(AND逻辑)
- 类型不匹配自动视为过滤不通过
特殊注意事项：
- 过滤器看到的事件数据格式固定，不受兼容性配置影响
- message字段始终为消息段数组格式
- raw_message保持原始CQ码格式