架構概覽
Tip
什麼時候需要讀這篇:想搞懂框架在背後做了什麼——一條訊息如何流轉、模組按什麼順序初始化、熱重載時發生了什麼,或排查「框架為什麼這樣表現」時讀。只想寫處理器的話,看 事件處理入門 就夠;不需要則跳過。
一條訊息從使用者發出到機器人回覆,要經過適配器轉換、中間件、作用域過濾、優先級調度好幾道環節;模組也不是啟動時就全部加載。這篇用圖表把這條鏈路畫清楚,並說明每個環節你能干預什麼。
SDK 核心架構
下圖展示了 SDK 的核心模組組成及其關係:
graph TB
SDK["sdk<br/>統一入口"]
SDK --> Event["Event<br/>事件系統"]
SDK --> Lifecycle["Lifecycle<br/>生命週期管理"]
SDK --> Logger["Logger<br/>日誌管理"]
SDK --> Storage["Storage / env<br/>儲存管理"]
SDK --> Config["Config<br/>配置管理"]
SDK --> AdapterMgr["Adapter<br/>適配器管理"]
SDK --> ModuleMgr["Module<br/>模組管理"]
SDK --> Router["Router<br/>路由管理"]
SDK --> Client["Client<br/>HTTP 客戶端"]
Event --> Command["command"]
Event --> Message["message"]
Event --> Notice["notice"]
Event --> Request["request"]
Event --> Meta["meta"]
Event --> Conversation["Conversation<br/>分支 + 持久化"]
AdapterMgr --> BaseAdapter["BaseAdapter"]
BaseAdapter --> P1["雲湖"]
BaseAdapter --> P2["Telegram"]
BaseAdapter --> P3["OneBot11/12"]
BaseAdapter --> PN["..."]
ModuleMgr --> BaseModule["BaseModule"]
BaseModule --> CM["自定義模組"]
BaseAdapter -.-> SendDSL["SendDSL<br/>訊息發送"]
核心模組說明
| 模組 | 說明 |
|---|---|
| Event | 事件系統,提供 command / message / notice / request / meta 五類事件處理,以及 Conversation 多輪對話 |
| Adapter | 適配器管理器,管理多平台適配器的註冊、啟動和關閉 |
| Module | 模組管理器,管理插件的註冊、加載和卸載,支持依賴聲明和拓撲排序 |
| Lifecycle | 生命週期管理器,提供事件驅動的生命週期鈎子 |
| Storage | 基於 SQLite 的鍵值儲存系統,支持通用 SQL 連式查詢 |
| Config | TOML 格式的配置檔案管理 |
| Logger | 模組化日誌系統,支持子日誌器 |
| Router | HTTP/WebSocket 路由管理,透過抽象層封裝底層後端(目前為 FastAPI + Uvicorn),支援裝飾器路由、中間件、分組、限流、CORS |
| Client | 統一 HTTP/WS 客戶端(2.8.0 前為 HttpClient,保留相容別名),透過抽象層封裝底層請求庫(目前為 aiohttp),提供請求統計、重試、日誌、WebSocket 客戶端、ErisPulse 異常體系等功能。客戶端和伺服器 WebSocket 共享 WebSocketConnectionBase 基類 |
初始化流程
下圖展示了 sdk.init() 的完整初始化過程:
flowchart TD
A["sdk.init()"] --> B["準備運行環境"]
B --> B1["載入配置檔案"]
B1 --> B2["設定全域異常處理"]
B2 --> C["適配器 & 模組發現"]
C --> D{"並行加載"}
D --> D1["從 PyPI 加載適配器"]
D --> D2["從 PyPI 加載模組"]
D1 & D2 --> E["註冊適配器"]
E --> E1["啟動適配器"]
E1 --> F["註冊模組"]
F --> F1{"依賴驗證"}
F1 -->|"缺失依賴"| F2["跳過該模組並記錄警告"]
F1 -->|"依賴滿足"| F3["拓撲排序<br/>(Kahn 算法 + 優先級)"]
F3 --> G["按序初始化模組<br/>(實例化 + on_load)"]
F2 --> G
G --> H["啟動路由伺服器"]
H --> K["運行就緒"]
初始化階段詳解
完整的初始化鏈路拆解(Finder / Loader / Manager / Router)、底層入口(
init()/init_task()/init_sync())與手動完整啟動見 啟動流程與手動控制。
事件處理流程
下圖展示了訊息從平台到處理器的完整流轉路徑:
flowchart LR
A["平台原始訊息"] --> B["適配器接收"]
B --> C["轉換為 OneBot12 標準"]
C --> D["adapter.emit()"]
D --> E["執行中間件鏈"]
E --> F{"事件分發"}
F --> G1["command<br/>命令處理器"]
F --> G2["message<br/>訊息處理器"]
F --> G3["notice<br/>通知處理器"]
F --> G4["request<br/>請求處理器"]
F --> G5["meta<br/>元事件處理器"]
G1 & G2 & G3 & G4 & G5 --> H["處理器回調執行"]
H --> I["event.reply()<br/>透過 SendDSL 回覆"]
I --> J["適配器發送至平台"]
事件處理鏈路詳解
上面這張圖是「結果」;下面拆開 adapter.emit() 之後框架在背後做了什麼——這是一條三層分發的鏈路:
sequenceDiagram
participant P as 平台
participant A as 適配器總線層<br/>AdapterManager.emit
participant T as 處理器 Task 層<br/>_dispatch_handler_task
participant E as Event 模組層<br/>_process_event
P->>A: 原生事件
A->>A: 提取 platform/type/detail_type + 原始字段
A->>A: [Recv] 接收日誌
A->>A: lifecycle.adapter.event.receive(最早期鈎子)
A->>A: 處理 self 字段(meta 分支 / Bot 自動註冊)
A->>A: 中間件鏈(串行,可改寫事件資料)
A->>A: 收集 handler(具體類型 + 通配符 *)
A->>A: 身份准入 + 作用域過濾(建立 Task 前,靜默丟棄/跳過)
A->>T: asyncio.create_task(fire-and-forget)
A->>A: lifecycle.adapter.event.dispatched(最末鈎子)
T->>T: 獲取併發信號量(預設上限 64)
T->>E: 調用 Event 模組掛載的處理器
E->>E: lifecycle.event.pre_process
E->>E: ignore_self(訊息事件預設忽略自身)
E->>E: 按優先級分組:高→低、組間串行、組內併發
E->>E: 組內副本執行 + 字段合併(衝突告警)
E->>E: 組後檢查 stop() 阻斷更低優先級
T->>T: 慢日誌(超過 1s 告警,wait_reply 時間白名單)
每一步框架做了什麼、你能干預什麼:
| 階段 | 框架做了什麼 | 你能干預的 |
|---|---|---|
| 接收 | 提取標準字段,保留 {platform}_raw 原始資料;寫 [Recv] 日誌 |
監聽 adapter.event.receive 拿到最早期事件 |
| self 字段 | meta 事件走 connect/disconnect/heartbeat 分支;普通事件自動註冊 Bot 並觸發 adapter.bot.online |
監聽 adapter.bot.online / bot.offline |
| 中間件 | 串行執行,返回值非 None 則替換事件資料 | 註冊中間件改寫/攔截事件 |
| 分發收集 | 先取具體類型 handler,再取 * 通配符 handler |
— |
| 身份維度 | 分發入口按 使用者>會話>Bot>適配器 判定事件收不收(scope.is_identity_allowed),拒絕則整個事件丟棄 |
ErisPulse.scope.identity 綁定 |
| 作用域過濾 | 按模組 owner 判定 scope.is_allowed(會話級>Bot級>平台級),不通過則靜默跳過 |
配置作用域白名單/黑名單 |
| 調度 | 每個匹配 handler 獨立 asyncio.Task,emit() 不等待 handler 完成即返回 |
— |
| 優先級 | 高優先級組先執行;組間串行、組內併發(組內各自持有事件副本,改字段合併回原事件,衝突打 WARNING) | @command(..., priority=N) / 註冊時指定 priority |
| 阻斷 | 每處理完一組檢查 event.is_stopped(),命中則不再執行更低優先級 |
event.mark_processed(stop=True) / event.done() |
常見誤區:
- 作用域過濾是靜默的——被屏蔽的 handler 不報錯不回應,只在 TRACE 級日誌可見(
core.scope.denied)。「我的模組沒收到訊息」優先排查作用域綁定。- handler 天然併發——框架已為每個 handler 建獨立 Task,你不需要再自己
asyncio.create_task包一層。- 同優先級組內不阻斷——
mark_processed(stop=True)只阻止更低優先級組,同組內已併發的 handler 不會中途被打斷。- 慢日誌閾值固定 1 秒——處理器耗時超過 1s 會在日誌打 WARNING(
wait_reply等待時間已從耗時中剔除),但不中斷執行。
作用域(scope)的模組維度三級綁定、身份維度准入與出站動作限制細節見 作用域(scope);事件作用域文字過濾與命令使用者 ACL 見 事件處理入門;併發上限配置見 配置指南。
生命週期事件
下圖展示了框架各組件的生命週期事件觸發順序:
flowchart LR
subgraph Core["核心"]
direction LR
C1["core.init.start"] --> C2["core.init.complete"]
end
subgraph AdapterLife["適配器"]
direction LR
A1["adapter.start"] --> A2["adapter.status.change"] --> A3["adapter.stop"] --> A4["adapter.stopped"]
end
subgraph ModuleLife["模組"]
direction LR
M1["module.load"] --> M2["module.init"] --> M3["module.unload"]
end
subgraph BotLife["Bot"]
direction LR
B1["adapter.bot.online"] --> B2["adapter.bot.offline"]
end
Core --> AdapterLife
AdapterLife --> ModuleLife
AdapterLife -.-> BotLife
監聽生命週期事件
完整的事件監聽方法(
lifecycle.on()/once()/has_handlers())、全部生命週期事件列表與資料格式見 生命週期管理。
模組加載策略
ErisPulse 支援三種模組加載策略,由 get_load_strategy() 返回的 ModuleLoadStrategy 聲明:
flowchart TD
A["模組註冊到 ModuleManager"] --> B{"加載策略"}
B -->|"lazy_load = true<br/>+ activate_on 聲明"| C["建立 ModuleActivator 代理"]
B -->|"lazy_load = true<br/>無 activate_on"| D["建立 LazyModule 代理"]
B -->|"lazy_load = false"| E["立即建立實例"]
C --> F["註冊事件/命令 stub 到分發器"]
F --> G["掛載到 sdk 屬性"]
G --> H["事件到達觸發激活"]
H --> I["實例化 + on_load() + 注銷 stub"]
D --> J["掛載到 sdk 屬性"]
J --> K["首次屬性存取時初始化"]
E --> L["呼叫 on_load()"]
L --> M["掛載到 sdk 屬性"]
事件驅動懶激活(activate_on)觸發架構
Note
本特性需要 ErisPulse **2.8.0+**。
activate_on 允許模組在首個匹配事件/命令到達時才加載,避免常駐記憶體,同時保證事件不丟失:
flowchart LR
subgraph Declare["模組聲明"]
S1["get_load_strategy() 返回<br/>ModuleLoadStrategy(activate_on=...)"] --> S2["activate_on 語法:<br/>str / dict / list 自由混合"]
S2 --> S2a["'message' → 事件類型級"]
S2 --> S2b["{'notice': 'group_member_increase'}<br/>→ 類型 + detail_type"]
S2 --> S2c["{'command': 'roll'}<br/>→ 命令觸發(簡寫/列表)"]
S2 --> S2d["{'command': {'name': 'dice', 'help': ...,<br/>'aliases': [...], 'hidden': ...}}<br/>→ 命令觸發(dict 聲明)"]
end
subgraph Runtime["執行期"]
R1["ModuleActivator 註冊 stub"] --> R1a["事件 stub → message/notice/request/meta 管理器<br/>優先級 ACTIVATION_STUB_PRIORITY(極低)"]
R1 --> R1b["命令 stub → 命令管理器<br/>佔位命令(鏡像 dict 聲明的 help/usage/group/aliases/hidden)"]
R1a --> R2{"觸發事件到達"}
R1b --> R2
R2 --> R3["按 owner 過作用域過濾"]
R3 --> R4["asyncio.Lock 防止重複激活"]
R4 --> R5["實例化模組 + 呼叫 on_load()"]
R5 --> R6["註銷全部 stub"]
R6 --> R7["事件轉發到真實處理器"]
end
Declare --> Runtime
觸發語義要點:
完整的
activate_on語法(str / dict / list)、命令 dict 聲明、佔位命令 help 回退鏈、作用域過濾與失敗語義見 懶加載系統。
本地插件檔案夾架構
Note
本特性需要 ErisPulse **2.8.0+**。
本地插件(plugins/ 目錄)無需打包發布,框架啟動時自動發現並加載:
flowchart TD
A["專案 plugins/ 目錄<br/>(ErisPulse.framework.plugins_dir,支援多目錄)"] --> B{"PluginFolderLoader.discover()"}
B --> C["單檔案:dice.py → 插件名 = 檔案名"]
B --> D["包形式:weather/(含 __init__.py)→ 插件名 = 目錄名"]
B --> E["忽略:__pycache__ / _ 開頭 / 非 .py / 無 __init__.py 目錄"]
C --> F["導入模組(spec_from_file_location)"]
D --> G["導入模組(sys.path + import_module)"]
F --> H["識別模組類:Main(BaseModule 子類)優先,回落首個子類"]
G --> H
H --> I["構造與 entry-point 一致的 moduleInfo"]
I --> J["ModuleLoader.load() 合併<br/>本地優先覆蓋 PyPI 同名安裝包"]
J --> K["與安裝包模組共用:<br/>啟用狀態 / 作用域 / meta / i18n / 上下文"]
約定與特性:
- 插件名來源:單檔案取檔案名,包形式取目錄名
- 本地插件
moduleInfo.meta.source == "plugin_folder",與 PyPI 安裝包模組無縫共存 - 同名時本地優先(便於本地覆蓋調試),被禁用時同時移除同名 entry-point 條目
模組熱重載架構
熱重載對全部模組來源一致:本地插件(plugins/ 目錄)、執行時註冊(sdk.module.register())、PyPI 安裝包模組均可透過 sdk.reload_module() / sdk.module.reload() 熱重載——預設即全量重載(按頂層包名清理 import 緩存並重導依賴者程式碼,full=False 為輕量逃生門);sdk.reload_all_modules() / sdk.module.reload_all() 可一次全量重載所有已註冊模組(pip 批量升級後呼叫即可全部生效):
flowchart TD
A["sdk.enable_plugin_hot_reload()<br/>(自動監控,僅本地插件目錄)"] --> B["PluginReloadWatcher 啟動"]
B --> C["PollingObserver(後台守護執行緒)<br/>定期比較 .py 檔案 mtime"]
C --> D{"插件檔案變更"}
D --> E["變更去抖(預設 1 秒)"]
E --> F["_handle_change 解析插件名<br/>(單檔案 / 包形式)"]
F --> G["asyncio.run_coroutine_threadsafe<br/>調度回主事件迴圈"]
G --> H["sdk.reload_module(name, full=True 預設)<br/>(也可對任意模組手動呼叫)"]
H --> I["語法預檢(逐檔案解析)<br/>失敗即拒絕重載,舊實例繼續服務"]
I --> J["卸載舊實例(on_before_unload → on_unload)<br/>收集依賴者準備級聯重載"]
J --> K{"模組來源?"}
K -->|"plugin_folder"| L["清理註冊與插件 sys.modules<br/>重掃描 plugins/ 目錄"]
K -->|"runtime 執行時註冊"| M["按定義模組清緩存重導<br/>按類名重取(__main__ 守衛)"]
K -->|"PyPI 安裝包"| N["清理註冊 + 按 top_level 清理包<br/>sys.modules 子樹 + __pycache__ 字節碼<br/>(元資料缺失時按舊模組物件頂層段兜底)<br/>刷新導入緩存後重查 entry-point"]
L --> O["重新 register + load"]
M --> O
N --> O
O --> P["掛載新實例到 sdk 屬性<br/>核對新舊類身份(假重載告警)"]
P --> Q["級聯重載依賴者<br/>(插件/執行時完整重載;<br/>PyPI 依賴者預設同樣重導程式碼)"]
L -.->|"檔案已刪除"| R["從加載結果移除"]
M -.->|"定義不可安全重導"| R
N -.->|"entry-point 已消失(已卸載)"| R
三種來源的差異僅在發現階段,預檢、卸載、級聯重載完全一致:
- 本地插件(
moduleInfo.meta.source == "plugin_folder"):清理插件名對應sys.modules後重掃描plugins/目錄;檔案已刪除則從加載結果移除 - 執行時註冊(
source == "runtime"):按定義模組重導、按類名重取並重建註冊;定義於__main__/ 無源檔案的類拒絕重導(守衛告警,避免重執行入口腳本) - PyPI 安裝包:按
meta.top_level清理包的sys.modules子樹,刷新導入緩存(突破 entry-point 60 秒緩存)後重查並重新導入;entry-point 已消失(pip 卸載)則從加載結果移除
預設語義與可靠性保障(2.11):
- reload 即全量重載:預設按頂層包名清理
sys.modules並重導依賴者程式碼;full=False僅按元資料清理、PyPI 依賴者直接重新實例化(超大依賴樹的效能逃生門) - 語法預檢閘門:進入卸載流程之前逐檔案語法解析,失敗即拒絕重載——舊實例未卸載、繼續服務,語法錯誤永遠不會把模組推進「半死狀態」(超大包超過檔案數上限時跳過預檢)
- 緩存兜底:
top_level元資料缺失時按「舊模組物件__name__前綴 → 模組類__module__前綴」兩級推導清理範圍;重載同時清除源檔案字節碼緩存(__pycache__),同秒同長度的小改寫也能生效 - 身份核對:重載成功後斷言新舊類身份變化,未變化(C 扩展等清不掉的緩存)顯式告警並隨
module.reload事件攜帶identity_changed: false;module.get_info()以running_identity/stale字段暴露「註冊版本 ≠ 運行版本」 - 失敗可查:load 失敗現場(異常 + traceback)可經
module.last_error(名字)/get_info()["last_error"]直接查詢,失敗路徑同時清洗該模組 import 緩存——「改完程式碼再 reload 一次」必定讀到新程式碼 - 重載會把原本懶加載的模組強制激活(顯式日誌);
reload_all_modules()則保持懶加載策略、僅將重載前處於已加載態的模組重新激活,歸眠(休眠)中的模組保持歸眠 reload_all_modules()按依賴拓撲序重新加載,單模組失敗僅記錄診斷並跳過(無整體回滾——on_unload 副作用不可撤銷,與單模組熱重載的盡力而為語義一致);重載失敗已回滾的場景同樣如此,日誌會明確提示舊實例處於已收尾狀態
適配器熱重載架構
適配器程式級熱重載(2.11)與模組管線同構:sdk.adapter.reload(平台名) / sdk.reload_adapter(平台名) 對本地插件與 PyPI 安裝包兩種來源執行——
flowchart TD
A["sdk.adapter.reload(平台名)"] --> B["語法預檢(逐檔案解析)<br/>失敗即拒絕重載,舊適配器繼續服務"]
B --> C["快照:adapterInfo / 實例 / 啟動態 /<br/>啟動任務 / bots / sys.modules 條目"]
C --> D["unload(shutdown 即清理:<br/>路由/事件/命令/任務/連線/bot offline + 註銷)"]
D --> E["清緩存:__pycache__ 字節碼 →<br/>sys.modules 子樹 → invalidate_caches<br/>→ finder 緩存 → 插件路徑記錄"]
E --> F{"來源?"}
F -->|"插件目錄"| G["重掃描 plugins/(discover_adapters)"]
F -->|"PyPI 安裝包"| H["重查 entry-point 並重導入<br/>(top_level 清理 + 類 __module__ 兜底)"]
G --> I["重新 register + startup(原運行態)<br/>核對類身份(假重載告警)"]
H --> I
I --> J["adapter.reload 事件<br/>identity_changed / version_old→new / was_started"]
G -.->|"插件已刪除"| K["從加載結果移除"]
H -.->|"entry-point 已消失"| K
I -.->|"失敗"| L["回滾:恢復 sys.modules /<br/>註冊存根 / 實例 / 啟動態"]
與模組管線的差異:
- 適配器無懶加載與依賴級聯:重載不級聯依賴它的其它適配器(僅告警——依賴方經註冊表間接消費,無實例級聯語義)
- 啟動是異步鏈(
startup經_run_adapter派發,含依賴跳過與指數退避重試):啟動暫時失敗不判重載失敗(程式碼已換新),結果經adapter.status.change播報 register()的實例重用陷阱(類同物件則舊實例被復用)由「pyc 清理 + sys.modules 清除 + 身份核對」三件套兜底- 生命週期事件:
adapter.reload(payload 携带adapter_name/success/full/duration_ms/identity_changed/version_old→new/was_started/source)