K2CrO4/NeoBot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
镀铬酸钾
2026-01-12 02:20:53 +08:00
committed by GitHub
parent acd49a3bf4
commit a6464c36b1
1 changed files with 176 additions and 357 deletions
Download Patch File Download Diff File Expand all files Collapse all files

429
README.md
View File

@@ -1,395 +1,214 @@
# Calglau BOT by NEO Bot Framework
Calglau BOT by NEO Bot Framework
> **[INTERNAL USE ONLY]**
>
> 本仓库为 Calglau BOT 的内部开发版本，请遵守相关保密协议。
[INTERNAL USE ONLY]
**Powered by NEO Bot Framework**
本仓库为 Calglau BOT 的内部开发版本，请遵守相关保密协议。
## 📖 项目概述
Powered by NEO Bot Framework
**Calglau BOT** 是一个基于 NEO Bot Framework 构建的、功能丰富的 QQ 机器人。它被设计为一个模块化、易于扩展的内部工具，通过插件化的方式集成了多种实用与娱乐功能。
项目概述
本项目旨在提供一个稳定、高性能且开发体验优秀的机器人平台，服务于我们的社群管理和日常自动化需求。
Calglau BOT 是一款基于 NEO Bot Framework 构建的功能丰富的 QQ 机器人，采用模块化插件架构设计，支持功能的灵活扩展与独立维护，旨在为社群管理和日常自动化需求提供稳定、高性能且开发体验友好的机器人平台。
### ✨ 核心特性
> **[INTERNAL USE ONLY]**
>
> 本仓库为 Calglau BOT 的内部开发版本，请遵守相关保密协议。
核心特性
**Powered by NEO Bot Framework**
- 模块化插件架构：所有功能均以独立插件形式存放于  plugins/  目录，支持开发、维护与热重载，降低功能迭代成本。
- 高性能异步核心：基于  asyncio  与  websockets  构建，可高效处理高并发消息，保障机器人在高负载场景下的响应速度。
- 开发者友好设计：内置插件热重载机制，修改代码无需重启机器人；配套完整类型提示与清晰 API 设计，提升开发效率。
- Redis 缓存集成：自动缓存群信息等高频 API 调用结果，减少重复请求，进一步优化响应性能。
- 内置帮助系统：通过  /help  指令可自动生成并展示所有已加载插件的功能说明，降低用户使用门槛。
## 📖 项目概述
技术栈
**Calglau BOT** 是一个基于 NEO Bot Framework 构建的、功能丰富的 QQ 机器人。它被设计为一个模块化、易于扩展的内部工具，通过插件化的方式集成了多种实用与娱乐功能。
- 核心框架: 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/` 目录，易于开发、维护和热重载。
* **高性能异步核心**：基于 `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 # 机器人主配置文件
└── requirements.txt # Python 依赖
```
├── main.py # 项目启动入口
└── requirements.txt # Python依赖清单
 
---
详细开发文档
## 📚 详细开发文档
想要深入了解框架的工作原理或开发更复杂的插件？
👉 点击这里，查阅完整的开发文档
**想要深入了解框架的工作原理或开发更复杂的插件？**
快速开始
👉 **[点击这里，查阅完整的开发文档](./docs/index.md)**
1. 环境准备
---
- Python 3.12 或更高版本
- 开发调试阶段推荐使用 CPython 解释器，保障第三方库兼容性与调试体验。
- 生产环境部署可考虑 PyPy 解释器，获取潜在性能提升（需注意部分库兼容性）。
- 部署并运行 Redis 服务
- 准备 OneBot v11 协议实现端（推荐 NapCatQQ）
## 🚀 快速开始
2. 安装依赖
### 1. 环境准备
克隆本项目后，在项目根目录执行以下命令安装依赖：
* **Python 3.12 或更高版本**
* **我觉得**: 在开发和调试阶段使用官方的 **CPython** 解释器，以获得最佳的第三方库兼容性和调试体验。
* **你也可以觉得**: 在生产环境部署时，可以考虑使用 **PyPy** 以获取潜在的性能提升，但这可能会牺牲一定的兼容性。
* Redis 服务
* 一个正在运行的 OneBot v11 实现端 (推荐 **NapCatQQ**)
* **Python 3.12 或更高版本**
* **我觉得**: 在开发和调试阶段使用官方的 **CPython** 解释器，以获得最佳的第三方库兼容性和调试体验。
* **你也可以觉得**: 在生产环境部署时，可以考虑使用 **PyPy** 以获取潜在的性能提升，但这可能会牺牲一定的兼容性。
* Redis 服务
* 一个正在运行的 OneBot v11 实现端 (推荐 **NapCatQQ**)
### 2. 安装依赖
克隆本项目后，在项目根目录执行：
克隆本项目后，在项目根目录执行：
```bash
bash
```
pip install -r requirements.txt
### 3. 配置
 
**[内部开发]**
3. 配置说明
[内部开发]
为了方便内部开发和调试，项目中的 `config.toml` 文件已预先配置为连接到官方的 DEV 调试服务器。
项目内置的  config.toml  已预先配置为连接官方 DEV 调试服务器，拉取仓库后通常无需修改即可直接运行。
**因此，在拉取仓库后，您通常无需对 `config.toml` 文件进行任何修改即可直接运行。**
如果您需要连接到本地或其他特定环境，可以参考以下配置结构进行修改。配置示例：
### 3. 配置
**[内部开发]**
为了方便内部开发和调试，项目中的 `config.toml` 文件已预先配置为连接到官方的 DEV 调试服务器。
**因此，在拉取仓库后，您通常无需对 `config.toml` 文件进行任何修改即可直接运行。**
如果您需要连接到本地或其他特定环境，可以参考以下配置结构进行修改。配置示例：
```toml
若需连接本地或其他环境，可参考以下配置模板调整：
# config.toml
toml
# config.toml
# Access Token (如果有)
[napcat_ws]
# OneBot 实现端的 WebSocket 地址
# 断线重连间隔（秒）
reconnect_interval = 5
# OneBot 实现端的 WebSocket 地址
uri = "ws://127.0.0.1:3001"
# Access Token (如果有)
token = ""
# 断线重连间隔（秒）
uri = "ws://127.0.0.1:3001"
# Access Token 鉴权（无则留空）
token = ""
# 断线重连间隔（单位：秒）
# 机器人指令的起始符号，可配置多个
reconnect_interval = 5
[bot]
# 机器人指令前缀（支持配置多个）
# Redis 连接信息
command_prefixes = ["/", "!", "！"]
[redis]
# Redis 服务连接信息
host = "127.0.0.1"
# 机器人指令的起始符号，可配置多个
command_prefixes = ["/", "!", "！"]
port = 6379
db = 0
[redis]
# Redis 连接信息
host = "127.0.0.1"
port = 6379
db = 0
password = ""
```
password = ""
 
### 4. 运行
4. 启动运行
```bash
在项目根目录执行以下命令启动机器人：
```
机器人启动后，将自动连接到 OneBot 实现端。控制台会输出加载的插件列表和连接状态。
bash
---
python main.py
## 🛠️ 插件开发指南
 
Calglau BOT 的所有功能都通过插件实现。开发新功能非常简单，并且得益于热重载，你无需在开发过程中频繁重启机器人。
启动成功后，控制台将输出已加载插件列表与 WebSocket 连接状态，机器人将自动接入 OneBot 实现端。
### 🔥 热重载工作流
插件开发指南
1. 保持 `python main.py` 进程运行。
2. 在 `plugins/` 目录下创建或修改任意 `.py` 文件。
3. **保存文件**。
4. 观察控制台输出 `[HotReload] 插件重载完成` 的提示。你的新代码已即时生效。
机器人启动后，将自动连接到 OneBot 实现端。控制台会输出加载的插件列表和连接状态。
Calglau BOT 的全部功能均通过插件实现，结合热重载机制，开发过程无需频繁重启机器人，极大提升开发效率。
热重载工作流
1. 保持  python main.py  进程持续运行
---
2. 在  plugins/  目录下创建或修改  .py  插件文件
3. 保存修改后的文件
## 🛠️ 插件开发指南
4. 观察控制台输出  [HotReload] 插件重载完成  提示，修改内容即刻生效
创建新插件
Calglau BOT 的所有功能都通过插件实现。开发新功能非常简单，并且得益于热重载，你无需在开发过程中频繁重启机器人。
1. 在  plugins/  目录下新建 Python 文件，例如  weather.py 
### 🔥 热重载工作流
2. 按照以下步骤编写插件逻辑
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
1. 定义插件元数据
# plugins/weather.py
通过  __plugin_meta__  字典定义插件信息，确保  /help  指令能自动识别并展示插件功能：
"description": "提供城市天气查询功能。",
"usage": "/weather [城市名] - 查询指定城市的实时天气。",
python
# plugins/weather.py
```
__plugin_meta__ = {
"name": "天气查询",
#### 2. 编写指令处理器
"description": "提供城市天气查询功能",
"usage": "/weather [城市名] - 查询指定城市的实时天气",
使用 `@matcher.command()` 装饰器来注册一个聊天指令。
"name": "天气查询",
"description": "提供城市天气查询功能。",
"usage": "/weather [城市名] - 查询指定城市的实时天气。",
}
```
}
 
#### 2. 编写指令处理器
使用 `@matcher.command()` 装饰器来注册一个聊天指令。
```python
# plugins/weather.py
2. 编写指令处理器
使用  @matcher.command()  装饰器注册聊天指令，实现指令响应逻辑：
# ... (元数据定义) ...
# ... (元数据定义) ...
python
async def handle_weather_command(event: MessageEvent, args: list[str]):
# plugins/weather.py
from core.command_manager import matcher
:param event: 消息事件对象，用于回复等操作
:param args: 用户发送的参数列表 (已按空格分割)
处理 /weather 指令
:param event: 消息事件对象，用于回复等操作
:param args: 用户发送的参数列表 (已按空格分割)
from models import MessageEvent
@matcher.command("weather")
async def handle_weather_command(event: MessageEvent, args: list[str]):
await event.reply("请输入要查询的城市名，例如：/weather 北京")
"""
处理 /weather 指令
:param event: 消息事件对象，用于回复消息
:param args: 用户输入的指令参数列表（按空格分割）
# 此处应调用天气 API 获取数据
# (示例代码，省略了真实 API 调用)
weather_data = f"{city}的天气是：晴，25°C。"
"""
if not args:
await event.reply("请输入要查询的城市名，例如：/weather 北京")
city = args[0]
return
# 此处应调用天气 API 获取数据
# (示例代码，省略了真实 API 调用)
weather_data = f"{city}的天气是：晴，25°C。"
city = args[0]
# 此处可接入天气API获取真实数据，以下为示例
await event.reply(weather_data)
```
weather_data = f"{city}的天气是：晴，25°C"
await event.reply(weather_data)
#### 3. 监听事件
除了指令，你还可以监听各种事件，例如新成员入群。
#### 3. 监听事件
除了指令，你还可以监听各种事件，例如新成员入群。
```python
 
3. 监听系统事件
from models import GroupIncreaseNoticeEvent
from models import GroupIncreaseNoticeEvent
使用  @matcher.on_notice()  装饰器监听机器人事件（如新成员入群），实现事件响应逻辑：
python
"""当有新成员加入群聊时触发"""
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/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  机器人管理员权限管理（添加/移除管理员、权限验证）
| 插件文件 (`plugins/`) | 功能描述 |
|-----------------------|----------|
| `admin.py` | 机器人管理员权限管理 |
| `bili_parser.py` | 自动解析 Bilibili 视频链接分享卡片 |
| `code_py.py` | 执行 Python 代码片段 (高危，仅限管理员) |
| `echo.py` | 提供 `/echo` 复读和 `/赞我` 功能 |
| `forward_test.py` | 演示如何发送合并转发消息 |
| `jrcd.py` | 娱乐功能：今日人品、牛牛词典 |
| `thpic.py` | 发送一张随机的东方 Project 图片 |
 bili_parser.py  自动解析 Bilibili 视频链接，生成精美分享卡片
 code_py.py  执行 Python 代码片段（高危功能，仅限管理员使用）
---
 echo.py  提供  /echo  复读指令与  /赞我  互动指令
 forward_test.py  演示合并转发消息的发送方法
 jrcd.py  提供今日人品测算、牛牛词典查询等娱乐功能
 thpic.py  随机发送东方 Project 相关图片
路线图 (Roadmap)
Web 仪表盘：开发可视化管理页面，支持查看机器人状态、插件列表与运行日志
## 🗺️ 路线图 (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...
权限系统重构：引入精细化权限节点，支持按插件/指令维度配置用户权限