✨ Nonebot-Plugin-QQDetail

基于 NoneBot2 的 QQ 公开资料卡片插件

多目标查询 · 中文 / Emoji 卡片 · 文本输出 · 群通知 · 延时撤回

安装 · 使用 · 配置 · 常见问题 · 参与贡献

📖 功能

资料来自 OneBot V11 的陌生人及群成员接口。协议端返回的字段不同，插件只展示可用资料；扩展字段的支持情况以所用协议端为准。

💿 安装

nb plugin install nonebot-plugin-qqdetail

uv add nonebot-plugin-qqdetail

[tool.nonebot]
plugins = ["nonebot_plugin_qqdetail"]

nonebot.load_plugin("nonebot_plugin_qqdetail")

🎉 使用

示例使用 / 前缀，实际前缀遵循机器人配置中的 COMMAND_START。命令同时支持群聊和私聊。

默认别名：qq资料、查qq、查q、box、盒、开盒。

文本展示示例

QQ号：123456
昵称：示例用户 🐱
群昵称：示例群名片
群身份：成员
性别：男
电话：138******78
邮箱：a***@example.com
QQ等级：太阳x1 月亮x1 (20)
签名：你好，NoneBot！

示例仅展示部分字段。实际输出由配置和协议端返回的数据决定，默认使用图片。

⚙️ 配置

所有配置均为可选项，在机器人项目的 .env 文件中设置即可。

常用配置示例：

QQDETAIL_OUTPUT_MODE=image
QQDETAIL_RECALL_TIME=10
QQDETAIL_DESENSITIZE=true
QQDETAIL_DISPLAY_OPTIONS=["QQ号","昵称","群昵称","性别","QQ等级","签名"]

查询权限与群通知

QQDETAIL_ONLY_ADMIN=true
QQDETAIL_PROTECT_IDS=["123456"]

QQDETAIL_AUTO_ENTER=true
QQDETAIL_AUTO_EXIT=false
QQDETAIL_AUTO_GROUPS=["234567"]

机器人始终不可查询。SUPERUSERS 和保护名单禁止他人查询，用户可以自查；群主、群管理员身份不会自动授予 SUPERUSERS 权限。

自动通知跳过机器人、SUPERUSERS 和保护名单，不受手动查询的 qqdetail_only_admin 限制，也不阻断其他插件。通知查询失败时保持静默。

QQDETAIL_DISPLAY_OPTIONS=["QQ号","nickname","card","qqLevel","long_nick"]

💬 常见问题

为什么部分资料没有显示？

私聊只查询陌生人资料，群聊还会查询群成员资料。检查 qqdetail_display_options 是否包含目标字段，以及协议端是否返回有效值。任一接口失败时仍会使用另一来源的可用资料，退群后的群成员信息可能无法获取。

图片发送异常时如何使用文本？

本次查询加上 --text，或设置 QQDETAIL_OUTPUT_MODE=text。头像下载失败会使用占位头像，字体或图片渲染失败会自动回退为文本。插件附带中文和单色 Emoji 字体，无需另行安装系统字体。

长资料会如何展示？

卡片每页最多 24 行，总计超过 160 行时会提示截断；单字段最多 4096 个字符。文本按 3000 字符分段发送，各页或各段分别撤回。

如何保留查询结果，或者沿用原来的文本输出？

QQDETAIL_OUTPUT_MODE=text
QQDETAIL_RECALL_TIME=0

qqdetail_recall_time=0 对图片和文本均可关闭撤回。

🤝 参与贡献

欢迎通过 Bug 反馈 和 功能建议 参与改进。反馈问题时请附上版本、命令、相关配置和复现步骤，并移除个人资料与密钥。

Fork 仓库并创建分支，使用 uv 准备开发环境：

uv sync --locked
uv pip install "nonebot2[fastapi]" nonebug pytest pytest-asyncio ruff

修改代码时补充相关测试和文档，再提交 PR。新增运行依赖使用 uv add <package>，同时提交 pyproject.toml 与 uv.lock。分支 push 和 PR 会自动运行 CI，在 Ubuntu / Python 3.13 上执行格式检查、测试和包构建。

⚠️ 重要提醒

• 学习交流用途：本插件仅供学习和交流使用，请勿用于任何非法目的
• 隐私保护：查询用户信息时请尊重他人隐私，确保使用符合相关法律法规
• 免责声明：用户需对自身使用行为负责，开发者不对使用本插件产生的任何后果承担责任

📃 许可与致谢

本项目采用 GNU AGPL v3（AGPL-3.0-only）。 中文与 Emoji 字体来自 Noto 项目，各自遵循 SIL OFL 1.1，详见 字体说明。

🙏 致谢

• astrbot_plugin_box为本插件的设计思路提供参考。