feat：统一加载插件，区分内部插件和外部插件，提供示例命令发送插件

Author: SengokuCola

.gitignore

@@ -309,10 +309,4 @@ src/plugins/test_plugin_pic/actions/pic_action_config.toml
 run_pet.bat
 
 # 忽略 /src/plugins 但保留特定目录
-/src/plugins/*
-!/src/plugins/doubao_pic/
-!/src/plugins/mute_plugin/
-!/src/plugins/tts_plugin/
-!/src/plugins/vtb_action/
-!/src/plugins/__init__.py
-!/src/plugins/example_commands/
+/plugins/*

HEARFLOW_API_说明文档.md

@@ -0,0 +1,241 @@
+# HearflowAPI 使用说明
+
+## 概述
+
+HearflowAPI 是一个新增的插件API模块，提供了与心流和子心流相关的操作接口。通过这个API，插件开发者可以方便地获取和操作sub_hearflow实例。
+
+## 主要功能
+
+### 1. 获取子心流实例
+
+#### `get_sub_hearflow_by_chat_id(chat_id: str) -> Optional[SubHeartflow]`
+根据chat_id获取指定的sub_hearflow实例（仅获取已存在的）。
+
+**参数：**
+- `chat_id`: 聊天ID，与sub_hearflow的subheartflow_id相同
+
+**返回值：**
+- `SubHeartflow`: sub_hearflow实例，如果不存在则返回None
+
+**示例：**
+```python
+# 获取当前聊天的子心流实例
+current_subflow = await self.get_sub_hearflow_by_chat_id(self.observation.chat_id)
+if current_subflow:
+    print(f"找到子心流: {current_subflow.chat_id}")
+else:
+    print("子心流不存在")
+```
+
+#### `get_or_create_sub_hearflow_by_chat_id(chat_id: str) -> Optional[SubHeartflow]`
+根据chat_id获取或创建sub_hearflow实例。
+
+**参数：**
+- `chat_id`: 聊天ID
+
+**返回值：**
+- `SubHeartflow`: sub_hearflow实例，创建失败时返回None
+
+**示例：**
+```python
+# 获取或创建子心流实例
+subflow = await self.get_or_create_sub_hearflow_by_chat_id("some_chat_id")
+if subflow:
+    print("成功获取或创建子心流")
+```
+
+### 2. 获取子心流列表
+
+#### `get_all_sub_hearflow_ids() -> List[str]`
+获取所有活跃子心流的ID列表。
+
+**返回值：**
+- `List[str]`: 所有活跃子心流的ID列表
+
+#### `get_all_sub_hearflows() -> List[SubHeartflow]`
+获取所有活跃的子心流实例。
+
+**返回值：**
+- `List[SubHeartflow]`: 所有活跃的子心流实例列表
+
+**示例：**
+```python
+# 获取所有活跃的子心流ID
+all_chat_ids = self.get_all_sub_hearflow_ids()
+print(f"共有 {len(all_chat_ids)} 个活跃的子心流")
+
+# 获取所有活跃的子心流实例
+all_subflows = self.get_all_sub_hearflows()
+for subflow in all_subflows:
+    print(f"子心流 {subflow.chat_id} 状态: {subflow.chat_state.chat_status.value}")
+```
+
+### 3. 心流状态操作
+
+#### `get_sub_hearflow_chat_state(chat_id: str) -> Optional[ChatState]`
+获取指定子心流的聊天状态。
+
+**参数：**
+- `chat_id`: 聊天ID
+
+**返回值：**
+- `ChatState`: 聊天状态，如果子心流不存在则返回None
+
+#### `set_sub_hearflow_chat_state(chat_id: str, target_state: ChatState) -> bool`
+设置指定子心流的聊天状态。
+
+**参数：**
+- `chat_id`: 聊天ID
+- `target_state`: 目标状态
+
+**返回值：**
+- `bool`: 是否设置成功
+
+**示例：**
+```python
+from src.chat.heart_flow.sub_heartflow import ChatState
+
+# 获取当前状态
+current_state = await self.get_sub_hearflow_chat_state(self.observation.chat_id)
+print(f"当前状态: {current_state.value}")
+
+# 设置状态
+success = await self.set_sub_hearflow_chat_state(self.observation.chat_id, ChatState.FOCUS)
+if success:
+    print("状态设置成功")
+```
+
+### 4. Replyer和Expressor操作
+
+#### `get_sub_hearflow_replyer_and_expressor(chat_id: str) -> Tuple[Optional[Any], Optional[Any]]`
+根据chat_id获取指定子心流的replyer和expressor实例。
+
+**参数：**
+- `chat_id`: 聊天ID
+
+**返回值：**
+- `Tuple[Optional[Any], Optional[Any]]`: (replyer实例, expressor实例)，如果子心流不存在或未处于FOCUSED状态，返回(None, None)
+
+#### `get_sub_hearflow_replyer(chat_id: str) -> Optional[Any]`
+根据chat_id获取指定子心流的replyer实例。
+
+**参数：**
+- `chat_id`: 聊天ID
+
+**返回值：**
+- `Optional[Any]`: replyer实例，如果不存在则返回None
+
+#### `get_sub_hearflow_expressor(chat_id: str) -> Optional[Any]`
+根据chat_id获取指定子心流的expressor实例。
+
+**参数：**
+- `chat_id`: 聊天ID
+
+**返回值：**
+- `Optional[Any]`: expressor实例，如果不存在则返回None
+
+**示例：**
+```python
+# 获取replyer和expressor
+replyer, expressor = await self.get_sub_hearflow_replyer_and_expressor(self.observation.chat_id)
+if replyer and expressor:
+    print(f"获取到replyer: {type(replyer).__name__}")
+    print(f"获取到expressor: {type(expressor).__name__}")
+    
+    # 检查属性
+    print(f"Replyer聊天ID: {replyer.chat_id}")
+    print(f"Expressor聊天ID: {expressor.chat_id}")
+    print(f"是否群聊: {replyer.is_group_chat}")
+
+# 单独获取replyer
+replyer = await self.get_sub_hearflow_replyer(self.observation.chat_id)
+if replyer:
+    print("获取到replyer实例")
+
+# 单独获取expressor  
+expressor = await self.get_sub_hearflow_expressor(self.observation.chat_id)
+if expressor:
+    print("获取到expressor实例")
+```
+
+## 可用的聊天状态
+
+```python
+from src.chat.heart_flow.sub_heartflow import ChatState
+
+ChatState.FOCUS    # 专注模式
+ChatState.NORMAL   # 普通模式  
+ChatState.ABSENT   # 离开模式
+```
+
+## 完整插件示例
+
+```python
+from typing import Tuple
+from src.chat.actions.plugin_action import PluginAction, register_action
+from src.chat.heart_flow.sub_heartflow import ChatState
+
+@register_action
+class MyHearflowPlugin(PluginAction):
+    """我的心流插件"""
+    
+    activation_keywords = ["心流信息"]
+    
+    async def process(self) -> Tuple[bool, str]:
+        try:
+            # 获取当前聊天的chat_id
+            current_chat_id = self.observation.chat_id
+            
+            # 获取子心流实例
+            subflow = await self.get_sub_hearflow_by_chat_id(current_chat_id)
+            if not subflow:
+                return False, "未找到子心流实例"
+            
+            # 获取状态信息
+            current_state = await self.get_sub_hearflow_chat_state(current_chat_id)
+            
+            # 构建回复
+            response = f"心流信息：\n"
+            response += f"聊天ID: {current_chat_id}\n"
+            response += f"当前状态: {current_state.value}\n"
+            response += f"是否群聊: {subflow.is_group_chat}\n"
+            
+            return True, response
+            
+        except Exception as e:
+            return False, f"处理出错: {str(e)}"
+```
+
+## 注意事项
+
+1. **线程安全**: API内部已处理锁机制，确保线程安全。
+
+2. **错误处理**: 所有API方法都包含异常处理，失败时会记录日志并返回安全的默认值。
+
+3. **性能考虑**: `get_sub_hearflow_by_chat_id` 只获取已存在的实例，性能更好；`get_or_create_sub_hearflow_by_chat_id` 会在需要时创建新实例。
+
+4. **状态管理**: 修改心流状态时请谨慎，确保不会影响系统的正常运行。
+
+5. **日志记录**: 所有操作都会记录适当的日志，便于调试和监控。
+
+6. **Replyer和Expressor可用性**: 
+   - 这些实例仅在子心流处于**FOCUSED状态**时可用
+   - 如果子心流处于NORMAL或ABSENT状态，将返回None
+   - 需要确保HeartFC实例存在且正常运行
+
+7. **使用Replyer和Expressor时的注意事项**:
+   - 直接调用这些实例的方法需要谨慎，可能影响系统正常运行
+   - 建议主要用于监控、信息获取和状态检查
+   - 不建议在插件中直接调用回复生成方法，这可能与系统的正常流程冲突
+
+## 相关类型和模块
+
+- `SubHeartflow`: 子心流实例类
+- `ChatState`: 聊天状态枚举
+- `DefaultReplyer`: 默认回复器类
+- `DefaultExpressor`: 默认表达器类
+- `HeartFChatting`: 专注聊天主类
+- `src.chat.heart_flow.heartflow`: 主心流模块
+- `src.chat.heart_flow.subheartflow_manager`: 子心流管理器
+- `src.chat.focus_chat.replyer.default_replyer`: 回复器模块
+- `src.chat.focus_chat.expressors.default_expressor`: 表达器模块 

docs/plugin_loading_paths.md

@@ -0,0 +1,119 @@
+# 插件加载路径说明
+
+## 概述
+
+MaiBot-Core 现在支持从多个路径加载插件，为插件开发者提供更大的灵活性。
+
+## 支持的插件路径
+
+系统会按以下优先级顺序搜索和加载插件：
+
+### 1. 项目根目录插件路径：`/plugins`
+- **路径**: 项目根目录下的 `plugins/` 文件夹
+- **优先级**: 最高
+- **用途**: 用户自定义插件、第三方插件
+- **特点**: 
+  - 与项目源码分离
+  - 便于版本控制管理
+  - 适合用户添加个人插件
+
+### 2. 源码目录插件路径：`/src/plugins`
+- **路径**: src目录下的 `plugins/` 文件夹
+- **优先级**: 次高
+- **用途**: 系统内置插件、官方插件
+- **特点**:
+  - 与项目源码集成
+  - 适合系统级功能插件
+
+## 插件结构支持
+
+两个路径都支持相同的插件结构：
+
+### 传统结构（推荐用于复杂插件）
+```
+plugins/my_plugin/
+├── __init__.py
+├── actions/
+│   ├── __init__.py
+│   └── my_action.py
+├── commands/
+│   ├── __init__.py
+│   └── my_command.py
+└── config.toml
+```
+
+### 简化结构（推荐用于简单插件）
+```
+plugins/my_plugin/
+├── __init__.py
+├── my_action.py
+├── my_command.py
+└── config.toml
+```
+
+## 文件命名约定
+
+### 动作文件
+- `*_action.py`
+- `*_actions.py`
+- 包含 `action` 字样的文件名
+
+### 命令文件
+- `*_command.py`
+- `*_commands.py`
+- 包含 `command` 字样的文件名
+
+## 加载行为
+
+1. **顺序加载**: 先加载 `/plugins`，再加载 `/src/plugins`
+2. **重名处理**: 如果两个路径中有同名插件，优先加载 `/plugins` 中的版本
+3. **错误隔离**: 单个插件加载失败不会影响其他插件的加载
+4. **详细日志**: 系统会记录每个插件的来源路径和加载状态
+
+## 最佳实践
+
+### 用户插件开发
+- 将自定义插件放在 `/plugins` 目录
+- 使用清晰的插件命名
+- 包含必要的 `__init__.py` 文件
+
+### 系统插件开发
+- 将系统集成插件放在 `/src/plugins` 目录
+- 遵循项目代码规范
+- 完善的错误处理
+
+### 版本控制
+- 将 `/plugins` 目录添加到 `.gitignore`（如果是用户自定义插件）
+- 或者为插件创建独立的git仓库
+
+## 示例插件
+
+参考 `/plugins/example_root_plugin/` 中的示例插件，了解如何在根目录创建插件。
+
+## 故障排除
+
+### 常见问题
+
+1. **插件未被加载**
+   - 检查插件目录是否有 `__init__.py` 文件
+   - 确认文件命名符合约定
+   - 查看启动日志中的加载信息
+
+2. **导入错误**
+   - 确保插件依赖的模块已安装
+   - 检查导入路径是否正确
+
+3. **重复注册**
+   - 检查是否有同名的动作或命令
+   - 避免在不同路径放置相同功能的插件
+
+### 调试日志
+
+启动时查看日志输出：
+```
+[INFO] 正在从 plugins 加载插件...
+[INFO] 正在从 src/plugins 加载插件...
+[SUCCESS] 插件加载完成: 总计 X 个动作, Y 个命令
+[INFO] 插件加载详情:
+[INFO]   example_plugin (来源: plugins): 1 动作, 1 命令
+``` 

src/chat/actions/plugin_action.py

@@ -17,6 +17,7 @@
 from src.chat.actions.plugin_api.config_api import ConfigAPI
 from src.chat.actions.plugin_api.utils_api import UtilsAPI
 from src.chat.actions.plugin_api.stream_api import StreamAPI
+from src.chat.actions.plugin_api.hearflow_api import HearflowAPI
 
 # 以下为类型注解需要
 from src.chat.message_receive.chat_stream import ChatStream # noqa
@@ -27,7 +28,7 @@
 logger = get_logger("plugin_action")
 
 
-class PluginAction(BaseAction, MessageAPI, LLMAPI, DatabaseAPI, ConfigAPI, UtilsAPI, StreamAPI):
+class PluginAction(BaseAction, MessageAPI, LLMAPI, DatabaseAPI, ConfigAPI, UtilsAPI, StreamAPI, HearflowAPI):
     """插件动作基类
 
     封装了主程序内部依赖，提供简化的API接口给插件开发者