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