帮助文档
IdhagnBot 会为命令自动生成帮助,你也可以编写自定义的帮助项。
用户说明
在群聊或私聊中发送 /help
就可以查看所有帮助,你应该看到如下格式的帮助文档。不能执行的命令会被自动隐藏。
第 1 页,共 10 页
使用 /帮助 <命令名> 查看详细用法
.foxtail - 兽云祭
.furbot - 绒狸
.meme_pic - 头像梗图生成器
.meme_word - 文字梗图生成器
/60秒 - 用60秒迅速看世界
/emojimix - 缝合两个emoji
/epicfree - 看看E宝又在送什么
/fortune - 随机显示一条可能有用的格言
/idhagnfetch - 显示机器人的状态
其中以 .
点号开头的是子分类,以 /
斜线开头的是命令,在查看帮助时不能带上这两个符号,比如:
- ✅ 你应该使用
/help meme_pic
和/help idhagnfetch
- ❌ 而非
/help .meme_pic
和/help /idhagnfetch
子分类是树形的,意味着子分类下还可以有子分类,但目前 IdhagnBot 的通用插件并不包含二级子分类,如果有,你需要输入 /help some_category some_child
这样的形式来查看。
在 /help 命令最后加上空格和数字可以指定页数,如:
/help 2
/help meme_pic 2
/help some_category some_child 2
在查看命令帮助时,会在末尾显示命令的别名,输入 /help <别名>
也能看到帮助,但别名不会显示在帮助列表中。并且当一个命令位于子分类中时,不能带上子分类,比如你应该输入 /help rua
而非 /help meme_pic rua
。
比如 /help idhagnfetch
和 /help state
都会显示如下内容:
/idhagnfetch - 显示机器人的状态
服务器在线在重启系统(含崩溃自动重启)时归零
机器人在线在重启机器人(含重启系统)时归零
该命令有以下别名:状态、state、运行时间、uptime
部分命令,如 /rua
,采用类似于 UNIX shell 的命令解析(参见 Python 标准库:argparse 和 shlex),为了和其他不使用 shell 解析的命令统一,输入 /rua -h
或者 /rua --help
查看帮助的方法已被禁用。
搭建说明
命令帮助会被自动创建,如果需要完整的列表,同样可以运行 pdm start --export-html <HTML文件名>
来导出。
如果需要创建自定义的帮助项目,可以编辑 configs/help.yaml
,参考如下:
page_size: 10 # 每页的项目数,默认为 10
user_helps: # 自定义帮助项
- # 指定一个自定义命令
priority: 0 # 排序优先级,优先级相同时权限小的在前面,权限也相同时按字典序排列,默认为 0
node_str: some_node.some_child # 权限节点,不满足权限时不显示帮助项目,默认为不检查
has_group: # 参见 上下文#用户说明 里的第一类命令,默认为不检查
- 123456789
in_group: # 参见 上下文#用户说明 里的第二类命令,默认为不检查
- 123456789
private: true # true:只在私聊显示,false:只在群聊显示,null:都显示,默认为 null
level: member # 权限等级,默认为 member
category: some_category.some_child # 分类,默认为根分类(即直接输入 /help 显示的分类)
command: # 命令名,第一个为主名称(会在帮助列表中显示),其余为别名,不可以省略
- 主名称
- 别名1
- 别名2
brief: "帮助列表中的简单描述,默认为空"
usage: "输入 /help 命令名 时的完整描述,默认为空"
- # 指定一行自定义文本,所有自定义文本都会排在优先级相同的命令前面
priority: 0
node_str: ""
has_group: []
in_group: []
private: null
level: member
category: ""
# 以上选项含义相同,并且都可以省略
string: "内容,不可以省略"
- # 在指定 category 时,如果对应分类不存在,会自动创建一个没有描述的分类,可以增加描述
category: some_category.some_child
brief: "这是描述blabla"
# 分类同样可以指定权限信息等
- "如果不需要参数,也可以直接输入字符串"
开发示例
CommandBuilder
会自动为命令创建帮助,参见以下示例:
from nonebot.rule import ArgumentParser
from util import command
# 简单命令示例:
# 其余参数,如 level、in_group、has_group 等也会自动应用到帮助上。
matcher = (
command.CommandBuilder("some_plugin.some_command", "命令名")
.brief("简单描述")
.usage("使用说明")
.build()
)
@matcher.handle()
async def handler() -> None:
pass
# argparse / nonebot.on_shell_command 示例:
# CommandBuilder.shell 会自动加上命令名,此处无需指定 prog
# add_help=False 的原因见上
parser = ArgumentParser(add_help=False)
matcher = (
command.CommandBuilder("some_plugin.some_command", "命令名")
.brief("简单描述")
.usage("覆盖使用说明") # 如有需要也可以覆盖 usage,在 .shell() 之前或之后均可
.shell(parser) # 当使用 argparse 时,会使用 ArgumentParser.format_help 自动创建 usage
.build()
)
@matcher.handle()
async def handler() -> None:
pass
同 help.yaml,CommandBuilder 遇到不存在的 category 时也会自动创建,可以使用以下代码添加描述和自定义文本:
from util import help
# 第二个参数为 True 时,不存在自动创建,否则抛出异常,默认为 False
category = help.CategoryItem.find("some_category.some_child", True)
category.brief = "这是描述blabla"
data = help.CommonData(priority=123) # 使用 CommonData 指定优先级、权限节点等,也可以不指定
category.add(help.StringItem("你也可以加入自定义文本", data))
# 尽管可以自行实例化 CommandItem,但建议优先考虑 CommandBuilder
category.add(help.CommandItem(["命令名"], "简单描述", "使用说明", data))
# CommandItem 也有 find 方法,参数接受命令名而非权限节点
command = help.CommandItem.find("命令名")
# 使用 CategoryItem.ROOT 获取根分类
category = help.CategoryItem.ROOT