K2cr2O1
56b1014419
将核心模块按功能重新组织为更清晰的结构，包括 managers、handlers 和 utils 目录 添加完整的开发文档，涵盖快速开始、项目结构、核心概念和插件开发指南 更新所有相关模块的导入路径以匹配新的结构 将单例模式实现提取到单独的 singleton.py 文件
114 lines
3.5 KiB
Markdown
114 lines
3.5 KiB
Markdown
# 快速上手
|
||
|
||
本指南将引导您完成 NEO Bot Framework 的本地开发环境搭建、配置和首次运行。
|
||
|
||
## 1. 环境准备
|
||
|
||
在开始之前，请确保您的开发环境中已安装以下软件：
|
||
|
||
* **Python**: 版本要求 `3.12` 或更高。
|
||
* 我们推荐使用官方的 CPython 解释器。
|
||
* 您可以通过在终端运行 `python --version` 来检查您的 Python 版本。
|
||
|
||
* **Git**: 用于克隆项目仓库。
|
||
|
||
* **Redis**: 一个键值对数据库，用于缓存和数据共享。
|
||
* 对于 Windows 用户，可以考虑使用 `memurai` 或通过 WSL2 安装 Redis。
|
||
* 对于 macOS 用户，可以使用 `brew install redis`。
|
||
* 安装后，请确保 Redis 服务正在运行。
|
||
|
||
* **OneBot v11 实现端**: 机器人框架需要连接到一个实现了 OneBot v11 协议的客户端。
|
||
* **推荐**: [NapCatQQ](https://github.com/NapNeko/NapCatQQ)
|
||
|
||
## 2. 克隆与安装
|
||
|
||
### 克隆项目
|
||
|
||
打开您的终端，并克隆项目仓库到本地：
|
||
|
||
```bash
|
||
git clone [项目仓库地址]
|
||
cd [项目目录]
|
||
```
|
||
|
||
### 创建虚拟环境 (推荐)
|
||
|
||
为了保持项目依赖的隔离，强烈建议您创建一个 Python 虚拟环境。
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
|
||
# 激活虚拟环境
|
||
# Windows
|
||
.\venv\Scripts\activate
|
||
# macOS / Linux
|
||
source venv/bin/activate
|
||
```
|
||
|
||
### 安装依赖
|
||
|
||
激活虚拟环境后，使用 `pip` 安装所有必需的第三方库：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## 3. 配置
|
||
|
||
项目的核心配置位于根目录下的 `config.toml` 文件中。
|
||
|
||
对于内部开发，该文件通常已预先配置好，可以直接连接到测试服务器。如果您需要连接到自己的环境，请修改以下关键部分：
|
||
|
||
```toml
|
||
# config.toml
|
||
|
||
[napcat_ws]
|
||
# 您的 OneBot v11 实现端的 WebSocket 地址
|
||
# 格式通常为 ws://<IP地址>:<端口号>
|
||
uri = "ws://127.0.0.1:3001"
|
||
|
||
# Access Token (访问令牌)，如果您的 OneBot 端设置了
|
||
token = ""
|
||
|
||
[redis]
|
||
# Redis 服务的连接信息
|
||
host = "127.0.0.1"
|
||
port = 6379
|
||
db = 0
|
||
password = "" # 如果您的 Redis 设置了密码
|
||
```
|
||
|
||
## 4. 首次运行
|
||
|
||
完成以上所有步骤后，您就可以启动机器人了。在项目根目录运行：
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
如果一切顺利，您将在控制台看到类似以下的输出：
|
||
|
||
```
|
||
2026-01-07 22:42:41.718 | INFO | ... - 管理员管理器初始化完成
|
||
2026-01-07 22:42:41.826 | INFO | ... - 正在从 plugins 加载插件...
|
||
2026-01-07 22:42:41.994 | SUCCESS | ... - Redis 连接成功！
|
||
...
|
||
2026-01-07 22:42:42.618 | SUCCESS | ... - 连接成功！
|
||
```
|
||
|
||
看到 `连接成功！` 的日志，即表示您的机器人已成功连接到 OneBot 客户端并准备好接收消息。
|
||
|
||
## 5. 常见问题排查 (FAQ)
|
||
|
||
* **Q: 启动时报错 `redis.exceptions.ConnectionError`**
|
||
* **A**: 请检查您的 Redis 服务是否已启动，以及 `config.toml` 中的 `host` 和 `port` 是否正确。
|
||
|
||
* **Q: 无法连接到 WebSocket，提示 `ConnectionRefusedError`**
|
||
* **A**: 请确认您的 OneBot v11 客户端（如 NapCatQQ）是否正在运行，并检查 `config.toml` 中的 `uri` 地址和端口是否匹配。
|
||
|
||
* **Q: 修改了插件代码但没有生效**
|
||
* **A**: 框架默认开启了热重载功能。请检查控制台是否有 `[HotReload]` 相关的日志输出。如果没有，请确认 `watchdog` 库已正确安装。
|
||
|
||
现在，您的开发环境已经准备就绪。接下来，您可以尝试修改一个现有插件或[创建您的第一个插件](./plugin-development/index.md)！
|