PageSourceSearch
Opt out API access

https://docs.ncatbot.xyz/assets/index.html-BHP8nYIM.js

js ncatbot.xyz collected 2026-09-25 20:05:26 UTC 65,613 bytes, 151 lines download raw bytes 

1import{_ as e,c as k,a as l,b as i,e as a,d as t,w as h,r as p,o as d}from"./app-X5ZAzaQf.js";const r={};function g(y,s){const n=p("RouteLink");return d(),k("div",null,[s[9]||(s[9]=l('<blockquote><p>分类：qq</p></blockquote><h2 id="这个示例教什么" tabindex="-1"><a class="header-anchor" href="#这个示例教什么"><span>这个示例教什么</span></a></h2><p>NcatBot 中<strong>事件处理器是怎么注册的</strong>。通过 <code>@registrar.qq.*</code> 系列装饰器，你可以为不同类型的 QQ 事件注册处理器——命令、消息、通知、请求，并控制优先级和大小写匹配。</p><h2 id="你将学到" tabindex="-1"><a class="header-anchor" href="#你将学到"><span>你将学到</span></a></h2><ul><li><code>on_command</code> — 群聊 + 私聊通用命令注册</li><li><code>on_group_command</code> / <code>on_private_command</code> — 仅群聊 / 仅私聊命令</li><li><code>on_message</code> / <code>on_group_message</code> / <code>on_private_message</code> — 消息监听</li><li><code>on_notice</code> / <code>on_request</code> — 通知与请求事件监听</li><li><code>priority</code> — 多个处理器的执行顺序控制</li><li><code>ignore_case</code>

1 — 命令匹配时忽略大小写</li></ul><h2 id="前置知识" tabindex="-1"><a class="header-anchor" href="#前置知识"><span>前置知识</span></a></h2>',6)),i("ul",null,[s[2]||(s[2]=i("li",null,[a("了解 NcatBot 插件的基本结构（"),i("code",null,"NcatBotPlugin"),a(" 基类、"),i("code",null,"manifest.toml"),a("）")],-1)),i("li",null,[s[1]||(s[1]=a("建议先完成 ")),t(n,{to:"/examples/common/01_hello_world/"},{default:h(()=>s[0]||(s[0]=[a("common/01_hello_world")])),_:1})])]),s[10]||(s[10]=l(`<h2 id="目录结构" tabindex="-1"><a class="header-anchor" href="#目录结构"><span>目录结构</span></a></h2><div class="language-text line-numbers-mode" data-ext="text" data-title="text"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span>01_event_registration/</span></span>
2<span class="line"><span>├── main.py          # 插件代码</span></span>
3<span class="line"><span>├── manifest.toml    # 插件清单</span></span>
4<span class="line"><span>└── README.md</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="完整代码" tabindex="-1"><a class="header-anchor" href="#完整代码"><span>完整代码</span></a></h2><div class="language-python line-numbers-mode" data-ext="python" data-title="python"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
5<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">qq/01_event_registration — QQ 事件注册方式演示</span></span>
6<span class="line"></span>
7<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">演示功能:</span></span>
8<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @registrar.qq.on_command()          群聊+私聊通用命令</span></span>
9<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @registrar.qq.on_group_command()    群聊专属命令</span></span>
10<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @registrar.qq.on_private_command()  私聊专属命令</span></span>
11<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @registrar.qq.on_message()          所有消息监听</span></span>
12<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @registrar.qq.on_group_message()    群聊消息监听</span></span>
13<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @registrar.qq.on_private_message()  私聊消息监听</span></span>
14<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @registrar.qq.on_notice()           通知事件监听</span></span>
15<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @registrar.qq.on_request()          请求事件监听</span></span>
16<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - priority 参数                       优先级控制</span></span>
17<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - ignore_case 参数                    大小写不敏感</span></span>
18<span class="line"></span>
19<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">本示例只回答&quot;怎么注册事件处理器&quot;，不涉及参数绑定、消息构造、</span></span>
20<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Notice/Request 细分处理等内容。</span></span>
21<span class="line"></span>
22<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">提及但不展开:</span></span>
23<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - on_meta / on_message_sent</span></span>
24<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - registrar.qq 下的细粒度快捷装饰器（如 on_group_increase）</span></span>
25<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - platform 参数</span></span>
26<span class="line"></span>
27<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">使用方式: 将本文件夹复制到 plugins/ 目录，启动 Bot。</span></span>
28<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
29<span class="line"></span>
30<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">from</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> ncatbot</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">core </span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">

30import</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> registrar</span></span>
31<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">from</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> ncatbot</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">qq </span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> (</span></span>
32<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">    GroupMessageEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span></span>
33<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">    NoticeEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span></span>
34<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">    PrivateMessageEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span></span>
35<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">    RequestEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span></span>
36<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
37<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">from</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> ncatbot</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">plugin </span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">import</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> NcatBotPlugin</span></span>
38<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">from</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> ncatbot</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">utils </span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">import</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> get_log</span></span>
39<span class="line"></span>
40<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">LOG</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> get_log</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">EventRegistration</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
41<span class="line"></span>
42<span class="line"></span>
43<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">class</span><span style="--shiki-light:#2E8F82;--shiki-dark:#5DA994;"> EventRegistrationPlugin</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">NcatBotPlugin</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
44<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">    name </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">event_registration_qq</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
45<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">    version </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">1.0.0</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
46<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">    author </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">NcatBot</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
47<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">    description </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">QQ 事件注册方式演示</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
48<span class="line"></span>
49<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
50<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 1. on_command — 群聊 + 私聊通用命令</span></span>
51<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
52<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ignore_case=True 让 &quot;Ping&quot;、&quot;PING&quot;、&quot;ping&quot; 都能触发。</span></span>
53<span class="line"></span>
54<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ping</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;"> ignore_case</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">True</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
55<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_ping</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">

55self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
56<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">群聊和私聊都能触发的通用命令</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
57<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">        await</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">reply</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">text</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">pong!</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
58<span class="line"></span>
59<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
60<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 2. on_group_command / on_private_command — 平台专属命令</span></span>
61<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
62<span class="line"></span>
63<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_group_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">group-only</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
64<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_group_only</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> GroupMessageEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
65<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">仅群聊可触发的命令</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
66<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">        await</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">reply</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">text</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">

66这条命令只在群聊中生效 📢</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
67<span class="line"></span>
68<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_private_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">private-only</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
69<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_private_only</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> PrivateMessageEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
70<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">仅私聊可触发的命令</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
71<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">        await</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">reply</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">text</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">这条命令只在私聊中生效 🔒</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
72<span class="line"></span>
73<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
74<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 3. on_message / on_group_message / on_private_message — 消息监听</span></span>
75<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
76<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 消息监听器会收到所有消息（不限于命令），适合做日志、统计等。</span></span>
77<span class="line"></span>
78<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_message</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">()</span></span>
79<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_any_message</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">

79self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
80<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">监听所有 QQ 消息（群聊 + 私聊）</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
81<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">        LOG</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">debug</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">收到消息: </span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">%s</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">raw_message</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
82<span class="line"></span>
83<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_group_message</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">()</span></span>
84<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_group_msg</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> GroupMessageEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
85<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">仅监听群聊消息</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
86<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">        LOG</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">debug</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">群 </span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">%s</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">

86 消息: </span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">%s</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">group_id</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">raw_message</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
87<span class="line"></span>
88<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_private_message</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">()</span></span>
89<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_private_msg</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> PrivateMessageEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
90<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">仅监听私聊消息</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
91<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">        LOG</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">debug</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">

91私聊消息: </span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">%s</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">raw_message</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
92<span class="line"></span>
93<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
94<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 4. on_notice / on_request — 通知与请求事件</span></span>
95<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
96<span class="line"></span>
97<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_notice</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">()</span></span>
98<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_notice</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> NoticeEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
99<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">监听所有通知事件（群成员变动、撤回、戳一戳等）</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
100<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">        LOG</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">info</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">收到通知事件: </span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">%s</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">notice_type</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
101<span class="line"></span>
102<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_request</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">()</span></span>
103<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_request</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">

103self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> RequestEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
104<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">监听所有请求事件（加群申请、好友请求等）</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
105<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">        LOG</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">info</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">收到请求事件: </span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">%s</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">request_type</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
106<span class="line"></span>
107<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
108<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 5. priority — 优先级控制</span></span>
109<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
110<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # priority 值越小优先级越高（默认为 0）。</span></span>
111<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 下面两个处理器监听同一事件（群聊命令 &quot;priority-demo&quot;），</span></span>
112<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # high_priority_handler 会先于 low_priority_handler 执行。</span></span>
113<span class="line"></span>
114<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_group_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">priority-demo</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;"> priority</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
115<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> high_priority_handler</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">

115self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> GroupMessageEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
116<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">高优先级处理器（priority=0，先执行）</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
117<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">        LOG</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">info</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">⚡ 高优先级处理器执行</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
118<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">        await</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">reply</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">text</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">高优先级处理器先响应 ⚡</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
119<span class="line"></span>
120<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_group_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">priority-demo</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;"> priority</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">10</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
121<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> low_priority_handler</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> GroupMessageEvent</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
122<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">低优先级处理器（priority=10，后执行）</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
123<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">

123        LOG</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">info</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">🐢 低优先级处理器执行</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
124<span class="line"></span>
125<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
126<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 6. ignore_case — 大小写不敏感</span></span>
127<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
128<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 默认情况下命令匹配区分大小写。</span></span>
129<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 设置 ignore_case=True 后，&quot;Help&quot;、&quot;HELP&quot;、&quot;help&quot; 都能匹配。</span></span>
130<span class="line"></span>
131<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    @</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Help</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;"> ignore_case</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">True</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
132<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">    async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> on_help_ignore_case</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
133<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">        &quot;&quot;&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">大小写不敏感：Help / HELP / help 都能触发</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
134<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">        await</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">reply</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">text</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">输入 ping / group-only / private-only / priority-demo 试试</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
135<span class="line"></span>
136<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
137<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 提及但不展开的注册方式</span></span>
138<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # ================================================================</span></span>
139<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # - @registrar.qq.on_meta()          元事件（心跳等）</span></span>
140<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # - @registrar.qq.on_message_sent()  Bot 自身发送的消息</span></span>
141<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # - registrar.qq 下还有更多细粒度快捷装饰器，例如：</span></span>
142<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    #     @registrar.qq.on_group_increase()  群成员增加</span></span>
143<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    #     @registrar.qq.on_group_decrease()  群成员减少</span></span>
144<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">

144    #     @registrar.qq.on_friend_add()      好友添加</span></span>
145<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    #   这些装饰器是 on_notice() 的细分版本，详见 reference 文档。</span></span>
146<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # - 跨平台注册可使用 @registrar.on_command() 或 platform 参数，</span></span>
147<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    #   详见 common/01_hello_world 示例。</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="关键代码讲解" tabindex="-1"><a class="header-anchor" href="#关键代码讲解"><span>关键代码讲解</span></a></h2><h3 id="命令注册三件套" tabindex="-1"><a class="header-anchor" href="#命令注册三件套"><span>命令注册三件套</span></a></h3><table><thead><tr><th>

147装饰器</th><th>触发场景</th><th>典型用途</th></tr></thead><tbody><tr><td><code>@registrar.qq.on_command(&quot;cmd&quot;)</code></td><td>群聊 + 私聊</td><td>通用命令（最常用）</td></tr><tr><td><code>@registrar.qq.on_group_command(&quot;cmd&quot;)</code></td><td>仅群聊</td><td>群管理命令</td></tr><tr><td><code>@registrar.qq.on_private_command(&quot;cmd&quot;)</code></td><td>仅私聊</td><td>敏感操作命令</td></tr></tbody></table><h3 id="消息监听三件套" tabindex="-1"><a class="header-anchor" href="#消息监听三件套"><span>消息监听三件套</span></a></h3><table><thead><tr><th>装饰器</th><th>触发场景</th><th>典型用途</th></tr></thead><tbody><tr><td><code>@registrar.qq.on_message()</code></td><td>所有 QQ 消息</td><td>全局日志、关键词检测</td></tr><tr><td><code>@registrar.qq.on_group_message()</code></td><td>仅群聊消息</td><td>群消息统计</td></tr><tr><td><code>@registrar.qq.on_private_message()</code></td><td>仅私聊消息</td><td>私聊消息处理</td></tr></tbody></table><h3 id="通知-请求" tabindex="-1"><a class="header-anchor" href="#通知-请求"><span>通知 &amp; 请求</span></a></h3><table><thead><tr><th>装饰器</th><th>触发场景</th></tr></thead><tbody><tr><td><code>@registrar.qq.on_notice()</code></td><td>群成员变动、消息撤回、戳一戳等</td></tr><tr><td><code>@registrar.qq.on_request()</code></td><td>加群申请、好友请求等</td></tr></tbody></table><h3 id="priority-优先级" tabindex="-1"><a class="header-anchor" href="#priority-优先级"><span>priority 优先级</span></a></h3><div class="language-python line-numbers-mode" data-ext="python" data-title="python"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">@</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_group_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">priority-demo</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;"> priority</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">   # 先执行</span></span>
148<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> high_priority_handler</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> ...</span></span>
149<span class="line"></span>
150<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">@</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_group_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">priority-demo</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;"> priority</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">10</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">  # 后执行</span></span>
151<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> def</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> low_priority_handler</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">

151self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> event</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> ...</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p><code>priority</code> 值越小，优先级越高。默认值为 <code>0</code>。当多个处理器匹配同一事件时，按 priority 从小到大依次执行。</p><h3 id="ignore-case-大小写不敏感" tabindex="-1"><a class="header-anchor" href="#ignore-case-大小写不敏感"><span>ignore_case 大小写不敏感</span></a></h3><div class="language-python line-numbers-mode" data-ext="python" data-title="python"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">@</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">registrar</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">qq</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">on_command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Help</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;"> ignore_case</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">True</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>设置 <code>ignore_case=True</code> 后，用户输入 <code>Help</code>、<code>HELP</code>、<code>help</code> 都能匹配。默认区分大小写。</p><h2 id="运行方式" tabindex="-1"><a class="header-anchor" href="#运行方式"><span>运行方式</span></a></h2><ol><li>将 <code>01_event_registration/</code> 文件夹复制到项目的 <code>plugins/</code> 目录</li><li>启动 Bot（<code>python main.py</code> 或 <code>ncatbot run</code>）</li><li>在群聊或私聊中发送以下命令测试： <ul><li><code>ping</code> — 通用命令（群聊 + 私聊均可）</li><li><code>group-only</code> — 仅群聊生效</li><li><code>private-only</code> — 仅私聊生效</li><li><code>priority-demo</code> — 在群聊中测试优先级（观察日志输出顺序）</li><li><code>help</code> / <code>Help</code> / <code>HELP</code> — 大小写不敏感命令</li></ul></li></ol><h2 id="延伸阅读" tabindex="-1"><a class="header-anchor" href="#延伸阅读"><span>延伸阅读</span></a></h2>`,20)),i("ul",null,[i("li",null,[t(n,{to:"/examples/common/01_hello_world/"},{default:h(()=>s[3]||(s[3]=[a("common/01_hello_world")])),_:1}),s[4]||(s[4]=a(" — 跨平台命令注册（")),s[5]||(s[5]=i("code",null,"@registrar.on_command",-1)),s[6]||(s[6]=a("）"))]),s[7]||(s[7]=i("li",null,[a("事件类型参考（Reference）— "),i("code",null,"GroupMessageEvent"),a("、"),i("code",null,"PrivateMessageEvent"),a("、"),i("code",null,"NoticeEvent"),a("、"),i("code",null,"RequestEvent"),a(" 的完整字段")],-1)),s[8]||(s[8]=i("li",null,[a("细粒度快捷装饰器 — "),i("code",null,"registrar.qq.on_group_increase()"),a(" 等 Notice 子类型装饰器")],-1))])])}const A=e(r,[["render",g],["__file","index.html.vue"]]),c=JSON.parse('{"path":"/examples/qq/01_event_registration/","title":"01_event_registration","lang":"zh-CN","frontmatter":{"title":"01_event_registration","description":"分类：qq 这个示例教什么 NcatBot 中事件处理器是怎么注册的。通过 @registrar.qq.* 系列装饰器，你可以为不同类型的 QQ 事件注册处理器——命令、消息、通知、请求，并控制优先级和大小写匹配。 你将学到 on_command — 群聊 + 私聊通用命令注册 on_group_command / on_private_command...","head":[["meta",{"property":"og:url","content":"http://docs.ncatbot.xyz/examples/qq/01_event_registration/"}],["meta",{"property":"og:site_name","content":"NcatBot 文档"}],["meta",{"property":"og:title","content":"01_event_registration"}],["meta",{"property":"og:description","content":"分类：qq 这个示例教什么 NcatBot 中事件处理器是怎么注册的。通过 @registrar.qq.* 系列装饰器，你可以为不同类型的 QQ 事件注册处理器——命令、消息、通知、请求，并控制优先级和大小写匹配。 你将学到 on_command — 群聊 + 私聊通用命令注册 on_group_command / on_private_command..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"zh-CN"}

151],["meta",{"property":"og:updated_time","content":"2026-04-17T14:13:00.000Z"}],["meta",{"property":"article:modified_time","content":"2026-04-17T14:13:00.000Z"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"01_event_registration\\",\\"image\\":[\\"\\"],\\"dateModified\\":\\"2026-04-17T14:13:00.000Z\\",\\"author\\":[]}"]]},"headers":[],"readingTime":{"minutes":4.65,"words":1394},"git":{"updatedTime":1776435180000,"contributors":[{"name":"GEYUANwuqi","username":"GEYUANwuqi","email":"[email protected]","commits":1,"avatar":"https://gravatar.com/avatar/1cf26d82e91dff657f3fa4d4911cdabcf7b76396339e886e69f99b15d4c8c808?d=retro"}]},"autoDesc":true,"filePathRelative":"examples/qq/01_event_registration/README.md","categoryList":[{"id":"bfebe3","sort":10000,"name":"examples"},{"id":"89b1a9","sort":10030,"name":"qq"},{"id":"c38c20","sort":10033,"name":"01_event_registration"}]}');export{A as comp,c as data};

Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.