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 调用逻辑吗？