ErisPulse.sdk 模块
模块概述
ErisPulse SDK 主类
提供统一的 SDK 接口,整合所有核心模块和加载器
提示 example:
from ErisPulse import sdk await sdk.init() await sdk.adapter.startup()
函数列表
_resolve_core(attr: str)
内部方法 动态解析核心模块单例引用
每次访问时通过 import 系统获取最新单例,确保软重启后 SDK 始终 指向当前有效的模块级单例对象。
- attr: 核心属性名
返回值: 对应的单例对象
异常: AttributeError - 当属性名不在核心映射中时
类列表
class SDK
ErisPulse SDK 主类
整合所有核心模块和加载器,提供统一的初始化和管理接口
设计说明: 核心模块属性(adapter, module, router, logger, lifecycle 等) 通过动态解析获取,不缓存在实例上。这确保软重启后 SDK 始终 指向最新的模块级单例,无需手动刷新引用。
提示 SDK 提供以下核心属性:
- Event: 事件系统
- lifecycle: 生命周期管理器
- logger: 日志管理器
- storage: 存储管理器
- env: 存储管理器别名
- config: 配置管理器
- i18n: 国际化管理器
- adapter: 适配器管理器
- BaseAdapter: 适配器基类
- SendDSL: DSL 发送接口基类
- module: 模块管理器
- router: 路由管理器
- client: HTTP 客户端
- master: 框架主人管理器
- scope: 作用域管理器(模块 / 身份 / 出站 三维,"什么范围内生效")
- transcript: 会话收件箱(每会话近期消息流的记录与查询)
- interaction: 交互会话管理器(wait_reply 等待表 / 会话租约 / 按归属取消)
- Event: 事件模块包(command 命令处理器 / message / notice / request 等事件处理器)
- context: 模块上下文管理(owner_scope / get_current_owner / trace-id / 消息事务账本)
方法列表
__init__()
初始化 SDK 实例
不缓存任何核心模块引用。核心属性通过 getattr 动态解析, 确保软重启后始终指向最新的模块级单例。
version -> str(property)
获取当前 ErisPulse 安装版本
每次访问实时查询 importlib.metadata,确保框架热更新后 能读到最新版本(如果框架本身被upgrade)。
返回值 (str): 版本号字符串,未安装时返回 "UnknownVersion"
示例:
print(sdk.version)
'2.6.2'
__dir__() -> list[str]
列出实例属性(含核心模块动态属性)
让 dir(sdk) 与交互式补全反映 __getattr__ 提供的核心模块单例
(scope / command / master / adapter 等)。用类级 dir() 避免
触发 __getattr__ 的递归解析。
返回值: 属性名列表(去重排序)
__getattr__(name: str)
动态解析核心模块属性
当属性不在实例 dict 中时调用。对核心属性名使用动态 import 解析, 确保软重启后始终获取最新单例。对未知属性提供友好的错误提示。
- name: 属性名
返回值: 属性值
异常: AttributeError - 当属性不存在时
__repr__() -> str
返回 SDK 的字符串表示
展示版本、初始化状态、适配器/模块计数,便于调试时一眼查看运行状态。 适配器/模块计数失败时静默降级为只显示版本与初始化状态。
返回值: str SDK 的字符串表示
_start_proactive_gc() -> None
内部方法
启动主动 GC 后台任务(实现见 runtime/proactive_gc.start_proactive_gc)
_stop_proactive_gc() -> None
内部方法
停止主动 GC 后台任务并反注册配置钩子(实现见 runtime/proactive_gc.stop_proactive_gc)
_read_gc_config() -> tuple[float, int, int, int, bool, int](staticmethod)
内部方法
读取并钳制主动 GC 框架配置(实现见 runtime/proactive_gc.read_gc_config)
_on_gc_config_event(_data: dict) -> None
内部方法
proactive_gc_* 配置变更时重启 GC 任务(实现见 runtime/proactive_gc.on_gc_config_event)
_has_handler_backlog() -> bool(staticmethod)
内部方法
事件处理器洪峰检测(实现见 runtime/proactive_gc.has_handler_backlog)
_run_full_gc_collection(gc_module: Any, baseline: float | None, growth_mb: int) -> tuple[int, float | None](staticmethod)
内部方法
执行一次全量回收(实现见 runtime/proactive_gc.run_full_gc_collection)
dump_state() -> dict
导出框架当前运行状态的快照
返回值 (dict): 包含所有子系统状态的字典
async init(*, before_init: Callable[[], Any] | None = None, after_init: Callable[[], Any] | None = None) -> bool
SDK 初始化入口
重复调用保护:若 SDK 已经初始化成功,重复调用不会重新初始化,
会记录一条警告并直接返回 True。如需强制重新初始化,请先
调用 sdk.uninit() 或使用 sdk.restart()。
- before_init: 初始化前回调(同步或异步),在环境准备之前执行
- after_init: 初始化成功后回调(同步或异步),在初始化完成后执行
返回值: bool SDK 初始化是否成功(已初始化时返回 True)
示例:
success = await sdk.init()
if success:
await sdk.adapter.startup()
# 使用回调
async def setup():
print("初始化前")
async def ready():
print("初始化完成")
await sdk.init(before_init=setup, after_init=ready)
async _prepare_environment() -> bool
内部方法 准备运行环境
初始化配置和全局异常处理
返回值 (bool): 环境准备是否成功
init_sync(*, before_init: Callable[[], Any] | None = None, after_init: Callable[[], Any] | None = None) -> bool
SDK 初始化入口(同步版本)
用于命令行直接调用,自动在事件循环中运行异步初始化
- before_init: 初始化前回调(同步或异步)
- after_init: 初始化成功后回调(同步或异步)
返回值: bool SDK 初始化是否成功
init_task(*, before_init: Callable[[], Any] | None = None, after_init: Callable[[], Any] | None = None) -> asyncio.Task | concurrent.futures.Future
SDK 初始化入口,返回 Task 对象
- before_init: 初始化前回调(同步或异步)
- after_init: 初始化成功后回调(同步或异步)
返回值 (asyncio.Task): 初始化任务(在事件循环内调用时);并发 Future
(无运行循环但主循环已注册时,经线程安全方式调度回主循环)
异常: RuntimeError - 当前无运行中的事件循环且主循环未注册——
此前本场景会新建一个永不运行的循环并返回永不完成的悬挂 Task
async load_module(module_name: str) -> bool
手动加载指定模块
- module_name (
str): 要加载的模块名称
返回值 (bool): 加载是否成功
示例:
await sdk.load_module("MyModule")
async run(keep_running: bool = True, *, before_init: Callable[[], Any] | None = None, after_init: Callable[[], Any] | None = None, on_ready: Callable[[], Any] | None = None) -> None
无头模式运行 ErisPulse
内部调用 init() 完成初始化,然后在 on_ready 回调执行完毕后
挂起主程序(当 keep_running=True 时)。
硬重启(hard_restart())通过退出码 42 契约交由外部
监督者(epsdk run / systemd / Docker / PM2 等,见 startup.md
「监督者指南」)重新拉起。
提示 异常处理原则:
- 模块/适配器的任何错误都会被拦截,不会导致进程退出
- 只有 KeyboardInterrupt(Ctrl+C)会正常向上传播,触发优雅关闭
- 其他 BaseException(如 SystemExit)会被拦截并记录,防止意外终止 回调执行顺序:
before_init → 初始化 → after_init → on_ready → [挂起]回调可以是同步或异步函数,框架自动检测并 await。 回调中的异常会被捕获并记录日志,不会中断启动流程。
- keep_running (
bool): 是否保持运行 - before_init: 初始化前回调,转发给
init() - after_init: 初始化成功后回调,转发给
init() - on_ready: 初始化完成且
after_init执行后、挂起前的回调
示例:
await sdk.run(keep_running=True)
# 使用 on_ready 回调
async def on_startup():
print("SDK 就绪,开始业务逻辑")
await sdk.run(on_ready=on_startup)
# 分阶段回调
async def before():
print("即将初始化")
async def after():
print("初始化完成,适配器已就绪")
async def ready():
print("一切就绪,开始挂起")
await sdk.run(before_init=before, after_init=after, on_ready=ready)
_start_script_dev_watcher() -> None
内部方法 脚本模式:挂载细粒度 watcher 并写入能力标记
_stop_script_dev_watcher() -> None
内部方法 停止脚本模式 watcher 并清除能力标记
shutdown() -> None
请求优雅关闭
设置关闭事件,使正在 await sdk.run() 挂起的主循环返回,
进而触发 uninit() 完成资源清理。可由模块/适配器在运行时调用,
也用作 SIGTERM 等信号的处理入口。
示例:
sdk.shutdown() # 任意协程中调用,触发优雅退出
enable_plugin_hot_reload(interval: float = 1.0) -> bool
启用本地插件文件夹热重载(自动监控)
监控插件文件夹(默认 plugins/,可通过 ErisPulse.framework.plugins_dir
配置)下 .py 文件的变更,自动重新加载对应插件。
需在 await sdk.run() 之前调用。
提示 自动监控仅覆盖本地插件目录;PyPI 安装包模块可通过 :meth:
reload_module手动热重载(pip 升级后调用即可)。
- interval: 轮询间隔(秒,默认 1.0)
返回值: 是否启动成功(无插件目录或已在运行返回 False)
示例:
await sdk.init()
sdk.enable_plugin_hot_reload()
await sdk.run()
async reload_module(module_name: str, *, full: bool = True) -> bool
热重载单个模块(手动触发,支持任意来源)
完整执行 语法预检 → 卸载旧实例 → 清理注册与 sys.modules 缓存
(按顶层包名 + invalidate_caches,默认全量)→ 重新发现/导入 →
重新注册并加载 流程;依赖该模块的模块会级联重载并默认重导代码。
本地插件(plugins/ 目录)来源重扫描插件目录;运行时注册来源按
定义模块重导并按类名重取;PyPI 安装包来源重新查询 entry-point 并
重导入模块代码(pip 升级后调用即可生效)。
module_name: 模块名(entry-point 名称、插件名或运行时注册名)
full: 是否全量重载(默认 True;False 为轻量逃生门——仅按
元数据清理缓存、PyPI 依赖者直接重新实例化,仅供超大依赖树的 性能敏感场景)
返回值: 是否重载成功
示例:
await sdk.reload_module("dice") # 本地插件
await sdk.reload_module("MyRuntime") # 运行时注册模块
await sdk.reload_module("Weather") # PyPI 安装包模块(默认全量)
async reload_adapter(adapter_name: str, *, full: bool = True) -> bool
热重载单个适配器(代码级,手动触发)
完整执行 语法预检 → 卸载(shutdown 即清理:路由/事件/任务/bot offline
- 注销)→ 清理
sys.modules子树与__pycache__字节码 → 重新 发现/导入 → 重新注册 → 原运行态则重新拉起 流程;任一步失败自动回滚 旧注册状态(尽力而为语义:断连等 unload 副作用不可撤销)。支持本地 插件(plugins/目录)与 PyPI 安装包两种来源。
- adapter_name: 适配器名(平台名称)
- full: 保留参数位(当前两种来源均执行全量清理,与模块语义对齐)
返回值: 是否重载成功(适配器被移除视为成功)
示例:
await sdk.reload_adapter("aiocqhttp") # pip 升级后调用即可生效
async reload_all_modules() -> dict[str, bool]
全量热重载所有已注册模块(尽力而为语义)
执行 卸载全部 → 清理全部 sys.modules 子树 → 重新发现/注册 →
按依赖拓扑序加载 → 此前已加载的懒加载模块重新激活 流程,一次刷新
全部模块代码(pip 批量升级后调用即可全部生效)。单模块失败仅记录
诊断并跳过,不影响其余模块;无整体回滚(on_unload 副作用不可撤销,
与单模块热重载语义一致)。
返回值: 模块注册名 → 是否重载成功(发现阶段即失败的模块不在结果中;
SDK 未初始化时返回空字典)
示例:
await sdk.reload_all_modules()
async _reload_module(module_name: str) -> bool
内部方法 插件热发现回调(由 PluginReloadWatcher 调度):按名字路由
已知模块 → 单模块热重载;已知适配器 → 适配器代码级热重载(适配器 插件文件的保存/删除此前完全无自动反应);全新文件(on_created)→ 先按模块插件热装载,不是模块插件再按适配器插件热装载。失败仅记录 不抛异常。
- module_name: 插件名(由插件目录路径解析)
返回值: 是否成功(路由失败/异常为 False)
stop_plugin_hot_reload() -> None
停止本地插件热重载监控
_register_signal_handlers() -> None
内部方法 注册进程信号处理器:SIGTERM / SIGHUP 转为优雅关闭,SIGUSR1 转为 进程内软重启(组件级热重载)
SIGUSR1 供 epsdk restart 对容器内 PID 1 实例使用——容器主进程
被终止即容器退出,外部「停止后重拉」不可用,改由框架进程内完成重启。
Windows 不支持 loop.add_signal_handler,捕获异常后跳过
(Windows 下仍可通过 sdk.shutdown() 或 Ctrl+C 触发关闭)。
async _do_restart() -> bool
内部方法 实际执行软重启的内部方法(联动热重载系统)
在后台任务中运行,与调用 restart() 的事件处理器解耦, 确保即使调用者被取消,重启流程也能完整执行。
软重启 = 组件层代码级热重载(2.11 起不再整体 uninit/init):
- 全部已加载模块走统一热重载管线(
reload_all_modules: 整体语法预检 → 卸载 → 清 sys.modules / pycache → 重发现重导 → 重新注册加载 → 懒激活;预检失败整轮拒绝,旧实例继续服务) - 适配器层先重发现 entry-point(运行中 pip 新装/卸载的适配器即刻
生效——装完即用),再逐个走
reload_adapter(卸载清理 → 清缓存 重发现 → 重新注册 → 原运行态重新拉起)
全程持热重载互斥锁(与单模块重载/归眠串行);保存风暴下 restart 请求自动合并——进行中的请求置 dirty 标记,本轮完成后补跑至多一轮。
配置热更新由配置监听器处理;框架自身更新等整进程场景请使用
hard_restart()。
返回值 (bool): 软重启是否全部成功(任一组件失败即为 False,
失败清单见日志)
async _execute_restart_once() -> bool
内部方法
单轮软重启执行体(互斥与补跑循环由 _do_restart 负责)
async restart() -> bool
SDK 软重启(联动热重载系统)
全部已加载模块与适配器走统一代码级热重载管线(语法预检 → 卸载 →
清 sys.modules / __pycache__ → 重发现重导 → 重新注册加载 /
拉起;失败快照回滚,单组件失败不影响其余),不再整体 uninit() /
init()——框架进程、路由与配置监听保持在线,组件代码(pip 升级后)
即刻生效。
提示 重要设计说明: 此方法使用后台任务将重启流程注册到事件循环调度器,与调用栈完全解耦 (事件处理器内调用不会中断当前事件链路);立即返回
True表示 "重启任务已成功调度"而非"重启已完成"。 重启请求自动合并:已有 restart 进行中时,本次调用只置合并标记 (进行中的一轮完成后补跑至多一轮),绝不并发交叉。 语义分界(2.11 起):
restart():组件层代码热重载(模块 + 适配器;pip 升级组件、 新装适配器 entry-point 均即刻生效)hard_restart():整进程重启(框架自身更新 / 结构性配置变更 等需要全新解释器的场景)
返回值 (bool): 重启任务是否成功调度(并非重启是否完成)
示例:
await sdk.restart()
is_supervised() -> bool
检测当前进程是否由外部监督者启动(CLI run 命令 / systemd / Docker 等)
监督者会在进程退出码为 42(HARD_RESTART_EXIT_CODE)时重新拉起新进程。
未被监督时硬重启后进程不会自动恢复,hard_restart() 会打出警告提醒
配置外部监督者(见 startup.md「监督者指南」)。
返回值: 是否有外部监督者
async hard_restart(reason: str = '') -> bool
硬重启:反初始化后退出进程,由外部监督者重新启动新实例
与 restart() 的区别:
- restart(): 组件层代码热重载——模块与适配器统一走热重载管线 (含运行中新装适配器的重发现拉起),框架进程保持在线
- hard_restart(): 反初始化后以退出码 42 退出进程,由外部监督者 重新拉起全新进程——用于框架自身更新等只有新解释器才能清干净 状态的场景(升级后的框架代码、C 扩展、累积泄漏)
硬重启依赖外部监督者(epsdk run / systemd / Docker / PM2 / supervisord)
在退出码 42 时重新拉起进程;未被监督时进程退出后不会自动恢复,会打警告提醒。
监督场景下退出前会把 reason 写入运行状态文件(.erispulse/runtime.json
的 hard_restart_reason 字段),监督者重拉时向用户展示。
- reason: 硬重启原因(可选,供监督者展示与排障)
返回值 (bool): 硬重启任务是否成功调度
示例:
await sdk.hard_restart("sdk self-update")
get_topology(*, json_safe: bool = True) -> dict[str, Any]
获取完整的拓扑树数据(便于 Dashboard 等管理界面展示)
聚合模块、适配器与作用域的归属关系:
modules:每个模块拥有的命令 / 事件处理器 / 路由 / 生命周期钩子adapters:每个适配器的运行状态、下属 Bot 状态与作用域绑定scope:作用域(模块 / 身份 / 文本 / 出站动作)json_safe: 是否输出可直接 JSON 序列化的安全结构(默认 True)。
安全模式下模块 ``info`` 只保留纯数据 meta 子表, 并对整树做序列化兜底净化,返回值可直接 ``json.dumps``。
返回值: 拓扑树字典
{"modules": {...}, "adapters": {...}, "scope": {...}}
示例:
topology = sdk.get_topology()
topology["modules"]["Chat"]["commands"]
["chat"]
async uninit() -> bool
SDK 反初始化
执行以下操作:
- 关闭所有适配器
- 卸载所有模块
- 清理所有事件处理器
- 清理适配器管理器和模块管理器
- 清理 SDK 对象上的模块属性
返回值 (bool): 反初始化是否成功
示例:
await sdk.uninit()