# MaiBot 动作激活系统使用指南 ## 概述 MaiBot 的动作激活系统采用**双激活类型架构**,为Focus模式和Normal模式分别提供最优的激活策略。 **系统已集成四大核心特性:** - 🎯 **双激活类型**:Focus模式智能化,Normal模式高性能 - 🚀 **并行判定**:多个LLM判定任务并行执行 - 💾 **智能缓存**:相同上下文的判定结果缓存复用 - ⚡ **并行动作**:支持与回复同时执行的动作 ## 双激活类型系统 🆕 ### 系统设计理念 **Focus模式**:智能优先 - 支持复杂的LLM判定 - 提供精确的上下文理解 - 适合需要深度分析的场景 **Normal模式**:性能优先 - 使用快速的关键词匹配 - 采用简单的随机触发 - 确保快速响应用户 ### 核心属性配置 ```python from src.chat.focus_chat.planners.actions.base_action import BaseAction, register_action, ActionActivationType from src.chat.chat_mode import ChatMode @register_action class MyAction(BaseAction): action_name = "my_action" action_description = "我的动作描述" # 双激活类型配置 focus_activation_type = ActionActivationType.LLM_JUDGE # Focus模式使用智能判定 normal_activation_type = ActionActivationType.KEYWORD # Normal模式使用关键词 activation_keywords = ["关键词1", "关键词2", "keyword"] keyword_case_sensitive = False # 模式启用控制 mode_enable = ChatMode.ALL # 支持的聊天模式 # 并行执行控制 parallel_action = False # 是否与回复并行执行 # 插件系统控制 enable_plugin = True # 是否启用此插件 ``` ## 激活类型详解 ### 1. ALWAYS - 总是激活 **用途**:基础必需动作,始终可用 ```python focus_activation_type = ActionActivationType.ALWAYS normal_activation_type = ActionActivationType.ALWAYS ``` **示例**:`reply_action`, `no_reply_action` ### 2. RANDOM - 随机激活 **用途**:增加不可预测性和趣味性 ```python focus_activation_type = ActionActivationType.RANDOM normal_activation_type = ActionActivationType.RANDOM random_activation_probability = 0.2 # 20%概率激活 ``` **示例**:`vtb_action` (表情动作) ### 3. LLM_JUDGE - LLM智能判定 **用途**:需要上下文理解的复杂判定 ```python focus_activation_type = ActionActivationType.LLM_JUDGE # 注意:Normal模式使用LLM_JUDGE会产生性能警告 normal_activation_type = ActionActivationType.KEYWORD # 推荐在Normal模式使用KEYWORD ``` **优化特性**: - ⚡ **直接判定**:直接进行LLM判定,减少复杂度 - 🚀 **并行执行**:多个LLM判定同时进行 - 💾 **结果缓存**:相同上下文复用结果(30秒有效期) ### 4. KEYWORD - 关键词触发 **用途**:精确命令式触发 ```python focus_activation_type = ActionActivationType.KEYWORD normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["画", "画图", "生成图片", "draw"] keyword_case_sensitive = False # 不区分大小写 ``` **示例**:`pic_action`, `mute_action` ## 模式启用控制 (ChatMode) ### 模式类型 ```python from src.chat.chat_mode import ChatMode # 在所有模式下启用 mode_enable = ChatMode.ALL # 默认值 # 仅在Focus模式启用 mode_enable = ChatMode.FOCUS # 仅在Normal模式启用 mode_enable = ChatMode.NORMAL ``` ### 使用场景建议 - **ChatMode.ALL**: 通用功能(如回复、图片生成) - **ChatMode.FOCUS**: 需要深度理解的智能功能 - **ChatMode.NORMAL**: 快速响应的基础功能 ## 并行动作系统 🆕 ### 概念说明 ```python # 并行动作:与回复生成同时执行 parallel_action = True # 不会阻止回复,提升用户体验 # 串行动作:替代回复生成(传统行为) parallel_action = False # 默认值,动作执行时不生成回复 ``` ### 适用场景 **并行动作 (parallel_action = True)**: - 情感表达(表情、动作) - 状态变更(禁言、设置) - 辅助功能(TTS播报) **串行动作 (parallel_action = False)**: - 内容生成(图片、文档) - 搜索查询 - 需要完整注意力的操作 ### 实际案例 ```python @register_action class MuteAction(PluginAction): action_name = "mute_action" focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["禁言", "mute", "ban", "silence"] parallel_action = True # 禁言的同时还可以回复确认信息 @register_action class PicAction(PluginAction): action_name = "pic_action" focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["画", "绘制", "生成图片", "画图", "draw", "paint"] parallel_action = False # 专注于图片生成,不同时回复 ``` ## 推荐配置模式 ### 模式1:智能自适应(推荐) ```python # Focus模式智能判定,Normal模式快速触发 focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["相关", "关键词", "英文keyword"] mode_enable = ChatMode.ALL parallel_action = False # 根据具体需求调整 ``` ### 模式2:统一关键词 ```python # 两个模式都使用关键词,确保行为一致 focus_activation_type = ActionActivationType.KEYWORD normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["画", "图片", "生成"] mode_enable = ChatMode.ALL parallel_action = False ``` ### 模式3:Focus专享功能 ```python # 仅在Focus模式启用的高级功能 focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.ALWAYS # 不会生效 mode_enable = ChatMode.FOCUS parallel_action = False ``` ### 模式4:随机娱乐功能 ```python # 增加趣味性的随机功能 focus_activation_type = ActionActivationType.RANDOM normal_activation_type = ActionActivationType.RANDOM random_activation_probability = 0.08 # 8%概率 mode_enable = ChatMode.ALL parallel_action = True # 通常与回复并行 ``` ## 性能优化详解 ### 并行判定机制 ```python # 自动将多个LLM判定任务并行执行 async def _process_llm_judge_actions_parallel(self, llm_judge_actions, ...): tasks = [self._llm_judge_action(name, info, ...) for name, info in llm_judge_actions.items()] results = await asyncio.gather(*tasks, return_exceptions=True) ``` **优势**: - 多个LLM判定同时进行,显著减少总耗时 - 异常处理确保单个失败不影响整体 - 自动负载均衡 ### 智能缓存系统 ```python # 基于上下文哈希的缓存机制 cache_key = f"{action_name}_{context_hash}" if cache_key in self._llm_judge_cache: return cached_result # 直接返回缓存结果 ``` **特性**: - 30秒缓存有效期 - MD5哈希确保上下文一致性 - 自动清理过期缓存 - 命中率优化:相同聊天上下文的重复判定 ### 分层判定架构 #### 第一层:智能动态过滤 ```python def _pre_filter_llm_actions(self, llm_judge_actions, observed_messages_str, ...): # 动态收集所有KEYWORD类型actions的关键词 all_keyword_actions = self.action_manager.get_registered_actions() collected_keywords = {} for action_name, action_info in all_keyword_actions.items(): if action_info.get("activation_type") == "KEYWORD": keywords = action_info.get("activation_keywords", []) if keywords: collected_keywords[action_name] = [kw.lower() for kw in keywords] # 基于实际配置进行智能过滤 for action_name, action_info in llm_judge_actions.items(): # 策略1: 避免与KEYWORD类型重复 # 策略2: 基于action描述进行语义相关性检查 # 策略3: 保留核心actions ``` **智能过滤策略**: - **动态关键词收集**:从各个action的实际配置中收集关键词,无硬编码 - **重复避免机制**:如果存在对应的KEYWORD触发action,优先使用KEYWORD - **语义相关性检查**:基于action描述和消息内容进行智能匹配 - **长度与复杂度匹配**:短消息自动排除复杂operations - **核心action保护**:确保reply/no_reply等基础action始终可用 #### 第二层:LLM精确判定 通过第一层过滤后的动作才进入LLM判定,大幅减少: - LLM调用次数 - 总处理时间 - API成本 ## HFC流程级并行化优化 🆕 ### 三阶段并行架构 除了动作激活系统内部的优化,整个HFC(HeartFocus Chat)流程也实现了并行化: ```python # 在 heartFC_chat.py 中的优化 if global_config.focus_chat.parallel_processing: # 并行执行调整动作、回忆和处理器阶段 with Timer("并行调整动作、回忆和处理", cycle_timers): async def modify_actions_task(): await self.action_modifier.modify_actions(observations=self.observations) await self.action_observation.observe() self.observations.append(self.action_observation) return True # 创建三个并行任务 action_modify_task = asyncio.create_task(modify_actions_task()) memory_task = asyncio.create_task(self.memory_activator.activate_memory(self.observations)) processor_task = asyncio.create_task(self._process_processors(self.observations, [])) # 等待三个任务完成 _, running_memorys, (all_plan_info, processor_time_costs) = await asyncio.gather( action_modify_task, memory_task, processor_task ) ``` ### 并行化阶段说明 **1. 调整动作阶段(Action Modifier)** - 执行动作激活系统的智能判定 - 包含并行LLM判定和缓存 - 更新可用动作列表 **2. 回忆激活阶段(Memory Activator)** - 根据当前观察激活相关记忆 - 检索历史对话和上下文信息 - 为规划器提供背景知识 **3. 信息处理器阶段(Processors)** - 处理观察信息,提取关键特征 - 生成结构化的计划信息 - 为规划器提供决策依据 ### 性能提升效果 **理论提升**: - 原串行执行:500ms + 800ms + 1000ms = 2300ms - 现并行执行:max(500ms, 800ms, 1000ms) = 1000ms - **性能提升:2.3x** **实际效果**: - 显著减少每个HFC循环的总耗时 - 提高机器人响应速度 - 优化用户体验 ### 配置控制 通过配置文件控制是否启用并行处理: ```yaml focus_chat: parallel_processing: true # 启用并行处理 ``` **建议设置**: - **生产环境**:启用(`true`)- 获得最佳性能 - **调试环境**:可选择禁用(`false`)- 便于问题定位 ## 使用示例 ### 定义新的动作类 ```python from src.chat.focus_chat.planners.actions.plugin_action import PluginAction, register_action, ActionActivationType from src.chat.chat_mode import ChatMode @register_action class MyAction(PluginAction): action_name = "my_action" action_description = "我的自定义动作" # 双激活类型配置 focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["自定义", "触发", "custom"] # 模式和并行控制 mode_enable = ChatMode.ALL parallel_action = False enable_plugin = True async def process(self): # 动作执行逻辑 pass ``` ### 关键词触发动作 ```python @register_action class SearchAction(PluginAction): action_name = "search_action" focus_activation_type = ActionActivationType.KEYWORD normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["搜索", "查找", "什么是", "search", "find"] keyword_case_sensitive = False mode_enable = ChatMode.ALL parallel_action = False ``` ### 随机触发动作 ```python @register_action class SurpriseAction(PluginAction): action_name = "surprise_action" focus_activation_type = ActionActivationType.RANDOM normal_activation_type = ActionActivationType.RANDOM random_activation_probability = 0.1 # 10%概率 mode_enable = ChatMode.ALL parallel_action = True # 惊喜动作与回复并行 ``` ### Focus专享智能动作 ```python @register_action class AdvancedAnalysisAction(PluginAction): action_name = "advanced_analysis" focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.ALWAYS # 不会生效 mode_enable = ChatMode.FOCUS # 仅Focus模式 parallel_action = False ``` ## 现有插件的配置示例 ### MuteAction (禁言动作) ```python focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["禁言", "mute", "ban", "silence"] mode_enable = ChatMode.ALL parallel_action = True # 可以与回复同时进行 ``` ### PicAction (图片生成) ```python focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["画", "绘制", "生成图片", "画图", "draw", "paint", "图片生成"] mode_enable = ChatMode.ALL parallel_action = False # 专注生成,不同时回复 ``` ### VTBAction (虚拟主播表情) ```python focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.RANDOM random_activation_probability = 0.08 mode_enable = ChatMode.ALL parallel_action = False # 替代文字回复 ``` ## 性能监控 ### 实时性能指标 ```python # 自动记录的性能指标 logger.debug(f"激活判定:{before_count} -> {after_count} actions") logger.debug(f"并行LLM判定完成,耗时: {duration:.2f}s") logger.debug(f"使用缓存结果 {action_name}: {'激活' if result else '未激活'}") logger.debug(f"清理了 {count} 个过期缓存条目") logger.debug(f"并行调整动作、回忆和处理完成,耗时: {duration:.2f}s") ``` ### 性能优化建议 1. **合理配置缓存时间**:根据聊天活跃度调整 `_cache_expiry_time` 2. **优化过滤规则**:根据实际使用情况调整 `_quick_filter_keywords` 3. **监控并行效果**:关注 `asyncio.gather` 的执行时间 4. **缓存命中率**:监控缓存使用情况,优化策略 5. **启用流程并行化**:确保 `parallel_processing` 配置为 `true` 6. **激活类型选择**:Normal模式优先使用KEYWORD,避免LLM_JUDGE ## 迁移指南 ⚠️ ### 重大变更说明 **旧的 `action_activation_type` 属性已被移除**,必须更新为新的双激活类型系统。 ### 快速迁移步骤 #### 第一步:更新基本属性 ```python # 旧的配置(已废弃)❌ class OldAction(BaseAction): action_activation_type = ActionActivationType.LLM_JUDGE # 新的配置(必须使用)✅ class NewAction(BaseAction): focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["相关", "关键词"] mode_enable = ChatMode.ALL parallel_action = False enable_plugin = True ``` #### 第二步:根据原类型选择对应策略 ```python # 原来是 ALWAYS focus_activation_type = ActionActivationType.ALWAYS normal_activation_type = ActionActivationType.ALWAYS # 原来是 LLM_JUDGE focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD # 添加关键词 activation_keywords = ["需要", "添加", "关键词"] # 原来是 KEYWORD focus_activation_type = ActionActivationType.KEYWORD normal_activation_type = ActionActivationType.KEYWORD # 保持原有的 activation_keywords # 原来是 RANDOM focus_activation_type = ActionActivationType.RANDOM normal_activation_type = ActionActivationType.RANDOM # 保持原有的 random_activation_probability ``` #### 第三步:配置新功能 ```python # 添加模式控制 mode_enable = ChatMode.ALL # 或 ChatMode.FOCUS / ChatMode.NORMAL # 添加并行控制 parallel_action = False # 根据动作特性选择True/False # 添加插件控制 enable_plugin = True # 是否启用此插件 ``` ### 批量迁移脚本 可以创建以下脚本来帮助批量迁移: ```python # migrate_actions.py import os import re def migrate_action_file(filepath): with open(filepath, 'r', encoding='utf-8') as f: content = f.read() # 替换 action_activation_type if 'action_activation_type = ActionActivationType.ALWAYS' in content: content = content.replace( 'action_activation_type = ActionActivationType.ALWAYS', 'focus_activation_type = ActionActivationType.ALWAYS\n normal_activation_type = ActionActivationType.ALWAYS' ) elif 'action_activation_type = ActionActivationType.LLM_JUDGE' in content: content = content.replace( 'action_activation_type = ActionActivationType.LLM_JUDGE', 'focus_activation_type = ActionActivationType.LLM_JUDGE\n normal_activation_type = ActionActivationType.KEYWORD\n activation_keywords = ["需要", "添加", "关键词"] # TODO: 配置合适的关键词' ) # ... 其他替换逻辑 # 添加新属性 if 'mode_enable' not in content: # 在class定义后添加新属性 # ... with open(filepath, 'w', encoding='utf-8') as f: f.write(content) # 使用示例 migrate_action_file('src/plugins/your_plugin/actions/your_action.py') ``` ## 测试验证 运行动作激活优化测试: ```bash python test_action_activation_optimized.py ``` 运行HFC并行化测试: ```bash python test_parallel_optimization.py ``` 测试内容包括: - ✅ 双激活类型功能验证 - ✅ 并行处理功能验证 - ✅ 缓存机制效果测试 - ✅ 分层判定规则验证 - ✅ 性能对比分析 - ✅ HFC流程并行化效果 - ✅ 多循环平均性能测试 - ✅ 并行动作系统验证 - ✅ 迁移兼容性测试 ## 最佳实践 ### 1. 激活类型选择 - **ALWAYS**:reply, no_reply 等基础动作 - **LLM_JUDGE**:需要智能判断的复杂动作(建议仅用于Focus模式) - **KEYWORD**:明确的命令式动作(推荐在Normal模式使用) - **RANDOM**:增趣动作,低概率触发 ### 2. 双模式配置策略 - **智能自适应**:Focus用LLM_JUDGE,Normal用KEYWORD - **性能优先**:两个模式都用KEYWORD或RANDOM - **功能分离**:某些功能仅在特定模式启用 ### 3. 并行动作使用建议 - **parallel_action = True**:辅助性、非内容生成类动作 - **parallel_action = False**:主要内容生成、需要完整注意力的动作 ### 4. LLM判定提示词编写 - 明确描述激活条件和排除条件 - 避免模糊的描述 - 考虑边界情况 - 保持简洁明了 ### 5. 关键词设置 - 包含同义词和英文对应词 - 考虑用户的不同表达习惯 - 避免过于宽泛的关键词 - 根据实际使用调整 ### 6. 性能优化 - 定期监控处理时间 - 根据使用模式调整缓存策略 - 优化激活判定逻辑 - 平衡准确性和性能 - **启用并行处理配置** - **Normal模式避免使用LLM_JUDGE** ### 7. 并行化最佳实践 - 在生产环境启用 `parallel_processing` - 监控并行阶段的执行时间 - 确保各阶段的独立性 - 避免共享状态导致的竞争条件 ## 总结 优化后的动作激活系统通过**五层优化策略**,实现了全方位的性能提升: ### 第一层:双激活类型系统 - **Focus模式**:智能化优先,支持复杂LLM判定 - **Normal模式**:性能优先,使用快速关键词匹配 - **模式自适应**:根据聊天模式选择最优策略 ### 第二层:动作激活内部优化 - **并行判定**:多个LLM判定任务并行执行 - **智能缓存**:相同上下文的判定结果缓存复用 - **分层判定**:快速过滤 + 精确判定的两层架构 ### 第三层:并行动作系统 - **并行执行**:支持动作与回复同时进行 - **用户体验**:减少等待时间,提升交互流畅性 - **灵活控制**:每个动作可独立配置并行行为 ### 第四层:HFC流程级并行化 - **三阶段并行**:调整动作、回忆、处理器同时执行 - **性能提升**:2.3x 理论加速比 - **配置控制**:可根据环境灵活开启/关闭 ### 第五层:插件系统增强 - **enable_plugin**:精确控制插件启用状态 - **mode_enable**:支持模式级别的功能控制 - **向后兼容**:平滑迁移旧系统配置 ### 综合效果 - **响应速度**:显著提升机器人反应速度 - **成本优化**:减少不必要的LLM调用 - **智能决策**:双激活类型覆盖所有场景 - **用户体验**:更快速、更智能的交互 - **灵活配置**:精细化的功能控制 **总性能提升预估:4-6x** - 双激活类型系统:1.5x (Normal模式优化) - 动作激活内部优化:1.5-2x - HFC流程并行化:2.3x - 并行动作系统:额外30-50%提升 - 缓存和过滤优化:额外20-30%提升 这使得MaiBot能够更快速、更智能地响应用户需求,同时提供灵活的配置选项以适应不同的使用场景,实现了卓越的交互体验。 ## 如何为Action添加激活类型 ### 对于普通Action ```python from src.chat.focus_chat.planners.actions.base_action import BaseAction, register_action, ActionActivationType from src.chat.chat_mode import ChatMode @register_action class YourAction(BaseAction): action_name = "your_action" action_description = "你的动作描述" # 双激活类型配置 focus_activation_type = ActionActivationType.LLM_JUDGE normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["关键词1", "关键词2", "keyword"] keyword_case_sensitive = False # 新增属性 mode_enable = ChatMode.ALL parallel_action = False enable_plugin = True # ... 其他代码 ``` ### 对于插件Action ```python from src.chat.focus_chat.planners.actions.plugin_action import PluginAction, register_action, ActionActivationType from src.chat.chat_mode import ChatMode @register_action class YourPluginAction(PluginAction): action_name = "your_plugin_action" action_description = "你的插件动作描述" # 双激活类型配置 focus_activation_type = ActionActivationType.KEYWORD normal_activation_type = ActionActivationType.KEYWORD activation_keywords = ["触发词1", "trigger", "启动"] keyword_case_sensitive = False # 新增属性 mode_enable = ChatMode.ALL parallel_action = True # 与回复并行执行 enable_plugin = True # ... 其他代码 ``` ## 工作流程 1. **ActionModifier处理**: 在planner运行前,ActionModifier会遍历所有注册的动作 2. **模式检查**: 根据当前聊天模式(Focus/Normal)和action的mode_enable进行过滤 3. **激活类型判断**: 根据当前模式选择对应的激活类型(focus_activation_type或normal_activation_type) 4. **激活决策**: - ALWAYS: 直接激活 - RANDOM: 根据概率随机决定 - LLM_JUDGE: 调用小模型判定(Normal模式会警告) - KEYWORD: 检测关键词匹配 5. **并行性检查**: 根据parallel_action决定是否与回复并行 6. **结果收集**: 收集所有激活的动作供planner使用 ## 配置建议 ### 双激活类型策略选择 - **智能自适应(推荐)**: Focus用LLM_JUDGE,Normal用KEYWORD - **性能优先**: 两个模式都用KEYWORD或RANDOM - **功能专享**: 某些高级功能仅在Focus模式启用 ### LLM判定提示词编写 - 明确指出激活条件和不激活条件 - 使用简单清晰的语言 - 避免过于复杂的逻辑判断 ### 随机概率设置 - 核心功能: 不建议使用随机 - 娱乐功能: 0.1-0.3 (10%-30%) - 辅助功能: 0.05-0.2 (5%-20%) ### 关键词设计 - 包含常用的同义词和变体 - 考虑中英文兼容 - 避免过于宽泛的词汇 - 测试关键词的覆盖率 ### 性能考虑 - LLM判定会增加响应时间,适度使用 - 关键词检测性能最好,推荐优先使用 - Normal模式避免使用LLM_JUDGE - 建议优先级:KEYWORD > ALWAYS > RANDOM > LLM_JUDGE ## 调试和测试 使用提供的测试脚本验证激活类型系统: ```bash python test_action_activation.py ``` 该脚本会显示: - 所有注册动作的双激活类型配置 - 模拟不同模式下的激活结果 - 并行动作系统的工作状态 - 帮助验证配置是否正确 ## 注意事项 1. **重大变更**: `action_activation_type` 已被移除,必须使用双激活类型 2. **向后兼容**: 系统不再兼容旧的单一激活类型配置 3. **错误处理**: LLM判定失败时默认不激活该动作 4. **性能警告**: Normal模式使用LLM_JUDGE会产生警告 5. **日志记录**: 系统会记录激活决策过程,便于调试 6. **性能影响**: LLM判定会略微增加响应时间 ## 未来扩展 系统设计支持未来添加更多激活类型和功能,如: - 基于时间的激活 - 基于用户权限的激活 - 基于群组设置的激活 - 基于对话历史的激活 - 基于情感状态的激活