ErisPulse ErisPulse
在交互式文档中心打开 →
本页章节
本文为静态镜像,内容以交互版为准 在交互式文档中心打开 →

Matrix平台特性文档

MatrixAdapter 是基于 Matrix协议 构建的适配器,整合了Matrix协议的所有核心功能模块,提供统一的事件处理和消息操作接口。


文档信息

  • 对应模块版本: 4.6.1
  • 维护者: ErisPulse
  • 最后更新: 2026-11-10

基本信息

  • 平台简介:Matrix是一个开放的去中心化通信协议,支持私聊、群组等多种场景
  • 适配器名称:MatrixAdapter
  • 多账户支持:支持同时配置多个 Matrix 账户
  • 连接方式:Long Polling(通过 Matrix Sync API /sync)
  • 认证方式:基于 access_token 或 user_id + password 登录获取 token
  • 链式修饰支持:支持 .Reply()、.At()、.AtAll() 等链式修饰方法
  • OneBot12兼容:支持发送 OneBot12 格式消息

配置说明

MatrixAdapter 支持多账户配置,每个账户独立配置 homeserver 和认证信息。

# config.toml
# 账户1
[Matrix_Adapter.accounts.default]
homeserver = "https://matrix.org"          # Matrix服务器地址(必填)
access_token = "YOUR_ACCESS_TOKEN"          # 访问令牌(与 user_id+password 二选一)
user_id = ""                                # Matrix用户ID(如 @bot:matrix.org)
password = ""                               # Matrix用户密码
auto_accept_invites = true                  # 是否自动接受房间邀请(可选,默认为true)
enabled = true                              # 是否启用(可选,默认为true)

# 账户2
[Matrix_Adapter.accounts.bot2]
homeserver = "https://matrix.example.com"
access_token = "ANOTHER_TOKEN"
enabled = true

兼容旧配置:若检测到旧的单账户 [Matrix_Adapter] 配置(含 access_token),会自动迁移为 accounts.default。

配置项说明(每个账户):

  • homeserver:Matrix服务器地址(必填),默认为 https://matrix.org
  • access_token:访问令牌,可从Matrix客户端获取。如果已有 token,直接填写即可
  • user_id:Matrix用户ID(如 @bot:matrix.org),与 password 配合使用进行登录
  • password:Matrix用户密码,用于自动登录获取 access_token
  • auto_accept_invites:是否自动接受房间邀请,默认为 true
  • enabled:是否启用该账户(可选,默认为true)
  • encryption_enabled:是否启用端到端加密,默认为 false
  • trust_all_devices:是否自动信任未验证设备(E2EE),默认为 true
  • device_id:设备 ID(E2EE,通常自动获取,无需填写)
  • store_path:加密会话存储目录(E2EE),默认为 data/matrix/<账户名>

认证方式:

  • 方式一(推荐):直接提供 access_token
  • 方式二:提供 user_id 和 password,适配器会自动调用登录接口获取 token

v5 范式更新(4.2.0)

  • BaseConverter 继承:转换器公共字段由框架 build_base_event 构建
  • Api DSL:get_self_info/get_user_info/get_group_info/get_group_list/get_group_member_list/leave_group/delete_message(redact) + 元动作
  • 消息事件补充 message_id(event_id);消息登记表支撑 delete_message
  • spawn_background 任务归属:同步/心跳任务改用 runtime.spawn_background
  • 框架软依赖:运行时检测 ErisPulse>=2.7.1 并提示;启动输出版本日志
  • Matrix 无原生按钮能力,标准 keyboard 段优雅忽略(不报错)

端到端加密(4.3.0)

4.3.0 起适配器原生支持加密房间的端到端加密(基于 matrix-nio[e2e] / vodozemac):

[Matrix_Adapter.accounts.default]
user_id = "@bot:matrix.org"
password = "YOUR_PASSWORD"
encryption_enabled = true       # 启用(默认 false,存量部署不受影响)
trust_all_devices = true        # 自动信任未验证设备(默认;false 为严格模式)
  • 加密房间消息收发自动解密/加密,媒体端到端加密(m.file.encrypted)
  • device_id 自动解析与持久化;会话存储于 store_path(默认 data/matrix/<账户名>,请勿删除,否则历史消息无法解密)
  • 事件 Mixin 新增 event.is_encrypted();媒体段携带 matrix_encrypted_file(JWK),可用 MatrixAdapter.decrypt_media() 解密
  • 不支持交叉签名与服务器端密钥备份;需要 Python >= 3.10
  • 未启用或未安装 matrix-nio 时自动降级为明文模式

详细说明见下文端到端加密(E2EE)章节与适配器 README。

标准化对齐

本节说明适配器与 ErisPulse 标准化规范对齐的行为。规范详情参见 SDK 文档《API 响应规范》(docs/zh-CN/standards/api-response.md)与《发送方法规范》(docs/zh-CN/standards/send-method-spec.md)。

多账户受理(4.6.1 起)

  • 所有事件注入 self.account_id(来源账户名);access_token 登录账户在 user_id 为空时也能正确完成多账户受理与事件回路由

错误码规范化(4.6.x)

  • 媒体上传/下载失败与请求超时统一 33001(网络错误)
  • 平台 API 失败统一 34100(平台错误),Matrix errcode 保留在 message 与 matrix_raw 字段
  • 撤回上下文缺失 10003:delete_message 未找到消息归属上下文时返回参数错误
retcode 说明
0 成功
10002 不支持的动作(如 get_friend_list,Matrix 无好友概念)
10003 发送目标无效(无法解析为 Matrix 房间)、撤回上下文缺失
33001 网络错误(媒体上传/下载失败、请求超时)
34100 平台 API 失败(Matrix errcode 保留在 message 与 matrix_raw)

Send 规范

  • Send 全方法读取 send_context:事件链内自动使用当前事件来源账户,显式 Using() 指定的账户优先
  • HTML 方法:.Html(html, fallback) 发送富文本消息;HTML 为规范拼写别名(Html 保留兼容既有模块)
  • get_group_list 返回每项补齐 group_name 字段(与 get_group_info 一致)

标准Api动作示例

from ErisPulse import sdk
matrix = sdk.adapter.get("matrix")
result = await matrix.Api.get_self_info()            # /account/whoami
result = await matrix.Api.get_group_info(room_id)    # m.room.name
result = await matrix.Api.get_group_list()           # /joined_rooms(每项含 group_name)
await matrix.Api.delete_message(event_id)            # redact(登记表补全 room_id)

已对接平台能力

  • 事件:消息(m.room.message:文本/图片/文件/音视频/回复/编辑)、成员增减(m.room.member)、房间名称变更等状态事件
  • 会话:私聊(DM 房间自动发现)/ 群组(房间);发送支持 Text/Image/File/Voice/Video/Markdown/Raw_ob12
  • API:whoami/profile/joined_rooms/房间状态/成员列表/leave/redact(见上方 Api DSL)

支持的消息发送类型

所有发送方法均通过链式语法实现,例如:

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

await matrix.Send.To("group", room_id).Text("Hello World!")

支持的发送类型包括:

  • .Text(text: str):发送纯文本消息。
  • .Image(file: bytes | str):发送图片消息,支持文件路径、URL、MXC URI、二进制数据。
  • .Voice(file: bytes | str):发送语音消息,支持文件路径、URL、MXC URI、二进制数据。
  • .Video(file: bytes | str):发送视频消息,支持文件路径、URL、MXC URI、二进制数据。
  • .File(file: bytes | str, filename: str = ""):发送文件消息,支持文件路径、URL、MXC URI、二进制数据。
  • .Notice(text: str):发送通知消息(Matrix的 m.notice 类型)。
  • .Html(html: str, fallback: str = ""):发送HTML格式消息,支持富文本内容(HTML 为规范拼写别名)。
  • .MergeForward(nodes, title="合并聊天记录"):发送合并转发消息(formatted_body blockquote 引用块形态;白名单会剥离 details/内联样式)。
  • .Raw_ob12(message: List[Dict], **kwargs):发送 OneBot12 格式消息。

链式修饰方法(可组合使用)

链式修饰方法返回 self,支持链式调用,必须在最终发送方法前调用:

  • .Reply(message_id: str):回复指定消息(通过 Matrix m.in_reply_to 关系)。
  • .At(user_id: str):@指定用户(通过 Matrix m.mentions 字段实现)。
  • .AtAll():@房间内所有人(通过 Matrix @room 提及实现)。

链式调用示例

# 基础发送("user" 目标支持用户 ID(@user:server,自动反查 DM 房间)或房间 ID(!room:server))
await matrix.Send.To("user", "@alice:matrix.org").Text("Hello")

# 回复消息
await matrix.Send.To("group", room_id).Reply("$event_id").Text("回复消息")

# @用户
await matrix.Send.To("group", room_id).At("@user:matrix.org").Text("你好")

# @所有人
await matrix.Send.To("group", room_id).AtAll().Text("公告通知")

# 组合使用:回复 + @
await matrix.Send.To("group", room_id).Reply("$event_id").At("@user:matrix.org").Text("复合消息")

# 发送HTML消息
await matrix.Send.To("group", room_id).Html("<h1>标题</h1><p>内容</p>", fallback="标题\n内容")

# 发送通知消息
await matrix.Send.To("group", room_id).Notice("系统通知")

OneBot12消息支持

适配器支持发送 OneBot12 格式的消息,便于跨平台消息兼容:

# 发送 OneBot12 格式消息
ob12_msg = [{"type": "text", "data": {"text": "Hello"}}]
await matrix.Send.To("user", dm_room_id).Raw_ob12(ob12_msg)

# 配合链式修饰
ob12_msg = [{"type": "text", "data": {"text": "回复消息"}}]
await matrix.Send.To("group", room_id).Reply("$event_id").Raw_ob12(ob12_msg)

# 复杂消息
ob12_msg = [
    {"type": "text", "data": {"text": "看这张图片:"}},
    {"type": "image", "data": {"file": "https://example.com/image.png"}},
    {"type": "text", "data": {"text": "不错吧?"}}
]
await matrix.Send.To("group", room_id).Raw_ob12(ob12_msg)

# 位置消息(标准 location 段 → Matrix m.location;与文本共存时拆分为独立事件)
ob12_msg = [
    {"type": "text", "data": {"text": "我在这里"}},
    {"type": "location", "data": {"latitude": 39.9, "longitude": 116.4, "title": "北京市"}}
]
await matrix.Send.To("group", room_id).Raw_ob12(ob12_msg)

发送方法返回值

所有发送方法均返回一个 Task 对象,可以直接 await 获取发送结果。返回结果遵循 ErisPulse 适配器标准化返回规范:

{
    "status": "ok",           // 执行状态: "ok" 或 "failed"
    "retcode": 0,             // 返回码
    "data": {...},            // 响应数据
    "message_id": "$event_id", // Matrix事件ID
    "message": "",            // 错误信息
    "matrix_raw": {...}       // 原始响应数据
}

错误码规范见上文标准化对齐章节。

特有事件类型

需要 platform=="matrix" 检测再使用本平台特性

核心差异点

  1. 去中心化架构:Matrix 是一个去中心化的通信协议,用户ID格式为 @user:server.domain,房间ID格式为 !room_id:server.domain
  2. 房间概念:Matrix 不区分群聊和私聊,所有会话都是"房间"。适配器通过 DM(Direct Message)账户数据自动识别私聊房间
  3. Long Polling 同步:使用 /sync API 进行长轮询获取新事件,而非 WebSocket
  4. MXC URI:媒体文件通过 mxc://server.domain/media_id 格式引用
  5. HTML 富文本:支持通过 formatted_body 发送 HTML 格式消息
  6. 表情回应:支持消息级别的表情回应(Reaction),区别于传统的回复消息
  7. 消息编辑:支持通过 m.replace 关系编辑已发送的消息
  8. 消息撤回:支持通过 m.room.redaction 撤回/删除消息

扩展字段

  • 所有特有字段均以 matrix_ 前缀标识
  • 保留原始数据在 matrix_raw 字段
  • matrix_raw_type 标识原始Matrix事件类型(如 m.room.message、m.room.member)

特殊字段示例

# 群组消息
{
  "type": "message",
  "detail_type": "group",
  "user_id": "@user:matrix.org",
  "group_id": "!room_id:matrix.org",
  "matrix_room_id": "!room_id:matrix.org"
}

# 私聊消息
{
  "type": "message",
  "detail_type": "private",
  "user_id": "@user:matrix.org",
  "matrix_room_id": "!dm_room_id:matrix.org"
}

# 表情回应
{
  "type": "notice",
  "detail_type": "matrix_reaction",
  "matrix_reaction_event_id": "$reacted_msg_id",
  "matrix_reaction_key": "👍"
}

# 消息撤回
{
  "type": "notice",
  "detail_type": "matrix_redaction",
  "matrix_redacted_event_id": "$deleted_msg_id"
}

# 消息编辑
{
  "type": "message",
  "detail_type": "group",
  "matrix_edit": true,
  "matrix_original_event_id": "$original_event_id"
}

# 线程消息
{
  "type": "message",
  "detail_type": "group",
  "thread_id": "$thread_root_id"
}

消息段类型

Matrix消息根据 msgtype 自动转换为对应的消息段:

msgtype 转换类型 说明
m.text text 文本消息
m.notice text 通知消息
m.emote text 动作消息
m.image image 图片消息
m.audio audio 音频消息(标准消息段名为 audio;voice 是发送方法名,不是段名)
m.video video 视频消息
m.file file 文件消息
m.location location 位置消息(latitude/longitude 由 geo URI 解析)

提及(mention):消息 content 中的 m.mentions(Matrix v1.11+ 规范)会转换为标准 mention 段—— m.mentions.user_ids → mention(user_id=...),m.mentions.room → mention(user_id="all")。

消息段结构示例:

// 文本消息(带HTML)
{
  "type": "text",
  "data": {
    "text": "纯文本内容",
    "html": "<b>HTML内容</b>"
  }
}

// 图片消息
{
  "type": "image",
  "data": {
    "url": "mxc://matrix.org/abc123",
    "filename": "photo.png",
    "matrix_mxc": "mxc://matrix.org/abc123",
    "info": {
      "mimetype": "image/png",
      "w": 800,
      "h": 600,
      "size": 123456
    }
  }
}

// 位置消息(latitude/longitude 从 geo URI 解析)
{
  "type": "location",
  "data": {
    "latitude": 39.9,
    "longitude": 116.4,
    "matrix_geo_uri": "geo:39.9,116.4",
    "text": "北京市"
  }
}

Event Mixin 方法

MatrixAdapter 注册了以下事件混入方法,可在事件处理中直接调用:

方法 返回类型 说明
get_room_id() str 获取房间ID
get_matrix_event_type() str 获取原始Matrix事件类型
get_matrix_sender() str 获取原始发送者ID
get_reaction_key() str 获取回应表情
is_edited() bool 判断消息是否为编辑消息
is_notice() bool 判断消息是否为 m.notice 类型
@message.on_message()
async def handle_message(event):
    if event.get("platform") != "matrix":
        return

    room_id = event.get_room_id()
    event_type = event.get_matrix_event_type()
    sender = event.get_matrix_sender()
    is_edited = event.is_edited()
    is_notice = event.is_notice()

Sync API 连接

同步流程

  1. 使用 access_token 或 user_id + password 进行认证
  2. 调用 /_matrix/client/v3/account/whoami 获取 bot_user_id
  3. 发出 connect 元事件
  4. 执行初始同步(/_matrix/client/v3/sync?timeout=0)获取 next_batch token
  5. 发现 DM 房间(/_matrix/client/v3/user/{user_id}/account_data/m.direct)
  6. 开始 Long Polling 同步循环(/_matrix/client/v3/sync?since={next_batch}&timeout=30000)
  7. 处理每次同步返回的新事件并转换发出

心跳机制

  • 适配器每 30 秒发出一次 heartbeat 元事件
  • 连接成功时发出 connect 元事件
  • 关闭时发出 disconnect 元事件

房间邀请

  • 收到房间邀请(invite 状态的房间)时,如果 auto_accept_invites 配置为 true(默认),适配器会自动加入房间
  • 加入房间调用 /_matrix/client/v3/join/{room_id} 接口

端到端加密(E2EE)

适配器自 4.3.0 起原生支持加密房间的端到端加密(基于 matrix-nio[e2e] / vodozemac),encryption_enabled = true 启用。

工作机制

  • 同步:启用后同步走 nio E2EE 会话,设备密钥上传、一次性密钥补充、to-device 消息(Olm/Megolm 会话密钥分发)全部自动处理;timeline 中的 m.room.encrypted 事件自动解密为明文事件再走统一转换
  • 发送:目标房间为加密房间时自动分享 Megolm 会话并加密载荷;解密失败的事件跳过并记录警告
  • 媒体:加密房间中的媒体上传为端到端加密(m.file.encrypted);接收侧媒体段携带 matrix_encrypted_file(JWK,含 url/key/iv/hashes),下载密文后可通过 MatrixAdapter.decrypt_media(ciphertext, key, iv, sha256) 解密
  • 设备:device_id 自动解析(登录响应 → /whoami → 本地持久化),密码重登复用同一设备;trust_all_devices = true(默认)自动信任未验证设备(bot 场景惯例),false 为严格模式
  • 降级:E2EE 未启用或 matrix-nio 未安装时自动回退明文 REST 路径,行为与旧版完全一致

模块侧接口

  • 事件 Mixin:event.is_encrypted() 判断消息是否来自加密房间
  • 媒体段标记:encrypted: true 与 matrix_encrypted_file(JWK)
  • 解密辅助:MatrixAdapter.decrypt_media(file_bytes, key, iv, hash_value) -> bytes

已知限制

  • 不支持交叉签名(cross-signing)与服务器端密钥备份(room key backup)
  • 本地会话存储目录(store_path,默认 data/matrix/<账户名>)删除后历史消息无法解密
  • 交互式 SAS(emoji)验证暂未支持,计划后续版本提供

使用示例

处理群组消息

from ErisPulse.Core.Event import message
from ErisPulse import sdk

matrix = sdk.adapter.get("matrix")

@message.on_message()
async def handle_group_msg(event):
    if event.get("platform") != "matrix":
        return
    if event.get("detail_type") != "group":
        return

    text = event.get_text()
    room_id = event.get("group_id")

    if text == "hello":
        await matrix.Send.To("group", room_id).Reply(
            event.get("message_id")
        ).Text("Hello!")

处理表情回应

from ErisPulse.Core.Event import notice

@notice.on_notice()
async def handle_reaction(event):
    if event.get("platform") != "matrix":
        return

    if event.get("detail_type") == "matrix_reaction":
        reaction_key = event.get("matrix_reaction_key")
        reacted_event_id = event.get("matrix_reaction_event_id")
        room_id = event.get_room_id()
        # 处理表情回应...

发送媒体消息

# 发送图片(URL)
await matrix.Send.To("group", room_id).Image("https://example.com/image.png")

# 发送图片(MXC URI)
await matrix.Send.To("group", room_id).Image("mxc://matrix.org/abc123")

# 发送图片(二进制数据)
with open("image.png", "rb") as f:
    image_bytes = f.read()
await matrix.Send.To("group", room_id).Image(image_bytes)

# 发送图片(本地文件路径)
await matrix.Send.To("group", room_id).Image("/path/to/image.png")

# 发送文件(带文件名)
await matrix.Send.To("group", room_id).File("/path/to/document.pdf", filename="文档.pdf")

处理消息编辑

@message.on_message()
async def handle_edited_message(event):
    if event.get("platform") != "matrix":
        return

    if event.is_edited():
        original_id = event.get("matrix_original_event_id")
        # 处理编辑消息...

监听成员变更

@notice.on_notice()
async def handle_member_change(event):
    if event.get("platform") != "matrix":
        return

    detail_type = event.get("detail_type")

    if detail_type == "group_member_increase":
        user_id = event.get("user_id")
        nickname = event.get("user_nickname")
        print(f"用户 {nickname} ({user_id}) 加入了房间")

    elif detail_type == "group_member_decrease":
        user_id = event.get("user_id")
        operator_id = event.get("operator_id")
        print(f"用户 {user_id} 被移除,操作者: {operator_id}")