修复优先级低插件的相同指令不会分发

Author: lengxi-root

PLUGIN_DEVELOPMENT.md

@@ -99,7 +99,7 @@ from core.plugin.decorators import handler, on_load, on_unload, interceptor
 ```python
 @handler(pattern, *, name='', desc='', priority=0, owner_only=False,
          group_only=False, direct_only=False, channel_only=False,
-         event_types=None, cooldown=0, ignore_at_check=False)
+         event_types=None, cooldown=0, ignore_at_check=False, block=False)
 ```
 
 | 参数 | 类型 | 默认 | 说明 |
@@ -115,6 +115,7 @@ from core.plugin.decorators import handler, on_load, on_unload, interceptor
 | `event_types` | `list[str]` | `None` | 仅响应指定事件类型 (见下表) |
 | `cooldown` | `int` | `0` | 冷却时间 (秒, 0 = 无冷却) |
 | `ignore_at_check` | `bool` | `False` | 全量模式: 不需@机器人也触发 |
+| `block` | `bool` | `False` | 命中后是否拦截后续处理器 (见 3.1.1) |
 
 **事件类型常量** (`event_types` 可选值):
 
@@ -152,6 +153,21 @@ async def check_in(event, match):
     await event.reply("✅ 签到成功!")
 ```
 
+#### 3.1.1 `block` 放行 / 拦截
+
+多个插件注册相同指令时, `block=False` (默认) 放行让所有命中处理器按 `priority` 顺序执行, `block=True` 命中即拦截后续低优先级处理器。
+
+```python
+@handler(r'^状态$', name='系统状态', priority=10, block=True)  # 命中即拦截, 只有它响应
+async def status(event, match):
+    await event.reply("✅ 系统正常")
+
+
+@handler(r'^状态$', name='天气状态', priority=0)  # 被上面 block 拦截, 不会触发
+async def weather(event, match):
+    await event.reply("☀️ 今天晴")
+```
+
 ### 3.2 `@on_load` / `@on_unload` 生命周期钩子
 
 ```python

README.md

@@ -16,7 +16,7 @@ ElainaBot V2是一个基于 Python 的 QQ 官方机器人框架，采用纯异
 </p>
 <br clear="left" />
 
-> 项目仅供学习交流使用，严禁用于非法行为。
+> 项目仅供学习交流使用，严禁用于任何商业用途和非法行为。
 
 ## 📢 交流群
 

core/plugin/_dispatch.py

@@ -102,6 +102,7 @@ async def dispatch(self, event: Event, sender: Any) -> bool:
             if not handlers:
                 return False
             scene: int = _event_scene(event)
+            matched: list[tuple[dict[str, Any], re.Match[str]]] = []
             for h in handlers:
                 ab = h['_allowed_bots']
                 if ab is not None and appid not in ab:
@@ -111,13 +112,13 @@ async def dispatch(self, event: Event, sender: Any) -> bool:
                     continue
                 if h['_smask'] & ~scene:
                     continue
-                plugin_name: str = h['name'] or h.get('_plugin', '')
-                log_service = self._get_log_service(event)
-                event._reply_log_cb = _make_reply_log_cb(plugin_name, log_service)
-                event._reply_plugin_name = plugin_name or ''
-                asyncio.create_task(self._run_handler(h, event, m, plugin_name, user_id, et, content))
-                return True
-            return False
+                matched.append((h, m))
+                if h.get('block', False):  # 默认放行, block=True 时拦截后续
+                    break
+            if not matched:
+                return False
+            asyncio.create_task(self._run_chain(matched, event, user_id, et, content))
+            return True
 
         # ── 消息事件: 完整检查链 ──
         _get = cfg.get_bot_setting
@@ -212,7 +213,8 @@ def _match_handlers(
         content: str,
         skip_at_other: bool = False,
     ) -> bool:
-        """内循环: 遍历 handler 尝试匹配, 匹配成功则 fire-and-forget 并返回 True"""
+        """内循环: 收集命中的 handler, 遇到 block=True 即停止, 随后顺序执行"""
+        matched: list[tuple[dict[str, Any], re.Match[str]]] = []
         for h in handlers:
             # 快速过滤: bot 白名单
             ab = h['_allowed_bots']
@@ -230,8 +232,9 @@ def _match_handlers(
                 continue
             # 场景过滤 (位掩码): handler 要求的场景位 & 事件不具备的场景位 → 不匹配
             if h['_smask'] & ~scene:
-                # 群聊专属指令在私聊环境 → 明确告知用户
+                # 群聊专属指令在私聊环境 → 告知用户并终止
                 if h['group_only'] and not is_non_at:
+                    self._fire_chain(matched, event, user_id, et, content)
                     asyncio.create_task(
                         event.reply(
                             template_name='group_only',
@@ -242,6 +245,7 @@ def _match_handlers(
                 continue
             # 权限
             if h['owner_only'] and not self._is_owner(event):
+                self._fire_chain(matched, event, user_id, et, content)
                 if not is_non_at:
                     asyncio.create_task(
                         event.reply(
@@ -250,16 +254,46 @@ def _match_handlers(
                         )
                     )
                 return True
-            # 日志绑定
-            plugin_name: str = h['name'] or h.get('_plugin', '')
-            log_service = self._get_log_service(event)
-            event._reply_log_cb = _make_reply_log_cb(plugin_name, log_service)
-            event._reply_plugin_name = plugin_name or ''
-            asyncio.create_task(self._run_handler(h, event, m, plugin_name, user_id, et, content))
-            return True
-        return False
+            matched.append((h, m))
+            if h.get('block', False):  # 默认放行, block=True 时拦截后续
+                break
+        if not matched:
+            return False
+        self._fire_chain(matched, event, user_id, et, content)
+        return True
+
+    def _fire_chain(
+        self,
+        matched: list[tuple[dict[str, Any], re.Match[str]]],
+        event: Event,
+        user_id: str,
+        et: str,
+        content: str,
+    ) -> None:
+        """调度命中的 handler 链顺序执行 (空则跳过)"""
+        if matched:
+            asyncio.create_task(self._run_chain(matched, event, user_id, et, content))
+
+    async def _run_chain(
+        self,
+        matched: list[tuple[dict[str, Any], re.Match[str]]],
+        event: Event,
+        user_id: str,
+        et: str,
+        content: str,
+    ) -> None:
+        """顺序执行 handler 链: 逐个绑定日志上下文, 结束后清理 event 引用"""
+        try:
+            for h, match in matched:
+                plugin_name: str = h['name'] or h.get('_plugin', '')
+                log_service = self._get_log_service(event)
+                event._reply_log_cb = _make_reply_log_cb(plugin_name, log_service)
+                event._reply_plugin_name = plugin_name or ''
+                await self._exec_handler(h, event, match, plugin_name, user_id, et, content)
+        finally:
+            event.raw = event._reply_log_cb = None
 
-    async def _run_handler(
+    async def _exec_handler(
         self,
         h: dict[str, Any],
         event: Event,

core/plugin/decorators.py

@@ -23,8 +23,9 @@ def handler(
     event_types=None,
     cooldown=0,
     ignore_at_check=False,
+    block=False,
 ):
-    """注册消息处理器"""
+    """注册消息处理器 (block=True 命中即拦截后续插件, 默认 False 放行)"""
 
     def decorator(func):
         _pending_handlers.append(
@@ -43,6 +44,7 @@ def decorator(func):
                 'event_types': frozenset(event_types) if event_types else None,
                 'cooldown': cooldown,
                 'ignore_at_check': ignore_at_check,
+                'block': block,
             }
         )
         return func

core/storage/statistics.py

@@ -10,6 +10,7 @@
 
 import asyncio
 import contextlib
+import gc
 import json
 import os
 import re
@@ -252,9 +253,11 @@ def _aggregate_sync(self, appid, date_str):
             return False
 
         self._merge_into_db(appid, date_str, day_user, day_group)
-        log.info(
-            f'[{appid}] {date_str} 已累加: 用户 {len(day_user)}, 群 {len(day_group)}'
-        )
+        user_count, group_count = len(day_user), len(day_group)
+        # 统计完成后主动释放大对象并触发 GC, 避免内存长期占用不回收
+        del day_user, day_group
+        gc.collect()
+        log.info(f'[{appid}] {date_str} 已累加: 用户 {user_count}, 群 {group_count}')
         return True
 
     def _scan_day(self, db_path, date_str):

plugins/alone/示例插件.py

@@ -411,3 +411,16 @@ async def panel_broadcast(event, match):
     import web.ws as ws
     ws.broadcast({'type': 'notification', 'message': match.group(1)})
     await event.reply(f"✅ 已广播: {match.group(1)}")
+
+
+# block 示例: 两个处理器同注册 "^拦截示例$", 高优先级设 block=True 命中即拦截, 低优先级不会触发
+@handler(r'^拦截示例$', name='拦截示例-高优先级', desc='block=True 命中即拦截后续插件',
+         priority=10, block=True)
+async def block_demo_high(event, match):
+    await event.reply("🛑 高优先级处理器 (block=True): 已拦截, 低优先级不会再触发")
+
+
+@handler(r'^拦截示例$', name='拦截示例-低优先级', desc='被高优先级 block 拦截, 不会触发',
+         priority=0)
+async def block_demo_low(event, match):
+    await event.reply("⬇️ 低优先级处理器: 你不应该看到这条 (已被 block 拦截)")

tests/core/test_dispatch_block.py

@@ -0,0 +1,87 @@
+"""分发 block 语义测试 — 多个插件注册相同指令时的放行/拦截行为"""
+
+import asyncio
+import os
+import sys
+import tempfile
+
+import pytest
+
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+
+from core.base.config import cfg  # noqa: E402
+from core.plugin.decorators import _pending_handlers, handler  # noqa: E402
+from core.plugin.manager import PluginManager  # noqa: E402
+from tests.stress.mocks.event_factory import EventFactory  # noqa: E402
+from tests.stress.mocks.message_sender import MockMessageSender  # noqa: E402
+
+APPID = '102000001'
+
+
+@pytest.fixture(autouse=True)
+def _init_cfg():
+    """dispatch() 依赖全局 cfg.get_bot_setting()"""
+    if not cfg._ready:
+        cfg.init(os.path.join(ROOT, 'config'))
+
+
+def _build_two_handlers(sink, block_first):
+    """注册两个 pattern 相同的 handler (高优先级 First, 低优先级 Second)"""
+    _pending_handlers.clear()
+
+    @handler(r'test', name='First', priority=10, block=block_first)
+    async def _first(event, match):
+        sink.append('first')
+
+    @handler(r'test', name='Second', priority=0)
+    async def _second(event, match):
+        sink.append('second')
+
+    collected = list(_pending_handlers)
+    _pending_handlers.clear()
+    return collected
+
+
+def _make_manager(handlers):
+    tmp = tempfile.mkdtemp(prefix='block_test_')
+    pm = PluginManager(plugins_dir=tmp, bot_appid=APPID)
+    for h in handlers:
+        h['_plugin'] = 'test_plugin'
+    pm._all_handlers = sorted(handlers, key=lambda h: -h['priority'])
+    pm._apply_bot_bindings()
+    pm._build_dispatch_index()
+    return pm
+
+
+async def _dispatch_and_collect(pm, content='test'):
+    sender = MockMessageSender(APPID)
+    event = EventFactory.group_at_message(content, appid=APPID)
+    await pm.dispatch(event, sender)
+    # 等待 fire-and-forget 的 handler 链执行完毕
+    for _ in range(50):
+        await asyncio.sleep(0.01)
+        pending = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
+        if not pending:
+            break
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_default_block_false_runs_all_matching_plugins():
+    """默认 block=False: 相同指令的多个插件都会响应 (按 priority 顺序)"""
+    sink: list[str] = []
+    pm = _make_manager(_build_two_handlers(sink, block_first=False))
+    await _dispatch_and_collect(pm)
+    assert sink == ['first', 'second']
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_block_true_intercepts_subsequent_plugins():
+    """高优先级 handler block=True: 命中后拦截, 只有它响应"""
+    sink: list[str] = []
+    pm = _make_manager(_build_two_handlers(sink, block_first=True))
+    await _dispatch_and_collect(pm)
+    assert sink == ['first']