# 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...