HeXi/hexi/core/docs/清单.md

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

---

业务层调用示例

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 封装