feat: 添加状态监控插件和Redis原子操作支持

- 新增 `/status` 指令,展示机器人运行状态和系统指标
- 实现Redis Lua脚本支持原子化计数器操作
- 添加消息收发统计功能
- 完善文档,包括插件开发和性能优化指南
- 重构WebSocket连接池,增加健康检查机制
- 移除旧版编译脚本,优化项目结构
This commit is contained in:
2026-01-23 15:54:45 +08:00
parent 489dd8c77d
commit d458413e4b
28 changed files with 1529 additions and 1177 deletions

View File

@@ -77,6 +77,32 @@ print(f"正常: {status.good}")
- `status`: 状态描述
- `good`: 运行是否正常
### `get_profile_like` - 获取资料点赞信息
```python
async def get_profile_like(self) -> Dict[str, Any]
```
获取个人资料的点赞信息。
**返回值:**
- 包含点赞信息的字典
### `nc_get_user_status` - 获取用户在线状态 (NapCat)
```python
async def nc_get_user_status(self, user_id: int) -> Dict[str, Any]
```
获取指定用户的在线状态NapCatQQ 特有 API
**参数:**
- `user_id`: 目标用户的 QQ 号
**返回值:**
- 包含用户状态信息的字典
## 状态设置
### `set_self_longnick` - 设置个性签名
@@ -381,16 +407,6 @@ async def handle_restore_profile(event: MessageEvent, args: str):
3. **客户端支持**: 不是所有 OneBot 客户端都支持全部 API使用前最好测试一下。
4. **谨慎操作**: `bot_exit` 会让机器人下线,谨慎使用。
## 重复的方法
`AccountAPI` 中还包含了一些与好友、群组相关的方法,这些方法在其他模块中也有定义:
- `get_stranger_info()`: 同 [好友 API](./friend.md#get_stranger_info---获取陌生人信息)
- `get_friend_list()`: 同 [好友 API](./friend.md#get_friend_list---获取好友列表)
- `get_group_list()`: 同 [群组 API](./group.md#get_group_list---获取群列表)
这些方法在 `AccountAPI` 中的实现可能略有不同(比如缓存逻辑),但功能相同。建议使用对应模块中的版本,因为那些是专门为该功能设计的。
## 下一步
- [好友 API](./friend.md): 管理好友相关功能

View File

@@ -81,6 +81,28 @@ async def handle_who(event: MessageEvent, args: str):
- `level`: QQ 等级
- 其他可能的信息字段
### `get_friends_with_category` - 获取分类好友列表
```python
async def get_friends_with_category(self) -> Dict[str, Any]
```
获取带分组信息的好友列表。
**返回值:**
- 包含分组和好友信息的字典
### `get_unidirectional_friend_list` - 获取单向好友列表
```python
async def get_unidirectional_friend_list(self) -> Dict[str, Any]
```
获取单向好友(你加了对方,对方没加你)的列表。
**返回值:**
- 单向好友列表
## 互动功能
### `send_like` - 发送点赞(戳一戳)
@@ -119,6 +141,55 @@ async def handle_like(event: MessageEvent, args: str):
- 有每日次数限制,不要滥用
- 对方可能关闭了"戳一戳"功能,这时会失败
### `friend_poke` - 发送好友戳一戳 (新)
```python
async def friend_poke(self, user_id: int) -> Dict[str, Any]
```
对指定好友发送"戳一戳"(比 `send_like` 更通用的接口)。
**参数:**
- `user_id`: 目标用户的 QQ 号
## 消息历史与状态
### `mark_private_msg_as_read` - 标记私聊已读
```python
async def mark_private_msg_as_read(self, user_id: int, time: int = 0) -> Dict[str, Any]
```
将与指定用户的私聊消息标记为已读。
**参数:**
- `user_id`: 目标用户的 QQ 号
- `time`: 将此时间戳(秒)之前的消息标记为已读,传 `0` 表示全部标记
### `get_friend_msg_history` - 获取私聊历史
```python
async def get_friend_msg_history(self, user_id: int, count: int = 20) -> Dict[str, Any]
```
获取与指定用户的私聊历史记录。
**参数:**
- `user_id`: 目标用户的 QQ 号
- `count`: 要获取的消息数量,默认 20
### `forward_friend_single_msg` - 转发单条消息
```python
async def forward_friend_single_msg(self, user_id: int, message_id: str) -> Dict[str, Any]
```
将一条消息转发给指定好友。
**参数:**
- `user_id`: 接收消息的好友 QQ 号
- `message_id`: 要转发的消息的 ID
## 加好友请求处理
### `set_friend_add_request` - 处理加好友请求

View File

@@ -408,6 +408,181 @@ honor = await bot.get_group_honor_info(123456, "talkative")
print(f"本周龙王: {honor.current_talkative.user_id}")
```
### `get_group_info_ex` - 获取群扩展信息 (NapCat)
```python
async def get_group_info_ex(self, group_id: int) -> Dict[str, Any]
```
获取群的扩展信息NapCatQQ 特有 API
**参数:**
- `group_id`: 群号
**返回值:**
- 包含群扩展信息的字典
## 精华消息
### `delete_essence_msg` - 删除精华消息
```python
async def delete_essence_msg(self, message_id: int) -> Dict[str, Any]
```
删除一条精华消息。
**参数:**
- `message_id`: 目标消息的 ID
## 互动与状态
### `group_poke` - 群内戳一戳
```python
async def group_poke(self, group_id: int, user_id: int) -> Dict[str, Any]
```
在群内对指定成员发送"戳一戳"。
**参数:**
- `group_id`: 群号
- `user_id`: 目标成员的 QQ 号
### `mark_group_msg_as_read` - 标记群消息已读
```python
async def mark_group_msg_as_read(self, group_id: int, time: int = 0) -> Dict[str, Any]
```
将指定群聊的消息标记为已读。
**参数:**
- `group_id`: 群号
- `time`: 将此时间戳(秒)之前的消息标记为已读,传 `0` 表示全部标记
## 消息转发
### `forward_group_single_msg` - 转发单条群消息
```python
async def forward_group_single_msg(self, group_id: int, message_id: str) -> Dict[str, Any]
```
将一条群消息转发到当前群聊。
**参数:**
- `group_id`: 群号
- `message_id`: 要转发的消息的 ID
## 群设置 (高级)
### `set_group_portrait` - 设置群头像
```python
async def set_group_portrait(self, group_id: int, file: str, cache: int = 1) -> Dict[str, Any]
```
设置群头像。
**参数:**
- `group_id`: 群号
- `file`: 图片文件的路径、URL 或 Base64 字符串
- `cache`: 是否使用缓存(`1` 是,`0` 否)
### `set_group_remark` - 设置群备注
```python
async def set_group_remark(self, group_id: int, remark: str) -> Dict[str, Any]
```
设置群备注NapCatQQ 特有 API
**参数:**
- `group_id`: 群号
- `remark`: 要设置的备注
### `set_group_sign` - 群签到
```python
async def set_group_sign(self, group_id: int) -> Dict[str, Any]
```
在指定群聊中进行签到。
**参数:**
- `group_id`: 群号
## 群公告
### `_send_group_notice` - 发送群公告
```python
async def _send_group_notice(self, group_id: int, content: str, **kwargs) -> Dict[str, Any]
```
发送群公告。
**参数:**
- `group_id`: 群号
- `content`: 公告内容
- `**kwargs`: 其他可选参数,如 `image`
### `_get_group_notice` - 获取群公告
```python
async def _get_group_notice(self, group_id: int) -> Dict[str, Any]
```
获取群公告列表。
**参数:**
- `group_id`: 群号
### `_del_group_notice` - 删除群公告
```python
async def _del_group_notice(self, group_id: int, notice_id: str) -> Dict[str, Any]
```
删除指定的群公告。
**参数:**
- `group_id`: 群号
- `notice_id`: 要删除的公告的 ID
## 其他信息获取
### `get_group_at_all_remain` - 获取@全体剩余次数
```python
async def get_group_at_all_remain(self, group_id: int) -> Dict[str, Any]
```
获取当天在指定群聊中 @全体成员 的剩余次数。
**参数:**
- `group_id`: 群号
### `get_group_system_msg` - 获取群系统消息
```python
async def get_group_system_msg(self) -> Dict[str, Any]
```
获取群系统消息(如加群请求、退群通知等)。
### `get_group_shut_list` - 获取群禁言列表
```python
async def get_group_shut_list(self, group_id: int) -> Dict[str, Any]
```
获取被禁言的群成员列表。
**参数:**
- `group_id`: 群号
## 加群请求处理
### `set_group_add_request` - 处理加群请求/邀请

View File

@@ -85,6 +85,20 @@ async def handle_imageinfo(event: MessageEvent):
await event.reply("消息中没有图片")
```
### `get_file` - 获取文件信息
```python
async def get_file(self, file_id: str) -> Dict[str, Any]
```
获取文件的详细信息比如文件名、大小、URL 等。
**参数:**
- `file_id`: 文件 ID通常从群文件上传事件中获取
**返回值:**
- 包含文件信息的字典
## 实际应用示例
### 图片转发器