nonebot-plugin-uninfo

✨ Nonebot2 多平台的会话信息(用户、群组、频道)获取插件 ✨

license Python NoneBot

本插件提供了多个模型，可以从不同适配器的 Bot 和 Event 中提取与会话相关的属性

安装

使用 nb-cli

nb plugin install nonebot-plugin-uninfo

使用 pip

pip install nonebot-plugin-uninfo

使用

获取 `Session`：

from nonebot_plugin_uninfo import get_session

@matcher.handle()
async def handle(bot: Bot, event: Event):
    session = await get_session(bot, event)

或使用依赖注入的形式：

from nonebot_plugin_uninfo import Uninfo, UniSession, Session

@matcher.handle()
async def handle(session: Session = UniSession()):
    ...

@matcher.handle()
async def handle1(session: Uninfo):
    ...

拉取用户/群组/频道列表：

from nonebot_plugin_uninfo import SceneType, QryItrface

@matcher.handle()
async def handle(interface: QryItrface):
    users = await interface.get_users()
    groups = await interface.get_scenes(SceneType.GROUP)
    members = await interface.get_members(groups[0].type, groups[0].id)

使用内建的 `Permission`:

from nonebot import on_command
from nonebot_plugin_uninfo import ADMIN

matcher = on_command("inspect", permission=ADMIN())

模型定义

`User`

属性	类型	含义	备注
`id`	str	用户 id
`name`	str \| None	用户名称
`nick`	str \| None	用户昵称	好友备注
`avatar`	str \| None	用户头像
`gender`	str	用户性别

`Scene`

属性	类型	含义	备注
`id`	str	场景 id
`type`	SceneType	场景类型	可分为 `Private`, `Group`, `Guild` 和 `Channel_XXX`
`name`	str \| None	场景名称
`avatar`	str \| None	场景图标
`parent`	Scene \| None	父级场景	适用于频道的二级群组场景, 或针对临时会话的来源群组

`Member`

属性	类型	含义	备注
`user`	User	成员的用户信息
`nick`	str \| None	成员昵称
`role`	str \| None	成员角色组	当可能存在多个角色组时，此处会使用 level 最高的那个
`mute`	MuteInfo \| None	成员禁言信息
`joined_at`	datetime \| None	成员加入时间

`Session`

属性	类型	含义	备注
`self_id`	str	机器人 id
`adapter`	str	适配器名称
`scope`	str	适配器范围	相比 adapter 更指向实际平台
`scene`	Scene	事件场景
`user`	User	用户信息
`member`	Member \| None	成员信息	仅适用于群组,频道场景
`operator`	Member \| None	操作者信息	仅适用于群组,频道场景

示例

from nonebot_plugin_uninfo import Uninfo
from nonebot import on_command

matcher = on_command("inspect", aliases={"查看"}, priority=1)


@matcher.handle()
async def inspect(session: Uninfo):
    texts = [
        f"平台名: {session.adapter} | {session.scope}",
        f"用户ID: {session.user.name + ' | ' if session.user.name else ''}{session.user.id}",
        f"自身ID: {session.self_id}",
        f"事件场景: {session.scene.type.name}",
        f"频道 ID: {session.scene.name + ' | ' if session.scene.name else ''}{session.scene.id}"
    ]
    if session.scene.parent:
        texts.append(f"群组 ID: {session.scene.parent.name + ' | ' if session.scene.parent.name else ''}{session.scene.parent.id}")
    if session.member:
        texts.append(f"成员 ID: {session.member.nick + ' | ' if session.member.nick else ''}{session.member.id}")
    await matcher.send("\n".join(texts))

支持的 adapter

OneBot v11
OneBot v12
Console
Kook (Kaiheila)
Github
Telegram
Feishu
Discord
QQ
Satori
DoDo
Kritor
Mirai
Tailchat
Mail
WXMP
heybox
Milky
EFChat
Yuhun
Bililive

鸣谢

nonebot-plugin-session 与 nonebot-plugin-userinfo 项目的灵感来源以及部分实现的参考

Metadata

Release files for nonebot-plugin-uninfo 0.11.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nonebot-plugin-uninfo 0.11.2
File	Size	Uploaded	Provenance
nonebot_plugin_uninfo-0.11.2.tar.gz	42.5 kB	Aug 31, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for nonebot-plugin-uninfo 0.11.2
File	Interpreter	ABI	Platform	Reset
nonebot_plugin_uninfo-0.11.2-py3-none-any.whl 68.3 kB Aug 31, 2026 Without provenance	Python 3	none	any	Details

Total release size: 110.8 kB

Release files / nonebot_plugin_uninfo-0.11.2.tar.gz

Download URL	nonebot_plugin_uninfo-0.11.2.tar.gz
Size	42.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`fd649a293f7a6b727e5ee31af0984285fc4af0cea876a60006c393908b1cf918`
BLAKE2b-256 checksum How to use checksums	`33bde3ff9a211f3bc9d9e48a4b2ae5b45fbb55fdc5a1edb0307e04aa8af35101`
Upload date	Aug 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`pdm/2.29.0 CPython/3.12.3 Linux/6.17.0-1022-azure`

Release files / nonebot_plugin_uninfo-0.11.2-py3-none-any.whl

Download URL	nonebot_plugin_uninfo-0.11.2-py3-none-any.whl
Size	68.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`47a42e16247649986affedc9c649d57a12d026b19f4d9c0c22829b4a585411a4`
BLAKE2b-256 checksum How to use checksums	`4ff237f1c7620d20891c652102bdd52681f2e6a2a079d2478aff4d0e59317c53`
Upload date	Aug 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`pdm/2.29.0 CPython/3.12.3 Linux/6.17.0-1022-azure`

Security for nonebot-plugin-uninfo 0.11.2

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.