Mofox-Core/CORRECTED_ARCHITECTURE.md

# 修正后的动作激活架构

## 架构原则

### 正确的职责分工
- **主循环 (`modify_actions`)**: 负责完整的动作管理，包括传统观察处理和新的激活类型判定
- **规划器 (`Planner`)**: 专注于从最终确定的动作集中进行决策，不再处理动作筛选

### 关注点分离
- **动作管理** → 主循环处理
- **决策制定** → 规划器处理
- **配置解析** → ActionManager处理

## 修正后的调用流程

### 1. 主循环阶段 (heartFC_chat.py)

```python
# 在主循环中调用完整的动作管理流程
async def modify_actions_task():
    # 提取聊天上下文信息
    observed_messages_str = ""
    chat_context = ""
    
    for obs in self.observations:
        if hasattr(obs, 'get_talking_message_str_truncate'):
            observed_messages_str = obs.get_talking_message_str_truncate()
        elif hasattr(obs, 'get_chat_type'):
            chat_context = f"聊天类型: {obs.get_chat_type()}"
    
    # 调用完整的动作修改流程
    await self.action_modifier.modify_actions(
        observations=self.observations,
        observed_messages_str=observed_messages_str,
        chat_context=chat_context,
        extra_context=extra_context
    )
```

**处理内容:**
- 传统观察处理（循环历史分析、类型匹配等）
- 激活类型判定（ALWAYS, RANDOM, LLM_JUDGE, KEYWORD）
- 并行LLM判定
- 智能缓存
- 动态关键词收集

### 2. 规划器阶段 (planner_simple.py)

```python
# 规划器直接获取最终的动作集
current_available_actions_dict = self.action_manager.get_using_actions()

# 获取完整的动作信息
all_registered_actions = self.action_manager.get_registered_actions()
current_available_actions = {}
for action_name in current_available_actions_dict.keys():
    if action_name in all_registered_actions:
        current_available_actions[action_name] = all_registered_actions[action_name]
```

**处理内容:**
- 仅获取经过完整处理的最终动作集
- 专注于从可用动作中进行决策
- 不再处理动作筛选逻辑

## 核心优化功能

### 1. 并行LLM判定
```python
# 同时判定多个LLM_JUDGE类型的动作
task_results = await asyncio.gather(*tasks, return_exceptions=True)
```

### 2. 智能缓存系统
```python
# 基于上下文哈希的缓存机制
cache_key = f"{action_name}_{context_hash}"
if cache_key in self._llm_judge_cache:
    return cached_result
```

### 3. 直接LLM判定
```python
# 直接对所有LLM_JUDGE类型的动作进行并行判定
llm_results = await self._process_llm_judge_actions_parallel(llm_judge_actions, ...)
```

### 4. 动态关键词收集
```python
# 从动作配置中动态收集关键词，避免硬编码
for action_name, action_info in llm_judge_actions.items():
    keywords = action_info.get("activation_keywords", [])
    if keywords:
        # 检查消息中的关键词匹配
```

## 四种激活类型

### 1. ALWAYS - 始终激活
```python
activation_type = ActionActivationType.ALWAYS
# 基础动作，如 reply, no_reply
```

### 2. RANDOM - 随机激活
```python
activation_type = ActionActivationType.RANDOM
random_probability = 0.3  # 激活概率
# 用于增加惊喜元素，如随机表情
```

### 3. LLM_JUDGE - 智能判定
```python
activation_type = ActionActivationType.LLM_JUDGE
llm_judge_prompt = "自定义判定提示词"
# 需要理解上下文的复杂动作，如情感表达
```

### 4. KEYWORD - 关键词触发
```python
activation_type = ActionActivationType.KEYWORD
activation_keywords = ["画", "图片", "生成"]
# 明确指令触发的动作，如图片生成
```

## 性能提升

### 理论性能改进
- **并行LLM判定**: 1.5-2x 提升
- **智能缓存**: 20-30% 额外提升
- **整体预期**: 2-3x 性能提升

### 缓存策略
- **缓存键**: `{action_name}_{context_hash}`
- **过期时间**: 30秒
- **哈希算法**: MD5 (消息内容+上下文)

## 向后兼容性

### 废弃方法处理
```python
async def process_actions_for_planner(...):
    """[已废弃] 此方法现在已被整合到 modify_actions() 中"""
    logger.warning("process_actions_for_planner() 已废弃")
    # 仍然返回结果以保持兼容性
    return current_using_actions
```

### 迁移指南
1. **主循环**: 使用 `modify_actions(observations, messages, context, extra)`
2. **规划器**: 直接使用 `ActionManager.get_using_actions()`
3. **移除**: 规划器中对 `process_actions_for_planner()` 的调用

## 测试验证

### 运行测试
```bash
python test_corrected_architecture.py
```

### 测试内容
- 架构正确性验证
- 数据一致性检查
- 职责分离确认
- 性能测试
- 向后兼容性验证

## 优势总结

### 1. 清晰的架构
- **单一职责**: 每个组件专注于自己的核心功能
- **关注点分离**: 动作管理与决策制定分离
- **可维护性**: 逻辑清晰，易于理解和修改

### 2. 高性能
- **并行处理**: 多个LLM判定同时进行
- **智能缓存**: 避免重复计算

### 3. 智能化
- **动态配置**: 从动作配置中收集关键词
- **上下文感知**: 基于聊天内容智能激活
- **冲突避免**: 防止重复激活

### 4. 可扩展性
- **插件式**: 新的激活类型易于添加
- **配置驱动**: 通过配置控制行为
- **模块化**: 各组件独立可测试

这个修正后的架构实现了正确的职责分工，确保了主循环负责动作管理，规划器专注于决策，同时集成了并行判定和智能缓存等优化功能。