将文件全部归进docs

2025-05-16 17:52:33 +08:00
parent 5d5033452d
commit e067384985
8 changed files with 34 additions and 139 deletions
--- a/docs/0.6Bing.md
+++ b/docs/0.6Bing.md
@@ -0,0 +1,79 @@
+- **智能化 MaiState 状态转换**:
+    - 当前 `MaiState` (整体状态，如 `OFFLINE`, `NORMAL_CHAT` 等) 的转换逻辑 (`MaiStateManager`) 较为简单，主要依赖时间和随机性。
+    - 未来的计划是让主心流 (`Heartflow`) 负责决策自身的 `MaiState`。
+    - 该决策将综合考虑以下信息：
+        - 各个子心流 (`SubHeartflow`) 的活动状态和信息摘要。
+        - 主心流自身的状态和历史信息。
+        - (可能) 结合预设的日程安排 (Schedule) 信息。
+    - 目标是让 Mai 的整体状态变化更符合逻辑和上下文。 (计划在 064 实现)
+
+- **参数化与动态调整聊天行为**:
+    - 将 `NormalChatInstance` 和 `HeartFlowChatInstance` 中的关键行为参数（例如：回复概率、思考频率、兴趣度阈值、状态转换条件等）提取出来，使其更易于配置。
+    - 允许每个 `SubHeartflow` (即每个聊天场景) 拥有其独立的参数配置，实现"千群千面"。
+    - 开发机制，使得这些参数能够被动态调整：
+        - 基于外部反馈：例如，根据用户评价（"话太多"或"太冷淡"）调整回复频率。
+        - 基于环境分析：例如，根据群消息的活跃度自动调整参与度。
+        - 基于学习：通过分析历史交互数据，优化特定群聊下的行为模式。
+    - 目标是让 Mai 在不同群聊中展现出更适应环境、更个性化的交互风格。
+
+- **动态 Prompt 生成与人格塑造**:
+    - 当前 Prompt (提示词) 相对静态。计划实现动态或半结构化的 Prompt 生成。
+    - Prompt 内容可根据以下因素调整：
+        - **人格特质**: 通过参数化配置（如友善度、严谨性等），影响 Prompt 的措辞、语气和思考倾向，塑造更稳定和独特的人格。
+        - **当前情绪**: 将实时情绪状态融入 Prompt，使回复更符合当下心境。
+    - 目标：提升 `HeartFlowChatInstance` (HFC) 回复的多样性、一致性和真实感。
+    - 前置：需要重构 Prompt 构建逻辑，可能引入 `PromptBuilder` 并提供标准接口 (认为是必须步骤)。
+
+
+- **增强工具调用能力 (Enhanced Tool Usage)**:
+    - 扩展 `HeartFlowChatInstance` (HFC) 可用的工具集。
+    - 考虑引入"元工具"或分层工具机制，允许 HFC 在需要时（如深度思考）访问更强大的工具，例如：
+        - 修改自身或其他 `SubHeartflow` 的聊天参数。
+        - 请求改变 Mai 的全局状态 (`MaiState`)。
+        - 管理日程或执行更复杂的分析任务。
+    - 目标：提升 HFC 的自主决策和行动能力，即使会增加一定的延迟。
+
+- **基于历史学习的行为模式应用**:
+    - **学习**: 分析过往聊天记录，提取和学习具体的行为模式（如特定梗的用法、情境化回应风格等）。可能需要专门的分析模块。
+    - **存储与匹配**: 需要有效的方法存储学习到的行为模式，并开发强大的 **匹配** 机制，在运行时根据当前情境检索最合适的模式。**(匹配的准确性是关键)**
+    - **应用与评估**: 将匹配到的行为模式融入 HFC 的决策和回复生成（例如，将其整合进 Prompt）。之后需评估该行为模式应用的实际效果。
+    - **人格塑造**: 通过学习到的实际行为来动态塑造人格，作为静态人设描述的补充或替代，使其更生动自然。
+
+- **标准化人设生成 (Standardized Persona Generation)**:
+    - **目标**: 解决手动配置 `人设` 文件缺乏标准、难以全面描述个性的问题，并生成更丰富、可操作的人格资源。
+    - **方法**: 利用大型语言模型 (LLM) 辅助生成标准化的、结构化的人格**资源包**。
+    - **生成内容**: 不仅生成描述性文本（替代现有 `individual` 配置），还可以同时生成与该人格配套的：
+        - **相关工具 (Tools)**: 该人格倾向于使用的工具或能力。
+        - **初始记忆/知识库 (Memories/Knowledge)**: 定义其背景和知识基础。
+        - **核心行为模式 (Core Behavior Patterns)**: 预置一些典型的行为方式，可作为行为学习的起点。
+    - **实现途径**: 
+        - 通过与 LLM 的交互式对话来定义和细化人格及其配套资源。
+        - 让 LLM 分析提供的文本材料（如小说、背景故事）来提取人格特质和相关信息。
+    - **优势**: 替代易出错且标准不一的手动配置，生成更丰富、一致、包含配套资源且易于系统理解和应用的人格包。
+
+
+- **探索高级记忆检索机制 (GE 系统概念):**
+    - 研究超越简单关键词/近期性检索的记忆模型。
+    - 考虑引入基于事件关联、相对时间线索和绝对时间锚点的检索方式。
+    - 可能涉及设计新的事件表示或记忆结构。
+
+
+- **实现 SubHeartflow 级记忆缓存池:**
+    - 在 `SubHeartflow` 层级或更高层级设计并实现一个缓存池，存储已检索的记忆/信息。
+    - 避免在 HFC 等循环中重复进行相同的记忆检索调用。
+    - 确保存储的信息能有效服务于当前交互上下文。
+
+- **基于人格生成预设知识:**
+    - 开发利用 LLM 和人格配置生成背景知识的功能。
+    - 这些知识应符合角色的行为风格和可能的经历。
+    - 作为一种"冷启动"或丰富角色深度的方式。
+
+
+## 开发计划TODO：LIST
+
+- 人格功能：WIP
+- 对特定对象的侧写功能
+- 图片发送，转发功能：WIP
+- 幽默和meme功能：WIP
+- 小程序转发链接解析
+- 自动生成的回复逻辑，例如自生成的回复方向，回复风格
--- a/docs/CONTRIBUTE.md
+++ b/docs/CONTRIBUTE.md
@@ -0,0 +1,88 @@
+# 如何给MaiCore做贡献v1.0
+
+修改时间2025/4/5
+
+如有修改建议或疑问，请在github上建立issue
+
+首先，非常感谢你抽出时间来做贡献！❤️
+
+这份文档是告诉你，当你想向MaiCore提交代码，或者想要以其他形式加入MaiCore的开发，或周边插件的开发，你可以怎么做。
+
+我们鼓励并重视任何形式的贡献，但无序的贡献只会使麦麦的维护与更新变成一团糟。因此，我们建议您在做出贡献之前，先查看本指南。
+
+
+> 另外，如果您喜欢这个项目，但只是没有时间做贡献，那也没关系。还有其他简单的方式来支持本项目并表达您的感激之情，我们也会非常高兴：
+> - 给我们点一颗小星星（Star）
+> - 在您的项目的readme中引用这个项目
+
+## 目录
+
+● [我有问题](#我有问题)
+● [我想做贡献](#我想做贡献)
+● [我想提出建议](#提出建议)
+
+## 我有问题
+
+> 如果你想问一个问题，我们会假设你已经阅读了现有的文档。
+
+在你提问之前，最好先搜索现有的[issue](/issues)，看看是否有助于解决你的问题。如果你找到了匹配的issue，但仍需要追加说明，你可以在该issue下提出你的问题。同时，我们还建议你先在互联网上搜索答案。
+
+如果你仍然觉得有必要提问并需要进行说明，我们建议你：
+
+● 开一个[新Issue](/issues/new)。并尽可能详细地描述你的问题。
+
+● 提供尽可能多的上下文信息，让我们更好地理解你遇到的问题。比如：提供版本信息（哪个分支，版本号是多少，运行环境有哪些等），具体取决于你认为相关的内容。
+
+只要你提出的issue明确且合理，我们都会回复并尝试解决您的问题。
+
+
+## 我想做贡献
+
+> ### 项目所有权与维护
+> MaiMBot项目（现更名为MaiBot，核心为MaiCore）由千石可乐SengokuCola创建，采用GPL3开源协议。
+> MaiBot项目现已移动至MaiM-with-u组织下，目前主要内容由核心开发组维护，整体由核心开发组、reviewer和所有贡献者共同维护（该部分在未来将会明确）。
+> 为了保证设计的统一和节省不必要的精力，以及为了对项目有整体的把控，我们对不同类型的贡献采取不同的审核策略：
+> 
+> #### 功能新增
+> - 定义：涉及新功能添加、架构调整、重要模块重构等
+> - 要求：原则上暂不接收，你可以发布issue提供新功能建议。
+> 
+> #### Bug修复
+> - 定义：修复现有功能中的错误，包括非预期行为（需要发布issue进行确认）和运行错误，不涉及新功能或架构变动
+> - 要求：由核心组成员或2名及以上reviewer同时确认才会被合并
+> - 关闭：包含预期行为改动，新功能，破坏原有功能，数据库破坏性改动等的pr将会被关闭
+> 
+> #### 文档修补
+> - 定义：修复现有文档中的错误，提供新的帮助文档
+> - 要求：现需要提交至组织下docs仓库，由reviewer确认后合并
+
+
+> ### 法律声明
+> 当你为本项目贡献代码/文档时，你必须确认：
+> 1. 你贡献的内容100%是由你创作；
+> 2. 你对这些内容拥有相应的权利；
+> 3. 你贡献的内容将按项目许可协议使用。
+
+
+## 提出建议
+
+这一部分指导您如何为MaiCore/MaiBot提交一个建议，包括全新的功能和对现有功能的小改进。遵循这些指南将有助于维护人员和社区了解您的建议并找到相关的建议。
+
+在提交建议之前
+
+● 请确保您正在使用最新版本（正式版请查看main分支，测试版查看dev分支）。
+
+● 请确保您已经阅读了文档，以确认您的建议是否已经被实现，也许是通过单独的配置。
+
+● 仔细阅读文档并了解项目目前是否支持该功能，也许可以通过单独的配置来实现。
+
+● 进行一番[搜索](/issues)以查看是否已经有人提出了这个建议。如果有，请在现有的issue下添加评论，而不是新开一个issue。
+
+● 请确保您的建议符合项目的范围和目标。你需要提出一个强有力的理由来说服项目的开发者这个功能的优点。请记住，我们希望的功能是对大多数用户有用的，而不仅仅是少数用户。如果你只是针对少数用户，请考虑编写一个插件。
+
+### 附（暂定）：
+核心组成员：@SengokuCola @tcmofashi @Rikki-Zero
+
+reviewer：核心组+MaiBot主仓库合作者/权限者
+
+贡献者：所有提交过贡献的用户
--- a/docs/HeartFC_chatting_logic.md
+++ b/docs/HeartFC_chatting_logic.md
@@ -0,0 +1,92 @@
+# HeartFChatting 逻辑详解
+
+`HeartFChatting` 类是心流系统（Heart Flow System）中实现**专注聊天**（`ChatState.FOCUSED`）功能的核心。顾名思义，其职责乃是在特定聊天流（`stream_id`）中，模拟更为连贯深入之对话。此非凭空臆造，而是依赖一个持续不断的 **思考(Think)-规划(Plan)-执行(Execute)** 循环。当其所系的 `SubHeartflow` 进入 `FOCUSED` 状态时，便会创建并启动 `HeartFChatting` 实例；若状态转为他途（譬如 `CHAT` 或 `ABSENT`），则会将其关闭。
+
+## 1. 初始化简述 (`__init__`, `_initialize`)
+
+创生之初，`HeartFChatting` 需注入若干关键之物：`chat_id`（亦即 `stream_id`）、关联的 `SubMind` 实例，以及 `Observation` 实例（用以观察环境）。
+
+其内部核心组件包括：
+
+-   `ActionManager`: 管理当前循环可选之策（如：不应、言语、表情）。
+-   `HeartFCGenerator` (`self.gpt_instance`): 专司生成回复文本之职。
+-   `ToolUser` (`self.tool_user`): 虽主要用于获取工具定义，然亦备 `SubMind` 调用之需（实际执行由 `SubMind` 操持）。
+-   `HeartFCSender` (`self.heart_fc_sender`): 负责消息发送诸般事宜，含"正在思考"之态。
+-   `LLMRequest` (`self.planner_llm`): 配置用于执行"规划"任务的大语言模型。
+
+*初始化过程采取懒加载策略，仅在首次需要访问 `ChatStream` 时（通常在 `start` 方法中）进行。*
+
+## 2. 生命周期 (`start`, `shutdown`)
+
+-   **启动 (`start`)**: 外部调用此法，以启 `HeartFChatting` 之流程。内部会安全地启动主循环任务。
+-   **关闭 (`shutdown`)**: 外部调用此法，以止其运行。会取消主循环任务，清理状态，并释放锁。
+
+## 3. 核心循环 (`_hfc_loop`) 与 循环记录 (`CycleInfo`)
+
+`_hfc_loop` 乃 `HeartFChatting` 之脉搏，以异步方式不舍昼夜运行（直至 `shutdown` 被调用）。其核心在于周而复始地执行 **思考-规划-执行** 之周期。
+
+每一轮循环，皆会创建一个 `CycleInfo` 对象。此对象犹如史官，详细记载该次循环之点滴：
+
+-   **身份标识**: 循环 ID (`cycle_id`)。
+-   **时间轨迹**: 起止时刻 (`start_time`, `end_time`)。
+-   **行动细节**: 是否执行动作 (`action_taken`)、动作类型 (`action_type`)、决策理由 (`reasoning`)。
+-   **耗时考量**: 各阶段计时 (`timers`)。
+-   **关联信息**: 思考消息 ID (`thinking_id`)、是否重新规划 (`replanned`)、详尽响应信息 (`response_info`，含生成文本、表情、锚点、实际发送ID、`SubMind`思考等)。
+
+这些 `CycleInfo` 被存入一个队列 (`_cycle_history`)，近者得观。此记录不仅便于调试，更关键的是，它会作为**上下文信息**传递给下一次循环的"思考"阶段，使得 `SubMind` 能鉴往知来，做出更连贯的决策。
+
+*循环间会根据执行情况智能引入延迟，避免空耗资源。*
+
+## 4. 思考-规划-执行周期 (`_think_plan_execute_loop`)
+
+此乃 `HeartFChatting` 最核心的逻辑单元，每一循环皆按序执行以下三步：
+
+### 4.1. 思考 (`_get_submind_thinking`)
+
+*   **第一步：观察环境**: 调用 `Observation` 的 `observe()` 方法，感知聊天室是否有新动态（如新消息）。
+*   **第二步：触发子思维**: 调用关联 `SubMind` 的 `do_thinking_before_reply()` 方法。
+    *   **关键点**: 会将**上一个循环**的 `CycleInfo` 传入，让 `SubMind` 了解上次行动的决策、理由及是否重新规划，从而实现"承前启后"的思考。
+    *   `SubMind` 在此阶段不仅进行思考，还可能**调用其配置的工具**来收集信息。
+*   **第三步：获取成果**: `SubMind` 返回两部分重要信息：
+    1.  当前的内心想法 (`current_mind`)。
+    2.  通过工具调用收集到的结构化信息 (`structured_info`)。
+
+### 4.2. 规划 (`_planner`)
+
+*   **输入**: 接收来自"思考"阶段的 `current_mind` 和 `structured_info`，以及"观察"到的最新消息。
+*   **目标**: 基于当前想法、已知信息、聊天记录、机器人个性以及可用动作，决定**接下来要做什么**。
+*   **决策方式**:
+    1.  构建一个精心设计的提示词 (`_build_planner_prompt`)。
+    2.  获取 `ActionManager` 中定义的当前可用动作（如 `no_reply`, `text_reply`, `emoji_reply`）作为"工具"选项。
+    3.  调用大语言模型 (`self.planner_llm`)，**强制**其选择一个动作"工具"并提供理由。可选动作包括：
+        *   `no_reply`: 不回复（例如，自己刚说过话或对方未回应）。
+        *   `text_reply`: 发送文本回复。
+        *   `emoji_reply`: 仅发送表情。
+        *   文本回复亦可附带表情（通过 `emoji_query` 参数指定）。
+*   **动态调整（重新规划）**:
+    *   在做出初步决策后，会检查自规划开始后是否有新消息 (`_check_new_messages`)。
+    *   若有新消息，则有一定概率触发**重新规划**。此时会再次调用规划器，但提示词会包含之前决策的信息，要求 LLM 重新考虑。
+*   **输出**: 返回一个包含最终决策的字典，主要包括：
+    *   `action`: 选定的动作类型。
+    *   `reasoning`: 做出此决策的理由。
+    *   `emoji_query`: (可选) 如果需要发送表情，指定表情的主题。
+
+### 4.3. 执行 (`_handle_action`)
+
+*   **输入**: 接收"规划"阶段输出的 `action`、`reasoning` 和 `emoji_query`。
+*   **行动**: 根据 `action` 的类型，分派到不同的处理函数：
+    *   **文本回复 (`_handle_text_reply`)**:
+        1.  获取锚点消息（当前实现为系统触发的占位符）。
+        2.  调用 `HeartFCSender` 的 `register_thinking` 标记开始思考。
+        3.  调用 `HeartFCGenerator` (`_replier_work`) 生成回复文本。**注意**: 回复器逻辑 (`_replier_work`) 本身并非独立复杂组件，主要是调用 `HeartFCGenerator` 完成文本生成。
+        4.  调用 `HeartFCSender` (`_sender`) 发送生成的文本和可能的表情。**注意**: 发送逻辑 (`_sender`, `_send_response_messages`, `_handle_emoji`) 同样委托给 `HeartFCSender` 实例处理，包含模拟打字、实际发送、存储消息等细节。
+    *   **仅表情回复 (`_handle_emoji_reply`)**:
+        1.  获取锚点消息。
+        2.  调用 `HeartFCSender` 发送表情。
+    *   **不回复 (`_handle_no_reply`)**:
+        1.  记录理由。
+        2.  进入等待状态 (`_wait_for_new_message`)，直到检测到新消息或超时（目前300秒），期间会监听关闭信号。
+
+## 总结
+
+`HeartFChatting` 通过 **观察 -> 思考（含工具）-> 规划 -> 执行** 的闭环，并利用 `CycleInfo` 进行上下文传递，实现了更加智能和连贯的专注聊天行为。其核心在于利用 `SubMind` 进行深度思考和信息收集，再通过 LLM 规划器进行决策，最后由 `HeartFCSender` 可靠地执行消息发送任务。
--- a/docs/HeartFC_readme.md
+++ b/docs/HeartFC_readme.md
@@ -0,0 +1,159 @@
+# HeartFC_chat 工作原理文档
+
+HeartFC_chat 是一个基于心流理论的聊天系统，通过模拟人类的思维过程和情感变化来实现自然的对话交互。系统采用Plan-Replier-Sender循环机制，实现了智能化的对话决策和生成。
+
+## 核心工作流程
+
+### 1. 消息处理与存储 (HeartFCProcessor)
+[代码位置: src/plugins/focus_chat/heartflow_processor.py]
+
+消息处理器负责接收和预处理消息，主要完成以下工作：
+```mermaid
+graph TD
+    A[接收原始消息] --> B[解析为MessageRecv对象]
+    B --> C[消息缓冲处理]
+    C --> D[过滤检查]
+    D --> E[存储到数据库]
+```
+
+核心实现：
+- 消息处理入口：`process_message()` [行号: 38-215]
+  - 消息解析和缓冲：`message_buffer.start_caching_messages()` [行号: 63]
+  - 过滤检查：`_check_ban_words()`, `_check_ban_regex()` [行号: 196-215]
+  - 消息存储：`storage.store_message()` [行号: 108]
+
+### 2. 对话管理循环 (HeartFChatting)
+[代码位置: src/plugins/focus_chat/focus_chat.py]
+
+HeartFChatting是系统的核心组件，实现了完整的对话管理循环：
+
+```mermaid
+graph TD
+    A[Plan阶段] -->|决策是否回复| B[Replier阶段]
+    B -->|生成回复内容| C[Sender阶段]
+    C -->|发送消息| D[等待新消息]
+    D --> A
+```
+
+#### Plan阶段 [行号: 282-386]
+- 主要函数：`_planner()`
+- 功能实现：
+  * 获取观察信息：`observation.observe()` [行号: 297]
+  * 思维处理：`sub_mind.do_thinking_before_reply()` [行号: 301]
+  * LLM决策：使用`PLANNER_TOOL_DEFINITION`进行动作规划 [行号: 13-42]
+
+#### Replier阶段 [行号: 388-416]
+- 主要函数：`_replier_work()`
+- 调用生成器：`gpt_instance.generate_response()` [行号: 394]
+- 处理生成结果和错误情况
+
+#### Sender阶段 [行号: 418-450]
+- 主要函数：`_sender()`
+- 发送实现：
+  * 创建消息：`_create_thinking_message()` [行号: 452-477]
+  * 发送回复：`_send_response_messages()` [行号: 479-525]
+  * 处理表情：`_handle_emoji()` [行号: 527-567]
+
+### 3. 回复生成机制 (HeartFCGenerator)
+[代码位置: src/plugins/focus_chat/heartFC_generator.py]
+
+回复生成器负责产生高质量的回复内容：
+
+```mermaid
+graph TD
+    A[获取上下文信息] --> B[构建提示词]
+    B --> C[调用LLM生成]
+    C --> D[后处理优化]
+    D --> E[返回回复集]
+```
+
+核心实现：
+- 生成入口：`generate_response()` [行号: 39-67]
+  * 情感调节：`arousal_multiplier = MoodManager.get_instance().get_arousal_multiplier()` [行号: 47]
+  * 模型生成：`_generate_response_with_model()` [行号: 69-95]
+  * 响应处理：`_process_response()` [行号: 97-106]
+
+### 4. 提示词构建系统 (HeartFlowPromptBuilder)
+[代码位置: src/plugins/focus_chat/heartflow_prompt_builder.py]
+
+提示词构建器支持两种工作模式，HeartFC_chat专门使用Focus模式，而Normal模式是为normal_chat设计的：
+
+#### 专注模式 (Focus Mode) - HeartFC_chat专用
+- 实现函数：`_build_prompt_focus()` [行号: 116-141]
+- 特点：
+  * 专注于当前对话状态和思维
+  * 更强的目标导向性
+  * 用于HeartFC_chat的Plan-Replier-Sender循环
+  * 简化的上下文处理，专注于决策
+
+#### 普通模式 (Normal Mode) - Normal_chat专用
+- 实现函数：`_build_prompt_normal()` [行号: 143-215]
+- 特点：
+  * 用于normal_chat的常规对话
+  * 完整的个性化处理
+  * 关系系统集成
+  * 知识库检索：`get_prompt_info()` [行号: 217-591]
+
+HeartFC_chat的Focus模式工作流程：
+```mermaid
+graph TD
+    A[获取结构化信息] --> B[获取当前思维状态]
+    B --> C[构建专注模式提示词]
+    C --> D[用于Plan阶段决策]
+    D --> E[用于Replier阶段生成]
+```
+
+## 智能特性
+
+### 1. 对话决策机制
+- LLM决策工具定义：`PLANNER_TOOL_DEFINITION` [focus_chat.py 行号: 13-42]
+- 决策执行：`_planner()` [focus_chat.py 行号: 282-386]
+- 考虑因素：
+  * 上下文相关性
+  * 情感状态
+  * 兴趣程度
+  * 对话时机
+
+### 2. 状态管理
+[代码位置: src/plugins/focus_chat/focus_chat.py]
+- 状态机实现：`HeartFChatting`类 [行号: 44-567]
+- 核心功能：
+  * 初始化：`_initialize()` [行号: 89-112]
+  * 循环控制：`_run_pf_loop()` [行号: 192-281]
+  * 状态转换：`_handle_loop_completion()` [行号: 166-190]
+
+### 3. 回复生成策略
+[代码位置: src/plugins/focus_chat/heartFC_generator.py]
+- 温度调节：`current_model.temperature = global_config.llm_normal["temp"] * arousal_multiplier` [行号: 48]
+- 生成控制：`_generate_response_with_model()` [行号: 69-95]
+- 响应处理：`_process_response()` [行号: 97-106]
+
+## 系统配置
+
+### 关键参数
+- LLM配置：`model_normal` [heartFC_generator.py 行号: 32-37]
+- 过滤规则：`_check_ban_words()`, `_check_ban_regex()` [heartflow_processor.py 行号: 196-215]
+- 状态控制：`INITIAL_DURATION = 60.0` [focus_chat.py 行号: 11]
+
+### 优化建议
+1. 调整LLM参数：`temperature`和`max_tokens`
+2. 优化提示词模板：`init_prompt()` [heartflow_prompt_builder.py 行号: 8-115]
+3. 配置状态转换条件
+4. 维护过滤规则
+
+## 注意事项
+
+1. 系统稳定性
+- 异常处理：各主要函数都包含try-except块
+- 状态检查：`_processing_lock`确保并发安全
+- 循环控制：`_loop_active`和`_loop_task`管理
+
+2. 性能优化
+- 缓存使用：`message_buffer`系统
+- LLM调用优化：批量处理和复用
+- 异步处理：使用`asyncio`
+
+3. 质量控制
+- 日志记录：使用`get_module_logger()`
+- 错误追踪：详细的异常记录
+- 响应监控：完整的状态跟踪
--- a/docs/HeartFC_system.md
+++ b/docs/HeartFC_system.md
@@ -0,0 +1,241 @@
+# 心流系统 (Heart Flow System)
+
+## 一条消息是怎么到最终回复的？简明易懂的介绍
+
+1 接受消息，由HeartHC_processor处理消息，存储消息
+
+    1.1 process_message()函数，接受消息
+
+    1.2 创建消息对应的聊天流(chat_stream)和子心流(sub_heartflow)
+
+    1.3 进行常规消息处理
+
+    1.4 存储消息 store_message()
+
+    1.5 计算兴趣度Interest
+
+    1.6 将消息连同兴趣度，存储到内存中的interest_dict(SubHeartflow的属性)
+
+2 根据 sub_heartflow 的聊天状态，决定后续处理流程
+
+    2a ABSENT状态：不做任何处理
+
+    2b CHAT状态：送入NormalChat 实例
+
+    2c FOCUS状态：送入HeartFChatting 实例
+
+b NormalChat工作方式
+
+    b.1 启动后台任务 _reply_interested_message，持续运行。
+    b.2 该任务轮询 InterestChatting 提供的 interest_dict
+    b.3 对每条消息，结合兴趣度、是否被提及(@)、意愿管理器(WillingManager)计算回复概率。（这部分要改，目前还是用willing计算的，之后要和Interest合并）
+    b.4 若概率通过：
+        b.4.1 创建"思考中"消息 (MessageThinking)。
+        b.4.2 调用 NormalChatGenerator 生成文本回复。
+        b.4.3 通过 message_manager 发送回复 (MessageSending)。
+        b.4.4 可能根据配置和文本内容，额外发送一个匹配的表情包。
+        b.4.5 更新关系值和全局情绪。
+    b.5 处理完成后，从 interest_dict 中移除该消息。
+
+c HeartFChatting工作方式
+
+    c.1 启动主循环 _hfc_loop
+    c.2 每个循环称为一个周期 (Cycle)，执行 think_plan_execute 流程。
+    c.3 Think (思考) 阶段:
+        c.3.1 观察 (Observe): 通过 ChattingObservation，使用 observe() 获取最新的聊天消息。
+        c.3.2 思考 (Think): 调用 SubMind 的 do_thinking_before_reply 方法。
+            c.3.2.1 SubMind 结合观察到的内容、个性、情绪、上周期动作等信息，生成当前的内心想法 (current_mind)。
+            c.3.2.2 在此过程中 SubMind 的LLM可能请求调用工具 (ToolUser) 来获取额外信息或执行操作，结果存储在 structured_info 中。
+    c.4 Plan (规划/决策) 阶段:
+        c.4.1 结合观察到的消息文本、`SubMind` 生成的 `current_mind` 和 `structured_info`、以及 `ActionManager` 提供的可用动作，决定本次周期的行动 (`text_reply`/`emoji_reply`/`no_reply`) 和理由。
+        c.4.2 重新规划检查 (Re-plan Check): 如果在 c.3.1 到 c.4.1 期间检测到新消息，可能(有概率)触发重新执行 c.4.1 决策步骤。
+    c.5 Execute (执行/回复) 阶段:
+        c.5.1 如果决策是 text_reply:
+            c.5.1.1 获取锚点消息。
+            c.5.1.2 通过 HeartFCSender 注册"思考中"状态。
+            c.5.1.3 调用 HeartFCGenerator (gpt_instance) 生成回复文本。
+            c.5.1.4 通过 HeartFCSender 发送回复
+            c.5.1.5 如果规划时指定了表情查询 (emoji_query)，随后发送表情。
+        c.5.2 如果决策是 emoji_reply:
+            c.5.2.1 获取锚点消息。
+            c.5.2.2 通过 HeartFCSender 直接发送匹配查询 (emoji_query) 的表情。
+        c.5.3 如果决策是 no_reply:
+            c.5.3.1 进入等待状态，直到检测到新消息或超时。
+            c.5.3.2 同时，增加内部连续不回复计数器。如果该计数器达到预设阈值（例如 5 次），则调用初始化时由 `SubHeartflowManager` 提供的回调函数。此回调函数会通知 `SubHeartflowManager` 请求将对应的 `SubHeartflow` 状态转换为 `ABSENT`。如果执行了其他动作（如 `text_reply` 或 `emoji_reply`），则此计数器会被重置。
+    c.6 循环结束后，记录周期信息 (CycleInfo)，并根据情况进行短暂休眠，防止CPU空转。
+
+
+
+## 1. 一条消息是怎么到最终回复的？复杂细致的介绍
+
+### 1.1. 主心流 (Heartflow)
+- **文件**: `heartflow.py`
+- **职责**:
+    - 作为整个系统的主控制器。
+    - 持有并管理 `SubHeartflowManager`，用于管理所有子心流。
+    - 持有并管理自身状态 `self.current_state: MaiStateInfo`，该状态控制系统的整体行为模式。
+    - 统筹管理系统后台任务（如消息存储、资源分配等）。
+    - **注意**: 主心流自身不进行周期性的全局思考更新。
+
+### 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` 的成员变量存在。
+    - **在初始化时接收并持有 `Heartflow` 的 `MaiStateInfo` 实例。**
+    - 负责所有 `SubHeartflow` 实例的生命周期管理，包括：
+        - 创建和获取 (`get_or_create_subheartflow`)。
+        - 停止和清理 (`sleep_subheartflow`, `cleanup_inactive_subheartflows`)。
+        - 根据 `Heartflow` 的状态 (`self.mai_state_info`) 和限制条件，激活、停用或调整子心流的状态（例如 `enforce_subheartflow_limits`, `randomly_deactivate_subflows`, `sbhf_absent_into_focus`）。
+        - **新增**: 通过调用 `sbhf_absent_into_chat` 方法，使用 LLM (配置与 `Heartflow` 主 LLM 相同) 评估处于 `ABSENT` 或 `CHAT` 状态的子心流，根据观察到的活动摘要和 `Heartflow` 的当前状态，判断是否应在 `ABSENT` 和 `CHAT` 之间进行转换 (同样受限于 `CHAT` 状态的数量上限)。
+    - **清理机制**: 通过后台任务 (`BackgroundTaskManager`) 定期调用 `cleanup_inactive_subheartflows` 方法，此方法会识别并**删除**那些处于 `ABSENT` 状态超过一小时 (`INACTIVE_THRESHOLD_SECONDS`) 的子心流实例。
+
+### 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` 创建和管理子心流（**在创建 `SubHeartflowManager` 时会传入自身的 `MaiStateInfo`**）。
+    - 通过其成员 `self.current_state: MaiStateInfo` 控制整体行为模式。
+    - 管理系统级后台任务。
+    - **注意**: 不再提供直接获取所有子心流 ID (`get_all_subheartflows_streams_ids`) 的公共方法。
+
+### 2.2. Heart Flow 状态 (`MaiStateInfo`)
+- **定义与管理**: `Heartflow` 持有 `MaiStateInfo` 的实例 (`self.current_state`) 来管理其状态。状态的枚举定义在 `my_state_manager.py` 中的 `MaiState`。
+- **状态及含义**:
+    - `MaiState.OFFLINE` (不在线): 不观察任何群消息，不进行主动交互，仅存储消息。当主状态变为 `OFFLINE` 时，`SubHeartflowManager` 会将所有子心流的状态设置为 `ChatState.ABSENT`。
+    - `MaiState.PEEKING` (看一眼手机): 有限度地参与聊天（由 `MaiStateInfo` 定义具体的普通/专注群数量限制）。
+    - `MaiState.NORMAL_CHAT` (正常看手机): 正常参与聊天，允许 `SubHeartflow` 进入 `CHAT` 或 `FOCUSED` 状态（数量受限）。
+    *   `MaiState.FOCUSED_CHAT` (专心看手机): 更积极地参与聊天，通常允许更多或更高优先级的 `FOCUSED` 状态子心流。
+- **当前转换逻辑**: 目前，`MaiState` 之间的转换由 `MaiStateManager` 管理，主要基于状态持续时间和随机概率。这是一种临时的实现方式，未来计划进行改进。
+- **作用**: `Heartflow` 的状态直接影响 `SubHeartflowManager` 如何管理子心流（如激活数量、允许的状态等）。
+
+### 2.3. 聊天流状态 (`ChatState`) 与转换
+- **管理对象**: 每个 `SubHeartflow` 实例内部维护其 `ChatStateInfo`，包含当前的 `ChatState`。
+- **状态及含义**:
+    - `ChatState.ABSENT` (不参与/没在看): 初始或停用状态。子心流不观察新信息，不进行思考，也不回复。
+    - `ChatState.CHAT` (随便看看/水群): 普通聊天模式。激活 `NormalChatInstance`。
+    *   `ChatState.FOCUSED` (专注/认真水群): 专注聊天模式。激活 `HeartFlowChatInstance`。
+- **选择**: 子心流可以根据外部指令（来自 `SubHeartflowManager`）或内部逻辑（未来的扩展）选择进入 `ABSENT` 状态（不回复不观察），或进入 `CHAT` / `FOCUSED` 中的一种回复模式。
+- **状态转换机制** (由 `SubHeartflowManager` 驱动，更细致的说明):
+    - **初始状态**: 新创建的 `SubHeartflow` 默认为 `ABSENT` 状态。
+    - **`ABSENT` -> `CHAT` (激活闲聊)**:
+        - **触发条件**: `Heartflow` 的主状态 (`MaiState`) 允许 `CHAT` 模式，且当前 `CHAT` 状态的子心流数量未达上限。
+        - **判定机制**: `SubHeartflowManager` 中的 `sbhf_absent_into_chat` 方法调用大模型(LLM)。LLM 读取该群聊的近期内容和结合自身个性信息，判断是否"想"在该群开始聊天。
+        - **执行**: 若 LLM 判断为是，且名额未满，`SubHeartflowManager` 调用 `change_chat_state(ChatState.CHAT)`。
+    - **`CHAT` -> `FOCUSED` (激活专注)**:
+        - **触发条件**: 子心流处于 `CHAT` 状态，其内部维护的"开屎热聊"概率 (`InterestChatting.start_hfc_probability`) 达到预设阈值（表示对当前聊天兴趣浓厚），同时 `Heartflow` 的主状态允许 `FOCUSED` 模式，且 `FOCUSED` 名额未满。
+        - **判定机制**: `SubHeartflowManager` 中的 `sbhf_absent_into_focus` 方法定期检查满足条件的 `CHAT` 子心流。
+        - **执行**: 若满足所有条件，`SubHeartflowManager` 调用 `change_chat_state(ChatState.FOCUSED)`。
+        - **注意**: 无法从 `ABSENT` 直接跳到 `FOCUSED`，必须先经过 `CHAT`。
+    - **`FOCUSED` -> `ABSENT` (退出专注)**:
+        - **主要途径 (内部驱动)**: 在 `FOCUSED` 状态下运行的 `HeartFlowChatInstance` 连续多次决策为 `no_reply` (例如达到 5 次，次数可配)，它会通过回调函数 (`sbhf_focus_into_absent`) 请求 `SubHeartflowManager` 将其状态**直接**设置为 `ABSENT`。
+        - **其他途径 (外部驱动)**:
+            - `Heartflow` 主状态变为 `OFFLINE`，`SubHeartflowManager` 强制所有子心流变为 `ABSENT`。
+            - `SubHeartflowManager` 因 `FOCUSED` 名额超限 (`enforce_subheartflow_limits`) 或随机停用 (`randomly_deactivate_subflows`) 而将其设置为 `ABSENT`。
+    - **`CHAT` -> `ABSENT` (退出闲聊)**:
+        - **主要途径 (内部驱动)**: `SubHeartflowManager` 中的 `sbhf_absent_into_chat` 方法调用 LLM。LLM 读取群聊内容和结合自身状态，判断是否"不想"继续在此群闲聊。
+        - **执行**: 若 LLM 判断为是，`SubHeartflowManager` 调用 `change_chat_state(ChatState.ABSENT)`。
+        - **其他途径 (外部驱动)**:
+            - `Heartflow` 主状态变为 `OFFLINE`。
+            - `SubHeartflowManager` 因 `CHAT` 名额超限或随机停用。
+    - **全局强制 `ABSENT`**: 当 `Heartflow` 的 `MaiState` 变为 `OFFLINE` 时，`SubHeartflowManager` 会调用所有子心流的 `change_chat_state(ChatState.ABSENT)`，强制它们全部停止活动。
+    - **状态变更执行者**: `change_chat_state` 方法仅负责执行状态的切换和对应聊天实例的启停，不进行名额检查。名额检查的责任由 `SubHeartflowManager` 中的各个决策方法承担。
+    - **最终清理**: 进入 `ABSENT` 状态的子心流不会立即被删除，只有在 `ABSENT` 状态持续一小时 (`INACTIVE_THRESHOLD_SECONDS`) 后，才会被后台清理任务 (`cleanup_inactive_subheartflows`) 删除。
+
+## 3. 聊天实例详解 (Chat Instances Explained)
+
+### 3.1. NormalChatInstance
+- **激活条件**: 对应 `SubHeartflow` 的 `ChatState` 为 `CHAT`。
+- **工作流程**:
+    - 当 `SubHeartflow` 进入 `CHAT` 状态时，`NormalChatInstance` 会被激活。
+    - 实例启动后，会创建一个后台任务 (`_reply_interested_message`)。
+    - 该任务持续监控由 `InterestChatting` 传入的、具有一定兴趣度的消息列表 (`interest_dict`)。
+    - 对列表中的每条消息，结合是否被提及 (`@`)、消息本身的兴趣度以及当前的回复意愿 (`WillingManager`)，计算出一个回复概率。
+    - 根据计算出的概率随机决定是否对该消息进行回复。
+    - 如果决定回复，则调用 `NormalChatGenerator` 生成回复内容，并可能附带表情包。
+- **行为特点**:
+    - 回复相对常规、简单。
+    - 不投入过多计算资源。
+    - 侧重于维持基本的交流氛围。
+    - 示例：对问候语、日常分享等进行简单回应。
+
+### 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` 的限制，调用 `get_or_create_subheartflow` 获取或创建子心流，并通过 `change_chat_state` 将部分子心流状态从 `ABSENT` 激活为 `CHAT`。
+4.  **子心流激活**: 被激活的 `SubHeartflow` 启动其 `NormalChatInstance`。
+5.  **信息接收**: 该 `SubHeartflow` 的 `ChattingObservation` 开始从数据库拉取新消息。
+6.  **普通回复**: `NormalChatInstance` 处理观察到的信息，执行普通回复逻辑。
+7.  **兴趣评估**: `SubHeartflowManager` 定期评估该子心流的 `InterestChatting` 状态。
+8.  **提升状态**: 若兴趣度达标且 `Heartflow` 状态允许，`SubHeartflowManager` 调用该子心流的 `change_chat_state` 将其状态提升为 `FOCUSED`。
+9.  **子心流切换**: `SubHeartflow` 内部停止 `NormalChatInstance`，启动 `HeartFlowChatInstance`。
+10. **专注回复**: `HeartFlowChatInstance` 开始根据其逻辑进行更深入的交互。
+11. **状态回落/停用**: 若 `Heartflow` 状态变为 `OFFLINE`，`SubHeartflowManager` 会调用所有活跃子心流的 `change_chat_state(ChatState.ABSENT)`，使其进入 `ABSENT` 状态（它们不会立即被删除，只有在 `ABSENT` 状态持续1小时后才会被清理）。
+
+## 5. 使用与配置 (Usage and Configuration)
+
+### 5.1. 使用说明 (Code Examples)
+- **(内部)创建/获取子心流** (由 `SubHeartflowManager` 调用, 示例):
+  ```python
+  # subheartflow_manager.py (get_or_create_subheartflow 内部)
+  # 注意：mai_states 现在是 self.mai_state_info
+  new_subflow = SubHeartflow(subheartflow_id, self.mai_state_info)
+  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)
+  ```
+
--- a/docs/use_tool.md
+++ b/docs/use_tool.md
@@ -0,0 +1,102 @@
+# 工具系统使用指南
+
+## 概述
+
+`tool_can_use` 是一个插件式工具系统，允许轻松扩展和注册新工具。每个工具作为独立的文件存在于该目录下，系统会自动发现和注册这些工具。
+
+## 工具结构
+
+每个工具应该继承 `BaseTool` 基类并实现必要的属性和方法：
+
+```python
+from src.tools.tool_can_use.base_tool import BaseTool, register_tool
+
+class MyNewTool(BaseTool):
+    # 工具名称，必须唯一
+    name = "my_new_tool"
+    
+    # 工具描述，告诉LLM这个工具的用途
+    description = "这是一个新工具，用于..."
+    
+    # 工具参数定义，遵循JSONSchema格式
+    parameters = {
+        "type": "object",
+        "properties": {
+            "param1": {
+                "type": "string",
+                "description": "参数1的描述"
+            },
+            "param2": {
+                "type": "integer",
+                "description": "参数2的描述"
+            }
+        },
+        "required": ["param1"]  # 必需的参数列表
+    }
+    
+    async def execute(self, function_args, message_txt=""):
+        """执行工具逻辑
+        
+        Args:
+            function_args: 工具调用参数
+            message_txt: 原始消息文本
+            
+        Returns:
+            dict: 包含执行结果的字典，必须包含name和content字段
+        """
+        # 实现工具逻辑
+        result = f"工具执行结果: {function_args.get('param1')}"
+        
+        return {
+            "name": self.name,
+            "content": result
+        }
+
+# 注册工具
+register_tool(MyNewTool)
+```
+
+## 自动注册机制
+
+工具系统通过以下步骤自动注册工具：
+
+1. 在`__init__.py`中，`discover_tools()`函数会自动遍历当前目录中的所有Python文件
+2. 对于每个文件，系统会寻找继承自`BaseTool`的类
+3. 这些类会被自动注册到工具注册表中
+
+只要确保在每个工具文件的末尾调用`register_tool(YourToolClass)`，工具就会被自动注册。
+
+## 添加新工具步骤
+
+1. 在`tool_can_use`目录下创建新的Python文件（如`my_new_tool.py`）
+2. 导入`BaseTool`和`register_tool`
+3. 创建继承自`BaseTool`的工具类
+4. 实现必要的属性（`name`, `description`, `parameters`）
+5. 实现`execute`方法
+6. 使用`register_tool`注册工具
+
+## 与ToolUser整合
+
+`ToolUser`类已经更新为使用这个新的工具系统，它会：
+
+1. 自动获取所有已注册工具的定义
+2. 基于工具名称找到对应的工具实例
+3. 调用工具的`execute`方法
+
+## 使用示例
+
+```python
+from src.tools.tool_use import ToolUser
+
+# 创建工具用户
+tool_user = ToolUser()
+
+# 使用工具
+result = await tool_user.use_tool(message_txt="查询关于Python的知识", sender_name="用户", chat_stream=chat_stream)
+
+# 处理结果
+if result["used_tools"]:
+    print("工具使用结果:", result["collected_info"])
+else:
+    print("未使用工具")
+```