Mofox-Core/HEARFLOW_API_说明文档.md

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

示例：

# 获取当前聊天的子心流实例
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

示例：

# 获取或创建子心流实例
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]: 所有活跃的子心流实例列表

示例：

# 获取所有活跃的子心流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: 是否设置成功

示例：

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

示例：

# 获取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实例")

可用的聊天状态

from src.chat.heart_flow.sub_heartflow import ChatState

ChatState.FOCUS    # 专注模式
ChatState.NORMAL   # 普通模式  
ChatState.ABSENT   # 离开模式

完整插件示例

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