Mofox-Core/action_activation_system_usage.md

MaiBot 动作激活系统使用指南

概述

MaiBot 的动作激活系统采用双激活类型架构，为Focus模式和Normal模式分别提供最优的激活策略。

系统已集成四大核心特性：

• 🎯 双激活类型：Focus模式智能化，Normal模式高性能
• 🚀 并行判定：多个LLM判定任务并行执行
• 💾 智能缓存：相同上下文的判定结果缓存复用
• ⚡ 并行动作：支持与回复同时执行的动作

双激活类型系统 🆕

系统设计理念

Focus模式：智能优先

• 支持复杂的LLM判定
• 提供精确的上下文理解
• 适合需要深度分析的场景

Normal模式：性能优先

• 使用快速的关键词匹配
• 采用简单的随机触发
• 确保快速响应用户

核心属性配置

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 - 总是激活

用途：基础必需动作，始终可用

focus_activation_type = ActionActivationType.ALWAYS
normal_activation_type = ActionActivationType.ALWAYS

示例：reply_action, no_reply_action

2. RANDOM - 随机激活

用途：增加不可预测性和趣味性

focus_activation_type = ActionActivationType.RANDOM
normal_activation_type = ActionActivationType.RANDOM
random_activation_probability = 0.2  # 20%概率激活

示例：vtb_action (表情动作)

3. LLM_JUDGE - LLM智能判定

用途：需要上下文理解的复杂判定

focus_activation_type = ActionActivationType.LLM_JUDGE
# 注意：Normal模式使用LLM_JUDGE会产生性能警告
normal_activation_type = ActionActivationType.KEYWORD  # 推荐在Normal模式使用KEYWORD

优化特性：

• ⚡ 直接判定：直接进行LLM判定，减少复杂度
• 🚀 并行执行：多个LLM判定同时进行
• 💾 结果缓存：相同上下文复用结果（30秒有效期）

4. KEYWORD - 关键词触发

用途：精确命令式触发

focus_activation_type = ActionActivationType.KEYWORD
normal_activation_type = ActionActivationType.KEYWORD
activation_keywords = ["画", "画图", "生成图片", "draw"]
keyword_case_sensitive = False  # 不区分大小写

示例：pic_action, mute_action

模式启用控制 (ChatMode)

模式类型

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: 快速响应的基础功能

并行动作系统 🆕

概念说明

# 并行动作：与回复生成同时执行
parallel_action = True   # 不会阻止回复，提升用户体验

# 串行动作：替代回复生成（传统行为）
parallel_action = False  # 默认值，动作执行时不生成回复

适用场景

并行动作 (parallel_action = True):

• 情感表达（表情、动作）
• 状态变更（禁言、设置）
• 辅助功能（TTS播报）

串行动作 (parallel_action = False):

• 内容生成（图片、文档）
• 搜索查询
• 需要完整注意力的操作

实际案例

@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：智能自适应（推荐）

# Focus模式智能判定，Normal模式快速触发
focus_activation_type = ActionActivationType.LLM_JUDGE
normal_activation_type = ActionActivationType.KEYWORD
activation_keywords = ["相关", "关键词", "英文keyword"]
mode_enable = ChatMode.ALL
parallel_action = False  # 根据具体需求调整

模式2：统一关键词

# 两个模式都使用关键词，确保行为一致
focus_activation_type = ActionActivationType.KEYWORD
normal_activation_type = ActionActivationType.KEYWORD
activation_keywords = ["画", "图片", "生成"]
mode_enable = ChatMode.ALL
parallel_action = False

模式3：Focus专享功能

# 仅在Focus模式启用的高级功能
focus_activation_type = ActionActivationType.LLM_JUDGE
normal_activation_type = ActionActivationType.ALWAYS  # 不会生效
mode_enable = ChatMode.FOCUS
parallel_action = False

模式4：随机娱乐功能

# 增加趣味性的随机功能
focus_activation_type = ActionActivationType.RANDOM
normal_activation_type = ActionActivationType.RANDOM
random_activation_probability = 0.08  # 8%概率
mode_enable = ChatMode.ALL
parallel_action = True  # 通常与回复并行

性能优化详解

并行判定机制

# 自动将多个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判定同时进行，显著减少总耗时
• 异常处理确保单个失败不影响整体
• 自动负载均衡

智能缓存系统

# 基于上下文哈希的缓存机制
cache_key = f"{action_name}_{context_hash}"
if cache_key in self._llm_judge_cache:
    return cached_result  # 直接返回缓存结果

特性：

• 30秒缓存有效期
• MD5哈希确保上下文一致性
• 自动清理过期缓存
• 命中率优化：相同聊天上下文的重复判定

分层判定架构

第一层：智能动态过滤

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）流程也实现了并行化：

# 在 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循环的总耗时
• 提高机器人响应速度
• 优化用户体验

配置控制

通过配置文件控制是否启用并行处理：

focus_chat:
  parallel_processing: true  # 启用并行处理

建议设置：

• 生产环境：启用（true）- 获得最佳性能
• 调试环境：可选择禁用（false）- 便于问题定位

使用示例

定义新的动作类

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

关键词触发动作

@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

随机触发动作

@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专享智能动作

@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 (禁言动作)

focus_activation_type = ActionActivationType.LLM_JUDGE
normal_activation_type = ActionActivationType.KEYWORD
activation_keywords = ["禁言", "mute", "ban", "silence"]
mode_enable = ChatMode.ALL
parallel_action = True  # 可以与回复同时进行

PicAction (图片生成)

focus_activation_type = ActionActivationType.LLM_JUDGE
normal_activation_type = ActionActivationType.KEYWORD
activation_keywords = ["画", "绘制", "生成图片", "画图", "draw", "paint", "图片生成"]
mode_enable = ChatMode.ALL
parallel_action = False  # 专注生成，不同时回复

VTBAction (虚拟主播表情)

focus_activation_type = ActionActivationType.LLM_JUDGE
normal_activation_type = ActionActivationType.RANDOM
random_activation_probability = 0.08
mode_enable = ChatMode.ALL
parallel_action = False  # 替代文字回复

性能监控

实时性能指标

# 自动记录的性能指标
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 属性已被移除，必须更新为新的双激活类型系统。

快速迁移步骤

第一步：更新基本属性

# 旧的配置（已废弃）❌
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

第二步：根据原类型选择对应策略

# 原来是 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

第三步：配置新功能

# 添加模式控制
mode_enable = ChatMode.ALL  # 或 ChatMode.FOCUS / ChatMode.NORMAL

# 添加并行控制  
parallel_action = False  # 根据动作特性选择True/False

# 添加插件控制
enable_plugin = True  # 是否启用此插件

批量迁移脚本

可以创建以下脚本来帮助批量迁移：

# 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')

测试验证

运行动作激活优化测试：

python test_action_activation_optimized.py

运行HFC并行化测试：

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

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

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

调试和测试

使用提供的测试脚本验证激活类型系统：

python test_action_activation.py

该脚本会显示：

• 所有注册动作的双激活类型配置
• 模拟不同模式下的激活结果
• 并行动作系统的工作状态
• 帮助验证配置是否正确

注意事项

1. 重大变更: action_activation_type 已被移除，必须使用双激活类型
2. 向后兼容: 系统不再兼容旧的单一激活类型配置
3. 错误处理: LLM判定失败时默认不激活该动作
4. 性能警告: Normal模式使用LLM_JUDGE会产生警告
5. 日志记录: 系统会记录激活决策过程，便于调试
6. 性能影响: LLM判定会略微增加响应时间

未来扩展

系统设计支持未来添加更多激活类型和功能，如：

• 基于时间的激活
• 基于用户权限的激活
• 基于群组设置的激活
• 基于对话历史的激活
• 基于情感状态的激活