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.orgaccess_token:访问令牌,可从Matrix客户端获取。如果已有 token,直接填写即可user_id:Matrix用户ID(如@bot:matrix.org),与password配合使用进行登录password:Matrix用户密码,用于自动登录获取 access_tokenauto_accept_invites:是否自动接受房间邀请,默认为trueenabled:是否启用该账户(可选,默认为true)encryption_enabled:是否启用端到端加密,默认为falsetrust_all_devices:是否自动信任未验证设备(E2EE),默认为truedevice_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):回复指定消息(通过 Matrixm.in_reply_to关系)。.At(user_id: str):@指定用户(通过 Matrixm.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" 检测再使用本平台特性
核心差异点
- 去中心化架构:Matrix 是一个去中心化的通信协议,用户ID格式为
@user:server.domain,房间ID格式为!room_id:server.domain - 房间概念:Matrix 不区分群聊和私聊,所有会话都是"房间"。适配器通过 DM(Direct Message)账户数据自动识别私聊房间
- Long Polling 同步:使用
/syncAPI 进行长轮询获取新事件,而非 WebSocket - MXC URI:媒体文件通过
mxc://server.domain/media_id格式引用 - HTML 富文本:支持通过
formatted_body发送 HTML 格式消息 - 表情回应:支持消息级别的表情回应(Reaction),区别于传统的回复消息
- 消息编辑:支持通过
m.replace关系编辑已发送的消息 - 消息撤回:支持通过
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 连接
同步流程
- 使用 access_token 或 user_id + password 进行认证
- 调用
/_matrix/client/v3/account/whoami获取 bot_user_id - 发出 connect 元事件
- 执行初始同步(
/_matrix/client/v3/sync?timeout=0)获取next_batchtoken - 发现 DM 房间(
/_matrix/client/v3/user/{user_id}/account_data/m.direct) - 开始 Long Polling 同步循环(
/_matrix/client/v3/sync?since={next_batch}&timeout=30000) - 处理每次同步返回的新事件并转换发出
心跳机制
- 适配器每 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}")