yunhu2onebot12 0.1.0

云湖事件到OneBot12的协议格式转换器

云湖平台事件转换模块 (YunhuAdapter4OneBot12)

功能概述

本模块用于将云湖平台的事件数据转换为标准的OneBot12格式。模块会自动根据eventType字段判断事件类型并进行相应的转换，支持消息、通知等多种事件类型。

安装方法

pip install yunhu2onebot12

使用方法

基本使用

from yunhu2onebot12 import Converter

# 创建转换器实例
converter = Converter()

# 云湖平台原始事件数据
yunhu_event = {
    "version": "1.0",
    "header": {
        "eventId": "c192ccc83d5147f2859ca77bcfafc9f9",
        "eventType": "message.receive.normal",
        "eventTime": 1748613099002
    },
    "event": {
        # ... 事件数据 ...
    }
}

# 转换为OneBot12格式
onebot_event = converter.convert(yunhu_event)

支持的事件类型

云湖事件类型	对应OneBot事件类型	说明
message.receive.normal	message	普通消息
message.receive.instruction	message + command	指令消息
bot.followed	notice.friend_increase	用户关注机器人
bot.unfollowed	notice.friend_decrease	用户取消关注
group.join	notice.group_member_increase	用户加入群组
group.leave	notice.group_member_decrease	用户离开群组
button.report.inline	notice.button_click	按钮点击事件
bot.shortcut.menu	notice.shortcut_menu	快捷菜单事件

消息类型支持

支持以下内容类型的消息转换：

• 文本(text)
• 图片(image)
• 视频(video)
• 文件(file)
• 表单指令(form)

特殊字段处理

部分云湖特有字段会在转换后的OneBot事件中以yunhu_前缀的非标准字段形式保留：

• yunhu_form: 表单类型指令数据
• yunhu_button: 按钮相关数据
• yunhu_menu: 快捷菜单数据

错误处理

• 如果传入不支持的事件类型，方法会返回None
• 当事件数据格式错误时会抛出ValueError

注意事项

1. 使用 Python 3.7 及更高版本
2. 本模块仅处理事件格式转换，不包含网络通信功能
3. 云湖特有字段在OneBot12标准中可能不被其他组件识别
4. 表单消息和按钮事件是云湖平台特有功能，转换后会添加yunhu_前缀

贡献指南

欢迎提交Pull Request或Issue报告问题。提交代码前请确保：

1. 通过所有单元测试
2. 添加新功能的测试用例
3. 更新文档和示例