feat：给动作添加了选择器，并添加了新api

Author: SengokuCola

CORRECTED_ARCHITECTURE.md

@@ -0,0 +1,189 @@
+# 修正后的动作激活架构
+
+## 架构原则
+
+### 正确的职责分工
+- **主循环 (`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. 可扩展性
+- **插件式**: 新的激活类型易于添加
+- **配置驱动**: 通过配置控制行为
+- **模块化**: 各组件独立可测试
+
+这个修正后的架构实现了正确的职责分工，确保了主循环负责动作管理，规划器专注于决策，同时集成了并行判定和智能缓存等优化功能。