From a6464c36b1087522f32e47844193d2adfcb7d9ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=95=80=E9=93=AC=E9=85=B8=E9=92=BE?= <148796996+K2cr2O1@users.noreply.github.com> Date: Mon, 12 Jan 2026 02:20:53 +0800 Subject: [PATCH] Update README.md --- README.md | 533 ++++++++++++++++++------------------------------------ 1 file changed, 176 insertions(+), 357 deletions(-) diff --git a/README.md b/README.md index 5e14e47..62bf06d 100644 --- a/README.md +++ b/README.md @@ -1,395 +1,214 @@ -# 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` (用于热重载) - ---- - -## 📂 项目结构 - -``` +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 -│ ├── 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 # 主配置文件 +├── 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 依赖 -``` - ---- - -## 📚 详细开发文档 - -**想要深入了解框架的工作原理或开发更复杂的插件？** - -👉 **[点击这里，查阅完整的开发文档](./docs/index.md)** - ---- - -## 🚀 快速开始 - -### 1. 环境准备 - -* **Python 3.12 或更高版本** - * **我觉得**: 在开发和调试阶段使用官方的 **CPython** 解释器，以获得最佳的第三方库兼容性和调试体验。 - * **你也可以觉得**: 在生产环境部署时，可以考虑使用 **PyPy** 以获取潜在的性能提升，但这可能会牺牲一定的兼容性。 -* Redis 服务 -* 一个正在运行的 OneBot v11 实现端 (推荐 **NapCatQQ**) -* **Python 3.12 或更高版本** - * **我觉得**: 在开发和调试阶段使用官方的 **CPython** 解释器，以获得最佳的第三方库兼容性和调试体验。 - * **你也可以觉得**: 在生产环境部署时，可以考虑使用 **PyPy** 以获取潜在的性能提升，但这可能会牺牲一定的兼容性。 -* Redis 服务 -* 一个正在运行的 OneBot v11 实现端 (推荐 **NapCatQQ**) - -### 2. 安装依赖 - -克隆本项目后，在项目根目录执行： -克隆本项目后，在项目根目录执行： -```bash +└── requirements.txt # Python依赖清单 +  + +详细开发文档 + +想要深入了解框架的工作原理或开发更复杂的插件？ +👉 点击这里，查阅完整的开发文档 + +快速开始 + +1. 环境准备 + +- 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 +  + +3. 配置说明 + +[内部开发] +项目内置的  config.toml  已预先配置为连接官方 DEV 调试服务器，拉取仓库后通常无需修改即可直接运行。 + +若需连接本地或其他环境，可参考以下配置模板调整： + +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 +uri = "ws://127.0.0.1:3001" +# Access Token 鉴权（无则留空） +token = "" +# 断线重连间隔（单位：秒） +reconnect_interval = 5 [bot] -# 机器人指令的起始符号，可配置多个 -command_prefixes = ["/", "!", "！"] +# 机器人指令前缀（支持配置多个） +command_prefixes = ["/", "!", "！"] [redis] -# 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 +  + +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 +  + +启动成功后，控制台将输出已加载插件列表与 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 -# plugins/weather.py - __plugin_meta__ = { "name": "天气查询", - "description": "提供城市天气查询功能。", - "usage": "/weather [城市名] - 查询指定城市的实时天气。", + "description": "提供城市天气查询功能", + "usage": "/weather [城市名] - 查询指定城市的实时天气", } -``` - -#### 2. 编写指令处理器 - -使用 `@matcher.command()` 装饰器来注册一个聊天指令。 - "name": "天气查询", - "description": "提供城市天气查询功能。", - "usage": "/weather [城市名] - 查询指定城市的实时天气。", -} -``` - -#### 2. 编写指令处理器 - -使用 `@matcher.command()` 装饰器来注册一个聊天指令。 - -```python -# plugins/weather.py +  + +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]): async def handle_weather_command(event: MessageEvent, args: list[str]): """ 处理 /weather 指令 - :param event: 消息事件对象，用于回复等操作 - :param args: 用户发送的参数列表 (已按空格分割) - 处理 /weather 指令 - :param event: 消息事件对象，用于回复等操作 - :param args: 用户发送的参数列表 (已按空格分割) + :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。" - + # 此处可接入天气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 +  + +3. 监听系统事件 + +使用  @matcher.on_notice()  装饰器监听机器人事件（如新成员入群），实现事件响应逻辑： + +python +# plugins/weather.py from core.command_manager import matcher -from models import GroupIncreaseNoticeEvent -from models import GroupIncreaseNoticeEvent from core.bot import Bot - +from models import GroupIncreaseNoticeEvent @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... + """监听群成员增加事件，发送欢迎消息""" + 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 调用逻辑吗？ \ No newline at end of file