🚀 ncatbot
NcatBot 是基于 OneBot11 协议的 Python SDK/Framework，提供开箱即用的 QQ 机器人开发体验。
它深度考虑了 AI 时代的开发者需求，工作区内置丰富的 Skills 能力，Agent 可自主完成插件编写、调试与测试。
只需要一句话，就能写出你的 QBot！
快速开始
1. 安装
pip install ncatbot5
2. 获取 AI 参考资料（推荐）
ncatbot ref # 交互式选择 IDE
ncatbot ref --vscode # VSCode + Copilot / Cursor
ncatbot ref --trae # Trae
一键从 GitHub Releases 下载最新版 user-reference.zip 并自动解压到当前目录（自动使用 GitHub 代理加速）。也可以手动前往 GitHub Releases 页面下载。解压后目录结构如下：
your-project/
├── .agents/skills/ ← AI Agent 技能文件（framework-usage / testing 等）
├── docs/
│ └── docs/
│ ├── examples/ ← 示例代码（qq / github / cross_platform …）
│ └── notes/
│ ├── guide/ ← 使用指南（快速开始 → 多平台开发，共 11 章）
│ └── reference/ ← API 参考（Bot API / 事件类型 / 插件系统 等）
├── config.yaml
└── plugins/
这些文件让 AI Agent（如 VS Code 中的 Copilot Chat）理解 NcatBot 的 API 和用法，从而提供精准的代码建议。
3. 初始化项目并配置适配器
ncatbot init
按提示输入机器人 QQ 号和管理员 QQ 号（非 QQ 平台可留空），随后会自动进入适配器管理界面（TUI）。启动机器人前，请在这里启用并配置要连接的平台适配器：
- ↑ / ↓：选择适配器。
- 空格：启用或禁用适配器。
- Enter：进入所选适配器的配置向导，按提示填写连接信息；完成配置后会自动启用该适配器。
- q：保存并退出。
例如，连接 QQ 时选择 NapCat 并按 Enter，按提示选择自动安装，或填写已有 NapCat 的 WebSocket / WebUI 地址和 Token。请完成配置后再保存退出，仅勾选启用不会运行配置向导。
CLI 会将配置保存到 config.yaml，并创建一个以你计算机用户名命名的模板插件。使用 QQ 模板时，在群聊或私聊中发送 hello，机器人会回复 hi。
后续需要修改连接信息或启用其他适配器时，在项目目录运行以下命令，即可重新打开同一配置界面：
ncatbot adapter
4. 启动
ncatbot run
常用 CLI 命令：
ncatbot adapter # 启用、禁用或配置平台适配器
ncatbot config show # 查看当前配置
ncatbot napcat diagnose # 诊断 NapCat 连接
ncatbot napcat stop # 停止本机 NapCat（仅 Linux）
AI Agent 开发
工作区中预置了领域专有技能（Skills），在 VS Code 中使用 Copilot Chat 即可获得定制化辅助：
- 开发插件：Agent 利用
framework-usage技能提供消息发送、事件注册、Hook/过滤器等建议 - 框架开发：
codebase-nav（代码定位）、framework-dev（框架开发）、testing（测试）、release（发版）
直接用自然语言描述你要实现的功能，Agent 会自主编写插件代码。
其它资源
- 容器化部署：推荐使用 Docker 部署环境
- 官方文档：docs.ncatbot.xyz
交流群体
获取帮助
遇到问题时，请按以下顺序尝试：
使用限制
- 严禁将本项目以任何形式用于传播淫秽、反动或暴力等信息。
- 未经授权，禁止将本项目以任何形式用于盈利。
致谢
感谢 NapCat 提供底层接口 | IppClub 的宣传支持 | Fcatbot 提供代码和灵感。
感谢 林枫云 提供服务器支持。
参与贡献
欢迎给本 Repo 贡献代码！请先阅读 贡献指南。
1 maintainer
Metadata
1 maintainer
Release files for ncatbot5 5.5.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ncatbot5-5.5.10.tar.gz | 311.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ncatbot5-5.5.10-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 748.9 kB
Release files / ncatbot5-5.5.10.tar.gz
| Download URL | ncatbot5-5.5.10.tar.gz |
|---|---|
| Size | 311.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
edba4d98af0d649ccdf6226f3a65bd51f564c18f935b42a4ffafe727b5221a2d
|
|
BLAKE2b-256 checksum How to use checksums |
9823eed55744b02047288c7a17a89005ed48192f1726a3536ca555d9ce0bb117
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ncatbot5-5.5.10-py3-none-any.whl
| Download URL | ncatbot5-5.5.10-py3-none-any.whl |
|---|---|
| Size | 437.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
99c65d4225950e6515dc4a13b052f0f59d953b21a3c8dda473d6895476a621cf
|
|
BLAKE2b-256 checksum How to use checksums |
94f5eaa6209ea219fe3c16a7b48aecd315a386d5559727b139ad20b5a53c8616
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
