结构调整
视频解析多图/多媒体结构 消息体适配
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
# HexiCore 能力清单（精简版）
|
||||
|
||||
> **设计目标**
|
||||
>
|
||||
> HexiCore 是原生能力的便利封装层，只封装「原生写起来麻烦」的操作。
|
||||
> 普通消息发送、构建、解析直接使用 Alconna UniMessage，不重复封装。
|
||||
|
||||
---
|
||||
|
||||
# 需要封装的能力
|
||||
|
||||
## 一、消息操作（简化 API 调用）
|
||||
|
||||
| 能力 | 原生写法 | HexiCore 写法 |
|
||||
|---|---|---|
|
||||
| 戳一戳 | `bot.call_api("send_poke", group_id=..., user_id=...)` | `await hexi.poke(group_id, user_id)` |
|
||||
| 消息加精 | `bot.call_api("set_msg_essence", message_id=...)` | `await hexi.essence(msg_id)` |
|
||||
| 取消加精 | `bot.call_api("delete_msg_essence", message_id=...)` | `await hexi.unessence(msg_id)` |
|
||||
| 合并转发 | 手动构建 node 结构 | `forward.add(user_id, nickname, content).send(group_id)` |
|
||||
|
||||
---
|
||||
|
||||
## 二、信息提取（省去遍历/判断）
|
||||
|
||||
| 能力 | 原生写法 | HexiCore 写法 |
|
||||
|---|---|---|
|
||||
| 获取 At 用户列表 | `[seg.data["qq"] for seg in event.message if seg.type == "at"]` | `hexi.get_at_users(event)` |
|
||||
| 获取回复内容 | `bot.get_msg(message_id=event.reply.message_id)` | `hexi.get_reply_content(event)` |
|
||||
| 获取消息来源 | 类型判断 + 字段访问 | `hexi.get_source(event)` |
|
||||
|
||||
---
|
||||
|
||||
## 三、身份查询（需要 API 调用）
|
||||
|
||||
| 能力 | 原生写法 | HexiCore 写法 |
|
||||
|---|---|---|
|
||||
| 是否好友 | `bot.get_stranger_info()` + 异常处理 | `await hexi.is_friend(user_id)` |
|
||||
| 是否群成员 | `bot.get_group_member_info()` + 异常处理 | `await hexi.is_member(group_id, user_id)` |
|
||||
| 获取群成员信息 | `bot.get_group_member_info()` | `await hexi.get_member_info(group_id, user_id)` |
|
||||
|
||||
---
|
||||
|
||||
## 四、权限推断（原生无直接 API）
|
||||
|
||||
| 能力 | 说明 |
|
||||
|---|---|
|
||||
| `hexi.can_ban(group_id, user_id)` | 检查目标是否可被禁言（机器人是管理员 + 目标不是群主） |
|
||||
| `hexi.can_kick(group_id, user_id)` | 检查目标是否可被踢出 |
|
||||
| `hexi.can_set_admin(group_id)` | 检查机器人是否有管理员权限 |
|
||||
| `hexi.is_admin(user_id)` | 判断用户是否为管理员 |
|
||||
| `hexi.is_owner(user_id)` | 判断用户是否为群主 |
|
||||
| `hexi.is_superuser(user_id)` | 判断用户是否为超级用户 |
|
||||
|
||||
---
|
||||
|
||||
## 五、批量操作（省去循环）
|
||||
|
||||
| 能力 | 说明 |
|
||||
|---|---|
|
||||
| `hexi.ban_multi(group_id, user_ids, duration)` | 批量禁言 |
|
||||
| `hexi.kick_multi(group_id, user_ids)` | 批量踢出 |
|
||||
|
||||
---
|
||||
|
||||
# 不需要封装（直接用原生）
|
||||
|
||||
| 类别 | 能力 | 原生用法 |
|
||||
|---|---|---|
|
||||
| 消息发送 | 文本/图片/语音/视频/文件 | `UniMessage.text/image/record/video/file().send()` |
|
||||
| 消息发送 | @某人/@全体 | `UniMessage.at()/at_all().send()` |
|
||||
| 消息发送 | 回复消息 | `UniMessage.reply(msg_id).send()` |
|
||||
| 消息操作 | 撤回消息 | `bot.delete_msg(message_id=...)` |
|
||||
| 群管理 | 禁言 | `bot.set_group_ban(group_id=..., user_id=..., duration=...)` |
|
||||
| 群管理 | 踢人 | `bot.set_group_kick(group_id=..., user_id=...)` |
|
||||
| 群管理 | 群名片 | `bot.set_group_card(group_id=..., user_id=..., card=...)` |
|
||||
| 群管理 | 管理员 | `bot.set_group_admin(group_id=..., user_id=..., enable=...)` |
|
||||
| 群管理 | 群头衔 | `bot.set_group_special_title(group_id=..., user_id=..., title=...)` |
|
||||
| 群管理 | 群名 | `bot.set_group_name(group_id=..., group_name=...)` |
|
||||
| 群管理 | 全员禁言 | `bot.set_group_whole_ban(group_id=..., enable=...)` |
|
||||
| 请求处理 | 好友申请 | `bot.set_friend_add_request(flag=..., approve=...)` |
|
||||
| 请求处理 | 加群申请 | `bot.set_group_add_request(flag=..., sub_type=..., approve=...)` |
|
||||
| 事件判断 | 群/私聊消息 | `isinstance(event, GroupMessageEvent)` |
|
||||
| 事件信息 | 发送者 | `event.sender.user_id` / `event.sender.nickname` |
|
||||
| 事件信息 | 群号 | `event.group_id` |
|
||||
| 事件信息 | 消息ID | `event.message_id` |
|
||||
| 事件信息 | 纯文本 | `event.get_plaintext()` |
|
||||
| 事件信息 | 消息段遍历 | `for seg in event.message: ...` |
|
||||
|
||||
---
|
||||
|
||||
# 业务层调用示例
|
||||
|
||||
```python
|
||||
from nonebot_plugin_alconna import UniMessage
|
||||
|
||||
# 普通消息 — 直接用 UniMessage
|
||||
await UniMessage.text("Hello").send()
|
||||
await UniMessage.image(url="https://...").send()
|
||||
await UniMessage.at("123456").text("你好").send()
|
||||
|
||||
# 平台能力 — 用 HexiCore 封装
|
||||
await hexi.poke(group_id, user_id) # 戳一戳
|
||||
await hexi.essence(msg_id) # 加精
|
||||
await hexi.unessence(msg_id) # 取消加精
|
||||
|
||||
# 转发消息 — 链式构建
|
||||
forward = hexi.forward()
|
||||
forward.add("123", "Alice", UniMessage.text("消息1"))
|
||||
forward.add("456", "Bob", UniMessage.image(url="..."))
|
||||
await forward.send(group_id)
|
||||
|
||||
# 信息提取 — 一行搞定
|
||||
users = hexi.get_at_users(event) # At 用户列表
|
||||
reply = hexi.get_reply_content(event) # 回复内容
|
||||
source = hexi.get_source(event) # 消息来源
|
||||
|
||||
# 身份查询 — 异常处理已封装
|
||||
is_friend = await hexi.is_friend(user_id) # 是否好友
|
||||
is_member = await hexi.is_member(group_id, uid) # 是否群成员
|
||||
info = await hexi.get_member_info(group_id, uid)# 群成员信息
|
||||
|
||||
# 权限推断 — 自动检查机器人权限
|
||||
if await hexi.can_ban(group_id, user_id):
|
||||
await bot.set_group_ban(group_id=group_id, user_id=user_id, duration=60)
|
||||
|
||||
# 身份判断
|
||||
if hexi.is_admin(event): # 管理员
|
||||
if hexi.is_owner(event): # 群主
|
||||
if hexi.is_superuser(event): # 超级用户
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 架构设计
|
||||
|
||||
```
|
||||
hexi/core/
|
||||
├── __init__.py # 插件入口，导出 hexi 对象
|
||||
├── poke.py # 戳一戳
|
||||
├── forward.py # 合并转发消息构建器
|
||||
├── essence.py # 消息加精/取消
|
||||
├── extract.py # 消息提取（At列表、回复内容、来源）
|
||||
├── member.py # 身份查询（好友、群成员）
|
||||
├── permission.py # 权限推断（可禁言、可踢人等）
|
||||
└── utils.py # 工具函数
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 设计原则
|
||||
|
||||
1. **薄封装** — 每个函数只是对原生 API 的简化调用，不添加额外逻辑
|
||||
2. **类型安全** — 使用类型注解，配合 Pydantic 校验
|
||||
3. **异常处理** — 内部处理 API 异常，对外返回布尔值或 None
|
||||
4. **单一职责** — 每个模块只负责一类能力
|
||||
5. **可选依赖** — 业务层可以选择用原生 API 或 HexiCore 封装
|
||||
Reference in New Issue
Block a user