MessageBuilder 详解

MessageBuilder 是 ErisPulse 提供的 OneBot12 标准消息段构建工具，用于构建结构化的消息内容，配合 Send.Raw_ob12() 使用。

导入方式

MessageBuilder 支持以下两种导入方式（效果相同，推荐使用第一种）：

from ErisPulse.Core.Event import MessageBuilder        # 推荐，通过包导出
from ErisPulse.Core.Event.message_builder import MessageBuilder  # 直接导入模块

双模式机制

MessageBuilder 提供两种使用模式，通过 Python 描述符机制（__get__）实现类级别和实例级别的不同行为：当通过类调用方法时，__get__ 返回静态方法的执行结果；当通过实例调用时，返回 self 以支持链式调用。

链式调用模式（实例）

通过实例化 MessageBuilder() 使用，每个方法返回 self，支持链式调用，最后用 .build() 获取消息段列表：

from ErisPulse.Core.Event.message_builder import MessageBuilder

segments = (
    MessageBuilder()
    .text("你好！")
    .image("https://example.com/photo.jpg")
    .build()
)
# [
#     {"type": "text", "data": {"text": "你好！"}},
#     {"type": "image", "data": {"file": "https://example.com/photo.jpg"}}
# ]

快速构建模式（静态）

通过类直接调用方法，每个方法直接返回消息段列表，适合单段消息：

# 直接返回 list[dict]，无需 .build()
segments = MessageBuilder.text("你好！")
# [{"type": "text", "data": {"text": "你好！"}}]

消息段类型

配合 Send 使用

构建的消息段列表通过 Send.Raw_ob12() 发送：

from ErisPulse import sdk
from ErisPulse.Core.Event.message_builder import MessageBuilder

# 链式构建 + 发送
segments = (
    MessageBuilder()
    .mention("user123", "张三")
    .text(" 请查看这张图片")
    .image("https://example.com/photo.jpg")
    .build()
)
await sdk.adapter.myplatform.Send.To("group", "group456").Raw_ob12(segments)

配合 Event 回复

from ErisPulse.Core.Event import command

@command("report")
async def report_handler(event):
    await event.reply_ob12(
        MessageBuilder()
        .text("📊 日报汇总\n")
        .text("今日完成任务: 5\n")
        .text("进行中任务: 3")
        .build()
    )

工具方法

copy()

复制当前构建器，用于基于同一基础内容创建多个消息变体：

base = MessageBuilder().text("基础内容").mention("admin")

# 基于相同前缀构建不同消息
msg1 = base.copy().text(" 变体A").build()
msg2 = base.copy().text(" 变体B").image("img.jpg").build()

clear()

清空已添加的消息段，复用同一个构建器：

builder = MessageBuilder()

for user_id in ["user1", "user2", "user3"]:
    builder.clear()
    msg = builder.mention(user_id).text(" 你好！").build()
    await adapter.Send.To("user", user_id).Raw_ob12(msg)

len() / bool()

builder = MessageBuilder()
print(bool(builder))   # False

builder.text("Hello")
print(len(builder))    # 1
print(bool(builder))   # True

自定义消息段

使用 custom() 方法添加平台扩展消息段：

# 添加平台特有的消息段
segments = (
    MessageBuilder()
    .text("请填写表单：")
    .custom("yunhu_form", {"form_id": "12345"})
    .build()
)

自定义消息段只在对应平台的适配器中有效，其他适配器会忽略不认识的消息段。

完整示例

多元素消息

segments = (
    MessageBuilder()
    .reply(event.get_id())                    # 回复原消息
    .mention(event.get_user_id())             # @发送者
    .text(" 这是你的查询结果：\n")             # 文本
    .image("https://example.com/chart.png")   # 图片
    .text("\n详细数据见附件：")
    .file("https://example.com/data.csv", filename="data.csv")
    .build()
)
await event.reply_ob12(segments)

静态工厂 + 链式混合

# 快速构建单段消息
simple_msg = MessageBuilder.text("简单文本")

# 链式构建复杂消息
complex_msg = (
    MessageBuilder()
    .at_all()
    .text(" 📢 公告：")
    .text("今天下午3点开会")
    .build()
)

相关文档

• 适配器 SendDSL 详解 - Send 链式发送接口
• 事件转换标准 - 消息段转换规范
• Event 包装类 - Event.reply_ob12() 方法