ErisPulse-MatrixAdapter 1.0.0__tar.gz

erispulse_matrixadapter-1.0.0/ErisPulse_MatrixAdapter.egg-info/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: ErisPulse-MatrixAdapter
+Version: 1.0.0
+Summary: ErisPulse的Matrix协议适配模块
+Author-email: wsu2059 <wsu2059@qq.com>
+Project-URL: homepage, https://github.com/ErisPulse/ErisPulse-MatrixAdapter
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.8.0
+
+# MatrixAdapter 模块文档
+
+## 简介
+MatrixAdapter 是基于 [ErisPulse](https://github.com/ErisPulse/ErisPulse/) 架构的 Matrix 协议适配器，通过 Long Polling Sync API 接收事件，整合了私聊、群组等多种场景的功能模块，提供统一的事件处理和消息操作接口。
+
+## 使用示例
+
+### OneBot12标准事件类型
+
+MatrixAdapter 适配器完全兼容 OneBot12 标准事件格式，并提供了一些扩展字段：
+
+| 事件类型 | detail_type | 说明 |
+|----------|-------------|------|
+| 消息事件（私聊） | private | DM房间中用户发送的消息 |
+| 消息事件（群组） | group | 群组房间中用户发送的消息 |
+| 群成员增加 | group_member_increase | 用户加入房间 |
+| 群成员减少 | group_member_decrease | 用户离开/被封禁 |
+| 成员信息更新 | matrix_member_update | 房间成员信息变更 |
+| Matrix表情回应 | matrix_reaction | 消息表情回应 |
+| Matrix消息撤回 | matrix_redaction | 消息被撤回/删除 |
+| Matrix房间名称变更 | matrix_name | 房间名称变更 |
+| Matrix房间话题变更 | matrix_topic | 房间话题变更 |
+| Matrix房间头像变更 | matrix_avatar | 房间头像变更 |
+| Matrix权限等级变更 | matrix_power_levels | 房间权限变更 |
+
+---
+
+## 消息发送示例
+
+```python
+from ErisPulse import sdk
+matrix = sdk.adapter.get("matrix")
+
+# 发送文本消息
+await matrix.Send.To("group", room_id).Text("Hello World!")
+
+# 发送带@的消息
+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").Text("回复内容")
+
+# 发送图片（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_data = f.read()
+await matrix.Send.To("group", room_id).Image(image_data)
+
+# 发送图片（本地文件路径）
+await matrix.Send.To("group", room_id).Image("/path/to/image.png")
+
+# 发送通知消息（m.notice）
+await matrix.Send.To("group", room_id).Notice("系统通知")
+
+# 发送HTML格式消息
+await matrix.Send.To("group", room_id).Html("<b>加粗</b> <i>斜体</i>", fallback="加粗 斜体")
+
+# 发送文件（带文件名）
+await matrix.Send.To("group", room_id).File("/path/to/file.pdf", filename="文档.pdf")
+
+# 组合使用：回复 + @
+await matrix.Send.To("group", room_id).Reply("$event_id").At("@user:matrix.org").Text("复合消息")
+
+# 使用 Raw_ob12 发送 OneBot12 格式消息
+message = [
+    {"type": "text", "data": {"text": "第一行"}},
+    {"type": "image", "data": {"file": "https://example.com/img.jpg"}},
+    {"type": "text", "data": {"text": "第二行"}}
+]
+await matrix.Send.To("group", room_id).Raw_ob12(message)
+```
+
+---
+
+### 配置说明
+
+首次运行会自动生成默认配置。
+
+```toml
+# config.toml
+[Matrix_Adapter]
+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）
+```
+
+**配置项说明：**
+- `homeserver`：Matrix服务器地址（必填），默认为 `https://matrix.org`
+- `access_token`：访问令牌，可从Matrix客户端（如 Element）的设置中获取
+- `user_id`：Matrix用户ID（如 `@bot:matrix.org`），与 `password` 配合使用
+- `password`：Matrix用户密码，用于自动登录获取 access_token
+- `auto_accept_invites`：是否自动接受房间邀请，默认为 `true`
+
+**认证方式：**
+- 方式一（推荐）：直接提供 `access_token`
+- 方式二：提供 `user_id` 和 `password`，适配器会自动调用登录接口获取 token
+
+---
+
+## Matrix平台特有功能
+
+请参考 [Matrix平台特性文档](platform-features.md) 了解Matrix平台的特有功能，包括去中心化架构、房间概念、Long Polling同步、MXC URI、HTML富文本、表情回应、消息编辑、扩展字段说明等内容。
+
+详细的事件转换对照请参考 [转换对照文档](CoverToOnebot12.md)。
+
+## 事件监听示例
+
+### 使用 Event 模块（推荐）
+
+```python
+from ErisPulse.Core.Event import message, notice
+
+@message.on_message()
+async def handle_message(event):
+    if event["platform"] == "matrix":
+        detail_type = event["detail_type"]
+        if detail_type == "private":
+            # 处理私聊消息
+            pass
+        elif detail_type == "group":
+            # 处理群组消息
+            pass
+
+@notice.on_notice()
+async def handle_notice(event):
+    if event["platform"] == "matrix":
+        detail_type = event["detail_type"]
+        if detail_type == "matrix_reaction":
+            # 处理表情回应
+            reaction_key = event.get("matrix_reaction_key", "")
+        elif detail_type == "matrix_redaction":
+            # 处理消息撤回
+            redacted_id = event.get("matrix_redacted_event_id", "")
+        elif detail_type == "group_member_increase":
+            # 处理成员加入
+            user_id = event.get("user_id", "")
+```
+
+### 使用 OneBot12 标准事件
+
+```python
+@sdk.adapter.on("message")
+async def handle_message(event):
+    if event["platform"] == "matrix":
+        bot_id = event["self"]["user_id"]
+        print(f"消息来自Bot: {bot_id}")
+
+@sdk.adapter.on("notice")
+async def handle_notice(event):
+    if event["platform"] == "matrix":
+        # 处理Matrix通知事件
+        pass
+```
+
+### 使用 Event Mixin 方法
+
+```python
+@message.on_message()
+async def handle_message(event):
+    if event.get("platform") != "matrix":
+        return
+
+    room_id = event.get_room_id()           # 获取房间ID
+    event_type = event.get_matrix_event_type()  # 获取原始Matrix事件类型
+    sender = event.get_matrix_sender()      # 获取发送者ID
+    is_edited = event.is_edited()           # 是否为编辑消息
+    is_notice = event.is_notice()           # 是否为 m.notice 类型
+```
+
+## 注意事项：
+
+1. 确保在调用 `startup()` 前完成所有处理器的注册
+2. Matrix 是去中心化协议，用户ID格式为 `@user:server.domain`，房间ID格式为 `!room_id:server.domain`
+3. Matrix 不区分群聊和私聊，所有会话都是"房间"。适配器通过 DM 账户数据自动识别私聊
+4. 适配器使用 Long Polling（`/sync` API）获取事件，而非 WebSocket
+5. 媒体文件通过 `mxc://` URI 引用，适配器支持自动上传和下载
+6. 程序退出时请调用 `shutdown()` 确保资源释放
+7. 支持自动接受房间邀请（可通过 `auto_accept_invites` 配置关闭）
+8. 支持发送 HTML 格式消息，使用 `.Html()` 方法
+9. 支持消息回复（`.Reply()`）和用户提及（`.At()`、`.AtAll()`）
+
+---
+
+### 参考链接
+
+- [ErisPulse 主库](https://github.com/ErisPulse/ErisPulse/)
+- [Matrix 协议规范](https://spec.matrix.org/)
+- [Matrix Client-Server API](https://spec.matrix.org/v1.11/client-server-api/)
+- [模块开发指南](https://www.erisdev.com/#docs/developer-guide/README.md)

erispulse_matrixadapter-1.0.0/ErisPulse_MatrixAdapter.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+ErisPulse_MatrixAdapter.egg-info/PKG-INFO
+ErisPulse_MatrixAdapter.egg-info/SOURCES.txt
+ErisPulse_MatrixAdapter.egg-info/dependency_links.txt
+ErisPulse_MatrixAdapter.egg-info/entry_points.txt
+ErisPulse_MatrixAdapter.egg-info/requires.txt
+ErisPulse_MatrixAdapter.egg-info/top_level.txt
+MatrixAdapter/Converter.py
+MatrixAdapter/Core.py
+MatrixAdapter/__init__.py
+test/test.py

erispulse_matrixadapter-1.0.0/ErisPulse_MatrixAdapter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

erispulse_matrixadapter-1.0.0/ErisPulse_MatrixAdapter.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[erispulse.adapter]
+matrix = MatrixAdapter:MatrixAdapter

erispulse_matrixadapter-1.0.0/ErisPulse_MatrixAdapter.egg-info/requires.txt

@@ -0,0 +1 @@
+aiohttp>=3.8.0

erispulse_matrixadapter-1.0.0/ErisPulse_MatrixAdapter.egg-info/top_level.txt

@@ -0,0 +1 @@
+MatrixAdapter

erispulse_matrixadapter-1.0.0/MatrixAdapter/Converter.py

@@ -0,0 +1,284 @@
+import time
+import uuid
+from typing import Dict, Optional, List
+
+
+class MatrixConverter:
+    def __init__(self, bot_user_id: str = ""):
+        self.bot_user_id = bot_user_id
+        self._dm_rooms: Dict[str, str] = {}
+
+    def set_dm_rooms(self, dm_rooms: Dict[str, str]):
+        self._dm_rooms = dm_rooms
+
+    def convert(self, raw_event: Dict, room_id: str = "", is_dm: bool = False) -> Optional[Dict]:
+        if not isinstance(raw_event, dict):
+            return None
+
+        event_type = raw_event.get("type", "")
+        event_id = raw_event.get("event_id", str(uuid.uuid4()))
+
+        origin_server_ts = raw_event.get("origin_server_ts", 0)
+        if origin_server_ts:
+            if origin_server_ts > 10**12:
+                event_time = int(origin_server_ts / 1000)
+            else:
+                event_time = int(origin_server_ts)
+        else:
+            event_time = int(time.time())
+
+        sender = raw_event.get("sender", "")
+        if sender == self.bot_user_id:
+            return None
+
+        base_event = {
+            "id": event_id,
+            "time": event_time,
+            "type": "",
+            "detail_type": "",
+            "platform": "matrix",
+            "self": {
+                "platform": "matrix",
+                "user_id": self.bot_user_id,
+            },
+            "matrix_raw": raw_event,
+            "matrix_raw_type": event_type,
+        }
+
+        if is_dm:
+            base_event["detail_type"] = "private"
+        else:
+            base_event["detail_type"] = "group"
+
+        handler = getattr(self, f"_handle_{event_type.replace('.', '_')}", None)
+        if handler:
+            return handler(raw_event, base_event, room_id, is_dm)
+
+        if event_type.startswith("m.room."):
+            return self._handle_m_room_generic(raw_event, base_event, room_id, is_dm)
+
+        return self._create_unknown_event(raw_event, event_id, event_type)
+
+    def _handle_m_room_message(self, raw_event: Dict, base_event: Dict, room_id: str, is_dm: bool) -> Dict:
+        base_event["type"] = "message"
+        base_event["user_id"] = raw_event.get("sender", "")
+        base_event["user_nickname"] = raw_event.get("sender", "")
+
+        content = raw_event.get("content", {})
+        msgtype = content.get("msgtype", "m.text")
+
+        message_segments = self._parse_message_content(content, raw_event)
+        alt_message = self._generate_alt_message(message_segments)
+
+        base_event["message"] = message_segments
+        base_event["alt_message"] = alt_message
+
+        if room_id:
+            base_event["matrix_room_id"] = room_id
+            if is_dm:
+                pass
+            else:
+                base_event["group_id"] = room_id
+
+        relates_to = content.get("m.relates_to", {})
+        if relates_to:
+            rel_type = relates_to.get("rel_type", "")
+            if rel_type == "m.in_reply_to":
+                reply_event_id = relates_to.get("event_id", "")
+                if reply_event_id:
+                    reply_seg = {"type": "reply", "data": {"message_id": reply_event_id}}
+                    base_event["message"].insert(0, reply_seg)
+            elif rel_type == "m.thread":
+                base_event["thread_id"] = relates_to.get("event_id", "")
+
+        new_content = content.get("m.new_content")
+        if new_content:
+            base_event["matrix_edit"] = True
+            base_event["matrix_original_event_id"] = relates_to.get("event_id", "")
+
+        return base_event
+
+    def _handle_m_room_member(self, raw_event: Dict, base_event: Dict, room_id: str, is_dm: bool) -> Dict:
+        base_event["type"] = "notice"
+        base_event["user_id"] = raw_event.get("sender", "")
+        base_event["user_nickname"] = raw_event.get("sender", "")
+
+        content = raw_event.get("content", {})
+        prev_content = raw_event.get("unsigned", {}).get("prev_content", {})
+        membership = content.get("membership", "")
+        prev_membership = prev_content.get("membership", "")
+
+        state_key = raw_event.get("state_key", "")
+        target_user = state_key
+
+        if membership == "join" and prev_membership != "join":
+            base_event["detail_type"] = "group_member_increase"
+            base_event["user_id"] = target_user
+            displayname = content.get("displayname", target_user)
+            base_event["user_nickname"] = displayname
+            base_event["operator_id"] = raw_event.get("sender", "")
+            base_event["group_id"] = room_id
+            base_event["matrix_room_id"] = room_id
+        elif membership in ("leave", "ban") and prev_membership == "join":
+            base_event["detail_type"] = "group_member_decrease"
+            base_event["user_id"] = target_user
+            base_event["user_nickname"] = content.get("displayname", target_user)
+            base_event["operator_id"] = raw_event.get("sender", "")
+            base_event["group_id"] = room_id
+            base_event["matrix_room_id"] = room_id
+        else:
+            base_event["detail_type"] = "matrix_member_update"
+            base_event["user_id"] = target_user
+            base_event["group_id"] = room_id
+            base_event["matrix_room_id"] = room_id
+            base_event["matrix_membership"] = membership
+
+        return base_event
+
+    def _handle_m_reaction(self, raw_event: Dict, base_event: Dict, room_id: str, is_dm: bool) -> Dict:
+        base_event["type"] = "notice"
+        base_event["detail_type"] = "matrix_reaction"
+        base_event["user_id"] = raw_event.get("sender", "")
+        base_event["matrix_room_id"] = room_id
+        if not is_dm:
+            base_event["group_id"] = room_id
+
+        content = raw_event.get("content", {})
+        relates_to = content.get("m.relates_to", {})
+        base_event["matrix_reaction_event_id"] = relates_to.get("event_id", "")
+        base_event["matrix_reaction_key"] = relates_to.get("key", "")
+
+        return base_event
+
+    def _handle_m_room_redaction(self, raw_event: Dict, base_event: Dict, room_id: str, is_dm: bool) -> Dict:
+        base_event["type"] = "notice"
+        base_event["detail_type"] = "matrix_redaction"
+        base_event["user_id"] = raw_event.get("sender", "")
+        base_event["matrix_room_id"] = room_id
+        if not is_dm:
+            base_event["group_id"] = room_id
+
+        redacts = raw_event.get("redacts", "")
+        base_event["matrix_redacted_event_id"] = redacts
+
+        return base_event
+
+    def _handle_m_room_generic(self, raw_event: Dict, base_event: Dict, room_id: str, is_dm: bool) -> Dict:
+        event_type = raw_event.get("type", "")
+        base_event["type"] = "notice"
+        base_event["detail_type"] = f"matrix_{event_type.replace('.', '_').replace('m_room_', '')}"
+        base_event["user_id"] = raw_event.get("sender", "")
+        base_event["matrix_room_id"] = room_id
+        if not is_dm:
+            base_event["group_id"] = room_id
+
+        return base_event
+
+    def _parse_message_content(self, content: Dict, raw_event: Dict) -> List[Dict]:
+        segments = []
+        msgtype = content.get("msgtype", "m.text")
+        body = content.get("body", "")
+        formatted_body = content.get("formatted_body", "")
+
+        if msgtype in ("m.text", "m.notice", "m.emote"):
+            seg_data = {"text": body}
+            if formatted_body:
+                seg_data["html"] = formatted_body
+            segments.append({"type": "text", "data": seg_data})
+
+        elif msgtype == "m.image":
+            url = content.get("url", "")
+            segments.append({
+                "type": "image",
+                "data": {
+                    "url": url,
+                    "filename": body,
+                    "matrix_mxc": url,
+                    "info": content.get("info", {}),
+                },
+            })
+
+        elif msgtype == "m.audio":
+            url = content.get("url", "")
+            segments.append({
+                "type": "voice",
+                "data": {
+                    "url": url,
+                    "filename": body,
+                    "matrix_mxc": url,
+                    "info": content.get("info", {}),
+                },
+            })
+
+        elif msgtype == "m.video":
+            url = content.get("url", "")
+            segments.append({
+                "type": "video",
+                "data": {
+                    "url": url,
+                    "filename": body,
+                    "matrix_mxc": url,
+                    "info": content.get("info", {}),
+                },
+            })
+
+        elif msgtype == "m.file":
+            url = content.get("url", "")
+            segments.append({
+                "type": "file",
+                "data": {
+                    "url": url,
+                    "filename": body,
+                    "matrix_mxc": url,
+                    "info": content.get("info", {}),
+                },
+            })
+
+        elif msgtype == "m.location":
+            geo_uri = content.get("geo_uri", "")
+            segments.append({
+                "type": "location",
+                "data": {
+                    "latitude": 0.0,
+                    "longitude": 0.0,
+                    "matrix_geo_uri": geo_uri,
+                    "text": body,
+                },
+            })
+
+        return segments
+
+    def _create_unknown_event(self, raw_event: Dict, event_id: str, event_type: str) -> Dict:
+        return {
+            "id": event_id,
+            "time": int(time.time()),
+            "type": "unknown",
+            "detail_type": "unknown",
+            "platform": "matrix",
+            "self": {"platform": "matrix", "user_id": self.bot_user_id},
+            "matrix_raw": raw_event,
+            "matrix_raw_type": event_type,
+            "warning": f"Unsupported event type: {event_type}",
+            "alt_message": "This event type is not supported by this system.",
+        }
+
+    def _generate_alt_message(self, segments: List[Dict]) -> str:
+        parts = []
+        for seg in segments:
+            seg_type = seg["type"]
+            data = seg.get("data", {})
+            if seg_type == "text":
+                parts.append(data.get("text", ""))
+            elif seg_type == "image":
+                parts.append("[图片]")
+            elif seg_type == "voice":
+                parts.append("[语音]")
+            elif seg_type == "video":
+                parts.append("[视频]")
+            elif seg_type == "file":
+                parts.append(f"[文件:{data.get('filename', '')}]")
+            elif seg_type == "location":
+                parts.append("[位置]")
+            elif seg_type == "reply":
+                parts.append("[回复]")
+        return " ".join(parts).strip()