---

name: robius-matrix-integration description: | 关键：用于 Matrix SDK 与 Makepad 的集成。触发条件： Matrix SDK、sliding sync、MatrixRequest、timeline、 matrix-sdk、matrix client、robrix、matrix room、 Matrix 集成、聊天客户端 risk: unknown source: community

Robius Matrix SDK 集成 Skill

基于 Robrix 和 Moly 代码库的外部 API 与 Makepad 应用集成最佳实践。

源代码库：

• Robrix：Matrix SDK 集成 - sliding sync、timeline 订阅、实时更新
• Moly：OpenAI/LLM API 集成 - SSE 流式传输、MCP 协议、多 provider 支持

何时使用

在以下情况使用此 skill：

• 将 Matrix SDK 与 Makepad 集成
• 使用 Makepad 构建 Matrix 客户端
• 实现 Matrix 功能（房间、timeline、消息）
• 在 UI 中处理 Matrix SDK 异步操作
• 关键词：matrix-sdk、matrix client、robrix、matrix timeline、matrix room、sliding sync

概述

Robrix 使用 matrix-sdk 和 matrix-sdk-ui crate 连接到 Matrix homeserver。关键架构决策：

1. Sliding Sync：使用原生 sliding sync 实现高效的房间列表更新
2. 独立运行时：Tokio 运行时处理 Matrix 操作，Makepad 处理 UI
3. 请求/响应模式：UI 发送请求，接收 action/更新返回
4. 每房间后台任务：每个房间有专用的 timeline 订阅任务

MatrixRequest 模式

Request 枚举定义

/// All async requests that can be made to the Matrix worker task
pub enum MatrixRequest {
    /// Login requests
    Login(LoginRequest),
    Logout { is_desktop: bool },

    /// Timeline operations
    PaginateRoomTimeline {
        room_id: OwnedRoomId,
        num_events: u16,
        direction: PaginationDirection,
    },
    SendMessage {
        room_id: OwnedRoomId,
        message: RoomMessageEventContent,
        replied_to: Option<Reply>,
    },
    EditMessage {
        room_id: OwnedRoomId,
        timeline_event_item_id: TimelineEventItemId,
        edited_content: EditedContent,
    },
    RedactMessage {
        room_id: OwnedRoomId,
        timeline_event_id: TimelineEventItemId,
        reason: Option<String>,
    },

    /// Room operations
    JoinRoom { room_id: OwnedRoomId },
    LeaveRoom { room_id: OwnedRoomId },
    GetRoomMembers {
        room_id: OwnedRoomId,
        memberships: RoomMemberships,
        local_only: bool,
    },

    /// User operations
    GetUserProfile {
        user_id: OwnedUserId,
        room_id: Option<OwnedRoomId>,
        local_only: bool,
    },
    IgnoreUser {
        ignore: bool,
        room_member: RoomMember,
        room_id: OwnedRoomId,
    },

    /// Media operations
    FetchAvatar {
        mxc_uri: OwnedMxcUri,
        on_fetched: fn(AvatarUpdate),
    },
    FetchMedia {
        media_request: MediaRequestParameters,
        on_fetched: OnMediaFetchedFn,
        destination: MediaCacheEntryRef,
        update_sender: Option<crossbeam_channel::Sender<TimelineUpdate>>,
    },

    /// Typing/read indicators
    SendTypingNotice { room_id: OwnedRoomId, typing: bool },
    ReadReceipt { room_id: OwnedRoomId, event_id: OwnedEventId },
    FullyReadReceipt { room_id: OwnedRoomId, event_id: OwnedEventId },

    /// Reactions
    ToggleReaction {
        room_id: OwnedRoomId,
        timeline_event_id: TimelineEventItemId,
        reaction: String,
    },

    /// Subscriptions
    SubscribeToTypingNotices { room_id: OwnedRoomId, subscribe: bool },
    SubscribeToPinnedEvents { room_id: OwnedRoomId, subscribe: bool },
}

提交模式

static REQUEST_SENDER: Mutex<Option<UnboundedSender<MatrixRequest>>> = Mutex::new(None);

/// Submit request from UI thread to async runtime
pub fn submit_async_request(req: MatrixRequest) {
    if let Some(sender) = REQUEST_SENDER.lock().unwrap().as_ref() {
        sender.send(req).expect("BUG: matrix worker task receiver died!");
    }
}

// Usage in UI
submit_async_request(MatrixRequest::SendMessage {
    room_id: room_id.clone(),
    message: RoomMessageEventContent::text_plain(&text),
    replied_to: self.reply_to.take(),
});

Worker 任务处理器

async fn matrix_worker_task(
    mut request_receiver: UnboundedReceiver<MatrixRequest>,
    login_sender: Sender<LoginRequest>,
) -> Result<()> {
    while let Some(request) = request_receiver.recv().await {
        match request {
            MatrixRequest::PaginateRoomTimeline { room_id, num_events, direction } => {
                let (timeline, sender) = {
                    let rooms = ALL_JOINED_ROOMS.lock().unwrap();
                    let Some(room_info) = rooms.get(&room_id) else {
                        continue;  // Room not ready yet
                    };
                    (room_info.timeline.clone(), room_info.update_sender.clone())
                };

                // Spawn dedicated task for this operation
                Handle::current().spawn(async move {