BOT 命令系统 @命令 快捷命令 内联键盘
为什么需要命令系统
纯靠关键词匹配来响应消息既不清晰也不安全。命令系统让 BOT 的交互变得结构化、可预期、好上手——成员不用猜 BOT 会在什么情况下响应什么，而是通过明确的命令入口触发功能。
Fanbook 的 BOT 命令体系有三层：
- 频道机器人命令列表（输入
@机器人弹出） - 频道快捷命令列表（常驻输入框上方）
- 命令返回的内联键盘卡片（命令执行后的交互式 UI）
频道机器人命令列表
触发方式
在文本频道的输入框中输入 @ 并选择目标机器人，弹出该机器人的命令列表，展示它支持的所有命令及参数提示。
实现方式
开发者在 Bot API 中通过命令列表接口（具体端点见开发者平台）配置命令定义。每个命令包含：
- 命令名称（如
签到积分排行榜） - 命令的简短描述
- 可选的参数说明
- 是否显示在命令列表中（管理员可以隐藏低频命令）
示例体验
假设你在频道里输入 @积分BOT，弹出的命令列表可能长这样：
@积分BOT
[积分] 查询自己的积分余额
[积分排行榜] 查看积分排行
[积分兑换] 用积分兑换奖品频道快捷命令列表
功能
管理员可以从某个 BOT 的命令列表中，选择高频常用的命令配置为频道内的常驻快捷按钮，显示在聊天输入框上方。
与 @命令列表的区别
| 对比项 | 快捷命令 | @命令列表 |
|---|---|---|
| 显示位置 | 输入框上方，常驻 | 输入框内，输入 @ 才出现 |
| 适用命令 | 高频、常用 | 所有命令（含低频） |
| 操作方式 | 一键点击 | 输入 @ + 选择 |
| 成员感知 | 强——进来就看到 | 弱——需要主动触发 |
推荐配置
- 签到频道： 快捷命令只放
!签到，让签到变得零门槛 - 综合频道： 快捷命令放 2~3 个最常用的（如
!查看积分!反馈），其他留在 @命令列表里 - 不要贪多： 快捷按钮超过 5 个就会让界面变乱，反而找不到
配置方法
- 进入目标频道
- 频道设置 → 快捷命令（或类似选项）
- 选择已添加的 BOT → 勾选要设置为快捷命令的命令
- 保存后即可在频道内看到
内联键盘（交互卡片）
功能
命令执行后，BOT 可以返回一个带按钮的交互卡片，成员点击按钮进行下一步操作。这比纯文字回复的用户体验好得多。
典型场景
签到成功后：
✅ 签到成功！今日获得 10 乐豆，连续签到 7 天额外奖励 +50
[查看我的积分] [查看排行榜] [去兑换奖品]活动报名后：
🎮 你已报名「周末开黑活动」，活动时间本周六 20:00
[取消报名] [查看活动详情] [邀请好友一起]开发者实现
通过 Bot API 的 sendMessage 接口，在消息体中传入 reply_markup 字段定义内联键盘：
{
"chat_id": "xxx",
"text": "签到成功",
"reply_markup": {
"inline_keyboard": [
[{"text": "查看积分", "callback_data": "check_points"}],
[{"text": "排行榜", "callback_data": "ranking"}]
]
}
}用户点击按钮后，Bot 通过回调（callback）接收事件，执行对应操作并返回新的卡片或消息。
命令可见性规则
管理员可以控制命令的可见性：
- 某些命令只对特定角色可见（如管理员命令
!重置排行榜只在管理员的 @命令列表里出现） - 某些命令只在特定频道可用
- 某些命令可以完全隐藏（通过 Bot API 直接调用，但不在列表里展示）
命令设计建议
命名要直觉
- ✅
!签到!我的积分!排行榜 - ❌
!run!exec2!cmd-3
帮助信息要明确
每条命令都要有简短描述，告诉成员：
- 这个命令干什么的
- 需要什么参数（如果有）
- 执行后会发生什么
错误反馈要友好
命令执行失败时，不要只返回「错误」，告诉用户：
- 为什么失败（如「你已经签过到了，明天再来吧~」）
- 怎么解决（如「签到每天 00:00 刷新」）
不要过于依赖命令
不是所有 BOT 功能都需要命令触发。对于高频简单操作（签到），用快捷命令。对于需要复杂交互的，用内联键盘。对于纯自动化的（每日定时提醒），让 BOT 自己触发，不需要用户操作。