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 操作
• 高级用法

简单示例

importasyncioimporthyperothyperot.init()
fromhyperotimportClientfromhyperot.eventsimportGroupMessageEvent, PrivateMessageEventfromhyperot.commonimportMessagefromhyperot.segmentsimport*asyncdefhandler(event, actions):
ifstr(event.message) ==".ping":
awaitactions.send_msg(
f"pong! HypeR Core {hyperot.HYPER_BOT_VERSION}", group_id=event.group_id, user_id=event.user_id
)
withClient() ascli:
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 可跑通全链路验证。