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

1import{_ as l,c as h,b as a,a as d,e as i,d as t,w as n,r as p,o as r}from"./app-X5ZAzaQf.js";const k={};function o(c,s){const e=p("RouteLink");return r(),h("div",null,[a("blockquote",null,[a("p",null,[s[1]||(s[1]=i("通过真实场景学习 ")),s[2]||(s[2]=a("code",null,"ncatbot",-1)),s[3]||(s[3]=i(" 命令行工具的使用。完整命令签名速查请见 ")),t(e,{to:"/notes/reference/10.%20CLI/1.%20%E5%91%BD%E4%BB%A4%E5%8F%82%E8%80%83.html"},{default:n(()=>s[0]||(s[0]=[i("CLI 命令参考")])),_:1}),s[4]||(s[4]=i("。"))])]),s[11]||(s[11]=d(`<hr><h2 id="场景一-从零创建并运行一个-bot" tabindex="-1"><a class="header-anchor" href="#场景一-从零创建并运行一个-bot"><span>场景一：从零创建并运行一个 Bot</span></a></h2><h3 id="第-1-步-—-初始化项目" tabindex="-1"><a class="header-anchor" href="#第-1-步-—-初始化项目"><span>第 1 步 — 初始化项目</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">mkdir</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> my-bot</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> &amp;&amp;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> cd</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> my-bot</span></span>
2<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> init</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></div><p>按提示输入机器人 QQ 号和管理员 QQ 号，完成后目录结构如下：</p><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>my-bot/</span></span>
3<span class="line"><span>├── config.yaml            # 自动生成的配置文件</span></span>
4<span class="line"><span>├── plugins/               # 插件目录</span></span>
5<span class="line"><span>└── plugins/{username}/    # 自动生成的模板插件</span></span>
6<span class="line"><span>    ├── manifest.toml</span></span>
7<span class="line"><span>    └── plugin.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></div><blockquote><p>💡 也可以用 <code>ncatbot init --dir ./my-bot</code> 在当前目录外创建。</p></blockquote><h3 id="第-2-步-—-以开发模式启动" tabindex="-1"><a class="header-anchor" href="#第-2-步-—-以开发模式启动"><span>第 2 步 — 以开发模式启动</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> dev</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>debug=True</code> + 热重载启动 Bot。修改插件代码后无需重启。</p><h3 id="第-3-步-—-切换到生产模式" tabindex="-1"><a class="header-anchor" href="#第-3-步-—-切换到生产模式"><span>第 3 步 — 切换到生产模式</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</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>关闭 debug 日志并保持热重载。如需禁用热重载：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --no-hot-reload</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><blockquote><p>💡 如果尚未运行过 <code>ncatbot init</code>（<code>bot_uin</code> 仍为默认值），<code>ncatbot run</code> 会自动进入初始化流程。可通过 <code>--bot-uin</code> 或环境变量 <code>NCATBOT_BOT_UIN</code> 跳过交互：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --bot-uin</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 1234567890</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --root</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">

7 9876543210</span></span>
8<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 或</span></span>
9<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">NCATBOT_BOT_UIN</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">1234567890</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</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>--non-interactive</code> 可让运行期所有确认自动采用默认值（适用于 CI / Docker）。</p></blockquote><hr><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-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> plugin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> create</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> weather_bot</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>plugins/weather_bot/</code> 下生成 <code>__init__.py</code>、<code>manifest.toml</code>、<code>plugin.py</code>、<code>README.md</code> 标准脚手架。</p><h3 id="查看插件详情" tabindex="-1"><a class="header-anchor" href="#查看插件详情"><span>查看插件详情</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> plugin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> list</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">               # 列出所有已安装插件</span></span>
10<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> plugin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> info</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> weather_bot</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">   # 查看 weather_bot 的版本、作者等元信息</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></div><h3 id="临时禁用-重新启用" tabindex="-1"><a class="header-anchor" href="#临时禁用-重新启用"><span>临时禁用 / 重新启用</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> plugin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> disable</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> weather_bot</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">   # 禁用（加入黑名单）</span></span>
11<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> plugin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> enable</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> weather_bot</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 启用（移出黑名单）</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></div><p>全局开关：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> plugin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> off</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 全局关闭插件加载</span></span>
12<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> plugin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> on</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">     # 全局开启插件加载</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></div><h3 id="删除插件" tabindex="-1"><a class="header-anchor" href="#删除插件"><span>删除插件</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> plugin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> remove</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> weather_bot</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">   # 删除目录及黑白名单记录（需确认）</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><hr><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-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> config</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> show</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">                                       # 查看全部 YAML 配置</span></span>
13<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> config</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> get</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> napcat.ws_uri</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">                          # 查看某一项</span></span>
14<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> config</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> set</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> napcat.ws_uri</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ws://localhost:3001</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 修改值（自动类型转换）</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>true</code>/<code>yes</code> → <code>bool</code>，纯数字 → <code>int</code>，<code>[...]</code> JSON → <code>list</code>。</p><h3 id="安全检查" tabindex="-1"><a class="header-anchor" href="#安全检查"><span>安全检查</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> config</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> check</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>自动检查弱密码/Token、必填项缺失等安全问题，输出修复建议。</p><hr><h2 id="场景四-手动安装-napcat-docker-ci" tabindex="-1"><a class="header-anchor" href="#场景四-手动安装-napcat-docker-ci"><span>

14场景四：手动安装 NapCat（Docker / CI）</span></a></h2><p>默认情况下 NapCat 在 <code>ncatbot run</code> 首次启动时交互式安装。如需在 Docker 构建或 CI 中预装：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> napcat</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> install</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --yes</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">    # 跳过确认，非交互安装</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>Dockerfile 示例：</p><div class="language-dockerfile line-numbers-mode" data-ext="dockerfile" data-title="dockerfile"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span>RUN pip install ncatbot5</span></span>
15<span class="line"><span>RUN ncatbot napcat install --yes</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></div><p>若已安装则自动跳过。</p><hr><h2 id="场景五-napcat-连接诊断" tabindex="-1"><a class="header-anchor" href="#场景五-napcat-连接诊断"><span>场景五：NapCat 连接诊断</span></a></h2><p>Bot 连接不上 NapCat？用诊断命令一键排查：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> napcat</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">            # 完整诊断（WebSocket + WebUI）</span></span>
16<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> napcat</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ws</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">         # 仅检测 WebSocket 连接</span></span>
17<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> napcat</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> webui</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">      # 仅检测 WebUI 状态</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>可临时覆盖配置中的地址：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> napcat</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ws</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --uri</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ws://192.168.1.100:3001</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --token</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> mytoken</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="停止本机-napcat-仅-linux" tabindex="-1"><a class="header-anchor" href="#停止本机-napcat-仅-linux"><span>停止本机 NapCat（仅 Linux）</span></a></h3><p>如果 NapCat 由当前机器本地运行，可以使用：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> napcat</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> stop</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>该命令仅在 Linux 下生效，会调用平台层停止本机 NapCat 进程；若当前使用的是远端 <code>ws_uri</code> 或 <code>skip_setup: true</code>

17 的直连模式，它不会去停止远端服务。</p><hr><h2 id="场景六-snowluma-安装与诊断" tabindex="-1"><a class="header-anchor" href="#场景六-snowluma-安装与诊断"><span>场景六：SnowLuma 安装与诊断</span></a></h2><p>SnowLuma 是独立的 OneBot v11 协议端，协议层与 NapCat 兼容，但首次启用时需要你在 WebUI 中手动打开 OneBot v11 WebSocket 并扫码登录。</p><h3 id="预装-snowluma-windows-x64" tabindex="-1"><a class="header-anchor" href="#预装-snowluma-windows-x64"><span>预装 SnowLuma（Windows x64）</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> install</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --yes</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>使用精简包或指定安装目录：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> install</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --yes</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --lite</span></span>
18<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> install</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --install-dir</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ./runtime/snowluma</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></div><h3 id="诊断-websocket-webui" tabindex="-1"><a class="header-anchor" href="#诊断-websocket-webui"><span>诊断 WebSocket / WebUI</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">            # 完整诊断（WebSocket + WebUI）</span></span>
19<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ws</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">         # 仅检测 WebSocket</span></span>
20<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> webui</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">      # 仅检测 WebUI</span></span>
21<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> version</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">             # 查看安装版本与最新 release</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>可临时覆盖配置中的地址：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ws</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --uri</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ws://192.168.1.100:3001</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --token</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> mytoken</span></span>
22<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> snowluma</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> diagnose</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> webui</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --uri</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> http://192.168.1.100:5099</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></div><blockquote><p>当前 SnowLuma 自动安装 / 自动启动仅完整支持 Windows x64。Linux / macOS 请使用 <code>skip_setup: true</code>，将 SnowLuma 作为外部服务手动管理。</p></blockquote><hr><h2 id="场景七-交互式操作-repl" tabindex="-1"><a class="header-anchor" href="#场景七-交互式操作-repl"><span>场景七：交互式操作（REPL）</span></a></h2><p>直接运行 <code>ncatbot</code>（不带子命令）进入交互式 Shell，适合探索性操作：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">$</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ncatbot</span></span>
23<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [123456789]</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">&gt;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> config show</span></span>
24<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [123456789]</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">&gt;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> plugin list</span></span>
25<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [123456789]</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">&gt;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> config set debug true</span></span>
26<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [123456789]</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">&gt;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> exit</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>REPL 内支持所有子命令，输入 <code>help</code> 查看可用命令。</p><hr><h2 id="场景八-管理多平台适配器" tabindex="-1"><a class="header-anchor" href="#场景八-管理多平台适配器"><span>

26场景八：管理多平台适配器</span></a></h2><h3 id="进入适配器管理" tabindex="-1"><a class="header-anchor" href="#进入适配器管理"><span>进入适配器管理</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> adapter</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>进入副屏交互式管理界面，显示所有可用适配器及当前启用状态。</p><h3 id="操作方式" tabindex="-1"><a class="header-anchor" href="#操作方式"><span>操作方式</span></a></h3><table><thead><tr><th>按键</th><th>操作</th></tr></thead><tbody><tr><td>↑ / ↓</td><td>移动光标</td></tr><tr><td>空格</td><td>启用/禁用适配器</td></tr><tr><td>Enter</td><td>进入适配器配置流程</td></tr><tr><td>q / Esc</td><td>保存并退出</td></tr></tbody></table><p>按 Enter 后进入各适配器的配置交互：</p><ul><li><strong>Bilibili</strong>：询问是否扫码登录，选择扫码则自动获取凭据，否则手动输入 Cookie 字段；之后配置直播间 ID 和是否监听私信</li><li><strong>GitHub</strong>：按提示输入 <a href="https://github.com/settings/tokens" target="_blank" rel="noopener noreferrer">Personal Access Token</a>、仓库列表和事件接收模式</li><li><strong>NapCat</strong>：询问是否自动安装，选择安装则使用默认值，否则手动输入 WS/WebUI 地址</li><li><strong>SnowLuma</strong>：询问是否自动安装，选择安装则返回默认 WS/WebUI 参数；首次启动仍需在 WebUI 手动启用 OneBot v11 端点</li></ul><p>退出副屏后，所有变更自动保存到 <code>config.yaml</code>。</p><blockquote><p>同一 <code>BotClient</code> 内 <code>platform</code>

26 必须唯一，因此不能同时启用 NapCat 和 SnowLuma。</p></blockquote><hr><h2 id="场景九-下载-ai-用户参考资料" tabindex="-1"><a class="header-anchor" href="#场景九-下载-ai-用户参考资料"><span>场景九：下载 AI 用户参考资料</span></a></h2><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ref</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>自动从 GitHub Releases 下载最新版 <code>user-reference.zip</code> 并解压到当前目录，包含示例代码、使用指南、API 参考和 AI Agent 技能文件。下载时自动使用 GitHub 代理加速。</p><p>未指定 IDE 时会交互式提示选择，也可直接指定：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ref</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --vscode</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">            # 适配 VSCode + Copilot</span></span>
27<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ref</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --trae</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">              # 适配 Trae（自动将 .agents 重命名为 .trae）</span></span>
28<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ref</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --cursor</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">            # 适配 Cursor（与 VSCode 相同）</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>指定版本或禁用代理：</p><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><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:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ref</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --version</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 5.2.13</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">          # 下载指定版本</span></span>
29<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ref</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --no-proxy</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">                # 直连 GitHub 下载</span></span>
30<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">ncatbot</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ref</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --dir</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ./my-project</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">        # 解压到指定目录</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><hr><h2 id="延伸阅读" tabindex="-1"><a class="header-anchor" href="#延伸阅读"><span>延伸阅读</span></a></h2>`,91)),a("ul",null,[a("li",null,[t(e,{to:"/notes/reference/10.%20CLI/1.%20%E5%91%BD%E4%BB%A4%E5%8F%82%E8%80%83.html"},{default:n(()=>s[5]||(s[5]=[i("CLI 命令参考")])),_:1}),s[6]||(s[6]=i(" — 全部命令签名、选项、参数速查"))]),a("li",null,[t(e,{to:"/notes/guide/6.%20%E9%85%8D%E7%BD%AE%E7%AE%A1%E7%90%86/"},{default:n(()=>s[7]||(s[7]=[i("配置管理指南")])),_:1}),s[8]||(s[8]=i(" — config.yaml 字段详解"))]),a("li",null,[t(e,{to:"/notes/guide/3.%20%E6%8F%92%E4%BB%B6%E5%BC%80%E5%8F%91/"},{default:n(()=>s[9]||(s[9]=[i("插件开发指南")])),_:1}),s[10]||(s[10]=i(" — 插件开发完整教程"))])])])}const u=l(k,[["render",o],["__file","index.html.vue"]]),g=JSON.parse('{"path":"/guide/actioaxc/","title":"CLI 实战教程","lang":"zh-CN","frontmatter":{"title":"CLI 实战教程","createTime":"2026/03/19 17:26:45","permalink":"/guide/actioaxc/","de

30scription":"通过真实场景学习 ncatbot 命令行工具的使用。完整命令签名速查请见 。 场景一：从零创建并运行一个 Bot 第 1 æ­¥ — 初始化项目 按提示输入机器人 QQ 号和管理员 QQ 号，完成后目录结构如下： 💡 也可以用 ncatbot init --dir ./my-bot 在当前目录外创建。 第 2 æ­¥ — 以开发模式启动 将以 debug=T...","head":[["meta",{"property":"og:url","content":"http://docs.ncatbot.xyz/guide/actioaxc/"}],["meta",{"property":"og:site_name","content":"NcatBot 文档"}],["meta",{"property":"og:title","content":"CLI 实战教程"}],["meta",{"property":"og:description","content":"通过真实场景学习 ncatbot 命令行工具的使用。完整命令签名速查请见 。 场景一：从零创建并运行一个 Bot 第 1 æ­¥ — 初始化项目 按提示输入机器人 QQ 号和管理员 QQ 号，完成后目录结构如下： 💡 也可以用 ncatbot init --dir ./my-bot 在当前目录外创建。 第 2 æ­¥ — 以开发模式启动 将以 debug=T..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"zh-CN"}],["meta",{"property":"og:updated_time","content":"2026-05-15T15:15:21.000Z"}],["meta",{"property":"article:modified_time","content":"2026-05-15T15:15:21.000Z"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"CLI 实战教程\\",\\"image\\":[\\"\\"],\\"dateModified\\":\\"2026-05-15T15:15:21.000Z\\",\\"author\\":[]}"]]},"headers":[],"readingTime":{"minutes":5.19,"words":1558},"git":{"updatedTime":1778858121000,"contributors":[{"name":"GEYUANwuqi","username":"GEYUANwuqi","email":"[email protected]","commits":2,"avatar":"https://gravatar.com/avatar/1cf26d82e91dff657f3fa4d4911cdabcf7b76396339e886e69f99b15d4c8c808?d=retro"}]},"autoDesc":true,"filePathRelative":"notes/guide/8. 命令行工具/1. 命令.md"}');export{u as comp,g as data};