指令手册#

本文覆盖 ILBB 在 QQ（OneBot V11）里的全部指令。所有指令都能用 WebUI 的「指令中心」干跑预览，不用真的发到群里试。

一、触发规则#

规则	由谁控制	默认
指令前缀	`BOT_PREFIX`	`/`（最多 3 个字符，可改成 `#` 等）
群聊是否必须 @ 机器人	`BOT_GROUP_NEED_AT`	`false`（直接发 `/help` 就回）
是否允许私聊使用	`BOT_ALLOW_PRIVATE`	`true`
同一用户指令最小间隔	`BOT_COOLDOWN_SEC`	`3` 秒（冷却期内静默忽略）
指令总开关	`BOT_ENABLED`	`true`（设 `false` 则全部静默，含 `/help`）

几条容易被忽略的行为：

群里要求 @ 机器人时，@机器人 /meme 摸头 这种不带前缀的写法也认。
机器人不会回自己的消息（self_id 等于发送者时直接跳过），所以不会自问自答。
冷却期内不给任何提示，直接忽略，避免刷屏。
机器人只处理 message 类型事件；通知、请求、元事件只在后台日志与事件流里展示，不回应。

二、指令总览#

指令	别名	作用
`/help`	`/菜单` `/menu` `/?` `/？`	返回图片版指令总览菜单
`/meme`	`/表情` `/生图`	表情生成
`/pair`	`/配对` `/卡片`	生成 QQ 风格配对卡片
`/quote`	`/名言` `/名言图`	生成名言图
`<插件触发词>`	—	由插件 `plugin.json` 声明

单独发 /help 之外的任何未知词，机器人会回一张「没有这条指令」的提示图，并告诉你用 /help 查看全部指令。

三、`/help` —— 图片菜单#

文本

/help

返回一张排版好的图片菜单（不是文字），包含：

全部指令的用法与一句话说明
4 张真实素材的效果预览
素材总数与落款（落款文字由 BOT_FOOTER 控制）

手机端也能看清，适合直接转发给群友当说明书。

四、`/meme` —— 表情生成#

4.1 三种用法#

文本

/meme                      打开表情生成器用法说明（帮助图）
/meme list [页码/关键词]    浏览 / 搜索素材
/meme help [ID]            单个表情的图文教程
/meme [关键词] [文本…]      直接合成表情

4.2 直接合成#

文本

/meme 摸头
/meme 摸头 你好呀
/meme 摸头 @某人
/meme 摸头 10001
/meme 摸头 文本1 文本2

参数解析规则（照这个顺序）：

键=值 —— 如果键名是该表情支持的预设项，则作为预设参数，例如 mode=loop、num=3、name=小明。多个预设用空格分隔，顺序不限。
@某人 —— 取出被 @ 者的 QQ 号备用。
5~12 位纯数字 —— 视为 QQ 号（因此文本如果正好是 5~12 位数字会被当成 QQ 号，这种文本请放在其它位置或改用 键=值 形式）。
其余 —— 当作文本段，按顺序对应表情要求的第 1、2… 段文本。

4.3 怎么给图#

方式	写法	说明
直接带图	指令和图片一起发	图片按发送顺序作为第 1、2… 张素材
引用图片	回复一条带图消息再发指令	使用被引用消息里的图片
@ 某人	`/meme 摸头 @群友`	机器人取 TA 的头像当素材
写 QQ 号	`/meme 摸头 10001`	机器人取该 QQ 的头像当素材，不用带图

图片不够时，机器人会按「先 @ 的人，再指令里的 QQ 号」的顺序自动补头像。所以需要 2 张图的表情，/meme 亲亲 @A @B 就能直接用。

4.4 浏览与搜索素材#

文本

/meme list            第 1 页
/meme list 3          第 3 页
/meme list 摸头        按关键词搜索
/meme list 2 摸头      搜索结果的第 2 页

每页条数由 BOT_MEME_LIST_PAGE 控制（默认 12），超出会自动分成多张图发送。列表里每个素材都带列表 ID，供下一条指令使用。

4.5 看单个表情的教程#

文本

/meme help 42

返回一张图，包含该表情的底图、名称、支持的预设项与取值、需要几张图、需要几段文本、使用示例。不确定某个表情怎么用的时候先发这个。

4.6 预设参数#

不同表情支持的预设完全不同（比如 mode=loop、num=3、name=小明），没有统一清单，用 /meme help [ID] 查。

4.7 常见报错#

提示	原因	怎么办
找不到这个表情	关键词拼错，或素材未下载	`/meme list 关键词` 搜索正确名字；确认引导页素材已下载
图片数量不对	该表情要求固定张数	按提示增减图片，或多 @ 几个人
文本数量不对	文本段数与表情要求不符	参考 `/meme help [ID]` 里的说明
文字太长	单段文本超过该表情上限	缩短文本
图片过大	超过 `BOT_MAX_IMAGE_MB`	机器人会尝试压缩，压不动就放弃

五、`/pair` —— 配对卡片#

生成一张 QQ 风格的配对卡片（头像 + 标题 + 按钮），和 WebUI 里的配对生成器同款。

文本

/pair                        帮助图
/pair 10001                  用 QQ 号 10001 的头像
/pair 10001 我们的配对结果     带标题
/pair @某人 我们的配对结果     群里 @ 群友

可选参数#

参数	取值	说明
`template=`	`classic` / `dark` / `paper`	模板：经典弹窗（浅蓝玻璃，默认）/ 深邃玻璃 / 清新纸张
`title=`	任意文字	卡片标题；标题含空格时用 `title=` 更稳
`bg=`	`random` / `color` / `gradient` / `image`	背景：随机（默认）/ 纯色 / 渐变 / 图片
`btn=`	用 `\|` 分隔的文字	按钮文字，最多 4 个，如 `btn=配对\|接受\|拒绝`

示例#

文本

/pair 10001 我们的配对结果
/pair 10001 title=今天的缘分 template=paper
/pair @某人 btn=接受|拒绝 bg=gradient

六、`/quote` —— 名言图#

给一张头像 + 一句话（或一个表情包），合成名言图，输出 JPG。

文本

/quote 这就是名言                     署名默认是发送者昵称（群聊取群名片）
/quote @某人 这就是名言                用被 @ 者的头像与昵称
/quote 10001 这就是名言               直接写 QQ 号
/quote help                          帮助图

成品结构：

版式 —— 横屏 16:9（QUOTE_WIDTH × QUOTE_HEIGHT，默认 1280×720），左侧一块独立的长方形圆角头像，右侧铺满右半边的白色磨砂玻璃面板，面板里放文字或表情包
背景 —— 与主页背景同源的随机二次元图（BG_API），背景上压一层灰色蒙版（QUOTE_MASK_ALPHA，默认 0.35 = 压 35% 灰，背景仍可辨认）；玻璃面板 / 头像 / 文字都绘制在蒙版之上
磨砂玻璃面板 —— 铺满右半边（整高）：覆盖范围内的背景整块高斯模糊（QUOTE_TRAY_BLUR，默认 30），再叠一层暖白玻璃（QUOTE_TRAY_GLASS，默认 0.58）与顶部反光；面板左缘有一段横向渐变渐隐（QUOTE_TRAY_FADE），左边缘整体透明，和中间背景自然衔接、不会出现硬边；文字自动从大往小试字号，装不下就截断加省略号；表情包自适应缩放
头像 —— 左侧一块独立的长方形圆角头像（QUOTE_AVATAR，默认宽度 236，高度 = 宽度 × 1.32）；不填则用内置占位头像
署名 —— 右下角「—— 用户名」，字体跟随全局字体 FONT_FAMILY，不再单独配置

成品输出：面板内容是静态的给 JPG，内容是动图表情包的给 GIF（动图表情包会保留动画）。Web 端「名言图」表单里可以直接切全局字体（主页那套 ILBB 自定义下拉），署名会跟着一起变。

排版相关参数都能调，见 configuration.md。

想关掉这个功能：QUOTE_ENABLED=false，此时只回一张提示图。

七、插件指令#

插件可以注册自己的触发词，用法由插件自己定义：

文本

/<插件触发词> [参数…]

plugins/example/ 示例插件注册了：

指令	作用
`/example`	回一条示例消息（演示配置项与图片回复）
`/echodemo 内容`	原样回显
`/exampleinfo`	显示插件当前配置与运行信息

插件指令的解析优先级低于内置指令：如果插件触发词和 /meme 撞名，内置指令优先。写插件时避开内置名字（help menu meme 表情 生图 pair 配对 卡片 quote 名言 名言图）。

详见 plugin-dev.md。

八、在 WebUI 里试指令#

不想真的发到群里，用 WebUI 的指令中心：

模式	行为
干跑预览	不联网取图，@ / QQ 号的头像用本地占位图顶替，判定逻辑与真实发送完全一致
Web 会话	完全按真实发送走，包括联网取 QQ 头像

两者共用同一段指令解析代码（run_command()），所以预览结果就是真实结果。

九、速查卡#

文本

/help                                菜单（图片）
/meme                                表情生成帮助
/meme 摸头 你好呀                     合成表情
/meme 摸头 @某人                      用群友头像当素材
/meme 摸头 10001                      用 QQ 头像当素材
/meme 摸头 mode=loop num=3            带预设参数
/meme list                           素材列表第 1 页
/meme list 摸头                       搜索素材
/meme help 42                        第 42 号表情的教程
/pair 10001 我们的配对结果             配对卡片
/pair @某人 template=paper btn=A|B    带模板与按钮
/quote 这就是名言                     名言图
/quote @某人 这就是名言                指名道姓的名言图