!
为 AstrBot 提供表情包下载、整理、智能发送与自动收集功能。通过 WebUI 管理多个表情包，按会话或人格组合使用，并支持分类选图、语义检索和云端同步。
✨ 能做什么
| 你想做的事 | 表情包管理器如何帮你 | | -------------------- | ------------------------------------------------------------------------ | | 先让 Bot 用上表情 | 从资源广场安装表情包，设置使用规则，即可开始使用；无需额外选图模型或图床 | | 为不同聊天搭配表情 | 按默认、会话或人格绑定多个包，自由组合；无需修改人格提示词 | | 找到更贴合语境的图片 | 分类级或图片级标签，交给主模型自选或额外模型辅助；按需准备语义索引 | | 整理越来越大的图库 | WebUI 分类预览、拖拽整理、批量操作、跨包移动，资源包更新前逐图查看差异 | | 留下聊天里的好表情 | 自动识别、分类、去重，支持人工审核后入包与增量生成向量 | | 备份和分享自己的收藏 | 支持多种图床同步，也能按开放协议制作、发布社区表情包 |
第一次用？ 先安装一个表情包、保存使用规则，就能体验默认的“分类级标签 · 主模型自选”，无需额外的选图模型调用。语义选图和自动收集可按需开启，相关模型调用费用取决于所用服务。
📑 目录
📢 通知
[!IMPORTANT]
升级 AstrBot 前，建议先将本插件更新至 v5.2.9 或更新版本。
> 旧版插件可能与 AstrBot Desktop 的核心依赖锁冲突，导致安装失败。请先更新插件，按提示完成依赖安装并重载，再升级 AstrBot。
> 已有 R2 配置和桶内图片无需迁移，也无需手动降级 AstrBot 的核心依赖。
旧版本升级说明：v5.0.1 提示词模板
v5.0.1 提供新版提示词，请按需重置默认模板。 升级并重载插件后，进入 设置中心 → 提示词模板 → 恢复默认模板 → 保存并应用，载入新版前缀、后缀及附加模板。已有自定义内容请先复制备份，再按需合并回新版模板。
🛠️ 第一次使用
在 AstrBot 插件市场搜索 表情包管理器 安装
- 安装插件后，进入 AstrBot WebUI → 插件页面 → 表情包管理器。
- 打开资源广场，下载一个官方或社区表情包。
- 进入设置中心 → 使用规则，将下载的包设为默认，或绑定到指定会话、人格，然后保存规则。同一规则可多选表情包：展开“添加表情包”，按名称或 ID 搜索并勾选；在已选列表中上移、下移或移除，第一项为主表情包。
- 开始聊天。插件会自动提供当前表情包的分类提示，无需修改人格；有合适的表情时，模型可以配合文字发送，也可以只发表情。
❓ 常见问题
必须配置图床吗？ 不需要。图床用于云端同步，本地管理与表情发送可独立使用。
下载了新包，为什么聊天还用原来的？ 请在设置中心保存使用规则。下载或切换管理页的表情包，不会自动修改聊天选包规则。
可以流式回复吗？ 可以。经过 AstrBot 流式消息管线的标签会在发送前解析，有歧义的片段会暂时缓冲，图片在回复结束后发送。
必须进行语义化吗？ 不需要。“按分类取图”即可使用；希望按图片描述检索时，再配置语义化。
☁️ 支持的图床
图床仅用于云端同步，可在设置中心 → 存储与下载中选择并配置：
- 兰空图床（Lsky Pro 开源版 2.x）
- Cloudflare R2
- WebDAV
- StarDots
boto3 / botocore，避免其 python-dateutil<3 限制与桌面端依赖锁冲突。已有账户 ID、访问密钥、存储桶、路径前缀和公开访问地址配置继续使用，无需迁移桶内图片。
📚 协议与创作指引
协议文档
如何创建并分享自己的表情包（Issue / PR）
- 前往索引仓库 README 阅读完整提交指引：
- 按协议准备你的表情包仓库结构（manifest、memes、previews），并确保仓库可访问。
- 如果你会编辑索引文件：
- 如果你不会编辑索引文件：
- 你也可以先参考示例仓库模板：
建议：先在本地或测试环境通过“资源广场安装”验证一次，确保索引条目可安装、可预览、分类描述清晰。
🖥️ WebUI 管理界面
资源广场
浏览和安装官方、社区表情包，也支持通过 GitHub 仓库地址安装索引之外的表情包。
已安装的资源包有新版时，可在可更新栏目查看。
!资源广场
查看资源包更新预览
表情包管理
按分类预览图片，上传、删除、拖拽移动或批量整理表情，编辑分类描述，并切换不同表情包进行管理。
桌面端可拖拽移动图片，触屏端可长按进入多选，再批量操作。
切换到任意已安装的表情包即可直接在该包内上传、删除、拖拽移动、批量整理和编辑分类，修改不会落到其他包。新建表情包时可以填写自定义包 ID（留空自动生成），ID 只能包含小写字母、数字、点、下划线和短横线，重复 ID 会被拒绝。
语义表情包
普通模式按分类选择表情；语义模式会先为图片生成描述和检索向量，再根据对话寻找更贴切的图片。使用前需在设置中心配置图片描述模型与向量模型，并在“语义化”页面完成处理。生成描述和向量会调用对应模型，费用取决于所用服务。
语义化页面可以查看处理进度、继续任务和重试失败图片。自动收集的审核与向量设置见下文；待分类或描述未完成的图片需先在语义化页面处理，不影响已有有效向量的检索。
设置中心
在模式页（原“配图”）选择标签粒度与选择者，点击流程节点配置，再保存全部更改；使用规则单独保存。语义化页“模型设置”直达数据准备，旧链接继续有效。
导入与备份里的压缩包导入采用分片上传，导入大体积表情包时不会因为面板单次上传上限而失败；导入前会先校验包结构与兼容性，确认后再写入。
| 标签粒度 | 由谁选择 | 原模式名称 | | --- | --- | --- | | 分类级（随机取图） | 主模型 | 原生分类标签 | | 分类级（随机取图） | 额外辅助 | 辅助模型分类标签 | | 图片级（语义检索） | 主模型 | Tool 语义检索 | | 图片级（语义检索） | 额外辅助 | 辅助模型语义检索 |
旧配置保持原行为。图片级标签需先生成描述与向量索引；索引未就绪时回退对应分类方式，Tool 不可用时回退主模型分类自选。无候选、主动弃选或运行失败时不补发。
额外辅助支持聊天模型或 System One 决策服务，均增加请求。聊天模型留空跟随主模型；决策服务需配置地址、密钥和模型 ID，单选或不发送，失败保留文字。语义检索默认由聊天模型生成检索词，也可直接使用回复文本。
发送概率与 Tool 调用策略
「表情发送 → 出现时机」中的 表情发送概率（原「表情出现概率」）适用于所有自动配图组合，且只控制本轮自动附图资格。0% 不自动附图；100% 允许自动配图，但不强迫检索或出图。通过标记生成的纯表情回复也遵守该门控。配图模型请求和工具检索仍按各自流程执行。
启用主动发送表情工具默认开启：send_meme(target) 可按分类或本轮 search_memes 候选 ID 发图，遵守权限与图包绑定。可多次调用，不受自动配图概率和数量上限限制；调用后不再自动补图。完全停用发图需关闭此工具，并将自动配图概率设为 0%。
选择「图片级标签（语义）＋主模型自行选择」，点击流程中的「工具调用策略」，可用独立滑动开关启用 Tool 概率触发：
- 默认关闭，保留原有模型自主调用行为，升级旧配置不会自动增加前置请求。
- 开启后显示 工具调用概率，初始值为 100%。命中就用本轮回复 Provider 和 model 尝试一次
search_memes；未命中时本轮不提供或执行该工具，其他工具照常可用。0% 不检索，100% 每轮尝试，不要求额外辅助模型。 - 此策略可能增加一次当前主模型的前置请求。检索结果交给正常回复流程，仍由主模型从真实候选中决定是否选图。接口不支持强制调用、参数错误、检索失败或没有合适候选时，跳过表情并记录原因，正常文字回复继续；不额外重试或切换模式补发。
- 两个概率互相独立。例如自动发送 0%、检索调用 100% 仍会尝试检索，但不会自动附图，独立的主动发送工具仍可使用。一次用户消息触发的完整回复每个门控只判定一次；工具循环、流式输出、重试和多张候选复用该结果，自动配图的数量上限继续生效。
generation.emotion.probability、semantic.tool_probability_enabled（默认 false）和 semantic.tool_call_probability（默认 100），概率范围均为 0–100。
查看流程图中的配置入口示例
使用规则支持多包混用：同一默认、会话或人格规则可同时选择多个表情包。例如，日常聊天混用几个常用包，为指定会话或人格另设一组组合。通过“添加表情包”搜索并勾选，无需按住 Ctrl / Command；已选列表支持上移、下移和移除，越靠前越优先，第一项为主表情包，聊天上传写入该包。规则从上到下匹配，未匹配时使用默认规则。管理页切换表情包只影响浏览和整理，不改变聊天使用规则。
🤖 自动收集表情包
管理员可引用或附图发送 /表情管理 收集表情；连续整理用“开始收集／结束收集”。仅接收本人在当前聊天发送的图片，每条最多 10 张，空闲 10 分钟结束，已提交任务继续处理。手动收集无需开启自动监听，复用模型与审核设置，跳过来源、抽样和冷却限制。目标使用固定包或会话主包，连续收集期间不变。
在设置中心 → 自动收集的流程中，点击“来源与频率”开启，再点击“图片理解与判断”选择支持图片输入的视觉模型。插件会识别收到的图片，从目标表情包的现有分类中选择合适的分类，并进行去重。
默认由视觉模型一次完成识别、收录与分类；也可先理解图片，再用共享决策服务判断。决策不确定、分类不明或调用失败时强制人工复核，即使关闭普通人工审核也不自动入包。
可选的内容规则筛选位于“图片理解与判断”，默认关闭。视觉路径在同次识别中追加规则，决策路径依据图片理解的文字证据判断；规则可修改，清空使用默认值，未通过的不收录，不重新处理已有图库或待审图片。
平台明确标记为表情的图片按配置抽样识别；普通图片或缺少平台分类的图片首次仅记录，重复出现后逐步提高识别概率。
采样概率、重复计数与识别间隔
普通图片或缺少平台分类的图片第二次出现时有 45% 的识别采样概率，之后逐次提高，第八次必定触发。同一发送者在不同消息中重复发送也会计数；连续 7 天未出现的记录会过期。单条消息最多处理的图片数可设置为 1–10 张，默认 1 张；同一来源最短识别间隔限制的是不同消息的入队时间，不影响重复次数记录。
自动收集默认关闭，识图需要调用视觉模型。开启后默认启用人工审核，可在管理页统一处理候选图片：
- 进入表情包管理，切换到收集目标包。
- 有待审核图片时，选包框右侧显示待审核表情按钮，点击查看图片、建议分类和两项置信度。
- 默认按分类置信度从高到低排列，低把握度排在后面；可筛选分类、调整排序和修改接收分类，然后接收选中的图片。
- 不需要的图片可以丢弃；勾选“不再收集”后，相同内容不会再次进入该包的候选列表。
⚠️ 兼容性
需要 AstrBot 4.17.0 或更新版本。
部分微信 4.x 接入中，JPG/PNG 可能显示为普通图片而非表情气泡，可尝试开启设置中心 → 表情发送 → 静态图转 GIF 发送。该选项默认关闭，仅在发送时转换，不修改图库原文件；其他平台通常无需开启。
AstrBot 内置 send_message_to_user 自动支持表情标记和辅助选图，沿用权限、自动配图概率与整轮数量限制。跨会话按目标人格选包，同一目标不重复补图。
其他插件自行请求模型或发送消息时，可通过本插件的公开接口接入表情处理。接口说明与示例见 开发指南 → 插件联动接口，流式处理方式与边界见 解析与消息发送。
📝 使用指令
当前大部分功能都可以通过 AstrBot WebUI 管理界面操作，无需使用指令。以下为指令列表，供 CLI 用户参考：
| 指令 | 描述 |
| -------------------------------------- | --------------------------------------------------- |
| /表情管理 查看图库 | 📚 列出所有可用表情类别 |
| /表情管理 添加分类 [类别名称] [描述] | ➕ 创建新的表情包分类，可只输入名称后按提示补充描述 |
| /表情管理 添加表情 [类别] | ➕ 通过聊天上传表情到指定类别 |
| /表情管理 收集表情 | 引用消息或附图，识别分类并按审核设置收录 |
| /表情管理 开始收集 | 连续接收自己在当前聊天发送的图片 |
| /表情管理 结束收集 | 停止接收新图片并汇总，已提交任务继续处理 |
| /表情管理 恢复默认表情包 | ♻️ 从官方仓库一键安装首个官方表情包并设为默认 |
| /表情管理 清空指定类型 [类别] | ⚠️ 清空指定类别中的表情包，保留类型本身 |
| /表情管理 清空全部 | ⚠️ 清空全部表情包，保留所有类型和描述配置 |
| /表情管理 删除类型本身 [类别] | ⚠️ 删除指定类型及其描述配置 |
| /表情管理 同步状态 | 🔄 检查同步状态 |
| /表情管理 同步到云端 | ☁️ 将本地表情同步到云端 |
| /表情管理 从云端同步 | ⬇️ 从云端同步表情到本地 |
| /表情管理 覆盖到云端 | ⚠️ 让云端与本地完全一致 |
| /表情管理 从云端覆盖 | ⚠️ 让本地与云端完全一致 |
📜 更新日志
当前版本：v5.3.0
- 支持可选 System One 决策辅助选图与收集判断，不确定或判断失败的收集结果强制留待人工复核。
- 内置
send_message_to_user支持表情标记和辅助选图，保留权限、目标会话选包及重复发送保护。 - 默认启用主动
send_meme(target)工具，可发送分类图片或本轮检索候选；主动调用不受自动配图概率与数量上限限制。 - 管理员可用“收集表情”引用快收，或用“开始收集／结束收集”连续整理图片，无需开启自动监听。
- 重构“模式”设置流程、模型选择与参数弹窗，兼容旧深链，并修复 QQ 官方流式正文及工具补图问题。
完整版本记录请查看 CHANGELOG.md。
✨ Star
感谢每一位使用、反馈、分享表情包和贡献代码的朋友。如果这个插件对你有帮助，欢迎点一个 Star。
分享，让你我走到了今天。
📄 许可证
本项目基于 MIT 许可证开源。