ncatbot 命令行工具完整 API 参考。基于 Click 构建。

Quick Start

ncatbot --help          # 查看所有命令
ncatbot <command> --help  # 查看单个命令帮助

入口点

# pyproject.toml
[project.scripts]
ncatbot = "ncatbot.cli:main"

也可通过模块方式调用：

python -m ncatbot.cli

---

顶层命令

ncatbot [OPTIONS] [COMMAND]

选项	说明
--version	显示版本号
--help	显示帮助信息

无子命令时进入交互模式（REPL）。

init

ncatbot init [OPTIONS]

初始化项目，创建 config.yaml、plugins/ 目录，以及一个以当前计算机用户名命名的模板插件。

选项	类型	默认值	说明
--dir	str	.	目标目录

交互式提示：

提示	说明
请输入机器人 QQ 号	写入 bot_uin
请输入管理员 QQ 号	写入 root

若 config.yaml 已存在，提示是否覆盖。

生成的模板插件位于 plugins/{username}/，包含 manifest.toml 和 plugin.py，实现群聊/私聊发送 hello 回复 hi。若模板插件目录已存在则跳过。

run

ncatbot run [OPTIONS]

启动 NcatBot（连接 NapCat + 加载插件 + 监听事件）。

选项	类型	默认值	说明
--debug	flag	False	启用调试模式
--no-hot-reload	flag	False	禁用插件热重载
--plugin-dir	str	plugins	插件目录路径

dev

ncatbot dev [OPTIONS]

以开发模式启动（debug=True + 热重载）。

选项	类型	默认值	说明
--plugin-dir	str	plugins	插件目录路径

config

ncatbot config COMMAND

配置管理命令组。

config show

ncatbot config show

以 YAML 格式显示当前全部配置。

config get

ncatbot config get CONFIG_KEY

参数	类型	说明
CONFIG_KEY	str	配置项路径，支持点分（如 napcat.ws_uri）

config set

ncatbot config set CONFIG_KEY CONFIG_VALUE

参数	类型	说明
CONFIG_KEY	str	配置项路径，支持点分
CONFIG_VALUE	str	值（自动类型转换）

类型转换规则：

输入值	转换类型
true / yes	bool (True)
false / no	bool (False)
纯数字字符串	int
[...] JSON 格式	list
其它	str

config check

ncatbot config check

检查配置安全性和必填项，输出问题列表。

plugin

ncatbot plugin COMMAND

插件管理命令组。

plugin list

ncatbot plugin list

列出已安装插件，显示名称、版本、作者、状态。读取每个插件目录下的 manifest.toml。

plugin create

ncatbot plugin create NAME

参数	类型	说明
NAME	str	插件名（字母开头，仅字母/数字/下划线）

在插件目录下生成标准脚手架，包含 __init__.py、manifest.toml、plugin.py、README.md。

plugin info

ncatbot plugin info NAME

参数	类型	说明
NAME	str	插件名

显示插件 manifest.toml 元数据。

plugin enable

ncatbot plugin enable NAME

启用插件：从黑名单移除，若白名单存在则加入白名单。

plugin disable

ncatbot plugin disable NAME

禁用插件：从白名单移除，加入黑名单。

plugin remove

ncatbot plugin remove NAME

参数	类型	说明
NAME	str	插件名

删除插件目录（含所有文件），并从黑名单/白名单中移除。

版权所有

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)