IdeauraAdapter 模块文档

简介

IdeauraAdapter 是基于 ErisPulse 架构的花枫咖啡馆（RockyChat）协议适配器，整合了所有平台功能模块，提供统一的事件处理和消息操作接口。

使用示例

OneBot12标准事件类型

Ideaura适配器完全兼容 OneBot12 标准事件格式，并提供了一些扩展字段：

消息发送示例

from ErisPulse.Core import adapter
ideaura = adapter.get("ideaura")

# 发送文本消息
await ideaura.Send.To("user", "user_id").Text("Hello World!")

# 发送带@的消息
await ideaura.Send.To("group", "chatroom").At("456").Text("@李四 你好")

# 触发 Bot 指令
await ideaura.Send.To("group", "chatroom").Command("550e8400-e29b-41d4-a716-446655440000").Text("/weather 北京")

# @多人
await ideaura.Send.To("group", "chatroom").At("456").At("789").Text("@多人")

# @全体
await ideaura.Send.To("group", "chatroom").AtAll().Text("通知所有人")

# 发送回复消息
await ideaura.Send.To("group", "chatroom").Reply("1001").Text("回复内容")

# 发送图片（从本地文件）
with open("photo.jpg", "rb") as f:
    image_data = f.read()
await ideaura.Send.To("group", "chatroom").Image(image_data)

# 发送图片（从URL）
await ideaura.Send.To("group", "chatroom").Image("https://example.com/photo.jpg")

# 发送视频
await ideaura.Send.To("group", "chatroom").Video("https://example.com/video.mp4")

# 发送文件（带文件名）
with open("doc.pdf", "rb") as f:
    file_data = f.read()
await ideaura.Send.To("group", "chatroom").File(file_data, "文档.pdf")

# 发送 Markdown 格式消息
await ideaura.Send.To("group", "chatroom").Markdown("# 标题\n- 列表项")

# 发送 HTML 格式消息
await ideaura.Send.To("group", "chatroom").Html("<b>加粗</b>消息")

# 编辑消息
await ideaura.Send.To("group", "chatroom").Edit("message_id", "修改后的内容")

# 撤回消息
await ideaura.Send.To("group", "chatroom").Recall("message_id")

# 使用 Raw_ob12 发送复杂消息
message = [
    {"type": "text", "data": {"text": "第一行"}},
    {"type": "image", "data": {"file": "http://example.com/img.jpg"}},
    {"type": "text", "data": {"text": "第二行"}}
]
await ideaura.Send.To("group", "chatroom").Raw_ob12(message)

# 组合使用
await ideaura.Send.To("group", "chatroom").Reply("1001").At("456").Text("回复并@")

配置说明

首次运行会生成配置。花枫咖啡馆适配器支持多账户配置。

首次运行生成的默认配置

[IdeauraAdapter.accounts.default]
token = ""             # 机器人 API Token (bot-token-...)
enabled = false       # 是否启用（填写完 token 后改为 true）

适配器使用 Bot Token 进行认证。

Bot Token需要前往MSCPO开放平台获取。

多账户配置示例

# 账户1
[IdeauraAdapter.accounts.bot1]
token = "bot-token-xxxxxx1"
enabled = true

# 账户2
[IdeauraAdapter.accounts.bot2]
token = "bot-token-xxxxxx2"
enabled = true

# 可选：自定义服务器地址
[IdeauraAdapter]
base_url = "https://api.mscpo.com/api/rockychat"
ws_url = "wss://api-cofe.allons-y.uk:3009/mqtt"
heartbeat_interval = 30

配置项说明：

• token：机器人 API Token（以 bot-token- 开头）
• enabled：是否启用该账户（可选，默认为 true）

全局配置项：

• base_url：API 服务器地址（可选，默认为花枫咖啡馆官方地址）
• ws_url：WebSocket 服务器地址（可选，默认为花枫咖啡馆官方地址）
• heartbeat_interval：心跳间隔秒数（可选，默认30秒）

指定发送账户

可以通过 Using() 方法指定使用哪个账户发送消息：

from ErisPulse.Core import adapter
ideaura = adapter.get("ideaura")

# 使用账户名发送消息
await ideaura.Send.Using("bot1").To("user", "user123").Text("Hello from bot1!")

# 使用 user_id 发送消息（自动匹配对应账户）
await ideaura.Send.Using("456").To("group", "chatroom").Text("Hello from bot2!")

# 不指定时使用第一个启用的账户
await ideaura.Send.To("user", "user123").Text("Hello from default account!")

平台特有功能

请参考 平台特性文档 了解花枫咖啡馆平台的特有功能，包括特有事件类型、扩展字段说明、消息编辑事件、消息转发事件、好友在线状态事件、用户状态变更事件等内容。

事件监听示例

使用 Event 模块（推荐）

from ErisPulse.Core.Event import message, notice

@message.on_message()
async def handle_message(event):
    if event["platform"] == "ideaura":
        detail_type = event.get("detail_type")
        text = event.get_text()
        
        # 获取触发的 Bot 指令 ID（若有）
        cmd_id = event.get_command_id()
        if cmd_id:
            print(f"收到指令: {cmd_id}")

        if detail_type == "group":
            source_type = event.get_source_type()
            if source_type == "topic":
                topic_name = event.get("ideaura_topic_name")
        elif detail_type == "private":
            pass

@notice.on_notice()
async def handle_notice(event):
    if event["platform"] == "ideaura":
        detail_type = event.get("detail_type")
        
        if detail_type == "ideaura_message_edit":
            new_content = event.get("ideaura_new_content", "")
            
        elif detail_type == "ideaura_message_recall":
            message_id = event.get("message_id")
            
        elif detail_type == "ideaura_friend_online":
            friend_name = event.get_user_nickname()

使用 OneBot12 标准事件

from ErisPulse import sdk

@sdk.adapter.on("message")
async def handle_message(event):
    if event["platform"] == "ideaura":
        user_id = event["self"]["user_id"]
        print(f"消息来自账户: {user_id}")

@sdk.adapter.on("notice")
async def handle_notice(event):
    if event["platform"] == "ideaura":
        pass

@sdk.adapter.on("request")
async def handle_request(event):
    if event["platform"] == "ideaura":
        if event.get("detail_type") == "friend":
            user_nickname = event.get("user_nickname")
            message = event.get("ideaura_message", "")

注意事项

1. 确保在调用 startup() 前完成所有处理器的注册
2. 适配器使用 WebSocket 长连接接收事件，在连接时自动向 API 请求 internalToken 进行认证，支持自动重连（固定5秒延迟）
3. 二进制内容（图片/视频等）支持 bytes、URL、本地路径三种输入方式
4. 文件大小限制为 10MB
5. 自身发送的消息（isSelf: true）会被自动过滤，不会产生事件
6. @全体（AtAll()）需要管理员权限
7. 程序退出时请调用 shutdown() 确保资源释放

参考链接

• ErisPulse 主库
• 花枫咖啡馆
• OneBot12协议对照