Awesome
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) 启用 WebSockettest_villa_id
(int) 测试别野,上线后可填 0
启动时会自动登录并接收事件。
手动下线
调用 VillaBot.logout
方法。
Loop 后端
在不需要 HTTP WebHook 时,Herta SDK 提供了 LoopBackend
。
此后端仅依靠异步 loop
运行。
同时增加了监视 WS 连接(所有连接断开1时会自动关闭应用)
auto_shutdown
(bool) 启用自动关闭watch_interval
(int) 监视间隔
支持的 API
- 鉴权
- 校验用户机器人访问凭证
/checkMemberBotAccessToken
- 校验用户机器人访问凭证
- 大别野
- 获取大别野信息
/getVilla
- 获取大别野信息
- 用户
- 获取用户信息
/getMember
- 获取大别野成员列表
/getVillaMembers
- 踢出大别野用户
/deleteVillaMember
- 获取用户信息
- 消息
- 置顶消息
/pinMessage
- 撤回消息
/recallMessage
- 发送消息
/sendMessage
- 置顶消息
- 房间
- 创建分组
/createGroup
- 编辑分组
/editGroup
- 删除分组
/deleteGroup
- 获取分组列表
/getGroupList
- 编辑房间
/editRoom
- 删除房间
/deleteRoom
- 获取房间信息
/getRoom
- 获取房间列表信息
/getVillaGroupRoomList
- 创建分组
- 身份组
- 向身份组操作用户
/operateMemberToRole
- 创建身份组
/createMemberRole
- 编辑身份组
/editMemberRole
- 删除身份组
/deleteMemberRole
- 获取身份组
/getMemberRoleInfo
- 获取大别野下所有身份组
/getVillaMemberRoles
- 向身份组操作用户
- 表态表情
- 获取全量表情
/getAllEmoticons
- 获取全量表情
- 图片
- 图片转存
/transferImage
- 获取图片上传参数
/getUploadImageParams
- 图片转存
- 审核
/audit
- 获取 WebSocket 接入信息
/getWebsocketInfo
支持的事件
- JoinVilla 有新用户加入大别野
- SendMessage 用户@机器人发送消息
- CreateRobot 大别野添加机器人实例
- DeleteRobot 大别野删除机器人实例
- AddQuickEmoticon 用户使用表情回复消息表态
- AuditCallback 审核结果回调
Bug 反馈及建议
大别野 Bot 和 Herta SDK 均处于开发状态中,如遇到问题或有相关建议可通过 Issue 提出,感谢支持!
有关提出 Issue 和 Pull Request 的要点,请查看 贡献指南。
相关项目
- CMHopeSunshine/villa-py 米游社大别野 Bot Python SDK(非官方)
- CMHopeSunshine/nonebot-adapter-villa NoneBot2 米游社大别野 Bot 适配器
交流
- 前往大别野「斩尽芜杂」(
aaUeZqd
)
许可证
Footnotes
-
机器人主动 Logout 或者被服务器踢下线 ↩