feat(action): 重构 Action 激活机制并添加 go_activate() 方法

引入新的 Action 激活机制,允许通过重写 go_activate() 方法来自定义激活逻辑。提供了三个工具函数:
- _random_activation(): 随机概率激活
- _keyword_match(): 关键词匹配激活
- _llm_judge_activation(): LLM 智能判断激活

主要变更:
- 在 BaseAction 中添加 go_activate() 抽象方法和相关工具函数
- 更新 ActionModifier 使用新的激活判断逻辑
- 在 hello_world_plugin 中添加新的激活方式示例
- 更新文档说明新的激活机制
- 保持向后兼容,旧的激活类型配置仍然可用

BREAKING CHANGE: Action 激活判断现在通过 go_activate() 方法进行,旧的激活类型字段已标记为废弃但仍然兼容
This commit is contained in:
Windpicker-owo
2025-10-17 20:16:15 +08:00
parent ce3fe95b37
commit f22e6365cc
7 changed files with 961 additions and 65 deletions

View File

@@ -1,5 +1,9 @@
# ⚡ Action组件详解
> **🎉 新功能:更灵活的激活机制!**
> MoFox-Bot 现在支持通过 `go_activate()` 方法自定义 Action 激活逻辑!
> 详见:[Action 激活机制重构指南](./action-activation-guide.md)
## 📖 什么是Action
Action是给MoFox_Bot在回复之外提供额外功能的智能组件**由MoFox_Bot的决策系统自主选择是否使用**具有随机性和拟人化的调用特点。Action不是直接响应用户命令而是让MoFox_Bot根据聊天情境智能地选择合适的动作使其行为更加自然和真实。
@@ -72,11 +76,55 @@ Action采用**两层决策机制**来优化性能和决策质量:
**第一层激活控制Activation Control**
激活决定MoFox-Bot是否 **知道** 这个Action的存在即这个Action是否进入决策候选池。不被激活的ActionMoFox-Bot永远不会选择。
激活决定MoFox-Bot是否 **"知道"** 这个Action的存在即这个Action是否进入决策候选池。不被激活的ActionMoFox-Bot永远不会选择。
**第二层使用决策Usage Decision**
在Action被激活后使用条件决定MoFox-Bot什么时候会 **选择** 使用这个Action。
在Action被激活后使用条件决定MoFox-Bot什么时候会 **"选择"** 使用这个Action。
---
## 🆕 新的激活机制(推荐)
从现在开始,推荐使用 **`go_activate()` 方法** 来自定义 Action 的激活逻辑。这种方式更灵活、更强大!
### 快速示例
```python
class MyAction(BaseAction):
action_name = "my_action"
action_description = "我的自定义 Action"
async def go_activate(self, llm_judge_model=None) -> bool:
"""判断是否激活此 Action
注意:聊天内容会自动从实例属性中获取,无需手动传入
"""
# 关键词激活
if await self._keyword_match(["你好", "hello"]):
return True
# 或者随机 10% 概率激活
return await self._random_activation(0.1)
async def execute(self) -> tuple[bool, str]:
await self.send_text("Hello!")
return True, "发送成功"
```
**提供的工具函数:**
- `_random_activation(probability)` - 随机激活
- `_keyword_match(keywords)` - 关键词匹配(自动获取聊天内容)
- `_llm_judge_activation(judge_prompt, llm_judge_model)` - LLM 智能判断(自动获取聊天内容)
**📚 完整指南:** 查看 [Action 激活机制重构指南](./action-activation-guide.md) 了解详情和更多示例。
---
## 📜 旧的激活机制(已废弃但仍然兼容)
> ⚠️ **注意:** 以下激活类型配置方式已废弃,但仍然兼容。
> 推荐使用新的 `go_activate()` 方法来实现更灵活的激活逻辑。
### 决策参数详解 🔧