使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

截至 2026 年 10 月 10 日,PyPI 上列出了 Simple-Matrix-Bot-Lib 2.13.1 版本,發佈於 2026 年 3 月 29 日。該軟體包需要 Python 3.9 或更高版本,但 Python 3.9 已停止維護;請使用該軟體包支援的、維護良好的 Python 版本。託管的專案文件仍顯示版本為 2.11.0,並警告稱其已停止維護,因此本指南遵循 PyPI 上最新的機器人 API 範例,僅使用舊版手冊中明確標註的配置說明。請在 PyPI 上查看軟體包版本和元資料。閱讀項目文檔狀態。

最快捷可靠的配置方案是:一個專用的 Matrix 使用者、一個 Python 虛擬環境,以及一個在測試房間內回應的小型迴聲機器人!echo。此範例適用於未加密的房間;加密房間需要額外的配置。

安裝庫之前需要準備什麼?

在運行機器人的主伺服器上建立或申請一個普通帳號。給它一個獨特的使用者名,例如echo_bot`<your-root>`;它不需要主伺服器管理員權限。註冊功能可能被伺服器停用或限制,因此請遵循其帳號建立政策。僅邀請該帳號加入允許其發送訊息的私人測試房間。

請使用 Python 3.11 或其他目前支援的 Python 分支。雖然軟體包元資料仍然支援 Python 3.9,但 Python.org 已將該分支的生命週期標記為 2025 年 10 月 31 日結束,因此該軟體包的最低版本要求並非理想的部署建議。請參閱Python.org 的 Python 3.9 支援聲明。

如何安裝 Simple-Matrix-Bot-Lib?

請從新建的專案資料夾執行這些命令。虛擬環境可將此機器人的軟體包與其他 Python 專案隔離。版本鎖定確保範例可在本文驗證的最新版本上復現;升級時,請查看當前的 PyPI 版本及其相容性說明。

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "simplematrixbotlib==2.13.1"

.venv\Scripts\Activate.ps1在 Windows PowerShell 中,使用 `--enable-enable`而非 `--enable- enable` 指令啟動環境source。然後建立一個名為 ` bot.py.py` 的檔案。 PyPI 的專案頁面記錄了套件名稱和安裝命令,其發布的範例使用了 `.py` 、`.py` Creds、Bot訊息監聽器和 ` MessageMatch.py`。請參閱目前的 PyPI 使用範例。

使用終端指令建立 Python 虛擬環境、啟動環境並安裝 simplematrixbotlib 版本 2.13.1
終端顯示了機器人專案的隔離環境和已固定的軟體包安裝命令。

如何連接機器人帳號並新增指令?

將以下內容儲存為bot.py. 。啟動時會提示輸入機器人密碼,因此密碼不會寫入原始檔。對於無人值守服務部署,請從作業系統金鑰管理員或受保護的環境變數中讀取金鑰,而不是將其硬編碼。將庫建立的任何會話或存取令牌儲存視為憑證:務必將其保密,並排除在版本控制之外。

import getpass
import simplematrixbotlib as botlib

creds = botlib.Creds(
    homeserver="https://matrix.example.org",
    username="echo_bot",
    password=getpass.getpass("Bot password: "),
)
bot = botlib.Bot(creds)
PREFIX = "!"

@bot.listener.on_message_event
async def echo(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)
    if (match.is_not_from_this_bot()
            and match.prefix()
            and match.command("echo")):
        text = " ".join(match.args())
        reply = text or "Usage: !echo <text>"
        await bot.api.send_text_message(room.room_id, reply)

bot.run()

將範例主伺服器 URL 替換為您的伺服器基本 URL,並使用機器人的帳戶使用者名稱和密碼。監聽器接收房間訊息;MessageMatch確保忽略自身訊息,僅處理!echo指令。 API 呼叫會將剩餘的單字傳回同一房間。這些名稱和方法呼叫遵循庫在 PyPI 上發布的範例。請與 Simple-Matrix-Bot-Lib 快速入門進行比較。

Python 編輯器顯示了匯入語句、getpass 提示字元、Matrix homeserver 和 echo_bot 憑證以及 Bot 初始化資訊。
憑證區塊使用專用帳戶,並提示輸入其密碼,而不是將金鑰放在檔案中。
Python 編輯器顯示了 on_message_event 監聽器、MessageMatch 檢查和 send_text_message 呼叫。
處理程序會忽略機器人本身的訊息,匹配 !echo 命令,並將其參數發送回房間。

如何運行機器人並確認其正常工作?

在已啟動的虛擬環境中,運行:

python bot.py

出現提示時輸入機器人帳號密碼。在測試房間中發送訊息!echo hello。一個運作正常的基本機器人會回覆hello。如果機器人沒有回复,請確認機器人帳號已加入該房間,使用者擁有在該房間發送訊息的權限,主伺服器 URL 正確,並且訊息以正確的!前綴開頭。保持進程運作;關閉其終端將停止此簡單的前台部署。

類似《駭客任務》的測試房間,顯示 @you:example.org 發送 !echo hello,@echo_bot:example.org 回覆 hello。
範例房間對話顯示了 echo 命令的預期請求和回應;這只是一個範例,並非實際測試結果。

此範例無法處理端對端加密的房間訊息。該庫聲稱支援 E2EE,但其目前託管的手冊版本為 2.11.0,可能已過時;該手冊描述了額外的matrix-nio[e2e]依賴項和一個Config.encryption_enabled設定。在啟用加密之前,請務必確認您所安裝版本的確切安裝和驗證步驟。舊版文件還提供了一個join_on_invite設定:僅邀請機器人訪問它應該訪問的房間,如果您的部署需要控制自動加入房間,請檢查此設定。請查閱該庫的 E2EE 和設定手冊。

當機器人保持登入狀態、是測試房間的成員並能做出!echo hello正確回答時,設定即完成hello。在生產環境中,請在進程管理器下執行機器人,並保護其密碼和會話資料。

留下評論

無需猜測即可提高 Synapse 的 Systemd 檔案限制

無需猜測即可提高 Synapse 的 Systemd 檔案限制

診斷 Synapse 是否達到其每個程序開啟檔案上限,為正確的服務或工作進程設定 systemd drop-in,並驗證即時限制。

元素顯示“解密失敗”?恢復遺失的房間鑰匙

元素顯示“解密失敗”?恢復遺失的房間鑰匙

確定錯誤是否僅限於一個瀏覽器或一個事件,然後使用 Element 的恢復金鑰或受信任的設備,而不會危及您剩餘的加密歷史記錄。

清理舊的 Synapse 訊息和媒體檔案而不遺失數據

使用 Synapse 的歷史記錄和媒體清除 API 或保留設定安全地刪除過期數據,然後驗證完成情況和磁碟空間恢復情況。

使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

安裝目前庫,連接專用 Matrix 帳戶,並運行一個小型 !echo 機器人,該機器人具有更安全的憑證處理和清晰的測試。

使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

設定三個 Mautrix 橋接器,分別進行註冊、登入和測試-避免 Docker 網路、帳號原則和同步方面的意外情況。

無需破壞共用檔案即可回收 Synapse 媒體磁碟空間

尋找 Synapse 儲存空間佔用情況,設定安全媒體保留策略,並在不直接從磁碟刪除檔案的情況下清除遠端快取。

停用不活躍的矩陣用戶,而不刪除房間歷史記錄

停用不活躍的矩陣用戶,而不刪除房間歷史記錄

查看裝置活動,透過管理 API 停用已確認的非活動 Synapse 帳戶,並了解可選的擦除標誌實際刪除了哪些內容。

降低 Matrix Synapse 中的 PostgreSQL 記憶體壓力

找出 PostgreSQL 記憶體消耗是來自查詢工作、共享緩衝區、連接還是維護,然後進行有針對性的、Synapse 安全的變更。

為什麼 Matrix Synapse 會議室加入速度慢——以及需要檢查哪些方面

為什麼 Matrix Synapse 會議室加入速度慢——以及需要檢查哪些方面

在變更 Synapse 設定之前,請追蹤 Matrix 房間加入速度慢的原因,例如遠端 homeserver、聯盟退避、本機資料庫載入或出站傳送佇列。

關閉 Synapse 上的 Matrix 註冊或要求使用邀請令牌

停止在自架 Synapse 伺服器上建立公開帳戶,或保持註冊僅限邀請,並限制註冊令牌的使用次數。