Home

Awesome

Herta-villa-SDK

license pypi python version Ruff FOSSA Status

大别野「黑塔」Python SDK

停更说明

大别野聊天室于 2024 年 3 月 12 日正式停止服务,Herta-villa-SDK 停止更新。

详情请见 【公告】大别野聊天室下线说明

特性

安装

pip install herta-villa-sdk

FastAPI 后端支持:

pip install herta-villa-sdk[fastapi]

WebSocket 支持:

pip install herta-villa-sdk[ws]

快速开始

你需要拥有一个大别野机器人。可前往大别野「机器人开发者社区」OpenVilla)申请。

from hertavilla import MessageChain, SendMessageEvent, VillaBot, run, StartswithResult
from hertavilla.server import init_backend


PUB_KEY = """-----BEGIN PUBLIC KEY-----
aaa
bbb
ccc
-----END PUBLIC KEY-----
"""  # 开放平台 pub_key
# 需要注意 `-----BEGIN PUBLIC KEY-----` 前没有换行符
#  `-----END PUBLIC KEY-----` 后有一个换行符
# 目前从网页端复制下来的时候会为一串 pub_key,需要将空格转为换行

bot = VillaBot(
    "bot_id",  # 这里填写 bot_id
    "bot_secret",  # 这里填写 secret
    PUB_KEY,  # 开放平台提供的 pub_key
    callback_endpoint="/",  # bot 回调 endpoint
    # use_websocket=True,  # 使用 WebSocket
    # test_villa_id=0,  # 测试别野,上线后可填 0
)


@bot.startswith("/")  # 注册一个消息匹配器,匹配前缀为 / 的消息
async def _(event: SendMessageEvent, bot: VillaBot, match_result: StartswithResult):
    if match_result.text == "hello":
        chain = MessageChain("world")
        await bot.send(event.villa_id, event.room_id, chain)


init_backend()  # 初始化后端
run(bot)  # 运行 bot

可以向你的 bot 发送 @Bot /hello,bot 会回复 world

示例

详见 examples 文件夹。

WebSocket 支持

需在开放平台的「回调方式」中选择 「websocket回调」。

在实例化 VillaBot 时传入参数:

启动时会自动登录并接收事件。

手动下线

调用 VillaBot.logout 方法。

Loop 后端

在不需要 HTTP WebHook 时,Herta SDK 提供了 LoopBackend

此后端仅依靠异步 loop 运行。

同时增加了监视 WS 连接(所有连接断开1时会自动关闭应用)

支持的 API

支持的事件

Bug 反馈及建议

大别野 Bot 和 Herta SDK 均处于开发状态中,如遇到问题或有相关建议可通过 Issue 提出,感谢支持!

有关提出 Issue 和 Pull Request 的要点,请查看 贡献指南

相关项目

交流

许可证

MIT License

FOSSA Status

Footnotes

  1. 机器人主动 Logout 或者被服务器踢下线