HypeR Core

同时适配 OneBot v11 与 Milky 协议，目标多协议、功能模块化、易于扩展、高效的 QQ 机器人框架

概览

HypeR Core 是一个基于 Python asyncio 的 QQ 机器人框架，提供简洁的事件系统、消息构建与类型安全的 API 响应。当前支持 OneBot v11 与 Milky 两种协议，通过配置文件切换，业务代码无需改动。适配器经注册表动态加载，支持运行时注册与 entry points 自动发现，可接入自定义协议（见高级用法）。

English Documentation 中文文档

---

安装

需要 Python 3.11+。

pip install hyper-bot

开发和构建使用 uv：

git clone https://github.com/HarcicYang/HypeR_Bot
cd HyperBotCore
uv sync

文档

• 快速开始
• 配置文件
• Client 与生命周期
• 事件系统
• 消息与消息段
• Actions API 操作
• 高级用法

简单示例

import asyncio
import hyperot

hyperot.init()

from hyperot import Client
from hyperot.events import GroupMessageEvent, PrivateMessageEvent
from hyperot.common import Message
from hyperot.segments import *


async def handler(event, actions):
    if str(event.message) == ".ping":
        await actions.send_msg(
            f"pong! HypeR Core {hyperot.HYPER_BOT_VERSION}", group_id=event.group_id, user_id=event.user_id
        )


with Client() as cli:
    cli.subscribe(handler, [GroupMessageEvent, PrivateMessageEvent])
    asyncio.get_event_loop().run_until_complete(cli.run())

许可

GPL-3.0 License

---

Milky 协议

除了 OneBot v11，HypeR Core 也支持 Milky 协议——通过 config.json 的 protocol: "Milky" 切换，业务代码无需改动。框架作为应用端：WebSocket 连接 /event 接收事件，HTTP 调用 /api/:api。

{
  "protocol": "Milky",
  "owner": [],
  "black_list": [],
  "silents": [],
  "connection": {
    "mode": "Milky",
    "host": "127.0.0.1",
    "port": 5005,
    "auth": ""
  },
  "log_level": "INFO",
  "log_use_nf": false,
  "uin": 0,
  "max_workers": 1,
  "others": {}
}

与 OneBot 的主要差异：

• 事件：Milky 事件（message_receive、group_whole_mute、group_name_change、group_invitation、戳一戳等）统一映射到框架事件模型，见事件系统
• message_id：为 场景 + 序号 + 会话 的编码值，del_msg 自动解码
• actions.custom：直接返回响应 data 字典（OneBot 下返回 echo）
• 限制：send_forward_msg / send_callback 暂不支持；部分协议端（如 Lagrange.Milky）私聊撤回存在协议端侧 bug

仓库提供 test_milky.py 真机联调脚本（uv run python test_milky.py），在 QQ 上发送 .e2e 可跑通全链路验证。