ErisPulse ErisPulse
在互動式文檔中心打開 →
本頁章節
本文為靜態鏡像,內容以互動版為準 在互動式文檔中心打開 →

ErisPulse 文件

ErisPulse 是事件驅動的模組化異步機器人框架——業務程式碼只寫一次,透過適配器部署到 QQ、Telegram、Kook、雲湖等多個平台,插件系統、熱重載與完整開發者工具鏈開箱即用。

第一次使用? 直接看 5 分鐘快速入門 —— 從安裝到運行第一個機器人,一氣呵成。


選擇你的路徑

根據你的目標,選擇對應的學習路徑。每條路徑內部按由淺入深排列。

Important

不需要讀完所有文件。 絕大多數開發者只需按順序讀完 L1 核心五篇 (約 1–2 小時)即可獨立開發 90% 的功能;其餘文件全部是特定場景的按需 查閱資料——遇到對應需求再來翻,每篇開頭都標了"什麼時候需要讀這篇"。

L1 核心五篇:模組開發入門 → 基礎概念 → Event 包裝類 → 配置文件說明 → 異常捕獲

適配器作者另需:適配器開發入門 → 事件轉換器 → SendDSL 詳解

一、我要使用機器人

讓機器人跑起來、裝模組、做配置。

進度 文件 說明
① 上手 5 分鐘快速入門 安裝、初始化、運行 —— 唯一的起步入口
App 直裝 ErisPulse-App 客戶端 官方全平台客戶端:手機 / 電腦圖形介面直接運行與管理,免終端
② 深入 建立第一個機器人 編寫第一個命令處理器
③ 概念 基礎概念 理解適配器/模組/事件的設計
④ 實戰 常見任務示例 存儲、定時任務、權限控制
參考 配置文件說明 · CLI 命令 · 部署指南 按需查閱
參考 平台特性指南 各平台(雲湖/QQ/Telegram…)的差異
選型 選型指南 和 NoneBot2 / AstrBot / LangBot 的比較與遷移

二、我要開發模組 / 適配器

為 ErisPulse 編寫可分發的擴展。

類型 入門 進階
模組開發(推薦) 模組開發入門 核心概念 · Event 包裝類 · 最佳實踐
適配器開發 適配器開發入門 核心概念 · SendDSL 詳解 · 事件轉換器 · 最佳實踐
技術標準 標準規範總覽 適配器開發必須遵循的 會話類型 · 事件轉換 · 發送方法 · API 回應 · 請求操作 規範
測試與排查 模組測試(ErisPulse-Testing) 分發決策鏈排查"命令為什麼沒觸發"
發布 發布與模組商店 將作品發布到 PyPI 和模組商店

三、我要深入理解原理

了解框架內部如何運作。先看架構與 API 參考,再按下面對照表進入專題。

架構與 API 參考

文件 說明
架構概覽 可視化圖表:核心架構、初始化流程、事件處理、生命週期、模組加載策略(含 activate_on 事件驅動懶激活)、本地插件文件夾與模組熱重載架構(支援全部模組來源)
事件系統 五大類事件的完整 API
適配器系統 適配器註冊、啟停、API 調用
核心模組 Storage / Config / Logger / Router 等基礎能力

L2 必讀(寫生產級模組繞不開)

文件 說明
作用域(scope) 三維作用域控制:模組可用性 / 事件准入 / 出站動作限制(含方法級細粒度規則、綁定繼承 merge)
歸屬權(owner)系統 資源歸屬與自動回收:owner 上下文、歸屬資源全景、卸載清理序列、設計邊界與模組作者指南
生命週期管理 生命週期事件系統:模組 / 適配器加載、卸載、重載、禁用時各自該做什麼
互動會話系統 wait_reply 全解、會話定時器(remind/escalate)、多路等待(select)、會話互斥租約、收件箱、消息事務、鏈路追蹤

按場景分組(按需查閱)

分組 文件 不懂首篇會踩的坑
運行啟動 啟動流程與手動控制 · 懶加載 不懂啟動鏈路(Finder / Loader / Manager / Router),模組加載失敗時只能對著日誌干瞪眼
通信連接 模組間通信 · 連接池與廣播 · 路由系統 不懂服務契約(meta.services)白名單,跨模組 module.call 會被 ServiceNotProvidedError 拒絕且不知原因
數據存儲 存儲後端 · SQL 建構 · 網路客戶端 不懂連接失敗冷卻期語義,資料庫抖動時會誤判"框架掛了"(實際是存儲操作快速失敗、冷卻後自動重連)
消息對話 Conversation 多輪對話 · 會話收件箱 · MessageBuilder · 國際化 不懂會話互斥租約,兩個模組同時等同一用戶的回覆會互相踢掉
性能觀測 性能基準與調優 部署前不看基準數字,容量規劃全靠猜;升級後不做回歸對比,性能退化發現不了
灰度影子 影子模組與灰度轉正 不懂五道隔離閘就提前轉正,影子的出站消息會外溢到真實用戶

概念關係總表

分不清哪個子系統管什麼時,按這張表對號入座:

子系統 回答什麼問題 一句話口訣
通信(module-communication) 模組之間怎麼互相調用、怎麼定向發事件? 跨模組走 module.call;對方聲明了 meta.services 就只能調白名單內的方法
權限(scope) 誰能用這個模組、誰能觸發事件、能執行哪些動作? 三道閘——模組綁定、身份准入、出站限制,全部由用戶配置說了算
歸屬(ownership) 模組卸載後,它開的連接、定時器、訂閱去哪了? 誰註冊誰歸屬,卸載即回收,不留懸掛資源
懶加載與休眠(lazy-loading) 模組什麼時候才真正加載、閒置後去哪? activate_on 用到才醒,dormant_after 閒置歸眠
互動(interaction) 怎麼等用戶下一條回覆、多輪收集怎麼寫? wait_reply 等一條、.got() 鏈收多輪,租約保證不打架
影子灰度(shadow) 新版模組怎麼在不妨礙線上的情況下試運行? 影子收副本、出站只記賬,promote 由人確認才轉正
存儲(storage-backends) 數據存哪、後端怎麼換? 同一套存儲 API,sqlite / mysql / postgres 配置切換

四、生態與官方客戶端

官方客戶端 + 按需安裝、即裝即用的生態模組(都不是框架內建功能)。

文件 說明
生態總覽 如何安裝生態模組、為什麼這些不是內建功能
ErisPulse-QvQChat 通用智能體模組:工具循環 / MCP / 長期記憶 / 知識庫,聲明服務的模組自動成為 AI 工具
ErisPulse-ApiMCP 把機器人反向開放為 MCP 工具,讓 Claude 等 AI 客戶端直接操控
ErisPulse-App 官方全平台客戶端(Android / Windows / Linux / macOS):原生介面管理多個實例,手機直接運行,桌面托盤常駐
ErisPulse-Dashboard Web 管理介面 + 視窗註冊 API(模組可向側邊欄註冊自定義頁面)
ErisPulse-Cron 定時任務調度模組:一次性 / 間隔 / Cron 表達式,回調傳參,SQLite 持久化,其他模組可托管定時回調
ErisPulse-Takumi 圖片渲染(HTML / 節點樹 / SVG / 動畫,內置中英文字型)

五、我要為 ErisPulse 貢獻

讓框架更好

文件 說明
為 ErisPulse 貢獻 貢獻方式總覽:文件 / i18n / Bug / 模組 / 適配器
首次貢獻 從 fork 到提交 PR

高級特性版本速查表

做版本兼容判斷、或接手舊專案想知道"這個能力是哪個版本引入的"時,按此表對號入座(以倉庫根 CHANGELOG.md 各版本條目為準)。

版本 引入的能力
2.7 生產化基座:OneBot12 標準化基類(ApiDSL / BaseConverter)、配置熱更新系統化、優雅關閉與 SIGTERM/SIGHUP 信號處理、環境變數配置覆蓋、生命週期回調鉤子、Web 棧懶加載;2.7.1 補配置寫入可靠性與 GC 分代治理
2.8 權限與通信骨架:作用域三維體系(scope)、互動會話基礎設施(租約 / 檢查點 / 消息事務 / 會話收件箱 transcript)、模組間 RPC 協議化(module.call / meta.services 服務契約 / 定向事件 emit(to=))、多後端異步存儲(sqlite / mysql / postgres,連接失敗不阻塞框架)、歸屬權清理、配置註釋保留;2.8.x 後續版本為 CLI 腳手架、子命令等打磨
2.9 「模組開發體驗」主線(EPRFC-2026-001):聲明式命令參數(args= / options=)與命令治理(cooldown= / rate_limit=)、統一依賴注入(Depends)、中間件事件否決權、內建 ORM(自動遷移 + 關係映射)、影子模組灰度轉正、分發決策鏈追蹤與排查診斷、正式支援 Python 3.14
2.10 連接一等資源(connections 註冊表:廣播 / 業務分組 / 跨模組傳遞複用 / 卸載自動回收)、根導入契約(常用 API 全部可 from ErisPulse import)、歸屬權體系補全、收件箱保留策略運行時覆蓋;2.10.2 適配器本地插件目錄(plugins/)+ epsdk create pack + tomlclass 無損配置寫入
2.11(dev) 「改代碼 → 看效果」開發閉環:熱重載預設全量語義(語法預檢 + 代碼身份核對 + 依賴者級聯重導)、懶加載休眠(dormant_after)、適配器代碼級熱重載(sdk.adapter.reload)、.got() 命令流語法糖、epsdk stop / restart 運行時控制
2.12(dev) 生命週期治理與可運維性:嵌套生命週期(ownership.nest())、細粒度熱重載(單模組/單適配器判定,框架源碼變更走進程重啟)、後台任務待發隊列、事件分發鏈帳戶自動綁定(send_context / api_context / request_context 同口徑,多帳戶模組零改動)、跨帳戶重複受理關聯(framework.cross_account_policy)、影子模組 whl 攝取與持久化轉正閉環、容器內 epsdk restart 進程內軟重啟、SendDSL.Location()

開發方式

ErisPulse 支援兩種開發方式:

  • 模組開發(推薦):建立獨立的模組包,透過包管理器安裝,便於分發和管理。
  • 嵌入式開發:直接在專案中編寫處理器,適合快速原型。詳見 快速入門。

其他

獲取幫助

相關連結