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 (用于热重载)

---

📂 项目结构

.
├── 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/                 # 数据模型 (事件, 消息段等)
│   ├── ...
├── .gitignore
├── config.toml             # 主配置文件
├── main.py                 # 项目启动入口
└── requirements.txt        # Python 依赖

---

🚀 快速开始

1. 环境准备

• Python 3.12 或更高版本
  • 我觉得: 在开发和调试阶段使用官方的 CPython 解释器，以获得最佳的第三方库兼容性和调试体验。
  • 你也可以觉得: 在生产环境部署时，可以考虑使用 PyPy 以获取潜在的性能提升，但这可能会牺牲一定的兼容性。
• Redis 服务
• 一个正在运行的 OneBot v11 实现端 (推荐 NapCatQQ)

2. 安装依赖

克隆本项目后，在项目根目录执行：

pip install -r requirements.txt

3. 配置

[内部开发]

为了方便内部开发和调试，项目中的 config.toml 文件已预先配置为连接到官方的 DEV 调试服务器。

因此，在拉取仓库后，您通常无需对 config.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. 运行

python main.py

机器人启动后，将自动连接到 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__ 字典：

# plugins/weather.py

__plugin_meta__ = {
    "name": "天气查询",
    "description": "提供城市天气查询功能。",
    "usage": "/weather [城市名] - 查询指定城市的实时天气。",
}

2. 编写指令处理器

使用 @matcher.command() 装饰器来注册一个聊天指令。

# 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 获取数据
    # (示例代码，省略了真实 API 调用)
    weather_data = f"{city}的天气是：晴，25°C。"
    
    await event.reply(weather_data)

3. 监听事件

除了指令，你还可以监听各种事件，例如新成员入群。

from core.command_manager import matcher
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)

---

📦 当前功能插件

插件文件 (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...