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_uniref import EventSceneRef, EventUserRef


@matcher.handle()
async def handle(user_ref: EventUserRef, scene_ref: EventSceneRef): ...

或调用 get_user_ref(bot, session, event=None) 和 get_scene_ref(bot, session, event=None)。 无法建立 Ref 时抛出 RefUnavailableError。

构造 Ref

from nonebot_plugin_alconna import At, UniMsg
from nonebot_plugin_uniref import RefContext


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

编码与恢复 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)

省略 bot 时由 Ref 限定候选；传入 bot 时严格绑定同一逻辑 Bot，不回退到其他账号。 ref_to_target() 只构造发送地址，不保证 Bot 当前在线、具有权限或能够触达目标。

模型定义

UserRef

SceneRef

SceneKind 包含 private、group、guild、channel_text、channel_category 和 channel_voice；codec 仍将它们编码为对应的可读字符串。

namespace 表示 ID 的相等范围；同一真人在不同 namespace 中可以拥有不同的 UserRef。Ref 不绑定运行中 的 Bot，也不是数据库行引用。平台 ID 仅在某个 App 内有效时，对应平台的 AppID 会进入 namespace； 它表示身份作用域，不表示 Bot 实例。仅按 Bot 隔离业务数据时，仍由业务插件加入 Bot 维度。

支持的 Adapter

{...} 表示决定 ID 相等范围的平台值；id= 后才是实际的 Ref.id。Scene 类型已经由 SceneRef.type 保存，所以 namespace 不再重复 private、group 或 channel。

QQ UserRef 用 c2c / group / guild 区分三套用户 ID。群成员按 App 和群隔离，不能直接转换为发送 Target；频道用户按 App 和 Guild 隔离，可以转换为频道私信 Target。