Calglau BOT by NEO Bot Framework
[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 (插件热重载依赖)
项目结构
plaintext
. ├── plugins/ # 功能插件目录 │ ├── admin.py # 管理员权限管理插件 │ ├── bili_parser.py # B站链接解析插件 │ ├── code_py.py # Python代码执行插件 │ ├── echo.py # 复读与互动插件 │ ├── forward_test.py # 合并转发消息演示插件 │ ├── jrcd.py # 今日人品等娱乐功能插件 │ └── thpic.py # 东方Project图片发送插件 ├── core/ # NEO框架核心代码（无需修改） │ ├── api/ # 框架API模块 │ ├── bot.py # 机器人核心逻辑 │ └── ws.py # WebSocket通信模块 ├── data/ # 数据存储目录 │ ├── admin.json # 管理员列表配置 │ └── permissions.json # 权限配置文件 ├── html/ # 静态网页文件目录 │ ├── 404.html # 404页面 │ └── index.html # 主页 ├── models/ # 数据模型目录（事件、消息段等） ├── .gitignore # Git忽略文件配置 ├── config.toml # 机器人主配置文件 ├── main.py # 项目启动入口 └── requirements.txt # Python依赖清单
详细开发文档
想要深入了解框架的工作原理或开发更复杂的插件？ 👉 点击这里，查阅完整的开发文档
快速开始
- 环境准备
- Python 3.12 或更高版本
- 开发调试阶段推荐使用 CPython 解释器，保障第三方库兼容性与调试体验。
- 生产环境部署可考虑 PyPy 解释器，获取潜在性能提升（需注意部分库兼容性）。
- 部署并运行 Redis 服务
- 准备 OneBot v11 协议实现端（推荐 NapCatQQ）
- 安装依赖
克隆本项目后，在项目根目录执行以下命令安装依赖：
bash
pip install -r requirements.txt
- 配置说明
[内部开发] 项目内置的 config.toml 已预先配置为连接官方 DEV 调试服务器，拉取仓库后通常无需修改即可直接运行。
若需连接本地或其他环境，可参考以下配置模板调整：
toml
config.toml
[napcat_ws]
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 = ""
- 启动运行
在项目根目录执行以下命令启动机器人：
bash
python main.py
启动成功后，控制台将输出已加载插件列表与 WebSocket 连接状态，机器人将自动接入 OneBot 实现端。
插件开发指南
Calglau BOT 的全部功能均通过插件实现，结合热重载机制，开发过程无需频繁重启机器人，极大提升开发效率。
热重载工作流
1. 保持 python main.py 进程持续运行 2. 在 plugins/ 目录下创建或修改 .py 插件文件 3. 保存修改后的文件 4. 观察控制台输出 [HotReload] 插件重载完成 提示，修改内容即刻生效
创建新插件
1. 在 plugins/ 目录下新建 Python 文件，例如 weather.py 2. 按照以下步骤编写插件逻辑
- 定义插件元数据
通过 plugin_meta 字典定义插件信息，确保 /help 指令能自动识别并展示插件功能：
python
plugins/weather.py
plugin_meta = { "name": "天气查询", "description": "提供城市天气查询功能", "usage": "/weather [城市名] - 查询指定城市的实时天气", }
- 编写指令处理器
使用 @matcher.command() 装饰器注册聊天指令，实现指令响应逻辑：
python
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]): """ 处理 /weather 指令 :param event: 消息事件对象，用于回复消息 :param args: 用户输入的指令参数列表（按空格分割） """ if not args: await event.reply("请输入要查询的城市名，例如：/weather 北京") return
city = args[0]
# 此处可接入天气API获取真实数据，以下为示例
weather_data = f"{city}的天气是：晴，25°C"
await event.reply(weather_data)
- 监听系统事件
使用 @matcher.on_notice() 装饰器监听机器人事件（如新成员入群），实现事件响应逻辑：
python
plugins/weather.py
from core.command_manager import matcher from core.bot import Bot from models import GroupIncreaseNoticeEvent
@matcher.on_notice("group_increase") async def welcome_new_member(bot: Bot, event: GroupIncreaseNoticeEvent): """监听群成员增加事件，发送欢迎消息""" welcome_msg = f"欢迎新成员 @{event.user_id} 加入本群！" await bot.send_group_msg(event.group_id, welcome_msg)
当前功能插件
插件文件 ( plugins/ ) 功能描述 admin.py 机器人管理员权限管理（添加/移除管理员、权限验证） bili_parser.py 自动解析 Bilibili 视频链接，生成精美分享卡片 code_py.py 执行 Python 代码片段（高危功能，仅限管理员使用） echo.py 提供 /echo 复读指令与 /赞我 互动指令 forward_test.py 演示合并转发消息的发送方法 jrcd.py 提供今日人品测算、牛牛词典查询等娱乐功能 thpic.py 随机发送东方 Project 相关图片
路线图 (Roadmap)
Web 仪表盘：开发可视化管理页面，支持查看机器人状态、插件列表与运行日志 权限系统重构：引入精细化权限节点，支持按插件/指令维度配置用户权限 数据库集成：接入 SQLite 数据库，支持需要持久化存储的插件功能开发 新插件开发 天气查询插件 GIL 相关功能插件 更多功能持续更新中
需要我帮你写一个天气查询插件的完整可运行代码，包含真实的天气 API 调用逻辑吗？