ncatbot5 5.5.2.post3

NcatBot, NapCat Python SDK

🚀 ncatbot

---

文档 | 许可证 | QQ群 | 插件社区

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 号，CLI 会自动生成 config.yaml 和一个以你计算机用户名命名的模板插件。该模板插件的功能是：在群聊或私聊中发送 hello 时，机器人回复 hi。

4. 启动

ncatbot run

常用 CLI 命令：

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

交流群体

是 QQ 群哦喵~

获取帮助

遇到问题时，请按以下顺序尝试：

1. 阅读文档
2. 搜索 Issue 列表
3. 提交 Issue 或进群提问

使用限制

1. 严禁将本项目以任何形式用于传播淫秽、反动或暴力等信息。
2. 未经授权，禁止将本项目以任何形式用于盈利。

致谢

感谢 NapCat 提供底层接口 | IppClub 的宣传支持 | Fcatbot 提供代码和灵感。

感谢 林枫云 提供服务器支持。

参与贡献

欢迎给本 Repo 贡献代码！请先阅读 贡献指南。

Star History

贡献者们