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

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`: 表达器模块