内置管理命令
约 766 字大约 3 分钟
2026-03-23
框架内置
_system_manager插件提供的!前缀聊天命令：热重载、加载/卸载外部插件、系统信息与开关配置。
目录
权限与安全
- 所有命令仅当发送者 QQ 与全局配置中的
root（管理员）一致时才会执行；否则回复「无权执行此操作。」。 - 默认 仅私聊 可用；若要在群内使用，需将
plugin.builtin_commands_group_allowed设为true（群聊有泄露风险，请谨慎）。
命令一览
| 命令 | 作用 |
|---|---|
!reload <插件名> | 对 plugins/ 目录下已索引 的外部插件执行热重载（与文件监视触发的流程相同）。不支持内置插件名。 |
!load <插件名> | 按 manifest 加载单个外部插件（需已被扫描进索引）。 |
!unload <插件名> | 卸载已加载插件；禁止卸载内置插件（如 _system_manager）。 |
!sysinfo | 输出 NcatBot 版本、Python 与系统信息、已加载插件列表、debug / 热重载等状态（不含敏感 token）。 |
!builtin on / !builtin off | 写入全局配置中的 plugin.enable_builtin_commands 并保存；关闭后其它 ! 命令立即失效，!builtin on 在总开关关闭时仍可使用以便恢复。 |
!plugins | 列出所有已加载的插件（名称、版本、作者、描述）。 |
!indexed | 列出所有已索引但未加载的外部插件（可用 !load 加载）。 |
!commands | 列出所有在 HandlerDispatcher 中注册的命令及其所属插件。 |
!filter <子命令> | 管理分发过滤规则（详见下方）。 |
分发过滤命令
!filter 用于管理分发过滤规则——在群/用户维度禁用指定插件或命令。需要 dispatch_filter 服务可用。
!filter add
!filter add <group|user> <scope_id> <plugin_name> [command1,command2,...]添加一条过滤规则。plugin_name 为 * 时匹配全部插件。不指定命令列表时禁用整个插件。
示例：
!filter add group 12345 weather_plugin # 在群 12345 禁用 weather_plugin
!filter add user 67890 * echo,ping # 对用户 67890 禁用所有插件的 echo 和 ping 命令!filter remove
!filter remove <rule_id>按 rule_id 移除单条规则。rule_id 可通过 !filter list 获取。
!filter list
!filter list [group|user] [scope_id]查询过滤规则。不带参数列出全部规则。
!filter clear
!filter clear [plugin_name]批量清除规则。不带参数清除全部。
配置项
在 config.yaml 的 plugin 段：
plugin:
enable_builtin_commands: true # 总开关
builtin_commands_group_allowed: false # 是否允许在群聊使用（默认仅私聊）
builtin_commands:
reload: true
load: true
unload: true
sysinfo: true
config_toggle: true # 是否允许 !builtin on/off
plugins: true # 是否允许 !plugins
indexed: true # 是否允许 !indexed
commands: true # 是否允许 !commands
filter: true # 是否允许 !filter缺省情况下各子命令为 true；未列出的子命令视为开启。
说明与限制
- 热重载、加载、卸载仅针对 外部插件（
plugins/目录、manifest.toml已索引）。内置插件不提供聊天热重载。 - 配置项
plugin.enable_builtin_commands与细粒度开关可在 handler 内即时生效，无需重启 Bot。
完整示例
- 分发过滤（Mixin API + !filter）：examples/common/08_dispatch_filter/main.py
版权所有
版权归属：MI