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

ErisPulse.Core.scope 模块


模块概述

ErisPulse 作用域(scope)

控制权完全交给用户:在模块 / 适配器 / 处理器 / 出站调用注册的上层 (配置 ErisPulse.scope 或运行时 sdk.scope)统一声明"什么范围内生效"。 事件管线在入口、处理器过滤与出站闸口自动读取并执行。

作用域按事件处理生命周期回答三个问题:

  • 模块维度:某个上下文里哪些模块可用(平台 / Bot / 会话三级绑定)
  • 身份维度:谁的事件收不收(适配器 / Bot / 会话 / 用户四级策略)
  • 出站维度:模块能向外做什么(限制模块发起消息发送 / 标准 API 动作 / 请求操作)

配置树(ErisPulse.scope):

[ErisPulse.scope]
default_allow = true          # 全局兜底(未命中任何规则时放行/拒绝)

# ① 模块维度:哪些模块可用(优先级 会话 > Bot > 平台)
[ErisPulse.scope.platforms.onebot11]
modules = ["Chat", "Tool*"]   # 精确名 / glob / re:正则
blocked = ["re:^Danger"]
[ErisPulse.scope.bots.onebot11."123456"]
modules = ["Chat"]
merge = true                  # 在平台级绑定基础上追加(默认整体覆盖)
[ErisPulse.scope.sessions.onebot11."789012345"]
modules = ["Chat"]

# ② 身份维度:谁的事件收不收(优先级 用户 > 会话 > Bot > 适配器)
[ErisPulse.scope.identity.adapters.onebot11]
deny = true
[ErisPulse.scope.identity.bots.onebot11."123456"]
deny = true
[ErisPulse.scope.identity.sessions.onebot11."g_blocked"]
deny = true
[ErisPulse.scope.identity.users.onebot11]
allow = ["u_admin"]
deny = ["u_bad", "spam_*"]    # 支持 glob / re:正则

# ③ 出站维度:限制模块发起出站动作(默认全允许,显式收紧才禁)
[ErisPulse.scope.actions.MyModule]
send = { deny = true }                                   # 全禁发送
send = { allow = ["Text", "Image*"], deny = ["File"] }   # 方法级细粒度
api = { allow = ["get_*"] }                              # 仅允许查询类 API
request = { deny = true }                                # 禁止处理请求

匹配条目统一语法(见 :mod:ErisPulse.Core.text_match): 精确名 / glob(* / ? / [seq])/ re: 正则,默认大小写不敏感。

提示

  1. 通过 from ErisPulse.Core import scope 导入单例(sdk.scope 同对象)
  2. 判定:scope.is_allowed(...) / scope.is_identity_allowed(...) / scope.is_action_allowed(...) —— 对应 ①②④ 三个判定闸口
  3. 读写:像字典一样用点分路径操作任意配置节 —— scope.get("platforms.onebot11") / scope.set("actions.My", {...}) / scope.delete("actions.My.send"),也支持 scope[key] / scope[key] = v / del scope[key]
  4. 事件处理器文本条件覆写见 :mod:ErisPulse.Core.Event.overrides; 命令 ACL / 参数覆写见 :mod:ErisPulse.Core.Event.command

类列表

class ScopeManager

作用域管理器(单例)

统一管理三维作用域配置(模块 / 身份 / 出站),配置即一棵 ErisPulse.scope 字典树。API 面向原生字典风格收敛:

  • 判定::meth:is_allowed / :meth:is_identity_allowed /

    :meth:is_action_allowed(三个闸口的问询)

  • 读写::meth:get / :meth:set / :meth:delete(点分路径直达任意节,

    同时支持 scope[path] / scope[path] = value / del scope[path])

  • 全局::meth:clear / :meth:stats / :meth:reset_stats / :meth:topology

支持配置热更新、LRU 缓存与运行统计。 命令 ACL / 参数覆写由命令系统自持(ErisPulse.event.command)。

方法列表

_is_identity_binding(binding) -> str | None(staticmethod)

内部方法 读取身份绑定的策略(deny 优先于 allow)

  • binding: 绑定字典({"allow": true} 或 {"deny": true})

返回值: "allow" / "deny";未配置或格式非法时返回 None


_normalize_action_rule(rule) -> dict | None(staticmethod)

内部方法 归一化出站动作规则

合法输入形态:

  • True → {}(无限制,等价未配置)

  • False → {"deny": True}(全禁)

  • dict → 仅保留 allow(字符串列表)与 deny(布尔或字符串列表)键

  • rule: 配置中的动作规则(bool / dict)

返回值: 规范化规则字典;allow / deny 类型非法时返回 None


_deep_merge(dst: dict, src: dict) -> None(staticmethod)

内部方法 把 src 深合并进 dst(原地修改)


_warn_invalid(path: str, actual: str) -> None

内部方法 输出配置格式告警(同一路径去重)


_validated_bucket(config: dict, key: str) -> dict

内部方法 读取并校验一个 dict 型配置节(非法时告警并忽略)


_load_config() -> None

内部方法 从配置加载配置树(含格式校验)


_apply_tree(tree: dict) -> None

内部方法 校验并应用配置树到内存(含格式校验)


_replay_runtime_overrides() -> None

内部方法 按写入顺序把运行时覆盖层重放到重建后的配置树


_walk_to(tree: dict, parts: list[str]) -> dict(staticmethod)

内部方法 沿 parts 逐层下行(缺失的中间节建空 dict),返回目标父节


_restore_inmemory(snapshot: dict) -> None

内部方法 持久化内部热更新以旧盘配置重建了 _data,用内存最终态快照恢复(写后立读)。 与 :meth:_apply_tree 不同:快照含运行时值,直接恢复不触碰持久化基线


_record_runtime_owner(path: str) -> None

内部方法 记录运行时写入的调用方归属(模块卸载时兜底清理)


_clear_runtime_overrides(prefix: str) -> None

内部方法 清除某路径及其全部子路径的运行时覆盖记录


unregister_by_owner(caller: str) -> int

注销指定调用方的全部运行时(persist=False)作用域绑定

仅清理内存态运行时写入;persist=True 的写入属用户配置语义, 在模块卸载时不受影响。由模块管理器在卸载时兜底调用, 避免已卸载模块的运行时绑定残留生效。

  • caller: 调用方模块名 / 适配器平台名

返回值 (int): 清理的绑定条目数


_validated_actions(scope_config: dict) -> dict

内部方法 加载并校验出站动作规则


_on_config_updated(data: dict) -> None

配置变更回调:仅在 scope 配置实际变化时重建配置树

  • config.set:按事件 key 过滤,只有整棵写入或 ErisPulse.scope 子树内的写入才触发重建(无关模块写自己的 配置不应冲掉运行时绑定/清空判定缓存)

  • config.updated:对比新旧配置树的 scope 节,相同则跳过

  • data: 事件载荷(config.set 含 key;config.updated 含 old_config/new_config)


_invalidate_cache() -> None

内部方法 清空 LRU 结果缓存与预编译匹配器缓存


_compiled_list_matcher(entries) -> 'Callable[[str], bool] | None'

内部方法 编译匹配条目列表为判定函数(带内容元组键的预编译缓存)

  • entries: 匹配条目列表(空 / 非列表返回 None,不限制)

返回值: fn(text: str) -> bool 或 None


_entry_matcher(bucket: str, platform: str, key: str) -> 'Callable[[str], bool]'

内部方法 编译单个身份匹配条目(带 (桶, 平台, 条目) 键的预编译缓存)

  • bucket: 身份桶标识(adapters / bots / sessions / users)
  • platform: 平台名称
  • key: 匹配条目(精确 / glob / re: 正则)

返回值: fn(text: str) -> bool


_normalize(cfg: dict) -> 'tuple[Callable[[str], bool] | None, Callable[[str], bool] | None]'

内部方法 归一化绑定配置为 (modules 匹配器, blocked 匹配器)

条目统一走 :func:text_match.compile_entry_list(精确 / glob / re: 正则, 大小写不敏感)。空列表返回 None(不限制)。编译结果带预编译缓存。

  • cfg: 绑定配置字典(可含 modules / blocked 字段)

返回值: (modules 匹配器, blocked 匹配器)


_effective_module_cfg(platform: str, bot_id: str | None, session_id: str | None) -> dict | None

内部方法 沿"平台 → Bot → 会话"解析链计算生效的模块绑定

默认语义为整体覆盖:高优先级绑定完整替换低优先级; 子级绑定含 merge = true 时与低优先级逐条目并集 (modules / blocked 各自取并集)。merge 为控制键,不进入条目。

  • platform: 平台名称
  • bot_id (Bot): 用户 ID,None 表示不匹配 Bot 级
  • session_id: 会话 ID(群 / 频道 / 私聊),None 表示不匹配会话级

返回值: 生效绑定 {"modules": [...], "blocked": [...]},无绑定时返回 None


_get_binding(platform: str, bot_id: str | None, session_id: str | None) -> tuple[Callable[[str], bool] | None, Callable[[str], bool] | None] | None

内部方法 获取平台 / Bot / 会话的生效模块绑定(含 merge 链式合并)

  • platform: 平台名称
  • bot_id (Bot): 用户 ID,None 表示不匹配 Bot 级
  • session_id: 会话 ID(群 / 频道 / 私聊),None 表示不匹配会话级

返回值: (modules 匹配器, blocked 匹配器) 或 None


is_allowed(platform: str, bot_id: str | None, module_name: str | None, session_id: str | None = None) -> bool

判断模块是否允许在指定 Bot / 会话使用(① 模块维度)

模块名匹配大小写不敏感,条目支持 glob / re: 正则。 结果带 LRU 缓存,配置变更 / set / delete 时自动失效。 无绑定(默认)时遵循 default_allow;模块名为空(框架层资源)始终放行。

  • platform: 平台名称
  • bot_id (Bot): 用户 ID,None 表示不匹配 Bot 级绑定
  • module_name: 模块名称
  • session_id: 会话 ID(群 / 频道 / 私聊),None 表示不匹配会话级绑定

返回值: 是否允许

示例:

from ErisPulse.Core import scope
scope.is_allowed("onebot11", "123456", "Chat")
True
scope.is_allowed("onebot11", "123456", "Chat", "group_9")
True

_compute_allowed(platform: str, bot_id: str | None, session_id: str | None, module_key: str) -> bool

内部方法 计算模块是否允许(无缓存)


_resolve_identity_policy(platform: str, bot_id: str | None, session_id: str | None, user_id: str | None) -> str | None

内部方法 按特异性解析生效的身份策略:用户级 > 会话级 > Bot 级 > 适配器级

每个桶内:先精确命中,未命中再按 glob / re: 正则匹配该平台下全部条目。 取第一个产生策略的桶。

返回值: "allow" / "deny";均未配置绑定时返回 None


is_identity_allowed(platform: str, bot_id: str | None = None, session_id: str | None = None, user_id: str | None = None) -> bool

判断事件是否放行(② 身份维度:谁的事件收不收)

解析优先级:用户级 > 会话级 > Bot 级 > 适配器级,取最具体的 已配置绑定;均未配置时遵循 default_allow。 被拒绝的事件应在分发入口完全丢弃(不进入任何处理器)。

  • platform: 平台名称(适配器标识)
  • bot_id (Bot): 用户 ID,None 表示不匹配 Bot 级绑定
  • session_id: 会话 ID(群 / 频道 / 私聊),None 表示不匹配会话级
  • user_id: 用户 ID,None 表示不匹配用户级

返回值: 是否放行该事件

示例:

scope.is_identity_allowed("onebot11", "123456", "group_9", "999")
False

is_action_allowed(owner: str, action: str, name: str | None = None) -> bool

判断模块是否允许执行某类出站动作(④ 出站维度)

判定语义:默认允许——未配置、或 owner 为空(框架层调用)均视为允许。 规则判定顺序:deny = true → 拒绝;deny 列表命中 name → 拒绝; allow 列表非空且 name 未命中(或未提供)→ 拒绝;其余放行。 结果带 LRU 缓存,配置变更 / set / delete 时自动失效。

  • owner: 模块名(owner)

  • action: 动作类型,取值 self._ACTION_NAMES("send" / "api" / "request")

  • name: 具体调用名(send 传发送方法名如 "Text" / "Image",

           api 传标准动作名如 "get_group_info";request 无需提供)
    

返回值: 是否允许执行

示例:

scope.is_action_allowed("MyModule", "send")
True
scope.is_action_allowed("MyModule", "send", name="Image")
False

_compute_action_allowed(owner: str, action: str, name: str | None) -> bool

内部方法 计算出站动作是否允许(无缓存)


bot_id_from_event(event: dict) -> str(staticmethod)

从事件数据提取 Bot 标识

  • event: 事件数据(dict 或 Event 包装对象)

返回值 (Bot): 标识(account_id 优先,回退 user_id),无法识别时返回空字符串


session_id_from_event(event: dict) -> str(staticmethod)

从事件数据提取会话标识(群 / 频道 / 私聊的目标 ID)

直接按 ID 字段存在性提取(优先级 group > channel > guild > thread > user), 不做会话类型推断:meta(connect / disconnect / heartbeat)等不含任何 会话 ID 字段的事件会返回空字符串,不会触发 infer_receive_type 的 兜底推断与日志。语义与原实现(经推断后取值)等价——原实现中缺少 全部 ID 字段的事件同样返回空。

  • event: 事件数据(dict 或 Event 包装对象)

返回值: 会话 ID(如 group_id / channel_id / user_id),无法识别时返回空字符串


_put_cache(cache: OrderedDict, key: tuple, value: bool) -> None

内部方法 写入 LRU 缓存(超过容量时淘汰最旧)


_logger_trace(message: str) -> None(staticmethod)

内部方法 输出 TRACE 日志(logger 未就绪时静默)


_module_path(platform: str, bot_id: str | None, session_id: str | None) -> str(classmethod)

内部方法 模块维度路径(会话 > Bot > 平台)


_identity_path(platform: str, bot_id: str | None, session_id: str | None, user_id: str | None) -> str(classmethod)

内部方法 身份维度路径(用户 > 会话 > Bot > 适配器)


set_module(platform: str, bot_id: str | None = None, session_id: str | None = None, *, modules: list[str] | None = None, blocked: list[str] | None = None, merge: bool = False, persist: bool = True) -> None

绑定模块作用域(① 模块维度)

  • platform: 平台名称

  • bot_id (Bot): 用户 ID,None 且 session_id 为空时绑定平台级

  • session_id: 会话 ID(群 / 频道 / 私聊)。指定时绑定该会话;

                 否则有 bot_id 时绑定该 Bot;否则绑定平台级
    
  • modules: 白名单模块条目(精确 / glob / re: 正则)

  • blocked: 黑名单模块条目

  • merge: True 时与该级现有绑定逐条目并集(modules / blocked 各自合并),

            False 整体替换该节点(默认)
    
  • persist: 是否持久化到配置文件 (默认: True)

示例:

scope.set_module("onebot11", bot_id="123456", modules=["Chat", "Tool*"])
scope.set_module("onebot11", bot_id="123456", modules=["Music"], merge=True)

get_module(platform: str, bot_id: str | None = None, session_id: str | None = None, default: Any = None) -> Any

读取该层级原始模块绑定(不含 merge 跨级合并的最终生效结果, 需判定生效性请用 :meth:is_allowed)

  • platform: 平台名称
  • bot_id (Bot): 用户 ID
  • session_id: 会话 ID
  • default: 无绑定时返回值(默认 None)

返回值: {"modules": [...], "blocked": [...]} 或 default


delete_module(platform: str, bot_id: str | None = None, session_id: str | None = None, persist: bool = True) -> bool

移除该层级模块绑定(恢复 default_allow 兜底)

  • platform: 平台名称
  • bot_id (Bot): 用户 ID
  • session_id: 会话 ID
  • persist: 是否持久化到配置文件 (默认: True)

返回值: 是否存在并被删除


set_identity(platform: str, bot_id: str | None = None, session_id: str | None = None, user_id: str | None = None, *, allow: bool | None = None, deny: bool | None = None, persist: bool = True) -> None

绑定身份准入策略(② 身份维度,层级由参数决定:用户 > 会话 > Bot > 适配器)

绑定键支持 glob / re: 正则(如 user_id="spam_*")。

  • platform: 平台名称
  • bot_id (Bot): 用户 ID
  • session_id: 会话 ID
  • user_id: 用户 ID
  • allow: 放行该来源事件
  • deny: 拒绝该来源事件(allow 与 deny 同时给定时以 deny 为准)
  • persist: 是否持久化到配置文件 (默认: True)

示例:

scope.set_identity("onebot11", user_id="u_bad", deny=True)   # 拉黑
scope.set_identity("onebot11", user_id="spam_*", deny=True)  # glob 批量拉黑
scope.set_identity("onebot11", session_id="g1", allow=True)  # 例外放行

get_identity(platform: str, bot_id: str | None = None, session_id: str | None = None, user_id: str | None = None, default: Any = None) -> Any

读取该来源的身份绑定(原始配置形态,含 glob 键不展开; 需判定生效性请用 :meth:is_identity_allowed)

  • platform: 平台名称
  • bot_id (Bot): 用户 ID
  • session_id: 会话 ID
  • user_id: 用户 ID
  • default: 无绑定时返回值(默认 None)

返回值: {"allow": True} / {"deny": True} 或 default


delete_identity(platform: str, bot_id: str | None = None, session_id: str | None = None, user_id: str | None = None, persist: bool = True) -> bool

移除该来源的身份绑定(恢复 default_allow 兜底)

  • platform: 平台名称
  • bot_id (Bot): 用户 ID
  • session_id: 会话 ID
  • user_id: 用户 ID
  • persist: 是否持久化到配置文件 (默认: True)

返回值: 是否存在并被删除


set_action(module: str, action: str, *, allow: str | list[str] | None = None, deny: bool | str | list[str] | None = None, persist: bool = True) -> None

设置模块某类出站动作的限制规则(③ 出站维度)

仅影响本模块从事件处理器(handler 执行期 owner 上下文)发起的出站调用; 框架层内部调用(owner 为空)恒放行。

  • module: 模块名
  • action: 动作类型("send" / "api" / "request")
  • allow: 白名单条目(str 或 list;send 匹配发送方法名、api 匹配标准动作名)
  • deny: 全禁(True)或黑名单条目(str / list)
  • persist: 是否持久化到配置文件 (默认: True)

示例:

scope.set_action("MyModule", "send", deny=True)                # 全禁发送
scope.set_action("MyModule", "send", allow=["Text"])           # 仅允许发文本
scope.set_action("MyModule", "api", deny=["set_*", "leave_*"]) # 禁管理类 API

get_action(module: str, action: str, default: Any = None) -> Any

读取模块某类出站动作的原始规则(bool 原样存储,判定层归一化)

  • module: 模块名
  • action: 动作类型
  • default: 未配置时返回值(默认 None)

返回值: {"allow": [...], "deny": ...} / False 等原始形态或 default


delete_action(module: str, action: str | None = None, persist: bool = True) -> bool

移除模块的出站动作限制(恢复默认允许)

  • module: 模块名
  • action: 动作类型;None 表示移除该模块全部动作限制
  • persist: 是否持久化到配置文件 (默认: True)

返回值: 是否有内容被移除


_split_path(path: str) -> list[str](staticmethod)

内部方法 点分路径切分为段(过滤空段)


_node_at(path: str)

内部方法 按点分路径取节点(不存在返回 None)


get(path: str, default: Any = None) -> Any

读取作用域配置树中任意节(深拷贝)

  • path: 点分路径,如 "platforms.onebot11"、"identity.users.onebot11"

           (身份)、``"actions.MyModule"``(出站);
           空路径返回整棵树
    
  • default: 节不存在时的返回值(默认 None)

返回值: 节的深拷贝;不存在时返回 default

示例:

scope.get("actions.MyModule.send", {})
{"deny": True}

set(path: str, value: Any, persist: bool = True) -> None

写入作用域配置树中任意节(dict 深合并,标量直接覆盖)

写入后判定缓存自动失效,配置即时生效。

  • path: 点分路径,如 "bots.onebot11.123456"(模块绑定)、

           ``"identity.users.onebot11.u_bad"``(拉黑用户)、
    
           ``"actions.MyModule.send"``(出站规则)
    
  • value: 写入值(dict 时与现有值深合并,其余类型直接覆盖)

  • persist: 是否持久化到配置文件 (默认: True)。

    persist=False 为运行时绑定:写入覆盖层,任意配置写入/重载 均不会冲掉(但进程重启后丢失,且模块卸载时随调用方清理)

示例:

scope.set("bots.onebot11.123456", {"modules": ["Chat"], "blocked": []})
scope.set("identity.users.onebot11.u_bad", {"deny": True})   # 拉黑用户
scope.set("actions.MyModule.send", {"deny": True})           # 全禁发送

delete(path: str, persist: bool = True) -> bool

删除作用域配置树中任意键(父节经整节替换持久化,支持级联清空空父节)

  • path: 点分路径,如 "bots.onebot11.123456"、

           ``"identity.users.onebot11.u_bad"``、``"actions.MyModule.send"``
    
  • persist: 是否持久化到配置文件 (默认: True)。

    persist=False 为运行时删除:覆盖层记录删除标记, 任意配置写入/重载后仍保持"已删除"语义

返回值: 是否存在并被删除

示例:

scope.delete("bots.onebot11.123456")       # 移除 Bot 绑定
scope.delete("identity.users.onebot11.u_bad")  # 取消拉黑
scope.delete("actions.MyModule")           # 解除模块全部出站限制

__getitem__(path: str)

scope[path]:等价 :meth:get,节点不存在时抛 KeyError


__setitem__(path: str, value) -> None

scope[path] = value:等价 :meth:set(默认持久化)


__delitem__(path: str) -> None

del scope[path]:等价 :meth:delete,不存在时抛 KeyError


__contains__(path: str) -> bool

path in scope:判断配置树中是否存在该节点


clear() -> None

清空所有作用域配置(仅内存生效,不持久化;含运行时覆盖层)


stats() -> dict[str, int]

获取作用域运行统计

统计项:module_calls / module_filtered(模块维度)、 identity_checks / identity_denied(身份维度)、 action_checks / action_denied(出站维度)、 cache_hits / cache_misses(LRU 缓存)。

返回值: 统计字典


reset_stats() -> None

重置作用域运行统计


topology() -> dict

获取作用域配置的结构化数据(便于 WebUI 展示拓扑树)

等价于整棵配置树的深拷贝。

返回值: 全维度配置结构(模块 / 身份 / 文本 / 出站动作)