5f16c288bf
* 滚木 * feat: 重构核心架构，增强类型安全与插件管理 本次提交对核心模块进行了深度重构，引入 Pydantic 增强配置管理的类型安全性，并全面优化了插件管理系统。 主要变更详情： 1. 核心架构与配置 - 重构配置加载模块：引入 Pydantic 模型 (`core/config_models.py`)，提供严格的配置项类型检查、验证及默认值管理。 - 统一模块结构：规范化模块导入路径，移除冗余的 `__init__.py` 文件，提升项目结构的清晰度。 - 性能优化：集成 Redis 缓存支持 (`RedisManager`)，有效降低高频 API 调用开销，提升响应速度。 2. 插件系统升级 - 实现热重载机制：新增插件文件变更监听功能，支持开发过程中自动重载插件，提升开发效率。 - 优化生命周期管理：改进插件加载与卸载逻辑，支持精确卸载指定插件及其关联的命令、事件处理器和定时任务。 3. 功能特性增强 - 新增媒体 API：引入 `MediaAPI` 模块，封装图片、语音等富媒体资源的获取与处理接口。 - 完善权限体系：重构权限管理系统，实现管理员与操作员的分级控制，支持更细粒度的命令权限校验。 4. 代码质量与稳定性 - 全面类型修复：解决 `mypy` 静态类型检查发现的大量类型错误（包括 `CommandManager`、`EventFactory` 及 `Bot` API 签名不匹配问题）。 - 增强错误处理：优化消息处理管道的异常捕获机制，完善关键路径的日志记录，提升系统运行稳定性。 * feat: 添加测试用例并优化代码结构 refactor(permission_manager): 调整初始化顺序和逻辑 fix(admin_manager): 修复初始化逻辑和目录创建问题 feat(ws): 优化Bot实例初始化条件 feat(message): 增强MessageSegment功能并添加测试 feat(events): 支持字符串格式的消息解析 test: 添加核心功能测试用例 refactor(plugin_manager): 改进插件路径处理 style: 清理无用导入和代码 chore: 更新依赖项 * refactor(handler): 移除TYPE_CHECKING并直接导入Bot类 简化类型注解，直接导入Bot类而非使用TYPE_CHECKING条件导入，提高代码可读性和维护性 * fix(command_manager): 修复插件卸载时元信息移除不精确的问题 修复 CommandManager 中 unload_plugin 方法移除插件元信息时使用 startswith 导致可能误删其他插件的问题，改为精确匹配 同时调整相关测试用例验证精确匹配行为 * refactor: 清理未使用的导入和更新文档结构 docs: 添加config_models.py到项目结构文档 docs: 调整数据目录位置到core/data下 docs: 更新权限管理器文档描述 * 文档更新 * 更新thpic插件 支持一次返回多张图 --------- Co-authored-by: baby20162016 <2185823427@qq.com>
396 lines
14 KiB
Markdown
396 lines
14 KiB
Markdown
# Calglau BOT by NEO Bot Framework
|
||
|
||
> **[INTERNAL USE ONLY]**
|
||
>
|
||
> 本仓库为 Calglau BOT 的内部开发版本，请遵守相关保密协议。
|
||
|
||
**Powered by NEO Bot Framework**
|
||
|
||
## 📖 项目概述
|
||
|
||
**Calglau BOT** 是一个基于 NEO Bot Framework 构建的、功能丰富的 QQ 机器人。它被设计为一个模块化、易于扩展的内部工具，通过插件化的方式集成了多种实用与娱乐功能。
|
||
|
||
本项目旨在提供一个稳定、高性能且开发体验优秀的机器人平台，服务于我们的社群管理和日常自动化需求。
|
||
|
||
### ✨ 核心特性
|
||
> **[INTERNAL USE ONLY]**
|
||
>
|
||
> 本仓库为 Calglau BOT 的内部开发版本，请遵守相关保密协议。
|
||
|
||
**Powered by NEO Bot Framework**
|
||
|
||
## 📖 项目概述
|
||
|
||
**Calglau BOT** 是一个基于 NEO Bot Framework 构建的、功能丰富的 QQ 机器人。它被设计为一个模块化、易于扩展的内部工具，通过插件化的方式集成了多种实用与娱乐功能。
|
||
|
||
本项目旨在提供一个稳定、高性能且开发体验优秀的机器人平台，服务于我们的社群管理和日常自动化需求。
|
||
|
||
### ✨ 核心特性
|
||
|
||
* **模块化插件架构**：所有功能均以独立插件形式存在于 `plugins/` 目录，易于开发、维护和热重载。
|
||
* **高性能异步核心**：基于 `asyncio` 和 `websockets`，确保在高并发消息下依然响应迅速。
|
||
* **开发者友好**：内置插件热重载，修改代码无需重启；完整的类型提示和清晰的 API 设计，提升开发效率。
|
||
* **集成 Redis 缓存**：自动缓存常用 API 调用（如群信息），减少重复请求，提升响应速度。
|
||
* **内置帮助系统**：通过 `/help` 指令可自动生成并展示所有已加载插件的功能说明。
|
||
|
||
### 🛠️ 技术栈
|
||
|
||
* **核心框架**: Python 3.8+ & NEO Bot Framework
|
||
* **异步库**: `asyncio`
|
||
* **网络通信**: `websockets` (OneBot v11)
|
||
* **缓存**: `Redis`
|
||
* **日志**: `Loguru`
|
||
* **文件监控**: `watchdog` (用于热重载)
|
||
|
||
---
|
||
* **模块化插件架构**：所有功能均以独立插件形式存在于 `plugins/` 目录，易于开发、维护和热重载。
|
||
* **高性能异步核心**：基于 `asyncio` 和 `websockets`，确保在高并发消息下依然响应迅速。
|
||
* **开发者友好**：内置插件热重载，修改代码无需重启；完整的类型提示和清晰的 API 设计，提升开发效率。
|
||
* **集成 Redis 缓存**：自动缓存常用 API 调用（如群信息），减少重复请求，提升响应速度。
|
||
* **内置帮助系统**：通过 `/help` 指令可自动生成并展示所有已加载插件的功能说明。
|
||
|
||
### 🛠️ 技术栈
|
||
|
||
* **核心框架**: Python 3.8+ & NEO Bot Framework
|
||
* **异步库**: `asyncio`
|
||
* **网络通信**: `websockets` (OneBot v11)
|
||
* **缓存**: `Redis`
|
||
* **日志**: `Loguru`
|
||
* **文件监控**: `watchdog` (用于热重载)
|
||
|
||
---
|
||
|
||
## 📂 项目结构
|
||
|
||
```
|
||
.
|
||
├── plugins/ # 插件目录，所有机器人的功能模块都在这里
|
||
│ ├── admin.py
|
||
│ ├── bili_parser.py
|
||
│ ├── code_py.py
|
||
│ ├── echo.py
|
||
│ ├── forward_test.py
|
||
│ ├── jrcd.py
|
||
│ └── thpic.py
|
||
├── core/ # NEO 框架核心代码，通常无需修改
|
||
│ ├── api/
|
||
│ ├── data/ # 数据存储目录 (管理员列表, 权限配置)
|
||
│ │ ├── admin.json
|
||
│ │ └── permissions.json
|
||
│ ├── bot.py
|
||
│ ├── ...
|
||
│ └── ws.py
|
||
├── html/ # 静态网页文件
|
||
├── plugins/ # 插件目录，所有机器人的功能模块都在这里
|
||
│ ├── admin.py
|
||
│ ├── bili_parser.py
|
||
│ ├── code_py.py
|
||
│ ├── echo.py
|
||
│ ├── forward_test.py
|
||
│ ├── jrcd.py
|
||
│ └── thpic.py
|
||
├── core/ # NEO 框架核心代码，通常无需修改
|
||
│ ├── api/
|
||
│ ├── bot.py
|
||
│ ├── ...
|
||
│ └── ws.py
|
||
├── data/ # 数据存储目录 (管理员列表, 权限配置)
|
||
│ ├── admin.json
|
||
│ └── permissions.json
|
||
├── html/ # 静态网页文件
|
||
│ ├── 404.html
|
||
│ └── index.html
|
||
├── models/ # 数据模型 (事件, 消息段等)
|
||
│ ├── ...
|
||
├── models/ # 数据模型 (事件, 消息段等)
|
||
│ ├── ...
|
||
├── .gitignore
|
||
├── config.toml # 主配置文件
|
||
├── main.py # 项目启动入口
|
||
└── requirements.txt # Python 依赖
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 详细开发文档
|
||
|
||
**想要深入了解框架的工作原理或开发更复杂的插件？**
|
||
|
||
👉 **[点击这里，查阅完整的开发文档](./docs/index.md)**
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 环境准备
|
||
|
||
* **Python 3.12 或更高版本**
|
||
* **我觉得**: 在开发和调试阶段使用官方的 **CPython** 解释器，以获得最佳的第三方库兼容性和调试体验。
|
||
* **你也可以觉得**: 在生产环境部署时，可以考虑使用 **PyPy** 以获取潜在的性能提升，但这可能会牺牲一定的兼容性。
|
||
* Redis 服务
|
||
* 一个正在运行的 OneBot v11 实现端 (推荐 **NapCatQQ**)
|
||
* **Python 3.12 或更高版本**
|
||
* **我觉得**: 在开发和调试阶段使用官方的 **CPython** 解释器，以获得最佳的第三方库兼容性和调试体验。
|
||
* **你也可以觉得**: 在生产环境部署时，可以考虑使用 **PyPy** 以获取潜在的性能提升，但这可能会牺牲一定的兼容性。
|
||
* Redis 服务
|
||
* 一个正在运行的 OneBot v11 实现端 (推荐 **NapCatQQ**)
|
||
|
||
### 2. 安装依赖
|
||
|
||
克隆本项目后，在项目根目录执行：
|
||
克隆本项目后，在项目根目录执行：
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 配置
|
||
|
||
**[内部开发]**
|
||
|
||
为了方便内部开发和调试，项目中的 `config.toml` 文件已预先配置为连接到官方的 DEV 调试服务器。
|
||
|
||
**因此，在拉取仓库后，您通常无需对 `config.toml` 文件进行任何修改即可直接运行。**
|
||
|
||
如果您需要连接到本地或其他特定环境，可以参考以下配置结构进行修改。配置示例：
|
||
### 3. 配置
|
||
|
||
**[内部开发]**
|
||
|
||
为了方便内部开发和调试，项目中的 `config.toml` 文件已预先配置为连接到官方的 DEV 调试服务器。
|
||
|
||
**因此，在拉取仓库后，您通常无需对 `config.toml` 文件进行任何修改即可直接运行。**
|
||
|
||
如果您需要连接到本地或其他特定环境，可以参考以下配置结构进行修改。配置示例：
|
||
|
||
```toml
|
||
# config.toml
|
||
|
||
# config.toml
|
||
|
||
[napcat_ws]
|
||
# OneBot 实现端的 WebSocket 地址
|
||
uri = "ws://127.0.0.1:3001"
|
||
# Access Token (如果有)
|
||
token = ""
|
||
# 断线重连间隔（秒）
|
||
reconnect_interval = 5
|
||
# OneBot 实现端的 WebSocket 地址
|
||
uri = "ws://127.0.0.1:3001"
|
||
# Access Token (如果有)
|
||
token = ""
|
||
# 断线重连间隔（秒）
|
||
reconnect_interval = 5
|
||
|
||
[bot]
|
||
# 机器人指令的起始符号，可配置多个
|
||
command_prefixes = ["/", "!", "！"]
|
||
|
||
[redis]
|
||
# Redis 连接信息
|
||
host = "127.0.0.1"
|
||
port = 6379
|
||
db = 0
|
||
password = ""
|
||
# 机器人指令的起始符号，可配置多个
|
||
command_prefixes = ["/", "!", "！"]
|
||
|
||
[redis]
|
||
# Redis 连接信息
|
||
host = "127.0.0.1"
|
||
port = 6379
|
||
db = 0
|
||
password = ""
|
||
```
|
||
|
||
### 4. 运行
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
机器人启动后，将自动连接到 OneBot 实现端。控制台会输出加载的插件列表和连接状态。
|
||
|
||
---
|
||
|
||
## 🛠️ 插件开发指南
|
||
|
||
Calglau BOT 的所有功能都通过插件实现。开发新功能非常简单，并且得益于热重载，你无需在开发过程中频繁重启机器人。
|
||
|
||
### 🔥 热重载工作流
|
||
|
||
1. 保持 `python main.py` 进程运行。
|
||
2. 在 `plugins/` 目录下创建或修改任意 `.py` 文件。
|
||
3. **保存文件**。
|
||
4. 观察控制台输出 `[HotReload] 插件重载完成` 的提示。你的新代码已即时生效。
|
||
机器人启动后，将自动连接到 OneBot 实现端。控制台会输出加载的插件列表和连接状态。
|
||
|
||
---
|
||
|
||
## 🛠️ 插件开发指南
|
||
|
||
Calglau BOT 的所有功能都通过插件实现。开发新功能非常简单，并且得益于热重载，你无需在开发过程中频繁重启机器人。
|
||
|
||
### 🔥 热重载工作流
|
||
|
||
1. 保持 `python main.py` 进程运行。
|
||
2. 在 `plugins/` 目录下创建或修改任意 `.py` 文件。
|
||
3. **保存文件**。
|
||
4. 观察控制台输出 `[HotReload] 插件重载完成` 的提示。你的新代码已即时生效。
|
||
|
||
### 创建一个新插件
|
||
|
||
1. 在 `plugins/` 目录下新建一个 Python 文件，例如 `weather.py`。
|
||
2. 在该文件中编写你的逻辑。
|
||
|
||
#### 1. 定义插件元数据 (`__plugin_meta__`)
|
||
|
||
为了让 `/help` 指令能自动发现你的插件，请在文件顶部定义 `__plugin_meta__` 字典：
|
||
### 创建一个新插件
|
||
|
||
1. 在 `plugins/` 目录下新建一个 Python 文件，例如 `weather.py`。
|
||
2. 在该文件中编写你的逻辑。
|
||
|
||
#### 1. 定义插件元数据 (`__plugin_meta__`)
|
||
|
||
为了让 `/help` 指令能自动发现你的插件，请在文件顶部定义 `__plugin_meta__` 字典：
|
||
|
||
```python
|
||
# plugins/weather.py
|
||
# plugins/weather.py
|
||
|
||
__plugin_meta__ = {
|
||
"name": "天气查询",
|
||
"description": "提供城市天气查询功能。",
|
||
"usage": "/weather [城市名] - 查询指定城市的实时天气。",
|
||
}
|
||
```
|
||
|
||
#### 2. 编写指令处理器
|
||
|
||
使用 `@matcher.command()` 装饰器来注册一个聊天指令。
|
||
"name": "天气查询",
|
||
"description": "提供城市天气查询功能。",
|
||
"usage": "/weather [城市名] - 查询指定城市的实时天气。",
|
||
}
|
||
```
|
||
|
||
#### 2. 编写指令处理器
|
||
|
||
使用 `@matcher.command()` 装饰器来注册一个聊天指令。
|
||
|
||
```python
|
||
# plugins/weather.py
|
||
# plugins/weather.py
|
||
from core.command_manager import matcher
|
||
from models import MessageEvent
|
||
|
||
# ... (元数据定义) ...
|
||
# ... (元数据定义) ...
|
||
|
||
@matcher.command("weather")
|
||
async def handle_weather_command(event: MessageEvent, args: list[str]):
|
||
async def handle_weather_command(event: MessageEvent, args: list[str]):
|
||
"""
|
||
处理 /weather 指令
|
||
:param event: 消息事件对象，用于回复等操作
|
||
:param args: 用户发送的参数列表 (已按空格分割)
|
||
处理 /weather 指令
|
||
:param event: 消息事件对象，用于回复等操作
|
||
:param args: 用户发送的参数列表 (已按空格分割)
|
||
"""
|
||
if not args:
|
||
await event.reply("请输入要查询的城市名，例如：/weather 北京")
|
||
await event.reply("请输入要查询的城市名，例如：/weather 北京")
|
||
return
|
||
|
||
city = args[0]
|
||
|
||
# 此处应调用天气 API 获取数据
|
||
# (示例代码，省略了真实 API 调用)
|
||
weather_data = f"{city}的天气是：晴，25°C。"
|
||
|
||
await event.reply(weather_data)
|
||
city = args[0]
|
||
|
||
# 此处应调用天气 API 获取数据
|
||
# (示例代码，省略了真实 API 调用)
|
||
weather_data = f"{city}的天气是：晴，25°C。"
|
||
|
||
await event.reply(weather_data)
|
||
```
|
||
|
||
#### 3. 监听事件
|
||
|
||
除了指令，你还可以监听各种事件，例如新成员入群。
|
||
#### 3. 监听事件
|
||
|
||
除了指令，你还可以监听各种事件，例如新成员入群。
|
||
|
||
```python
|
||
from core.command_manager import matcher
|
||
from models import GroupIncreaseNoticeEvent
|
||
from models import GroupIncreaseNoticeEvent
|
||
from core.bot import Bot
|
||
|
||
|
||
@matcher.on_notice("group_increase")
|
||
async def welcome_new_member(bot: Bot, event: GroupIncreaseNoticeEvent):
|
||
"""当有新成员加入群聊时触发"""
|
||
welcome_message = f"欢迎新成员 @{event.user_id} 加入本群！"
|
||
await bot.send_group_msg(event.group_id, welcome_message)
|
||
async def welcome_new_member(bot: Bot, event: GroupIncreaseNoticeEvent):
|
||
"""当有新成员加入群聊时触发"""
|
||
welcome_message = f"欢迎新成员 @{event.user_id} 加入本群！"
|
||
await bot.send_group_msg(event.group_id, welcome_message)
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 当前功能插件
|
||
|
||
| 插件文件 (`plugins/`) | 功能描述 |
|
||
|-----------------------|----------|
|
||
| `admin.py` | 机器人管理员权限管理 |
|
||
| `bili_parser.py` | 自动解析 Bilibili 视频链接分享卡片 |
|
||
| `code_py.py` | 执行 Python 代码片段 (高危，仅限管理员) |
|
||
| `echo.py` | 提供 `/echo` 复读和 `/赞我` 功能 |
|
||
| `forward_test.py` | 演示如何发送合并转发消息 |
|
||
| `jrcd.py` | 娱乐功能：今日人品、牛牛词典 |
|
||
| `thpic.py` | 发送一张随机的东方 Project 图片 |
|
||
|
||
---
|
||
|
||
## 🗺️ 路线图 (Roadmap)
|
||
|
||
- [ ] **Web 仪表盘**: 开发一个简单的 Web 页面，用于查看机器人状态和插件列表。
|
||
- [ ] **权限系统重构**: 引入更精细化的权限节点，允许按插件或指令控制用户权限。
|
||
- [ ] **数据库集成**: 引入 `SQLite` 或其他数据库，用于需要持久化存储数据的功能。
|
||
- [ ] **新插件开发**:
|
||
- [ ] 天气查询插件
|
||
- [ ] GIL实现
|
||
- [ ] coming soon...
|
||
---
|
||
|
||
## 📦 当前功能插件
|
||
|
||
| 插件文件 (`plugins/`) | 功能描述 |
|
||
|-----------------------|----------|
|
||
| `admin.py` | 机器人管理员权限管理 |
|
||
| `bili_parser.py` | 自动解析 Bilibili 视频链接分享卡片 |
|
||
| `code_py.py` | 执行 Python 代码片段 (高危，仅限管理员) |
|
||
| `echo.py` | 提供 `/echo` 复读和 `/赞我` 功能 |
|
||
| `forward_test.py` | 演示如何发送合并转发消息 |
|
||
| `jrcd.py` | 娱乐功能：今日人品、牛牛词典 |
|
||
| `thpic.py` | 发送一张随机的东方 Project 图片 |
|
||
|
||
---
|
||
|
||
## 🗺️ 路线图 (Roadmap)
|
||
|
||
- [ ] **Web 仪表盘**: 开发一个简单的 Web 页面，用于查看机器人状态和插件列表。
|
||
- [ ] **权限系统重构**: 引入更精细化的权限节点，允许按插件或指令控制用户权限。
|
||
- [ ] **数据库集成**: 引入 `SQLite` 或其他数据库，用于需要持久化存储数据的功能。
|
||
- [ ] **新插件开发**:
|
||
- [ ] 天气查询插件
|
||
- [ ] GIL实现
|
||
- [ ] coming soon...
|