docs : EventFilter

docs/EventFilter.md

@@ -0,0 +1,132 @@
+# 事件过滤器
+
+在go-cqhttp同级目录下新建`filter.json`文件即可开启事件过滤器，启动时会读取该文件中定义的过滤规则（使用 JSON 编写），若文件不存在，或过滤规则语法错误，则会暂停所有上报。
+事件过滤器会处理所有事件(包括心跳事件在内的元事件),请谨慎使用！！
+
+## 示例
+
+这节首先给出一些示例，演示过滤器的基本用法，下一节将给出具体语法说明。
+
+### 只上报以「!!」开头的消息
+
+```json
+{
+    "raw_message": {
+        ".regex": "^!!"
+    }
+}
+```
+
+### 只上报群组的非匿名消息
+
+```json
+{
+    "message_type": "group",
+    "anonymous": {
+        ".eq": null
+    }
+}
+```
+
+### 只上报私聊或特定群组的非匿名消息
+
+```json
+{
+    ".or": [
+        {
+            "message_type": "private"
+        },
+        {
+            "message_type": "group",
+            "group_id": {
+                ".in": [
+                    123456
+                ]
+            },
+            "anonymous": {
+                ".eq": null
+            }
+        }
+    ]
+}
+```
+
+### 只上报群组 11111、22222、33333 中不是用户 12345 发送的消息，以及用户 66666 发送的所有消息
+
+```json
+{
+    ".or": [
+        {
+            "group_id": {
+                ".in": [11111, 22222, 33333]
+            },
+            "user_id": {
+                ".neq": 12345
+            }
+        },
+        {
+            "user_id": 66666
+        }
+    ]
+}
+```
+
+### 一个更复杂的例子
+
+```json
+{
+    ".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": "通知"
+                    }
+                }
+            ]
+        }
+    ]
+}
+```
+
+## 语法说明
+
+过滤规则最外层是一个 JSON 对象，其中的键，如果以 `.`（点号）开头，则表示运算符，其值为运算符的参数，如果不以 `.` 开头，则表示对事件数据对象中相应键的过滤。过滤规则中任何一个对象，只有在它的所有项都匹配的情况下，才会让事件通过（等价于一个 `and` 运算）；其中，不以 `.` 开头的键，若其值不是对象，则只有在这个值和事件数据相应值相等的情况下，才会通过（等价于一个 `eq` 运算符）。
+
+下面列出所有运算符（「要求的参数类型」是指运算符的键所对应的值的类型，「可作用于的类型」是指在过滤时事件对象相应值的类型）：
+
+| 运算符 | 要求的参数类型 | 可作用于的类型 |
+| ----- | ------------ | ----------- |
+| `.not` | object | 任何 |
+| `.and` | object | 若参数中全为运算符，则任何；若不全为运算符，则 object |
+| `.or` | array（数组元素为 object） | 任何 |
+| `.eq` | 任何 | 任何 |
+| `.neq` | 任何 | 任何 |
+| `.in` | string/array | 若参数为 string，则 string；若参数为 array，则任何 |
+| `.contains` | string | string |
+| `.regex` | string | string |
+
+
+## 过滤时的事件数据对象
+
+过滤器在go-cqhttp构建好事件数据后运行，各事件的数据字段见[OneBot标准]( https://github.com/howmanybots/onebot/blob/master/v11/specs/event/README.md )。
+
+这里有几点需要注意：
+
+- `message` 字段在运行过滤器时是消息段数组的形式（见 [消息格式]( https://github.com/howmanybots/onebot/blob/master/v11/specs/message/array.md )）
+- `raw_message` 字段为未经**CQ码**处理的原始消息字符串，这意味着其中可能会出现形如 `[CQ:face,id=123]` 的 CQ 码