Metadata-Version: 2.4
Name: xclr-milky
Version: 0.1.0.dev0
Summary: HypeR_Bot 兼容接口的 Milky 协议适配层（QQ Bot 框架，HTTP/WebSocket 通信）
Author: XCLR Milky
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Requires-Dist: websocket-client>=1.5

# xclr-milky

基于 [Milky 协议](https://milky.ntqqrev.org/) 的 QQ Bot 框架适配层。

本包提供与 `hyper-bot`（HypeR_Bot）**完全兼容的 `Hyper` 顶层接口**（`Configurator` / `Listener` / `Events` / `Logger` / `Manager` / `Segments` / `Network` / `Utils`），
但底层通信改为 Milky 协议：

- 事件推送：`ws://host:port/event`（WebSocket，支持 SSE 回退）
- API 调用：`POST http://host:port/api/{api}`，JSON 请求体，`Authorization: Bearer {access_token}`

## 安装

```bash
pip install xclr-milky          # 从 PyPI 安装
pip install -e ./hyper_milky    # 本地开发安装
```

## 使用

config.json 中配置：

```json
{
  "protocol": "Milky",
  "Connection": {
    "mode": "MILKY",
    "host": "127.0.0.1",
    "port": 9600,
    "access_token": "",
    "retries": 5,
    "event_mode": "websocket"
  }
}
```

代码与旧版 hyper-bot 完全一致：

```python
from Hyper import Configurator
Configurator.cm = Configurator.ConfigManager(Configurator.Config(file="config.json").load_from_file())
from Hyper import Listener, Events, Logger, Manager, Segments
from Hyper.Utils import Logic

@Listener.reg
async def handler(event, actions):
    if isinstance(event, Events.GroupMessageEvent):
        await actions.send(group_id=event.group_id, message=Manager.Message(Segments.Text("Hello")))

Listener.run()
```

## 兼容层说明

适配层把旧版 OneBot v11 风格的 API 调用/事件/消息段自动翻译为 Milky 协议：

- 事件：`message_receive` / `message_recall` / `friend_nudge` / `group_nudge` / `friend_request` /
  `group_join_request` / `group_invited_join_request` / `group_invitation` / `group_member_increase` /
  `group_member_decrease` / `group_admin_change` / `group_mute` / `group_essence_message_change` /
  `group_message_reaction` / `group_file_upload` / `friend_file_upload` 等 → 旧版 OneBot 风格事件对象
- API：`send_msg` → `send_group_message` / `send_private_message`，`delete_msg` → `recall_*_message`，
  `get_stranger_info` → `get_user_profile`，`group_poke` → `send_group_nudge`，
  `set_msg_emoji_like` → `send_group_message_reaction`，`get_version_info` → `get_impl_info` 等
- 消息段：`text` / `mention` / `mention_all` / `face` / `reply` / `image` / `record` / `video` /
  `forward` / `light_app` / `xml` / `markdown` 双向转换
- `message_id` 与 Milky 的 `message_seq` 语义互通（撤回 / 回复 / 精华均使用消息序列号）

由于撤回（`recall`）、取消息（`get_message`）、设精华等 API 在 Milky 中需要 `message_scene` + `peer_id`，
适配层维护了一个"消息注册表"，自动记录收发消息的会话上下文，供这些 API 解析使用。
