NeoBot/docs/getting-started.md

快速上手

本指南将引导您完成 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

2. 克隆与安装

克隆项目

打开您的终端，并克隆项目仓库到本地：

git clone [项目仓库地址]
cd [项目目录]

创建虚拟环境 (推荐)

为了保持项目依赖的隔离，强烈建议您创建一个 Python 虚拟环境。

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
.\venv\Scripts\activate
# macOS / Linux
source venv/bin/activate

安装依赖

激活虚拟环境后，使用 pip 安装所有必需的第三方库：

pip install -r requirements.txt

3. 配置

项目的核心配置位于根目录下的 config.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. 首次运行

完成以上所有步骤后，您就可以启动机器人了。在项目根目录运行：

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 库已正确安装。

现在，您的开发环境已经准备就绪。接下来，您可以尝试修改一个现有插件或创建您的第一个插件！