https://ncat-bot-docs-delta.vercel.app/assets/index.html-BW5BgOjZ.js

1import{_ as p,c as h,a as l,b as a,d as e,e as i,w as t,r as d,o as k}from"./app-C1L7GXRS.js";const o={};function r(c,s){const n=d("RouteLink");return k(),h("div",null,[s[7]||(s[7]=l('<blockquote><p>分类：common</p></blockquote><h2 id="这个示例教什么" tabindex="-1"><a class="header-anchor" href="#这个示例教什么"><span>这个示例教什么</span></a></h2><p>展示 <code>CommandGroupHook</code> 命令组分层路由机制：用一个前缀命令管理多个子命令，支持参数绑定和多别名。</p><h2 id="你将学到" tabindex="-1"><a class="header-anchor" href="#你将学到"><span>你将学到</span></a></h2><ul><li><code>CommandGroupHook</code> 的创建与注册</li><li><code>@hook.subcommand()</code> 子命令装饰器</li><li>子命令参数自动绑定（int / float / str）</li><li>命令别名支持（如 <code>/admin</code> 和 <code>/a</code>）</li><li><code>ignore_case</code> 大小写不敏感匹配</li></ul><h2 id="前置知识" tabindex="-1"><a class="header-anchor" href="#前置知识"><span>前置知识</span></a></h2>',6)),a("ul",null,[a("li",null,[e(n,{to:"/examples/common/01_hello_world/"},{default:t(()=>s[0]||(s[0]=[i("common/01_hello_world")])),_:1}),s[1]||(s[1]=i(" — 插件基础结构"))]),s[2]||(s[2]=a("li",null,[i("理解 "),a("code",null,"@registrar.on_group_message()"),i(" 装饰器")],-1))]),s[8]||(s[8]=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>07_command_group/</span></span>
2<span class="line"><span>├── main.py</span></span>
3<span class="line"><span>└── manifest.toml</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></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>
4<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">common/07_command_group — 命令组分层路由插件</span></span>
5<span class="line"></span>
6<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">演示功能:</span></span>
7<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - 使用 CommandGroupHook 实现分层命令</span></span>
8<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - 参数类型自动绑定（int/float/str/At）</span></span>
9<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - 命令别名支持</span></span>
10<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  - @hook.subcommand() 装饰器注册子命令并由主 handler 分发</span></span>
11<span class="line"></span>
12<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">使用方式:</span></span>
13<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  &quot;/admin kick 12345&quot;       → 踢出成员</span></span>
14<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  &quot;/admin ban 12345 120&quot;    → 禁言 120 分钟</span></span>
15<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  &quot;/calc add 10 20&quot;         → 计算加法</span></span>
16<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">  &quot;/help&quot; 或 &quot;/?&quot;           → 查看帮助</span></span>
17<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;&quot;&quot;</span></span>
18<span class="line"></span>
19<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">

19import</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> inspect</span></span>
20<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;">import</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> CommandGroupHook</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> registrar</span></span>
21<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:#393A34;--shiki-dark:#DBD7CAEE;"> GroupMessageEvent</span></span>
22<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>
23<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># ... (见 main.py 完整代码)</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></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><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:#393A34;--shiki-dark:#DBD7CAEE;">admin_hook </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> CommandGroupHook</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;">admin</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</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;">/admin</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</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;">a</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>

23第一个参数是命令组名，后续参数是触发前缀（可多个），<code>ignore_case=True</code> 表示 <code>/Admin</code> 和 <code>/admin</code> 均可触发。</p><h3 id="注册子命令" tabindex="-1"><a class="header-anchor" href="#注册子命令"><span>注册子命令</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;">admin_hook</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">subcommand</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;">kick</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</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;">remove</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
24<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;"> admin_kick</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;"> user_id</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> int</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
25<span class="line"><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></div><p><code>subcommand()</code> 接受一个或多个别名。参数自动从消息中提取和绑定。</p><h3 id="挂载到消息处理器" tabindex="-1"><a class="header-anchor" href="#挂载到消息处理器"><span>挂载到消息处理器</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;">on_group_message</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">()</span></span>
26<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">@</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">admin_hook</span></span>
27<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_admin</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:#AB5959;--shiki-dark:#CB7676;"> **</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">kwargs</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">):</span></span>
28<span class="line"><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></div><p>通过将 <code>@admin_hook</code> 作为装饰器叠加，实现命令组的自动分发。</p><h2 id="运行方式" tabindex="-1"><a class="header-anchor" href="#运行方式"><span>运行方式</span></a></h2><p>将本文件夹复制到 <code>plugins/</code> 目录，启动 Bot。在群里发送 <code>/admin kick 12345</code> 等命令即可测试。</p><h2 id="延伸阅读" tabindex="-1"><a class="header-anchor" href="#延伸阅读"><span>延伸阅读</span></a></h2>`,17)),a("ul",null,[a("li",null,[e(n,{to:"/examples/common/01_hello_world/"},{default:t(()=>s[3]||(s[3]=[i("common/01_hello_world")])),_:1}),s[4]||(s[4]=i(" — 基础命令注册"))]),a("li",null,[e(n,{to:"/examples/qq/02_command_binding/"},{default:t(()=>s[5]||(s[5]=[i("qq/02_command_binding")])),_:1}),s[6]||(s[6]=i(" — QQ 平台命令参数绑定全貌"))])])])}const u=p(o,[["render",r],["__file","index.html.vue"]]),g=JSON.parse('{"path":"/examples/common/07_command_group/","title":"07_command_group","lang":"zh-CN","frontmatter":{"title":"07_command_group","description":"分类：common 这个示例教什么 展示 CommandGroupHook 命令组分层路由机制：用一个前缀命令管理多个子命令，支持参数绑定和多别名。 你将学到 CommandGroupHook 的创建与注册 @hook.subcommand() 子命令装饰器 子命令参数自动绑定（int / float / str） 命令别名支持（如 /admin 和 ...","head":[["meta",{"property":"og:url","content":"http://docs.ncatbot.xyz/examples/common/07_command_group/"}],["meta",{"property":"og:site_name","content":"NcatBot 文档"}],["meta",{"property":"og:title","content":"07_command_group"}],["meta",{"property":"og:description","content":"分类：common 这个示例教什么 展示 CommandGroupHook 命令组分层路由机制：用一个前缀命令管理多个子命令，支持参数绑定和多别名。 你将学到 CommandGroupHook 的创建与注册 @hook.subcommand() 子命令装饰器 子命令参数自动绑定（int / float / str） 命令别名支持（如 /admin 和 ..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"zh-CN"}

28],["meta",{"property":"og:updated_time","content":"2026-04-30T14:41:02.000Z"}],["meta",{"property":"article:modified_time","content":"2026-04-30T14:41:02.000Z"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"07_command_group\\",\\"image\\":[\\"\\"],\\"dateModified\\":\\"2026-04-30T14:41:02.000Z\\",\\"author\\":[]}"]]},"headers":[],"readingTime":{"minutes":1.43,"words":428},"git":{"updatedTime":1777560062000,"contributors":[{"name":"GEYUANwuqi","username":"GEYUANwuqi","email":"[email protected]","commits":1,"avatar":"https://gravatar.com/avatar/1cf26d82e91dff657f3fa4d4911cdabcf7b76396339e886e69f99b15d4c8c808?d=retro"}]},"autoDesc":true,"filePathRelative":"examples/common/07_command_group/README.md","categoryList":[{"id":"bfebe3","sort":10000,"name":"examples"},{"id":"c42c0c","sort":10021,"name":"common"},{"id":"89a202","sort":10024,"name":"07_command_group"}]}');export{u as comp,g as data};