nonebot-plugin-uniref

✨ NoneBot2 可持久化的跨平台实体引用插件 ✨

本插件提供可比较、可序列化的 UserRef 与 SceneRef，用于在 NoneBot 插件中持久化用户和场景身份。

安装

• 使用 nb-cli

nb plugin install nonebot-plugin-uniref

• 使用 pip

pip install nonebot-plugin-uniref

使用

从事件上下文获取和构造 Ref

from nonebot_plugin_alconna import At, UniMsg
from nonebot_plugin_uniref import RefContext


@matcher.handle()
async def handle(message: UniMsg, refs: RefContext):
    user = refs.user_ref
    scene = refs.scene_ref
    user_ids = [at.target for at in message[At] if at.flag == "user"]
    users = [refs.build_user_ref(user_id) for user_id in user_ids]
    data_scene = refs.parent_scene_ref or scene

编码与恢复 Ref

from nonebot_plugin_uniref import UserRef, decode_ref, encode_ref

ref = UserRef(namespace="QQClient", id="123")
value = encode_ref(ref)

assert value == "user:QQClient:123"
assert decode_ref(value) == ref

构造 Alconna Target

from nonebot_plugin_uniref import decode_ref, ref_to_target

ref = decode_ref("scene:QQClient:group:456")
target = ref_to_target(ref, bot=bot)

模型定义

UserRef

SceneRef

SceneKind 包含 private、group、guild、channel_text、channel_category 和 channel_voice。

支持的 Adapter

{...} 表示决定 ID 有效范围的平台值；id= 后是被引用实体自身的 Ref.id。namespace 表达平台空间、 签发方、ID family，以及无法由其他字段表达的必要局部作用域。