Herta-villa-SDK

大别野「黑塔」Python SDK

停更说明

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

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

特性

• 多种服务器后端（内置 aiohttp 和 fastapi 后端），完整异步支持
• 完整类型注解支持
• ...

安装

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 时传入参数：

• use_websocket (bool) 启用 WebSocket
• test_villa_id (int) 测试别野，上线后可填 0

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

手动下线

调用 VillaBot.logout 方法。

Loop 后端

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

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

同时增加了监视 WS 连接（所有连接断开[^1]时会自动关闭应用）

[^1]:机器人主动 Logout 或者被服务器踢下线

• auto_shutdown (bool) 启用自动关闭
• watch_interval (int) 监视间隔

支持的 API

• [x] 鉴权
  • [x] 校验用户机器人访问凭证 /checkMemberBotAccessToken
• [x] 大别野
  • [x] 获取大别野信息 /getVilla
• [x] 用户
  • [x] 获取用户信息 /getMember
  • [x] 获取大别野成员列表 /getVillaMembers
  • [x] 踢出大别野用户 /deleteVillaMember
• [x] 消息
  • [x] 置顶消息 /pinMessage
  • [x] 撤回消息 /recallMessage
  • [x] 发送消息 /sendMessage
• [x] 房间
  • [x] 创建分组 /createGroup
  • [x] 编辑分组 /editGroup
  • [x] 删除分组 /deleteGroup
  • [x] 获取分组列表 /getGroupList
  • [x] 编辑房间 /editRoom
  • [x] 删除房间 /deleteRoom
  • [x] 获取房间信息 /getRoom
  • [x] 获取房间列表信息 /getVillaGroupRoomList
• [x] 身份组
  • [x] 向身份组操作用户 /operateMemberToRole
  • [x] 创建身份组 /createMemberRole
  • [x] 编辑身份组 /editMemberRole
  • [x] 删除身份组 /deleteMemberRole
  • [x] 获取身份组 /getMemberRoleInfo
  • [x] 获取大别野下所有身份组 /getVillaMemberRoles
• [x] 表态表情
  • [x] 获取全量表情 /getAllEmoticons
• [x] 图片
  • [x] 图片转存 /transferImage
  • [x] 获取图片上传参数 /getUploadImageParams
• [x] 审核 /audit
• [x] 获取 WebSocket 接入信息 /getWebsocketInfo

支持的事件

• [x] JoinVilla 有新用户加入大别野
• [x] SendMessage 用户@机器人发送消息
• [x] CreateRobot 大别野添加机器人实例
• [x] DeleteRobot 大别野删除机器人实例
• [x] AddQuickEmoticon 用户使用表情回复消息表态
• [x] AuditCallback 审核结果回调

Bug 反馈及建议

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

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

相关项目

• CMHopeSunshine/villa-py 米游社大别野 Bot Python SDK（非官方）
• CMHopeSunshine/nonebot-adapter-villa NoneBot2 米游社大别野 Bot 适配器

交流

• 前往大别野「斩尽芜杂」（aaUeZqd）

许可证

MIT License