本插件提供可比较、可序列化的 UserRef 与 SceneRef，用于在 NoneBot 插件中持久化用户和场景身份。
- 使用 nb-cli
nb plugin install nonebot-plugin-uniref- 使用 pip
pip install nonebot-plugin-unireffrom 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 scenefrom 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) == reffrom nonebot_plugin_uniref import decode_ref, ref_to_target
ref = decode_ref("scene:QQClient:group:456")
target = ref_to_target(ref, bot=bot)| 属性 | 类型 | 含义 |
|---|---|---|
namespace |
str | 用户 ID 所属的身份命名空间 |
id |
str | 用户 ID |
| 属性 | 类型 | 含义 |
|---|---|---|
namespace |
str | 场景 ID 所属的身份命名空间 |
type |
SceneKind |
UniRef 定义的场景种类 |
id |
str | 场景 ID |
SceneKind 包含 private、group、guild、channel_text、channel_category 和 channel_voice。
{...} 表示决定 ID 有效范围的平台值；id= 后是被引用实体自身的 Ref.id。namespace 表达平台空间、
签发方、ID family，以及无法由其他字段表达的必要局部作用域。
| 已验证 Adapter / 场景 | UserRef：namespace；ID | SceneRef：namespace；type；ID |
|---|---|---|
| OneBot V11、Milky |
QQClient；id=QQ 号 |
QQClient；private：QQ 号；group：群号 |
| Telegram |
Telegram；id=User ID |
private、group：Telegram；id=Chat ID；channel_text：Telegram:{Chat ID}；id=Thread ID |
| Discord |
Discord；id=User Snowflake |
Discord；private、guild、Channel；id=Snowflake |
| QQ C2C |
QQAPI:{QQ AppID}:c2c；id=user_openid
|
QQAPI:{QQ AppID}；private；id=user_openid
|
| QQ 群聊 |
QQAPI:{QQ AppID}:group:{group_openid}；id=member_openid
|
QQAPI:{QQ AppID}；group；id=group_openid
|
| QQ 公开文字子频道 |
QQAPI:{QQ AppID}:guild:{guild_id}；id=频道用户 ID |
QQAPI:{QQ AppID}；channel_text；id=channel_id
|
| 飞书私聊 |
Feishu:{Feishu AppID}；id=open_id
|
同 namespace；private；id=open_id
|
| 飞书群聊 |
Feishu:{Feishu AppID}；id=open_id
|
Feishu；group；id=chat_id
|
