MaiBot 文档中心

Appearance

表情包API ​

表情包API模块提供表情包的获取、查询和管理功能，让插件能够智能地选择和使用表情包。

导入方式 ​

python
from src.plugin_system.apis import emoji_api

主要功能 ​

1. 表情包获取 ​

get_by_description(description: str) -> Optional[Tuple[str, str, str]] ​

根据场景描述选择表情包

参数：

  • description：场景描述文本，例如"开心的大笑"、"轻微的讽刺"、"表示无奈和沮丧"等

返回：

  • Optional[Tuple[str, str, str]]：(base64编码, 表情包描述, 匹配的场景) 或 None

示例：

python
emoji_result = await emoji_api.get_by_description("开心的大笑")
if emoji_result:
    emoji_base64, description, matched_scene = emoji_result
    print(f"获取到表情包: {description}, 场景: {matched_scene}")
    # 可以将emoji_base64用于发送表情包

get_random() -> Optional[Tuple[str, str, str]] ​

随机获取表情包

返回：

  • Optional[Tuple[str, str, str]]：(base64编码, 表情包描述, 随机场景) 或 None

示例：

python
random_emoji = await emoji_api.get_random()
if random_emoji:
    emoji_base64, description, scene = random_emoji
    print(f"随机表情包: {description}")

get_by_emotion(emotion: str) -> Optional[Tuple[str, str, str]] ​

根据场景关键词获取表情包

参数：

  • emotion：场景关键词，如"大笑"、"讽刺"、"无奈"等

返回：

  • Optional[Tuple[str, str, str]]：(base64编码, 表情包描述, 匹配的场景) 或 None

示例：

python
emoji_result = await emoji_api.get_by_emotion("讽刺")
if emoji_result:
    emoji_base64, description, scene = emoji_result
    # 发送讽刺表情包

2. 表情包信息查询 ​

get_count() -> int ​

获取表情包数量

返回：

  • int：当前可用的表情包数量

get_info() -> dict ​

获取表情包系统信息

返回：

  • dict：包含表情包数量、最大数量等信息

返回字典包含：

  • current_count：当前表情包数量
  • max_count：最大表情包数量
  • available_emojis：可用表情包数量

get_emotions() -> list ​

获取所有可用的场景关键词

返回：

  • list：所有表情包的场景关键词列表（去重）

get_descriptions() -> list ​

获取所有表情包的描述列表

返回：

  • list：所有表情包的描述文本列表

使用示例 ​

1. 智能表情包选择 ​

python
from src.plugin_system.apis import emoji_api

async def send_emotion_response(message_text: str, chat_stream):
    """根据消息内容智能选择表情包回复"""
    
    # 分析消息场景
    if "哈哈" in message_text or "好笑" in message_text:
        emoji_result = await emoji_api.get_by_description("开心的大笑")
    elif "无语" in message_text or "算了" in message_text:
        emoji_result = await emoji_api.get_by_description("表示无奈和沮丧")
    elif "呵呵" in message_text or "是吗" in message_text:
        emoji_result = await emoji_api.get_by_description("轻微的讽刺")
    elif "生气" in message_text or "愤怒" in message_text:
        emoji_result = await emoji_api.get_by_description("愤怒和不满")
    else:
        # 随机选择一个表情包
        emoji_result = await emoji_api.get_random()
    
    if emoji_result:
        emoji_base64, description, scene = emoji_result
        # 使用send_api发送表情包
        from src.plugin_system.apis import send_api
        success = await send_api.emoji_to_group(emoji_base64, chat_stream.group_info.group_id)
        return success
    
    return False

2. 表情包管理功能 ​

python
async def show_emoji_stats():
    """显示表情包统计信息"""
    
    # 获取基本信息
    count = emoji_api.get_count()
    info = emoji_api.get_info()
    scenes = emoji_api.get_emotions()  # 实际返回的是场景关键词
    
    stats = f"""
📊 表情包统计信息：
- 总数量: {count}
- 可用数量: {info['available_emojis']}
- 最大容量: {info['max_count']}
- 支持场景: {len(scenes)}种

🎭 支持的场景关键词: {', '.join(scenes[:10])}{'...' if len(scenes) > 10 else ''}
    """
    
    return stats

3. 表情包测试功能 ​

python
async def test_emoji_system():
    """测试表情包系统的各种功能"""
    
    print("=== 表情包系统测试 ===")
    
    # 测试场景描述查找
    test_descriptions = ["开心的大笑", "轻微的讽刺", "表示无奈和沮丧", "愤怒和不满"]
    for desc in test_descriptions:
        result = await emoji_api.get_by_description(desc)
        if result:
            _, description, scene = result
            print(f"✅ 场景'{desc}' -> {description} ({scene})")
        else:
            print(f"❌ 场景'{desc}' -> 未找到")
    
    # 测试关键词查找
    scenes = emoji_api.get_emotions()
    if scenes:
        test_scene = scenes[0]
        result = await emoji_api.get_by_emotion(test_scene)
        if result:
            print(f"✅ 关键词'{test_scene}' -> 找到匹配表情包")
    
    # 测试随机获取
    random_result = await emoji_api.get_random()
    if random_result:
        print("✅ 随机获取 -> 成功")
    
    print(f"📊 系统信息: {emoji_api.get_info()}")

4. 在Action中使用表情包 ​

python
from src.plugin_system.base import BaseAction

class EmojiAction(BaseAction):
    async def execute(self, action_data, chat_stream):
        # 从action_data获取场景描述或关键词
        scene_keyword = action_data.get("scene", "")
        scene_description = action_data.get("description", "")
        
        emoji_result = None
        
        # 优先使用具体的场景描述
        if scene_description:
            emoji_result = await emoji_api.get_by_description(scene_description)
        # 其次使用场景关键词
        elif scene_keyword:
            emoji_result = await emoji_api.get_by_emotion(scene_keyword)
        # 最后随机选择
        else:
            emoji_result = await emoji_api.get_random()
        
        if emoji_result:
            emoji_base64, description, scene = emoji_result
            return {
                "success": True,
                "emoji_base64": emoji_base64,
                "description": description,
                "scene": scene
            }
        
        return {"success": False, "message": "未找到合适的表情包"}

场景描述说明 ​

常用场景描述 ​

表情包系统支持多种具体的场景描述，常见的包括：

  • 开心类场景：开心的大笑、满意的微笑、兴奋的手舞足蹈
  • 无奈类场景：表示无奈和沮丧、轻微的讽刺、无语的摇头
  • 愤怒类场景：愤怒和不满、生气的瞪视、暴躁的抓狂
  • 惊讶类场景：震惊的表情、意外的发现、困惑的思考
  • 可爱类场景：卖萌的表情、撒娇的动作、害羞的样子

场景关键词示例 ​

系统支持的场景关键词包括：

  • 大笑、微笑、兴奋、手舞足蹈
  • 无奈、沮丧、讽刺、无语、摇头
  • 愤怒、不满、生气、瞪视、抓狂
  • 震惊、意外、困惑、思考
  • 卖萌、撒娇、害羞、可爱

匹配机制 ​

  • 精确匹配：优先匹配完整的场景描述，如"开心的大笑"
  • 关键词匹配：如果没有精确匹配，则根据关键词进行模糊匹配
  • 语义匹配：系统会理解场景的语义含义进行智能匹配

注意事项 ​

  1. 异步函数：获取表情包的函数都是异步的，需要使用 await
  2. 返回格式：表情包以base64编码返回，可直接用于发送
  3. 错误处理：所有函数都有错误处理，失败时返回None或默认值
  4. 使用统计：系统会记录表情包的使用次数
  5. 文件依赖：表情包依赖于本地文件，确保表情包文件存在
  6. 编码格式：返回的是base64编码的图片数据，可直接用于网络传输
  7. 场景理解：系统能理解具体的场景描述，比简单的情感分类更准确