ErisPulse.Core.module 模块
模块概述
ErisPulse 模块系统
提供标准化的模块注册、加载和管理功能,与适配器系统保持一致的设计模式
类列表
class ModuleManager(ManagerBase)
模块管理器
提供标准化的模块注册、加载和管理功能,模仿适配器管理器的模式
提示
- 使用register方法注册模块类
- 使用load/unload方法加载/卸载模块
- 通过get方法获取模块实例
方法列表
_register_config_change_routing() -> None
内部方法 注册 config.set / config.updated 事件订阅,将配置变更路由到各模块的 on_config_update
config.set:代码或 Dashboard 调用 setConfig 时即时触发(单 key 变更)config.updated:用户手动编辑配置文件后由文件监听任务触发(整树变更)
_on_config_set(data: dict) -> None
内部方法 处理 config.set 事件:找出受影响的模块并触发 on_config_update
_on_config_updated(data: dict) -> None
内部方法 处理 config.updated 事件:对比新旧配置树,找出配置变化的模块并触发 on_config_update
_cleanup_lazy(module_name: str) -> None
内部方法 清理模块的懒加载代理与 SDK 属性(模块未实例化时也有效)
- module_name: 模块名称
_resolve_config_key(instance: Any) -> str(staticmethod)
内部方法 解析模块的配置键名(优先用注入的注册名,回退类名)
_notify_config_update(instance: Any, module_name: str, old_dict: dict | None, new_dict: dict | None) -> None
内部方法 调用模块的 on_config_update 回调,传入类型安全的配置对象
- instance: 模块实例
- module_name: 模块名(用于日志)
- old_dict: 变更前的配置字典(可能为 None)
- new_dict: 变更后的配置字典(可能为 None)
register(name: str | None = None, class_type: type | None = None, info: dict | None = None, *, module_name: str | None = None, module_class: type | None = None, module_info: dict | None = None) -> bool
注册模块类
- name: 模块名称
- class_type: 模块类
- info: 模块信息
- module_name (
已弃用): 兼容旧关键字参数,等同 name - module_class (
已弃用): 兼容旧关键字参数,等同 class_type - module_info (
已弃用): 兼容旧关键字参数,等同 info
返回值: 是否注册成功
异常: TypeError - 当模块类无效时抛出
示例:
module.register("MyModule", MyModuleClass)
_synthesize_runtime_meta(module_name: str, module_class: type) -> dict[str, Any](staticmethod)
内部方法 为运行时注册的模块合成最小 meta(来源标记 / top_level / 定义模块)
top_level 取定义模块 __module__ 的顶层段(与 sdk 层推导规则
一致),供 reload 清理 sys.modules 使用;描述 / 版本 / 作者字段
从 get_meta() 尽力补全(不可用则省略)。
_register_reload_snapshot(loader: Any, module_name: str, module_class: type) -> None
内部方法 运行时注册后同步登记模块加载器的重载快照条目
快照条目为模块类定义所在的模块对象(sys.modules 项),并为其
挂载合成 moduleInfo(若尚无)——reload 编排经该条目读取 meta 与
top_level。定义模块不可用或已被占用 moduleInfo 时回退为轻量命名
空间载体(reload 仅读取 __name__ 与 moduleInfo)。
register_lazy(name: str, lazy_proxy: Any) -> None
注册懒加载代理
- name: 模块名称
- lazy_proxy: 懒加载代理对象(LazyModule)
内部方法 由加载器在创建 LazyModule 后调用。注册后 get() 会返回该代理, 从而使“懒加载对用户透明”:已注册但未加载的模块不再返回 None。
unregister_lazy(name: str) -> None
取消注册懒加载代理
- name: 模块名称
内部方法 卸载/取消注册模块时调用,保持 _lazy_modules 与实际挂载状态一致。
async load(name: str | None = None, *, module_name: str | None = None) -> bool
加载指定模块(标准化加载逻辑)
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 是否加载成功
示例:
await module.load("MyModule")
_collect_dependents(name: str) -> list[str]
内部方法 收集直接或间接依赖指定模块的模块闭包(BFS)
返回顺序为由近及远(直接依赖者在前、间接依赖者在后); 卸载时应按相反顺序执行,保证每个依赖者卸载时其依赖仍可用。
- name: 目标模块名
返回值: 依赖者模块名列表(不含 name 本身)
async unload(name: str | None = None, *, module_name: str | None = None, purge: bool = False, reason: str = 'unload') -> bool
卸载指定模块或所有模块
卸载被其它模块依赖的模块时,依赖它的模块会级联卸载 (依赖者先卸载,日志说明级联链),避免依赖者持有失效引用继续运行。
purge 控制是否一并删除注册存根:
purge=False(默认):只取消加载——卸载实例与资源,但保留 注册存根(模块类与元信息),模块仍可被 discover 重新发现、load()重新实例化,无需重新register()purge=True:彻底卸载——同时删除注册存根(释放模块类引用), 并对插件文件夹来源的模块清理sys.modules,使插件及其独占依赖 可被 GC 回收(解决 NoneBot 式卸载后插件与依赖内存不释放的问题); 级联卸载的依赖者同样被 purge。卸载后重新加载需重新register()
卸载与热重载共用全局互斥:与进行中的 reload / restart / 归眠串行
(消除外部卸载与重载交叉导致的双重 on_unload);等待上限
UNLOAD_LOCK_WAIT_TIMEOUT_SECS 秒,超时降级直接执行并留痕
(持锁重载卡死的极端场景不阻塞调用方)。
name: 模块名称,None表示卸载所有模块(默认None)
module_name (
已弃用): 兼容旧关键字参数,等同 namepurge: 是否一并删除注册存根并清理 sys.modules(默认 False)
reason: 卸载来意标注,透传给
on_before_unload钩子与``module.before_unload`` 事件(``"unload"`` / ``"reload"`` / ``"disable"`` / ``"cascade"``;框架内部使用,常规调用保持默认)
返回值: 是否卸载成功
示例:
await module.unload("MyModule") # 卸载单个模块(依赖者级联卸载)
await module.unload("MyModule", purge=True) # 彻底卸载(释放类引用)
await module.unload() # 卸载所有模块
async _unload_locked(name: str | None, *, purge: bool = False, reason: str = 'unload') -> bool
内部方法 unload 的实现体(调用方已持有热重载互斥锁,或已限时降级)
- name: 模块名称,None 表示卸载所有模块
- purge: 是否一并删除注册存根并清理 sys.modules
- reason: 卸载来意标注
返回值: 是否卸载成功
async sleep(name: str | None = None, *, module_name: str | None = None) -> bool
归眠指定模块(懒加载休眠)
与 unload 的差异:释放运行时资源(on_unload / 归属任务 / 连接 /
注册资源),但保留懒加载代理与注册存根——模块回到"已注册未
加载"状态(与从未激活不可区分),下次属性访问 / module.call /
activate_on 事件将透明唤醒(重新实例化并 on_load)。
归眠前触发 on_before_unload(reason="dormant"),模块可借
此把状态保存到 storage,唤醒后在 on_load 中恢复。自动归眠需在
加载策略中声明 get_load_strategy(dormant_after="30m");任何已
加载模块均可手动归眠。
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 是否归眠成功(未加载/未注册返回 True——无事可做)
示例:
await module.sleep("HeavyTool") # 闲置归眠,释放资源
touch_activity(module_name: str) -> None
内部方法 记录模块活跃时间戳(休眠清扫判定用)
埋点位置:事件处理器调用(Core/Event/base._invoke_handler)、
命令执行(Core/Event/command)、module.call 目标解析。
- module_name: 模块注册名
_ensure_dormancy_sweeper() -> None
内部方法 确保休眠清扫器后台循环已启动(幂等;无休眠声明时不启动)
async _dormancy_sweep_loop() -> None
内部方法 休眠清扫循环:按固定间隔扫描已加载且声明 dormant_after 的模块, 闲置超阈值即自动归眠(uninit 时随后台任务统一取消)
async _dormancy_sweep() -> None
内部方法 单轮休眠扫描:对闲置超过阈值的已加载模块自动归眠
依赖方策略:不级联、不跳过——懒模块的依赖方经由持久代理
(sdk.<Name>)/ module.call 访问,归眠后与"从未激活"不可
区分,唤醒路径照常生效。
async reload(name: str, *, full: bool = True) -> bool
热重载单个模块(支持任意来源:本地插件 / 运行时注册 / PyPI 安装包)
经模块加载器完整执行 语法预检 → 卸载旧实例 → 清理注册与
sys.modules 缓存(按顶层包名 + invalidate_caches,默认全量)
→ 重新发现/导入 → 重新注册并加载 流程;依赖该模块的模块会级联
重载并默认重导代码。本地插件(plugins/ 目录)来源重扫描插件
目录;运行时注册来源按定义模块重导并按类名重取;PyPI 安装包来源
重新查询 entry-point 并重导入模块代码(pip 升级后调用即可生效)。
full=False 切换为轻量重载:仅按元数据清理 sys.modules,
PyPI 依赖者卸载后直接重新实例化——仅供超大依赖树的性能敏感场景。
- name: 模块名(entry-point 名称、插件名或运行时注册名)
- full: 是否全量重载(默认 True;False 为轻量逃生门)
返回值: 是否重载成功(SDK 未初始化时返回 False)
示例:
await sdk.module.reload("dice") # 本地插件
await sdk.module.reload("MyRuntime") # 运行时注册模块
await sdk.module.reload("Weather") # PyPI 安装包模块(默认全量)
async reload_all() -> 'dict[str, bool]'
全量热重载所有已注册模块(尽力而为语义)
经模块加载器执行 卸载全部 → 清理全部 sys.modules 子树 →
重新发现/注册 → 按依赖拓扑序加载 → 此前已加载的懒加载模块重新
激活 流程,一次刷新全部模块代码(pip 批量升级后调用即可全部生效)。
单模块失败仅记录诊断并跳过,不影响其余模块;无整体回滚——
on_unload 副作用不可撤销,与单模块热重载语义一致。
返回值: 模块注册名 → 是否重载成功(发现阶段即失败的模块不在结果中;
SDK 未初始化时返回空字典)
示例:
await sdk.module.reload_all()
async _run_before_unload(module_name: str, instance: Any, reason: str, timeout: float) -> None
内部方法
触发卸载前钩子与 module.before_unload 事件(卸载/禁用流水线第一步)
先广播事件(第三方状态管家模块可观测),再调用实例可选钩子
on_before_unload(event)——event 携带 module_name 与 reason
("reload" / "unload" / "disable" / "cascade")。
任一失败仅告警,不阻塞后续卸载流程(与 on_unload 容忍语义一致)。
- module_name: 模块注册名
- instance: 模块实例(可为 None——仅广播事件)
- reason: 卸载来意
- timeout: 钩子优雅执行超时(秒)
async _unload_single_module(module_name: str, *, reason: str = 'unload', sleep: bool = False) -> bool
内部方法
卸载单个模块(sleep=True 时为归眠:释放资源但保留懒加载代理)
module_name: 模块名称
reason: 卸载来意(透传给 on_before_unload / on_unload 钩子与
before_unload 事件;
"reload"时模块可推迟关闭外部资源, 回滚重放 on_load 后仍可继续服务)sleep: 归眠模式——保留懒加载代理与注册存根,模块回到"已注册未加载"状态
返回值: 是否卸载成功
_record_load_error(module_name: str, e: BaseException) -> None
内部方法
记录模块加载失败现场(last_error() / get_info().last_error 消费)
- module_name: 模块注册名
- e: 失败异常
_cleanup_failed_module_cache(module_name: str) -> None
内部方法 加载失败后的缓存自清洗
失败模块的 sys.modules 条目没有任何保留价值——主动弹出并刷新
插件路径记录,保证「改完代码再 load / reload 一次」必定读到磁盘
新代码,而不是复用失败存根 + 旧 import 缓存的组合。不影响注册表
中已登记的模块类(重新 load 无需重新 register)。
async _half_unload_failed_module(module_name: str, instance: Any) -> None
内部方法 加载失败(on_load 异常 / 构造后阶段异常)时的半卸载
对已构造实例按正常卸载同序触发资源回收(on_unload → 取消归属
任务 → 外部清理钩子 → 框架资源注销),保证 __init__ /
on_load 半途注册的资源不成为"有主孤儿"。
与正常卸载的差异:不触碰 _modules / _loaded_modules /
_module_services 与 sdk 属性——失败路径从未写入这些注册表;
on_unload 已执行的副作用(断连等)与正常卸载一致不可撤销,
但实例与注册资源不再泄漏。
- module_name: 模块注册名
- instance: 已构造的实例(构造函数本身抛异常时为 None)
_cleanup_module_registrations(module_name: str) -> None
内部方法 清理模块在加载上下文内注册的全部框架资源(unload / disable 共用)
委托归属权统一门面(Core/ownership)完成:i18n 翻译域、路由
(命名空间 + owner 兜底:中间件 / 首页入口 / 非命名空间路由)、
适配器事件处理器与中间件、命令与事件处理器、自定义会话类型、
平台事件方法注入、事件覆写、scope 覆写、交互会话等待、主人身份源
provider、生命周期钩子。每步失败仅记录日志,不中断后续清理。
- module_name: 模块名
audit(module_name: str, deep: bool = False) -> 'dict[str, Any]'
归属权泄漏审计(透传归属权统一门面)
module_name: 目标模块名
deep: 附带 gc 实例普查(weakref 存活检查 + 引用方类型;
有全局暂停开销,仅显式排障使用)
返回值: 审计报告 dict(owner / counts / orphans / 深普查结果)
示例:
report = sdk.module.audit("roll", deep=True)
report["instance_recyclable"]
True
is_shadow_module(module_name: str) -> bool
判断模块名是否为影子 owner(拓扑 / Dashboard 展示用)
- module_name: 模块名
返回值: 是否为影子 owner
list_shadows() -> 'dict[str, str]'
当前全部影子绑定(Dashboard 聚合展示用)
返回值: {原模块名: 影子 owner 名}
shadow_ingest_whl(module_name: str, *, data: bytes, filename: str) -> 'dict[str, str]'
摄取 whl 作为影子源:校验 → 原件落盘 → 解包 → 推导 source
- module_name: 被影子测试的模块名(仅作落盘目录段)
- data (
whl): 文件字节 - filename (
whl): 文件名(PEP 427)
返回值: {"source": 解包源目录, "whl_path": 原件路径}
异常: ShadowSourceError - 文件名/大小非法或无法推导源目录
示例:
sdk.module.shadow_ingest_whl("roll", data=whl_bytes, filename="roll-2.0-py3-none-any.whl")
async shadow_promote_persist(module_name: str, *, whl_path: str) -> 'dict[str, Any]'
转正并持久化:promote 成功后后台 pip 安装落盘的 whl 原件
- module_name: 原模块名
- whl_path: :meth:
shadow_ingest_whl返回的原件路径
返回值: {"task_id": 后台安装任务 ID}
异常: ShadowSourceError - whl_path 缺失 / 越界
示例:
await sdk.module.shadow_promote_persist("roll", whl_path=info["whl_path"])
shadow_persist_status(task_id: str) -> 'dict[str, Any] | None'
查询「转正并持久化」后台 pip 任务状态
- task_id: :meth:
shadow_promote_persist返回的任务 ID
返回值: {"status": running/success/error, "output": [...], ...};未知任务为 None
async shadow_start(module_name: str, source: 'str | Any', owner: 'str | None' = None) -> str
启动影子:把新版代码以独立 owner 装载为 module_name 的影子实例
(运行时 API;模块代码零改动,影子的出站被拦截记账、不真正发出)
module_name: 被 shadow 的已加载模块名
source: 新版代码路径(目录含
__init__.py或单.py文件;建议放在 plugins 目录之外)owner: 影子 owner 名(默认取路径名)
返回值: 影子 owner 名
示例:
await sdk.module.shadow_start("roll", source="downloads/roll_v2")
'roll_shadow'
async promote_shadow(module_name: str) -> bool
影子转正:卸载当前版本 → 影子以真名注册加载 → 失败自动回滚
转正永远由人确认(无自动晋升);复用重载快照机制保证失败时旧实例 继续服务(尽力而为语义:on_unload 已执行的副作用不可撤销)。转正后 请尽快持久化安装新版本(pip 升级 / 替换插件文件),使重启后仍生效。
- module_name: 原模块名
返回值: 是否转正成功
异常: ValueError - 该模块未绑定影子时
示例:
await sdk.module.promote_shadow("roll")
async dismiss_shadow(module_name: str) -> bool
放弃影子:回收影子资源并解除绑定(原模块不受影响)
- module_name: 原模块名
返回值: 是否成功(未绑定影子时 False)
示例:
await sdk.module.dismiss_shadow("roll")
shadow_diff(module_name: str) -> 'dict[str, Any]'
影子与线上的行为对比(影子意向出站 × transcript 实际发送,按 trace_id 对齐)
- module_name: 原模块名
返回值: 对比报告 dict(shadow_owner / count / aligned)
示例:
report = sdk.module.shadow_diff("roll")
report["count"]
3
_purge_module_stub(module_name: str) -> tuple[str, Any, Any]
内部方法 删除模块注册存根,释放模块类引用(并清理插件来源的 sys.modules)
返回 (module_name, class_weakref, instance_weakref) 供回收诊断。
- module_name: 模块名
返回值: 供 _report_purge_recyclability 消费的弱引用三元组
_purge_sys_modules(module_name: str, top_level: list[str]) -> None(staticmethod)
内部方法 从 sys.modules 移除插件自身模块与其子包(保守:不清理第三方/共享库)
移除前先清除对应源文件的字节码缓存:purge 卸载 → 改码 → 重新 load 的链路同样保证读到新代码(同秒同字节数改写不再命中旧 pyc)。
- module_name: 插件模块名
- top_level: 顶层包名列表(用于清理包内子模块)
_report_purge_recyclability(refs: list[tuple[str, Any, Any]]) -> None
内部方法 purge 卸载后诊断模块类/实例是否可回收,泄漏时告警并列出引用方
- refs:
_purge_module_stub产出的 (name, class_ref, instance_ref) 列表
get(name: str | None = None, *, module_name: str | None = None) -> '_TModule | Any | None'
获取模块实例或懒加载代理
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 模块实例 / 懒加载代理 / None
提示 不会触发加载。返回值优先级:
- 已加载的真实实例(_modules)
- 懒加载代理(_lazy_modules,访问其属性才会触发初始化)
- None(模块未注册或未挂载) 这使得
module.get()与sdk.xxx/module.MyModule在“懒加载对用户透明”上保持一致:已注册但未加载的模块不再返回 None。 由于框架通过 entry_points 动态发现模块,入口点无法静态获知 具体模块类型;返回值为泛型_TModule(默认基类)。 若调用方与模块同项目且能导入模块类,可添加类型注解获得更精确补全:my_module: MyModule = sdk.module.get("MyModule")
示例:
my_module = module.get("MyModule")
exists(name: str | None = None, *, module_name: str | None = None) -> bool
检查模块是否已注册
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 模块是否已注册(即 module.register() 已被调用)
提示 exists() 只检查模块类是否已注册到管理器,用于验证模块是否可以加载。 如需检查模块是否启用,请使用 is_enabled()。
is_loaded(name: str | None = None, *, module_name: str | None = None) -> bool
检查模块是否已加载
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 模块是否已加载
示例:
if module.is_loaded("MyModule"):
...
is_running(name: str | None = None, *, module_name: str | None = None) -> bool
检查模块是否正在运行(已加载)
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 模块是否正在运行
示例:
if module.is_running("MyModule"):
print("MyModule 正在运行")
list_running() -> list[str]
列出所有正在运行的模块(已加载)
返回值: 模块名称列表
示例:
running = module.list_running()
print("正在运行的模块:", running)
list_registered() -> list[str]
列出所有已注册的模块
返回值: 模块名称列表
示例:
registered = module.list_registered()
list_loaded() -> list[str]
列出所有已加载的模块
返回值: 模块名称列表
示例:
loaded = module.list_loaded()
_config_register(module_name: str, enabled: bool = DEFAULT_MODULE_ENABLED) -> bool
注册新模块信息
内部方法 此方法仅供内部使用
- module_name: 模块名称
- enabled: 是否启用模块 (默认: DEFAULT_MODULE_ENABLED)
返回值: 是否操作成功
is_enabled(name: str | None = None, *, module_name: str | None = None) -> bool
检查模块是否启用
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 模块是否启用
提示 模块启用条件:
- 模块在配置文件中(ErisPulse.modules.status.{module_name} 存在)
- 配置值为启用状态 如果模块未在配置中,默认启用并自动写入配置
enable(name: str | None = None, *, module_name: str | None = None) -> bool
启用模块
- name (
str): 模块名称 - module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值 (bool): 操作是否成功
disable(name: str | None = None, *, module_name: str | None = None) -> bool
禁用模块
- name (
str): 模块名称 - module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值 (bool): 操作是否成功
unregister(name: str | None = None, *, module_name: str | None = None) -> bool
取消注册模块
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 是否取消成功
内部方法 注意:此方法仅取消注册,不卸载已加载的模块
clear() -> None
清除所有模块实例和类
内部方法 此方法用于反初始化时完全重置模块管理器状态
list_items() -> dict[str, bool]
列出所有模块状态
合并配置项与已注册模块,确保禁用模块也可见。
返回值 (dict[str, bool): ] {模块名: 是否启用} 字典
last_error(name: str | None = None, *, module_name: str | None = None) -> dict | None
查询模块最近一次加载失败现场
load() 失败(构造 / on_load 异常 / SystemExit)时记录异常对象、
完整 traceback 与时间戳;下次加载成功后自动清除。失败详情同时随
get_info() 以 last_error 字段暴露——RPC / 编程调用方直接
取用,无需翻日志文件。
- name: 模块名称
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 失败现场字典 {"exception", "traceback", "at"},无记录返回 None
示例:
await module.load("X") # doctest: +SKIP
False
module.last_error("X")["exception"] # doctest: +SKIP
"AttributeError('...')"
get_info(name: str | None = None, *, module_name: str | None = None) -> dict | None
获取模块信息
返回值为注册元信息的浅拷贝,附加运行时诊断字段:
last_error:最近一次加载失败现场(见 :meth:last_error)running_identity:实际在跑的代码身份({"module", "version"})stale:注册版本 ≠ 运行版本时为 True("改了代码忘 reload" 一眼可见)name: 模块名称
module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 模块信息字典(含诊断字段),不存在则返回None
示例:
info = module.get_info("MyModule")
get_meta(name: str | None = None, *, resolve_i18n: bool = True, module_name: str | None = None) -> dict | None
获取模块的介绍元信息(描述这个模块是什么、属于哪一类等)
元信息是模块的通用介绍数据,供 help 模块、Dashboard 模块列表、 模块商店等各类界面 / 生态模块消费。
i18n 支持:元信息字段值可为纯字符串,或 i18n 字典
{"i18n": "key.path", "default": "兜底文本"}(与配置 description 约定一致)。
翻译键通过模块的 I18nClass 声明注册(键路径 <模块名>.<属性名>)。
resolve_i18n=True(默认)时解析为当前语言文本;False 时透传原始字典。
解析优先级:模块类声明的 get_meta() > 注册时传入的 info,缺失字段自动补全。
- name: 模块名称
- resolve_i18n: 是否解析 i18n 字典为当前语言文本(默认 True)
- module_name (
已弃用): 兼容旧关键字参数,等同 name
返回值: 元信息字典,模块未注册时返回 None
示例:
meta = module.get_meta("Weather")
meta["description"] # 当前语言下的模块简介
_resolve_meta_value(value: Any) -> Any(staticmethod)
内部方法 解析元信息字段值:i18n 字典 → 当前语言文本;其余原样返回
- value: 原始值(str 或 {"i18n": ..., "default": ...})
返回值: 解析后的值
_commands_of(module_name: str) -> list[str]
内部方法 列出该模块注册的主命令名
get_commands_overview(*, event: Any = None, platform: str | None = None, bot_id: str | None = None, session_id: str | None = None) -> dict[str, dict[str, Any]]
获取命令总览(模块 meta + 其注册的命令,按模块聚合)
聚合每个模块的介绍元信息与其注册的命令(含别名 / 分组 / 帮助文本), 便于 help 模块、管理界面等按模块展示"这个模块是干什么的 + 有哪些命令"。 命令的 help / hidden 字段为合并控制面覆盖后的生效值(用户优先)。
传入作用域上下文(event 或 platform / bot_id / session_id
任一)时,当前会话不可用模块不进入总览(会话感知总览)。
- event: 可选,事件上下文(Event 或 dict)
- platform: 可选,平台名(与 event 叠加时显式参数优先)
- bot_id: 可选,Bot 标识
- session_id: 可选,会话标识
返回值: {模块名: {"meta": {...}, "commands": [{name, aliases, group, help, hidden}]}}
示例:
overview = module.get_commands_overview()
overview["Weather"]["meta"]["description"]
"查询城市天气"
overview["Weather"]["commands"][0]["name"]
"weather"
overview = module.get_commands_overview(event=event) # 会话感知
get_status_summary() -> dict[str, Any]
获取模块的完整状态摘要
便于WebUI展示所有模块的注册、加载和启用状态, 包含已禁用模块以便于管理。
返回值: 状态摘要字典
示例:
summary = module.get_status_summary()
# {
# "modules": {
# "MyModule": {
# "status": "loaded",
# "enabled": True,
# "is_base_module": True
# },
# "DisabledModule": {
# "status": "disabled",
# "enabled": False,
# "is_base_module": None
# }
# }
# }
get_topology(*, json_safe: bool = True) -> dict[str, Any]
获取模块的拓扑树数据(便于 WebUI 展示)
聚合每个模块拥有的命令、事件处理器、路由与生命周期钩子, 按 owner(模块名)归并,展示模块与资源的归属关系。
json_safe: 是否输出可直接 JSON 序列化的安全结构(默认 True)。
安全模式下 ``info`` 只保留纯数据的 ``meta`` 子表 (丢弃 ``module_class`` / ``strategy`` 等运行时对象), 并对整树做序列化兜底净化。
返回值: 拓扑树字典
{"modules": {name: {
"loaded": bool, "enabled": bool,
"load_strategy": {"lazy": bool|None, "priority": int|None},
"info": dict|None,
"commands": [str, ...],
"services": [str, ...],
"handlers": {event_type: count},
"routes": {"http": [...], "ws": [...], "sse": [...]},
"lifecycle_hooks": int,
"scope_applies": bool,
}}}
示例:
topology = module.get_topology()
print(topology["modules"]["Chat"]["commands"])
["chat"]
_parse_replay_duration(value: Any) -> float(classmethod)
内部方法
解析回放时长声明("5m" / "1h" / "300")
- value: 时长值
返回值: 秒数
_build_replay_event(record: dict[str, Any]) -> Any | None
内部方法 从收件箱记录构造回放合成事件
合成事件带 replayed: True 标志(处理器可据此跳过副作用);
user_id 优先取记录的 sender,私聊场景回退为 target。
- record: 收件箱记录(role / text / ts / sender / session_key)
返回值: 合成事件(Event);无法解析会话键时返回 None
async _replay_events(module_name: str, replay: Any) -> None
内部方法 执行冷启动事件回放:收件箱最近消息 → 仅分发给该模块的处理器
- module_name: 模块名
- replay: 回放时长声明("5m" / "1h" / 秒数)
_resolve_services(module_name: str) -> 'list[dict[str, Any]] | None'
内部方法 解析模块的服务契约(get_meta().services),规范化为字典列表
- module_name: 模块名称
返回值: ``[{"name": ..., "description": <str|i18n dict|None>,
"parameters": <dict|None>}, ...]``;未声明时返回 None(公开方法全开放)
_service_names(module_name: str) -> 'list[str] | None'
内部方法 获取服务白名单(名字列表)
- module_name: 模块名称
返回值: 服务名列表;未声明时返回 None
_docstring_first_line(func: Any) -> str(staticmethod)
内部方法 提取函数 docstring 的摘要行(服务介绍的自动兜底)
兼容规范的多行 docstring(空行开头):取第一个非空行,
跳过 doctest 装饰行(>>> / ...)。无 docstring 时返回空串。
- func: 函数 / 绑定方法
返回值: 摘要文本(可能为空串)
_service_description(module_name: str, entry: dict[str, Any]) -> str
内部方法 解析服务介绍:显式声明(i18n 字典解析)> 方法 docstring 首行 > 空串
- module_name: 模块名
- entry: 规范化服务条目({"name", "description"})
返回值: 介绍文本
_docstring_params(func: Any) -> dict[str, str](staticmethod)
内部方法
从 docstring 提取参数说明(:param name: 文本 行),作为服务参数提示的自动兜底
兼容 Sphinx 带类型形态(:param int n: ...,取末位词为参数名);
每个参数取说明首行,重复声明取首个。
- func: 函数 / 绑定方法
返回值: {参数名: 说明文本}(无 docstring 或无参数区时为空字典)
_service_parameters(module_name: str, entry: dict[str, Any]) -> dict[str, str]
内部方法
解析服务参数提示:显式声明(i18n 字典解析)与方法 docstring :param: 行按参数合并,
单参数内显式声明优先
仅保留方法签名中实际存在的参数(首个 self / cls 与变长参数除外)——
声明与签名不一致时以签名为准,保证提示不会描述不存在的调用面。
- module_name: 模块名
- entry: 规范化服务条目({"name", "description", "parameters"})
返回值: {参数名: 提示文本}(无任何提示来源时为空字典)
services(module_name: str | None = None) -> 'dict[str, list[dict[str, Any]]]'
服务目录:列出模块通过 get_meta().services 声明的对外服务
仅包含显式声明的模块(未声明的模块不出现在结果中); 每个服务附带方法签名字符串、介绍文本与参数提示:
介绍来源:
services中{"name", "description"}的显式声明(支持 i18n 字典,解析为当前语言)> 方法 docstring 首行 > 空串
签名:
inspect.signature提取参数提示:
parameters中{参数名: 说明}显式声明(支持 i18n 字典)与方法 docstring
:param:行按参数合并, 单参数内显式声明优先;仅含签名内实际存在的参数
懒加载(已注册未加载)模块同样进入目录——服务发现先于加载发生,
调用方可据此决定是否 call() 唤醒目标模块。
为后续 MCP 化(调用点暴露给 AI)与生态服务发现提供数据基础。
- module_name: 仅查询指定模块;None 时列出全部已注册模块中声明了服务的
返回值: {模块名: [{"name", "signature", "description", "parameters"}]}
示例:
sdk.module.services()
{'Chat': [{'name': 'get_history',
'signature': '(session_id, n=20)',
'description': '查询会话历史',
'parameters': {'session_id': '会话 ID', 'n': '返回条数'}}]}
sdk.module.services("Chat")
{'Chat': [{'name': 'get_history', ...}]}
async _resolve_call_target(module_name: str) -> Any
内部方法 解析模块间调用的目标实例(含懒加载模块唤醒)
- module_name: 模块名称
返回值: 模块实例
异常: ModuleNotAvailableError - 模块未注册 / 未启用 / 唤醒失败时
async call(module_name: str, method: str, *args: Any, timeout: float | None = None, **kwargs: Any) -> Any
跨模块调用目标模块的服务方法(协议化 RPC)
与 module.<Name>.<method>() 裸属性访问的差异:
目标模块未注册 / 未启用时抛出类型化异常而非 AttributeError;
懒加载模块自动唤醒;get_meta().services 契约白名单校验;
调用方经过 scope 出站维度(actions.<caller>.call)审计;
被调方法执行期间 current_owner 归因到目标模块,
其内部的 wait_reply / 出站发送 / 日志等正确归属;
调用方身份保留在 current_caller 上下文中(get_current_caller()
读取),供被调方识别调用来源;
协程方法带超时语义(超时抛 :class:ModuleCallTimeoutError)。
- module_name: 目标模块名
- method: 目标方法名
- args: 位置参数(透传给目标方法)
- timeout: 超时秒数(默认 30 秒;None 表示不限时;仅对协程方法生效)
- kwargs: 关键字参数(透传给目标方法)
返回值: 目标方法的返回值
异常: ModuleNotAvailableError - 目标模块未注册 / 未启用 / 唤醒失败
异常: ServiceNotProvidedError - 方法不在目标模块的 services 白名单内(或为私有方法 / 不存在)
异常: ModuleCallError - 调用方被 scope 出站规则拒绝
异常: ModuleCallTimeoutError - 协程方法超时
示例:
result = await sdk.module.call("Chat", "get_history", session_id, n=20)
提示 服务方在
get_meta().services声明契约收紧调用面(缺省时公开方法全开放):class ChatModule(BaseModule): @staticmethod def get_meta() -> ModuleMeta: return ModuleMeta(services=["get_history", "translate"]) async def get_history(self, session_id, n=20): ...
__getattr__(module_name: str) -> Any
通过属性访问获取模块实例
- module_name (
str): 模块名称
返回值 (Any): 模块实例
异常: AttributeError - 当模块不存在或未启用时
示例:
my_module = module.MyModule
__contains__(module_name: str) -> bool
检查模块是否存在且处于启用状态
- module_name (
str): 模块名称
返回值 (bool): 模块是否存在且启用
示例:
if "MyModule" in module:
...