Metadata-Version: 2.4
Name: xclr-milky
Version: 0.1.0.dev2
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 协议：

- 事件：协议文档中的全部 21 种事件均转换为旧版 OneBot 风格事件对象（`message_receive` /
  `message_recall` / `bot_offline` / `peer_pin_change` / `friend_nudge` / `group_nudge` /
  `friend_request` / `friend_file_upload` / `group_join_request` / `group_invited_join_request` /
  `group_invitation` / `group_member_increase` / `group_member_decrease` / `group_admin_change` /
  `group_mute` / `group_whole_mute` / `group_disband` / `group_name_change` /
  `group_essence_message_change` / `group_message_reaction` / `group_file_upload`）
- 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`，
  `set_peer_pin` / `mark_message_as_read` / `get_history_messages` 支持按消息注册表兜底会话上下文等
- 消息段：`text` / `mention` / `mention_all` / `face` / `reply` / `image` / `record` / `video` /
  `file` / `forward` / `market_face` / `light_app` / `xml` / `markdown` 双向转换
- `message_id` 与 Milky 的 `message_seq` 语义互通（撤回 / 回复 / 精华均使用消息序列号）

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

## 协议覆盖（Milky 1.3）

`Actions` 已提供协议文档（Apifox）中全部 65 个 HTTP API 的一等公民方法 + 自定义 API（`actions.custom.*` / `actions.call_api`）透传：

| 分类 | API |
| --- | --- |
| 系统 | `get_login_info` `get_impl_info` `get_user_profile` `get_peer_pins` `set_peer_pin` `set_avatar` `set_nickname` `set_bio` `get_custom_face_url_list` `get_cookies` `get_csrf_token` |
| 消息 | `send_private_message` `send_group_message` `recall_private_message` `recall_group_message` `get_message` `get_history_messages` `get_resource_temp_url` `get_forwarded_messages` `mark_message_as_read` |
| 好友 | `send_friend_nudge` `send_profile_like` `delete_friend` `get_friend_requests` `accept_friend_request` `reject_friend_request` |
| 群聊 | `set_group_name` `set_group_avatar` `set_group_member_card` `set_group_member_special_title` `set_group_member_admin` `set_group_member_mute` `set_group_whole_mute` `kick_group_member` `get_group_announcements` `send_group_announcement` `delete_group_announcement` `get_group_essence_messages` `set_group_essence_message` `quit_group` `send_group_message_reaction` `send_group_nudge` `get_group_notifications` `accept_group_request` `reject_group_request` `accept_group_invitation` `reject_group_invitation` |
| 文件 | `upload_private_file` `upload_group_file` `get_private_file_download_url` `get_group_file_download_url` `get_group_files` `move_group_file` `rename_group_file` `delete_group_file` `create_group_folder` `rename_group_folder` `delete_group_folder` `persist_group_file` |

响应翻译（`translate_response`）会把 Milky 的响应包装还原为旧版代码习惯的形态：
`get_history_messages` / `get_forwarded_messages` / `get_group_essence_messages` 的消息自动转换消息段，
`get_peer_pins` / `get_group_files` / `get_friend_requests` 等列表类 API 解包为对应字段。

## 测试

```bash
# 适配层单元/集成测试（mock 协议端，无需真实环境）
.venv/bin/python tests/test_milky_translate.py

# 端到端验收（mock 协议端 + 完整机器人）
.venv/bin/python tests/run_acceptance.py
```
