214 lines
7.7 KiB
Markdown
214 lines
7.7 KiB
Markdown
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依赖清单
|
||
|
||
|
||
详细开发文档
|
||
|
||
想要深入了解框架的工作原理或开发更复杂的插件？
|
||
👉 点击这里，查阅完整的开发文档
|
||
|
||
快速开始
|
||
|
||
1. 环境准备
|
||
|
||
- Python 3.12 或更高版本
|
||
- 开发调试阶段推荐使用 CPython 解释器，保障第三方库兼容性与调试体验。
|
||
- 生产环境部署可考虑 PyPy 解释器，获取潜在性能提升（需注意部分库兼容性）。
|
||
- 部署并运行 Redis 服务
|
||
- 准备 OneBot v11 协议实现端（推荐 NapCatQQ）
|
||
|
||
2. 安装依赖
|
||
|
||
克隆本项目后，在项目根目录执行以下命令安装依赖：
|
||
|
||
bash
|
||
|
||
pip install -r requirements.txt
|
||
|
||
|
||
3. 配置说明
|
||
|
||
[内部开发]
|
||
项目内置的 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 = ""
|
||
|
||
|
||
4. 启动运行
|
||
|
||
在项目根目录执行以下命令启动机器人：
|
||
|
||
bash
|
||
|
||
python main.py
|
||
|
||
|
||
启动成功后，控制台将输出已加载插件列表与 WebSocket 连接状态，机器人将自动接入 OneBot 实现端。
|
||
|
||
插件开发指南
|
||
|
||
Calglau BOT 的全部功能均通过插件实现，结合热重载机制，开发过程无需频繁重启机器人，极大提升开发效率。
|
||
|
||
热重载工作流
|
||
|
||
1. 保持 python main.py 进程持续运行
|
||
2. 在 plugins/ 目录下创建或修改 .py 插件文件
|
||
3. 保存修改后的文件
|
||
4. 观察控制台输出 [HotReload] 插件重载完成 提示，修改内容即刻生效
|
||
|
||
创建新插件
|
||
|
||
1. 在 plugins/ 目录下新建 Python 文件，例如 weather.py
|
||
2. 按照以下步骤编写插件逻辑
|
||
|
||
1. 定义插件元数据
|
||
|
||
通过 __plugin_meta__ 字典定义插件信息，确保 /help 指令能自动识别并展示插件功能：
|
||
|
||
python
|
||
|
||
# plugins/weather.py
|
||
__plugin_meta__ = {
|
||
"name": "天气查询",
|
||
"description": "提供城市天气查询功能",
|
||
"usage": "/weather [城市名] - 查询指定城市的实时天气",
|
||
}
|
||
|
||
|
||
2. 编写指令处理器
|
||
|
||
使用 @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)
|
||
|
||
|
||
3. 监听系统事件
|
||
|
||
使用 @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 调用逻辑吗？ |