初始化

docs/plugins/api/emoji-api.md

@@ -0,0 +1,141 @@
+# 表情包API
+
+表情包API模块提供表情包的获取、查询和管理功能，让插件能够智能地选择和使用表情包。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import emoji_api
+# 或者
+from src.plugin_system import emoji_api
+```
+
+## 二步走识别优化
+
+从新版本开始，表情包识别系统采用了**二步走识别 + 智能缓存**的优化方案：
+
+### **收到表情包时的识别流程**
+1. **第一步**：VLM视觉分析 - 生成详细描述
+2. **第二步**：LLM情感分析 - 基于详细描述提取核心情感标签
+3. **缓存机制**：将情感标签缓存到数据库，详细描述保存到Images表
+
+### **注册表情包时的优化**
+- **智能复用**：优先从Images表获取已有的详细描述
+- **避免重复**：如果表情包之前被收到过，跳过VLM调用
+- **性能提升**：减少不必要的AI调用，降低延时和成本
+
+### **缓存策略**
+- **ImageDescriptions表**：缓存最终的情感标签（用于快速显示）
+- **Images表**：保存详细描述（用于注册时复用）
+- **双重检查**：防止并发情况下的重复生成
+
+## 主要功能
+
+### 1. 表情包获取
+```python
+async def get_by_description(description: str) -> Optional[Tuple[str, str, str]]:
+```
+根据场景描述选择表情包
+
+**Args：**
+- `description`：表情包的描述文本，例如"开心"、"难过"、"愤怒"等
+
+**Returns：**
+- `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用于发送表情包
+```
+
+### 2. 随机获取表情包
+```python
+async def get_random(count: Optional[int] = 1) -> List[Tuple[str, str, str]]:
+```
+随机获取指定数量的表情包
+
+**Args：**
+- `count`：要获取的表情包数量，默认为1
+
+**Returns：**
+- `List[Tuple[str, str, str]]`：一个包含多个表情包的列表，每个元素是一个元组: (表情包的base64编码, 描述, 情感标签)，如果未找到或出错则返回空列表
+
+### 3. 根据情感获取表情包
+```python
+async def get_by_emotion(emotion: str) -> Optional[Tuple[str, str, str]]:
+```
+根据情感标签获取表情包
+
+**Args：**
+- `emotion`：情感标签，例如"开心"、"悲伤"、"愤怒"等
+
+**Returns：**
+- `Optional[Tuple[str, str, str]]`：一个元组: (表情包的base64编码, 描述, 情感标签)，如果未找到则返回None
+
+### 4. 获取表情包数量
+```python
+def get_count() -> int:
+```
+获取当前可用表情包的数量
+
+### 5. 获取表情包系统信息
+```python
+def get_info() -> Dict[str, Any]:
+```
+获取表情包系统的基本信息
+
+**Returns：**
+- `Dict[str, Any]`：包含表情包数量、描述等信息的字典，包含以下键：
+    - `current_count`：当前表情包数量
+    - `max_count`：最大表情包数量
+    - `available_emojis`：当前可用的表情包数量
+
+### 6. 获取所有可用的情感标签
+```python
+def get_emotions() -> List[str]:
+```
+获取所有可用的情感标签 **（已经去重）**
+
+### 7. 获取所有表情包描述
+```python
+def get_descriptions() -> List[str]:
+```
+获取所有表情包的描述列表
+
+## 场景描述说明
+
+### 常用场景描述
+表情包系统支持多种具体的场景描述，举例如下：
+
+- **开心类场景**：开心的大笑、满意的微笑、兴奋的手舞足蹈
+- **无奈类场景**：表示无奈和沮丧、轻微的讽刺、无语的摇头
+- **愤怒类场景**：愤怒和不满、生气的瞪视、暴躁的抓狂
+- **惊讶类场景**：震惊的表情、意外的发现、困惑的思考
+- **可爱类场景**：卖萌的表情、撒娇的动作、害羞的样子
+
+### 情感关键词示例
+系统支持的情感关键词举例如下：
+- 大笑、微笑、兴奋、手舞足蹈
+- 无奈、沮丧、讽刺、无语、摇头
+- 愤怒、不满、生气、瞪视、抓狂
+- 震惊、意外、困惑、思考
+- 卖萌、撒娇、害羞、可爱
+
+### 匹配机制
+- **精确匹配**：优先匹配完整的场景描述，如"开心的大笑"
+- **关键词匹配**：如果没有精确匹配，则根据关键词进行模糊匹配
+- **语义匹配**：系统会理解场景的语义含义进行智能匹配
+
+## 注意事项
+
+1. **异步函数**：部分函数是异步的，需要使用 `await`
+2. **返回格式**：表情包以base64编码返回，可直接用于发送
+3. **错误处理**：所有函数都有错误处理，失败时返回None，空列表或默认值
+4. **使用统计**：系统会记录表情包的使用次数
+5. **文件依赖**：表情包依赖于本地文件，确保表情包文件存在
+6. **编码格式**：返回的是base64编码的图片数据，可直接用于网络传输
+7. **场景理解**：系统能理解具体的场景描述，比简单的情感分类更准确