# 快速上手

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