帮助消息与指令面板
读完这一页，你能给命令登记帮助文字，让用户在 QQ 里查到它的用法。
在 on_load 中调用 server.register_help_message(...)，为命令登记帮助文字和 QQ 指令面板项。命令树和帮助分开注册，互不影响。
先分清两个词。普通帮助列表就是用户在 QQ 里发 /botqraft 看到的那张表，按查询者的权限和语言生成。指令面板项是 QQ 客户端里机器人指令面板上的一条入口，由框架同步到平台。
登记命令帮助
给 Echo 添加帮助：
python
server.register_help_message(
'/echo',
{'zh_cn': '复述提供的文本', 'en_us': 'Echo the supplied text'},
scope=('group', 'c2c'),
)把这段放在命令注册之后。完整接口为：
python
server.register_help_message(
prefix, message, permission=0,
scope=('group', 'c2c'), only_admin=False,
)| 参数 | 填写方式 |
|---|---|
prefix | 命令前缀，用于帮助显示和面板项名称，例如 /echo。 |
message | 英文字符串、语言字典，或 server.rtr(...) 延迟翻译文本。 |
permission | 普通帮助列表所需的最低权限，默认 0。 |
scope | 帮助适用的场景，和命令注册保持一致。 |
only_admin | 平台指令面板的管理员点击和操作限制，默认 False。 |
scope 和 only_admin 是关键字参数。
在 QQ 里发送 /botqraft，看到的就是当前来源可见的插件帮助列表，也就是前面说的普通帮助列表。/botqraft help 展示的是内置运维命令目录。
普通帮助按查询来源的用户语言解析。QQ 指令面板在同步时按实例配置的语言解析。需要翻译文件时，阅读翻译与用户语言。
区分显示权限和执行权限
给群聊管理命令登记帮助时，可以这样写：
python
server.register_help_message(
'/admin',
{'zh_cn': '管理命令', 'en_us': 'Administration commands'},
permission=2,
scope=('group',),
only_admin=True,
)三项设置各管一件事：
permission=2过滤普通帮助列表，也就是/botqraft那张表。only_admin=True决定谁有 QQ 指令面板的管理员点击和操作资格。面板项是否可见由平台决定。- 命令节点上的
requires(lambda source: source.has_permission(2))检查真正执行时的权限。
按平台要求编写面板文字
QQ 指令面板把 prefix 当作名称，把翻译后的 message 当作描述：
| 字段 | 平台约束 |
|---|---|
| 名称 | 1–14 字符。 |
| 描述 | 1–30 字符。 |
| 字符 | 使用非控制字符。 |
| 项数 | 每个场景最多展示 20 项。 |
为每种语言准备简短描述。详细用法放进命令回复里，面板只留入口说明。
超出 20 项的前缀仍然保留命令注册，你可以通过面板状态查询没被展示的项目。面板同步和命令执行是两条路径。
查看面板状态
在插件回调中读取状态快照：
python
status = server.get_panel_status('group')
server.logger.info('Panel state: %s', status.state)
server.logger.info('Undisplayed prefixes: %s', status.undisplayed_prefixes)查询私聊面板时改用 server.get_panel_status('c2c')。状态快照还提供 reason、err_code、code、http_code 和 trace_id，方便你查同步失败的原因。
接下来，安装并验证第一个插件。