doc：提交心流的readme(部分）

2025-04-26 01:46:30 +08:00
parent 8652ceb13e
commit 27098321d5
1 changed files with 143 additions and 133 deletions
--- a/src/heart_flow/README.md
+++ b/src/heart_flow/README.md
@@ -1,157 +1,167 @@
 # 心流系统 (Heart Flow System)

-## 系统架构
+*在此处简要介绍心流系统的目标和作用*

-### 1. 主心流 (Heartflow)
- 位于 `heartflow.py`
- 作为整个系统的主控制器
- 负责管理和协调多个子心流
- 维护AI的整体思维状态
- 定期进行全局思考更新
+## 1. 系统架构 (System Architecture)

-### 2. 子心流 (SubHeartflow)
- 位于 `sub_heartflow.py`
- 处理具体的对话场景（如群聊）
- 维护特定场景下的思维状态
- 通过观察者模式接收和处理信息
- 能够进行独立的思考和回复判断
+### 1.1. 主心流 (Heartflow)
+- **文件**: `heartflow.py`
+- **职责**:
+    - 作为整个系统的主控制器。
+    - 持有并管理 `SubHeartflowManager`，用于管理所有子心流。
+    - 持有并管理自身状态 `self.current_state: MaiStateInfo`，该状态控制系统的整体行为模式。
+    - 统筹管理系统后台任务（如消息存储、资源分配等）。
+    - **注意**: 主心流自身不进行周期性的全局思考更新。

-### 3. 观察系统 (Observation)
- 位于 `observation.py`
- 负责收集和处理外部信息
- 支持多种观察类型（如聊天观察）
- 对信息进行实时总结和更新
+### 1.2. 子心流 (SubHeartflow)
+- **文件**: `sub_heartflow.py`
+- **职责**:
+    - 处理具体的交互场景，例如：群聊、私聊、与虚拟主播(vtb)互动、桌面宠物交互等。
+    - 维护特定场景下的思维状态和聊天流状态 (`ChatState`)。
+    - 通过关联的 `Observation` 实例接收和处理信息。
+    - 拥有独立的思考 (`SubMind`) 和回复判断能力。
+- **观察者**: 每个子心流可以拥有一个或多个 `Observation` 实例（目前每个子心流仅使用一个 `ChattingObservation`）。
+- **内部结构**:
+    - **聊天流状态 (`ChatState`)**: 标记当前子心流的参与模式 (`ABSENT`, `CHAT`, `FOCUSED`)，决定是否观察、回复以及使用何种回复模式。
+    - **聊天实例 (`NormalChatInstance` / `HeartFlowChatInstance`)**: 根据 `ChatState` 激活对应的实例来处理聊天逻辑。同一时间只有一个实例处于活动状态。

+### 1.3. 观察系统 (Observation)
+- **文件**: `observation.py`
+- **职责**:
+    - 定义信息输入的来源和格式。
+    - 为子心流提供其所处环境的信息。
+- **当前实现**: 
+    - 目前仅有 `ChattingObservation` 一种观察类型。
+    - `ChattingObservation` 负责从数据库拉取指定聊天的最新消息，并将其格式化为可读内容，供 `SubHeartflow` 使用。

-## 工作流程
+### 1.4. 子心流管理器 (SubHeartflowManager)
+- **文件**: `subheartflow_manager.py`
+- **职责**:
+    - 作为 `Heartflow` 的成员变量存在。
+    - 负责所有 `SubHeartflow` 实例的生命周期管理，包括：
+        - 创建和获取 (`create_or_get_subheartflow`)。
+        - 停止和清理 (`stop_subheartflow`, `cleanup_inactive_subheartflows`)。
+        - 根据 `Heartflow` 的状态和限制条件，激活、停用或调整子心流的状态。

-1. 主心流启动并创建必要的子心流
-2. 子心流通过观察者接收外部信息
-3. 系统进行信息处理和思维更新
-4. 根据情感状态和思维结果决定是否回复
-5. 生成合适的回复并更新思维状态
+### 1.5. 消息处理与回复流程 (Message Processing vs. Replying Flow)
+- **关注点分离**: 系统严格区分了接收和处理传入消息的流程与决定和生成回复的流程。
+    - **消息处理 (Processing)**: 
+        - 由一个独立的处理器（例如 `HeartFCProcessor`）负责接收原始消息数据。
+        - 职责包括：消息解析 (`MessageRecv`)、过滤（屏蔽词、正则表达式）、基于记忆系统的初步兴趣计算 (`HippocampusManager`)、消息存储 (`MessageStorage`) 以及用户关系更新 (`RelationshipManager`)。
+        - 处理后的消息信息（如计算出的兴趣度）会传递给对应的 `SubHeartflow`。
+    - **回复决策与生成 (Replying)**:
+        - 由 `SubHeartflow` 及其当前激活的聊天实例 (`NormalChatInstance` 或 `HeartFlowChatInstance`) 负责。
+        - 基于其内部状态 (`ChatState`、`SubMind` 的思考结果)、观察到的信息 (`Observation` 提供的内容) 以及 `InterestChatting` 的状态来决定是否回复、何时回复以及如何回复。
+- **消息缓冲 (Message Caching)**:
+    - `message_buffer` 模块会对某些传入消息进行临时缓存，尤其是在处理连续的多部分消息（如多张图片）时。
+    - 这个缓冲机制发生在 `HeartFCProcessor` 处理流程中，确保消息的完整性，然后才进行后续的存储和兴趣计算。
+    - 缓存的消息最终仍会流向对应的 `ChatStream`（与 `SubHeartflow` 关联），但核心的消息处理与回复决策仍然是分离的步骤。

-## 使用说明
+## 2. 核心控制与状态管理 (Core Control and State Management)

-### 创建新的子心流
+### 2.1. Heart Flow 整体控制
+- **控制者**: 主心流 (`Heartflow`)
+- **核心职责**:
+    - 通过其成员 `SubHeartflowManager` 创建和管理子心流。
+    - 通过其成员 `self.current_state: MaiStateInfo` 控制整体行为模式。
+    - 管理系统级后台任务。
+
+### 2.2. Heart Flow 状态 (`MaiStateInfo`)
+- **定义与管理**: `Heartflow` 持有 `MaiStateInfo` 的实例 (`self.current_state`) 来管理其状态。状态的枚举定义在 `my_state_manager.py` 中的 `MaiState`。
+- **状态及含义**:
+    - `MaiState.OFFLINE` (不在线): 不观察任何群消息，不进行主动交互，仅存储消息。
+    - `MaiState.PEEKING` (看一眼手机): 有限度地参与聊天（由 `MaiStateInfo` 定义具体的普通/专注群数量限制）。
+    - `MaiState.NORMAL_CHAT` (正常看手机): 正常参与聊天，允许 `SubHeartflow` 进入 `CHAT` 或 `FOCUSED` 状态（数量受限）。
+    *   `MaiState.FOCUSED_CHAT` (专心看手机): 更积极地参与聊天，通常允许更多或更高优先级的 `FOCUSED` 状态子心流。
+- **作用**: `Heartflow` 的状态直接影响 `SubHeartflowManager` 如何管理子心流（如激活数量、允许的状态等）。
+
+### 2.3. 聊天流状态 (`ChatState`) 与转换
+- **管理对象**: 每个 `SubHeartflow` 实例内部维护其 `ChatStateInfo`，包含当前的 `ChatState`。
+- **状态及含义**:
+    - `ChatState.ABSENT` (不参与/没在看): 初始或停用状态。子心流不观察新信息，不进行思考，也不回复。
+    - `ChatState.CHAT` (随便看看/水群): 普通聊天模式。激活 `NormalChatInstance`。
+    *   `ChatState.FOCUSED` (专注/激情水群): 专注聊天模式。激活 `HeartFlowChatInstance`。
+- **选择**: 子心流可以根据外部指令（来自 `SubHeartflowManager`）或内部逻辑（未来的扩展）选择进入 `ABSENT` 状态（不回复不观察），或进入 `CHAT` / `FOCUSED` 中的一种回复模式。
+- **状态转换机制** (由 `SubHeartflowManager` 驱动):
+    - **激活 `CHAT`**: 当 `Heartflow` 状态从 `OFFLINE` 变为允许聊天的状态时，`SubHeartflowManager` 会根据限制，选择部分 `ABSENT` 状态的子心流，调用其 `set_chat_state` 方法将其转换为 `CHAT`。
+    - **激活 `FOCUSED`**: `SubHeartflowManager` 会定期评估处于 `CHAT` 状态的子心流的兴趣度 (`InterestChatting.start_hfc_probability`)，若满足条件且未达上限，则调用 `set_chat_state` 将其提升为 `FOCUSED`。
+    - **停用/回退**: `SubHeartflowManager` 可能因 `Heartflow` 状态变化、达到数量限制、长时间不活跃或随机概率等原因，调用 `set_chat_state` 将子心流状态设置为 `ABSENT` 或从 `FOCUSED` 回退到 `CHAT`。
+
+## 3. 聊天实例详解 (Chat Instances Explained)
+
+### 3.1. NormalChatInstance
+- **激活条件**: 对应 `SubHeartflow` 的 `ChatState` 为 `CHAT`。
+- **工作流程**:
+    - 按照系统设定的普通聊天规则处理群消息。
+    - 定期检查新消息。
+    - 对简单询问、闲聊等进行及时回复。
+- **行为特点**:
+    - 回复相对常规、简单。
+    - 不投入过多计算资源。
+    - 侧重于维持基本的交流氛围。
+    - 示例：对问候语、日常分享等进行简单回应。
+
+### 3.2. HeartFlowChatInstance (继承自原 PFC 逻辑)
+- **激活条件**: 对应 `SubHeartflow` 的 `ChatState` 为 `FOCUSED`。
+- **工作流程**:
+    - 基于更复杂的规则（原 PFC 模式）进行深度处理。
+    - 对群内话题进行深入分析。
+    - 可能主动发起相关话题或引导交流。
+- **行为特点**:
+    - 回复更积极、深入。
+    - 投入更多资源参与聊天。
+    - 回复内容可能更详细、有针对性。
+    - 对话题参与度高，能带动交流。
+    - 示例：对复杂或有争议话题阐述观点，并与人互动。
+
+## 4. 工作流程示例 (Example Workflow)
+
+1.  **启动**: `Heartflow` 启动，初始化 `MaiStateInfo` (例如 `OFFLINE`) 和 `SubHeartflowManager`。
+2.  **状态变化**: 用户操作或内部逻辑使 `Heartflow` 的 `current_state` 变为 `NORMAL_CHAT`。
+3.  **管理器响应**: `SubHeartflowManager` 检测到状态变化，根据 `NORMAL_CHAT` 的限制，调用 `create_or_get_subheartflow` 获取或创建子心流，并通过 `set_chat_state` 将部分子心流状态从 `ABSENT` 激活为 `CHAT`。
+4.  **子心流激活**: 被激活的 `SubHeartflow` 启动其 `NormalChatInstance`。
+5.  **信息接收**: 该 `SubHeartflow` 的 `ChattingObservation` 开始从数据库拉取新消息。
+6.  **普通回复**: `NormalChatInstance` 处理观察到的信息，执行普通回复逻辑。
+7.  **兴趣评估**: `SubHeartflowManager` 定期评估该子心流的 `InterestChatting` 状态。
+8.  **提升状态**: 若兴趣度达标且 `Heartflow` 状态允许，`SubHeartflowManager` 调用该子心流的 `set_chat_state` 将其状态提升为 `FOCUSED`。
+9.  **子心流切换**: `SubHeartflow` 内部停止 `NormalChatInstance`，启动 `HeartFlowChatInstance`。
+10. **专注回复**: `HeartFlowChatInstance` 开始根据其逻辑进行更深入的交互。
+11. **状态回落/停用**: 若 `Heartflow` 状态变为 `OFFLINE`，`SubHeartflowManager` 会调用所有子心流的 `set_chat_state(ChatState.ABSENT)`，使其停止活动。
+
+## 5. 使用与配置 (Usage and Configuration)
+
+### 5.1. 使用说明 (Code Examples)
+- **(内部)创建/获取子心流** (由 `SubHeartflowManager` 调用):
  ```python
-heartflow = Heartflow()
-subheartflow = heartflow.create_subheartflow(chat_id)
+  # subheartflow_manager.py
+  new_subflow = SubHeartflow(subheartflow_id, mai_states)
+  await new_subflow.initialize()
+  observation = ChattingObservation(chat_id=subheartflow_id)
+  new_subflow.add_observation(observation)
+  ```
+- **(内部)添加观察者** (由 `SubHeartflowManager` 或 `SubHeartflow` 内部调用):
+  ```python
+  # sub_heartflow.py
+  self.observations.append(observation)
  ```

-### 添加观察者
-```python
-observation = ChattingObservation(chat_id)
-subheartflow.add_observation(observation)
-```
+### 5.2. 配置参数 (Key Parameters)
+- `sub_heart_flow_stop_time`: 子心流停止（标记为可清理）的不活跃时间阈值 (似乎由 `SubHeartflowManager.cleanup_inactive_subheartflows` 的参数 `inactive_threshold_seconds` 控制)。
+- `sub_heart_flow_freeze_time`: 子心流冻结时间 (当前文档未明确体现，可能需要审阅代码确认)。
+- `heart_flow_update_interval`: 主心流更新其状态或执行管理操作的频率 (需要审阅 `Heartflow` 代码确认)。
+- `MaiStateInfo` 内的限制: 定义了不同主状态下 `CHAT` 和 `FOCUSED` 子心流的数量上限。

-## 配置说明
+## 6. 注意事项 (Important Notes)

-系统的主要配置参数：
- `sub_heart_flow_stop_time`: 子心流停止时间
- `sub_heart_flow_freeze_time`: 子心流冻结时间
- `heart_flow_update_interval`: 心流更新间隔
+1.  **自动清理**: `SubHeartflowManager` 会定期检查并清理长时间不活跃的子心流。
+2.  **性能平衡**: 主心流执行管理操作的频率（如检查状态、清理、评估兴趣）需要合理配置，以平衡系统性能和响应速度。
+3.  **信息过载**: 单个 `ChattingObservation` 会限制一次性从数据库拉取的消息数量 (`max_now_obs_len`)。

-## 注意事项
+## 7. 待办与未来方向 (TODOs and Future Directions)

-1. 子心流会在长时间不活跃后自动清理
-2. 需要合理配置更新间隔以平衡性能和响应速度
-3. 观察系统会限制消息处理数量以避免过载 
-
-# HeartFChatting 与主动回复流程说明 (V2)
-
-本文档描述了 `HeartFChatting` 类及其在 `heartFC_controler` 模块中实现的主动、基于兴趣的回复流程。
-
-## 1. `HeartFChatting` 类概述
-
-*   **目标**: 管理特定聊天流 (`stream_id`) 的主动回复逻辑，使其行为更像人类的自然交流。
-*   **创建时机**: 当 `HeartFC_Chat` 的兴趣监控任务 (`_interest_monitor_loop`) 检测到某个聊天流的兴趣度 (`InterestChatting`) 达到了触发回复评估的条件 (`should_evaluate_reply`) 时，会为该 `stream_id` 获取或创建唯一的 `HeartFChatting` 实例 (`_get_or_create_heartFC_chat`)。
-*   **持有**:
-    *   对应的 `sub_heartflow` 实例引用 (通过 `heartflow.get_subheartflow(stream_id)`)。
-    *   对应的 `chat_stream` 实例引用。
-    *   对 `HeartFC_Chat` 单例的引用 (用于调用发送消息、处理表情等辅助方法)。
-*   **初始化**: `HeartFChatting` 实例在创建后会执行异步初始化 (`_initialize`)，这可能包括加载必要的上下文或历史信息（*待确认是否实现了读取历史消息*）。
-
-## 2. 核心回复流程 (由 `HeartFC_Chat` 触发)
-
-当 `HeartFC_Chat` 调用 `HeartFChatting` 实例的方法 (例如 `add_time`) 时，会启动内部的回复决策与执行流程：
-
-1.  **规划 (Planner):**
-    *   **输入**: 从关联的 `sub_heartflow` 获取观察结果、思考链、记忆片段等上下文信息。
-    *   **决策**:
-        *   判断当前是否适合进行回复。
-        *   决定回复的形式（纯文本、带表情包等）。
-        *   选择合适的回复时机和策略。
-    *   **实现**: *此部分逻辑待详细实现，可能利用 LLM 的工具调用能力来增强决策的灵活性和智能性。需要考虑机器人的个性化设定。*
-
-2.  **回复生成 (Replier):**
-    *   **输入**: Planner 的决策结果和必要的上下文。
-    *   **执行**:
-        *   调用 `ResponseGenerator` (`self.gpt`) 或类似组件生成具体的回复文本内容。
-        *   可能根据 Planner 的策略生成多个候选回复。
-    *   **并发**: 系统支持同时存在多个思考/生成任务（上限由 `global_config.max_concurrent_thinking_messages` 控制）。
-
-3.  **检查 (Checker):**
-    *   **时机**: 在回复生成过程中或生成后、发送前执行。
-    *   **目的**:
-        *   检查自开始生成回复以来，聊天流中是否出现了新的消息。
-        *   评估已生成的候选回复在新的上下文下是否仍然合适、相关。
-        *   *需要实现相似度比较逻辑，防止发送与近期消息内容相近或重复的回复。*
-    *   **处理**: 如果检查结果认为回复不合适，则该回复将被**抛弃**。
-
-4.  **发送协调:**
-    *   **执行**: 如果 Checker 通过，`HeartFChatting` 会调用 `HeartFC_Chat` 实例提供的发送接口：
-        *   `_create_thinking_message`: 通知 `MessageManager` 显示"正在思考"状态。
-        *   `_send_response_messages`: 将最终的回复文本交给 `MessageManager` 进行排队和发送。
-        *   `_handle_emoji`: 如果需要发送表情包，调用此方法处理表情包的获取和发送。
-    *   **细节**: 实际的消息发送、排队、间隔控制由 `MessageManager` 和 `MessageSender` 负责。
-
-## 3. 与其他模块的交互
-
-*   **`HeartFC_Chat`**:
-    *   创建、管理和触发 `HeartFChatting` 实例。
-    *   提供发送消息 (`_send_response_messages`)、处理表情 (`_handle_emoji`)、创建思考消息 (`_create_thinking_message`) 的接口给 `HeartFChatting` 调用。
-    *   运行兴趣监控循环 (`_interest_monitor_loop`)。
-*   **`InterestManager` / `InterestChatting`**:
-    *   `InterestManager` 存储每个 `stream_id` 的 `InterestChatting` 实例。
-    *   `InterestChatting` 负责计算兴趣衰减和回复概率。
-    *   `HeartFC_Chat` 查询 `InterestChatting.should_evaluate_reply()` 来决定是否触发 `HeartFChatting`。
-*   **`heartflow` / `sub_heartflow`**:
-    *   `HeartFChatting` 从对应的 `sub_heartflow` 获取进行规划所需的核心上下文信息 (观察、思考链等)。
-*   **`MessageManager` / `MessageSender`**:
-    *   接收来自 `HeartFC_Chat` 的发送请求 (思考消息、文本消息、表情包消息)。
-    *   管理消息队列 (`MessageContainer`)，处理消息发送间隔和实际发送 (`MessageSender`)。
-*   **`ResponseGenerator` (`gpt`)**:
-    *   被 `HeartFChatting` 的 Replier 部分调用，用于生成回复文本。
-*   **`MessageStorage`**:
-    *   存储所有接收和发送的消息。
-*   **`HippocampusManager`**:
-    *   `HeartFC_Processor` 使用它计算传入消息的记忆激活率，作为兴趣度计算的输入之一。
-
-## 4. 原有问题与状态更新
-
-1.  **每个 `pfchating` 是否对应一个 `chat_stream`，是否是唯一的？**
-    *   **是**。`HeartFC_Chat._get_or_create_heartFC_chat` 确保了每个 `stream_id` 只有一个 `HeartFChatting` 实例。 (已确认)
-2.  **`observe_text` 传入进来是纯 str，是不是应该传进来 message 构成的 list?**
-    *   **机制已改变**。当前的触发机制是基于 `InterestManager` 的概率判断。`HeartFChatting` 启动后，应从其关联的 `sub_heartflow` 获取更丰富的上下文信息，而非简单的 `observe_text`。
-3.  **检查失败的回复应该怎么处理？**
-    *   **暂定：抛弃**。这是当前 Checker 逻辑的基础设定。
-4.  **如何比较相似度？**
-    *   **待实现**。Checker 需要具体的算法来比较候选回复与新消息的相似度。
-5.  **Planner 怎么写？**
-    *   **待实现**。这是 `HeartFChatting` 的核心决策逻辑，需要结合 `sub_heartflow` 的输出、LLM 工具调用和个性化配置来设计。
-
-
-## 6. 未来优化点
-
-*   实现 Checker 中的相似度比较算法。
-*   详细设计并实现 Planner 的决策逻辑，包括 LLM 工具调用和个性化。
-*   确认并完善 `HeartFChatting._initialize()` 中的历史消息加载逻辑。
-*   探索更优的检查失败回复处理策略（例如：重新规划、修改回复等）。
-*   优化 `HeartFChatting` 与 `sub_heartflow` 的信息交互。
-
-
-
-BUG:
-2.复读，可能是planner还未校准好
-3.planner还未个性化，需要加入bot个性信息，且获取的聊天内容有问题
+*   **更新 "与其他模块的交互" 部分**: 详细说明 `SubHeartflowManager`, `SubHeartflow`, `NormalChatInstance`, `HeartFlowChatInstance` 之间以及与 `MessageManager`, `ResponseGenerator`, `InterestManager` 等外部模块的具体交互。
+*   **明确 `sub_heart_flow_freeze_time`**: 确认该配置项的实际作用和实现位置。
+*   **明确 `heart_flow_update_interval`**: 确认主心流管理循环的实际间隔。
+*   **扩展观察类型**: 实现更多 `Observation` 类型（如私聊、系统事件等）。
+*   **子心流内部状态转换**: 探索允许子心流根据自身思考结果主动请求状态转换的可能性。
+*   **资源管理**: 优化子心流的资源占用和清理策略。