QQbox - 仿QQ聊天气泡生成插件

插件简介

QQbox 是一个基于 AstrBot 框架的插件，用于生成高度仿真的QQ风格聊天气泡图片。它可以模拟QQ聊天界面的完整视觉效果，包括用户头像、昵称、自定义头衔和聊天气泡。插件支持纯文字、纯图片、图文混合以及GIF动画消息的生成。

主要特性

• 🎨 逼真的QQ风格：完美还原QQ聊天气泡的视觉效果
• 👥 智能用户管理：自动获取并缓存QQ用户昵称和头像
• 🏷️ 个性化头衔系统：支持自定义头衔文字和颜色
• 📝 备注名功能：可为用户设置显示备注名（覆盖原昵称）
• 🖼️ 多媒体支持：支持文字、图片、图文混合、GIF动画
• 🎯 高清输出：采用4倍超采样技术，生成超清晰图片
• 💾 数据持久化：所有用户设置自动保存到本地文件
• ⚡ 异步优化：全异步设计，高性能处理

安装配置

前置要求

• AstrBot 框架
• Python 3.10 或更高版本
• Pillow (PIL) 图像处理库
• 必要的字体文件

字体文件说明

插件需要以下字体文件（请确保路径正确）：

1. 气泡字体：用于聊天消息内容显示
2. 昵称字体：用于用户昵称/备注显示
3. 头衔字体：用于头衔气泡文字显示

使用指南

命令结构

所有命令均以 /qb 开头，基本格式：/qb [子命令] [参数]

核心命令

1. 生成文字聊天气泡

/qb echo [QQ号] [消息内容]

生成指定QQ用户发送文字消息的气泡图片。

示例：

/qb echo 123456789 大家好，欢迎加入本群！

2. 生成图片聊天气泡

/qb img [QQ号]

配合图片消息使用，生成指定QQ用户的图片聊天气泡。

使用方式：

• 发送图片并回复 /qb img [QQ号]
• 在消息中包含图片和 /qb img [QQ号]

3. 生成GIF聊天气泡

/qb gif [QQ号]

生成指定QQ用户的GIF动画聊天气泡，使用方法同图片命令。

4. 设置头衔颜色

/qb sc [QQ号] [颜色编号]

设置用户的头衔气泡背景颜色。

颜色编号：

• 1 - 灰色（默认）
• 2 - 紫色
• 3 - 黄色
• 4 - 绿色

示例：

/qb sc 123456789 3  # 设置为黄色头衔

5. 设置头衔文字

/qb st [QQ号] [头衔文字]

设置用户显示的头衔内容。

示例：

/qb st 123456789 管理员

6. 设置备注名

/qb sn [QQ号] [备注名]

设置用户的显示备注名（会覆盖从API获取的昵称）。

示例：

/qb sn 123456789 张三

7. 获取帮助

/qb help

显示完整的命令使用说明。

8.更新头像

/qb ua [QQ号]

更新对应用户的头像

使用示例

场景一：创建完整的用户身份

# 设置用户信息
/qb sn 123456789 张三
/qb st 123456789 群主
/qb sc 123456789 3

# 生成消息
/qb echo 123456789 欢迎大家积极参与讨论！

场景二：快速生成消息

# 直接生成消息（使用默认或已缓存的信息）
/qb echo 987654321 这个功能真好用！

场景三：发送图片消息

1. 发送一张图片
2. 回复该图片并输入：/qb img 123456789

高级用法

批量设置用户信息

可以一次性设置多个用户的完整信息：

# 用户A
/qb sn 111111111 张三
/qb st 111111111 管理员
/qb sc 111111111 2

# 用户B
/qb sn 222222222 李四
/qb st 222222222 活跃成员
/qb sc 222222222 4

数据管理

• 用户信息自动保存在 qq_data.json 文件中
• 头像图片缓存在指定的 avatar_image_path 目录
• 重启插件后所有设置保持不变

技术细节

头像获取流程

1. 首先检查本地缓存
2. 若无缓存，通过OneBot协议获取（如果可用）
3. 否则通过公共API获取
4. 下载并裁剪为圆形头像
5. 保存到本地缓存目录

昵称获取优先级

1. 用户设置的备注名（最高优先级）
2. OneBot协议获取的昵称
3. 公共API获取的昵称
4. QQ号本身（兜底）

气泡生成技术

• 超采样渲染：内部使用4倍分辨率渲染后降采样，确保边缘平滑
• 智能换行：自动处理中英文混合文本的换行
• 圆角优化：动态计算最佳圆角半径
• GIF优化：静态元素分离渲染，减少重复计算

故障排除

常见问题

1. 字体加载失败

错误信息：字体在加载中或字体没有被正确的加载
解决方法：
1. 检查配置文件中的字体路径是否正确
2. 确保字体文件存在且有读取权限
3. 重启插件

2. 头像获取失败

错误信息：下载头像失败
解决方法：
1. 检查网络连接
2. 确认QQ号格式正确（纯数字）
3. 尝试手动访问头像URL：https://q1.qlogo.cn/g?b=qq&nk=QQ号&s=640

3. 图片生成缓慢

原因：首次生成需要下载头像和字体
优化：首次使用后会缓存，后续生成会变快

4. 命令不响应

检查：
1. 命令格式是否正确
2. QQ号是否为纯数字
3. 是否有必要的权限
4. 查看日志文件中的错误信息

日志查看

插件运行日志可在AstrBot的日志系统中查看，关键词：QQbox

数据文件说明

目录结构

数据目录/
├── avatars/              # 头像缓存目录
│   ├── 123456789-.png   # 用户头像文件
│   └── qq_data.json     # 用户数据文件
└── fonts/               # 字体目录（需手动放置）

qq_data.json 格式

{
    "123456789": {
        "nickname": "用户昵称",
        "color": 3,
        "content": "头衔文字",
        "notes": "备注名"
    }
}

性能优化建议

1. 字体预加载：插件启动时会异步加载字体，首次使用前可能稍有延迟
2. 头像缓存：已下载的头像会永久缓存，可定期清理旧文件
3. 内存管理：GIF处理可能占用较多内存，建议控制GIF尺寸
4. 网络优化：使用稳定的网络环境以确保API调用成功率

更新日志

v1.0.0

• 初始版本发布
• 基础聊天气泡生成功能
• 用户信息管理系统
• 数据持久化支持

v1.1.9（当前版本）

• 新增GIF动画支持
• 优化字体加载机制
• 改进错误处理和日志
• 性能优化和内存管理改进

注意事项

1. 隐私保护：本插件仅用于生成娱乐性图片，请勿用于侵犯他人隐私
2. API限制：公共API有调用频率限制，请合理使用
3. 存储空间：头像缓存会占用磁盘空间，建议定期清理
4. 字体版权：请确保使用的字体有合法授权
5. 兼容性：建议在AstrBot最新版本上使用

开发者信息

• 插件名称：QQbox
• 作者：Lishining
• 版本：1.2.8
• 框架：AstrBot
• 最后更新：2026.02.23
• QQ群： 1083090761

支持与反馈

如有问题或建议，请：

1. 查看AstrBot官方文档
2. 检查日志文件获取详细错误信息
3. 确保使用最新版本的插件
4. 在相关社区寻求帮助

---

免责声明：本插件仅供学习和娱乐使用。生成的内容不应用于任何商业用途或侵犯他人权益的行为。使用者应对生成内容负全部责任。