Merge branch 'debug' of https://github.com/SengokuCola/MaiMBot into debug

docs/doc1.md

@@ -1,16 +1,20 @@
-# 📂 文件及功能介绍(AI生成)
+# 📂 文件及功能介绍 (2025年更新)
 
 ## 根目录
 - **README.md**: 项目的概述和使用说明。
 - **requirements.txt**: 项目所需的Python依赖包列表。
-- **bot.py**: 主要的机器人逻辑和功能实现。
-- **env.example**: 环境变量示例文件。
+- **bot.py**: 主启动文件，负责环境配置加载和NoneBot初始化。
+- **template.env**: 环境变量模板文件。
+- **pyproject.toml**: Python项目配置文件。
+- **docker-compose.yml** 和 **Dockerfile**: Docker配置文件，用于容器化部署。
+- **run_*.bat**: 各种启动脚本，包括数据库、maimai和thinking功能。
 
-## `src/` 目录
+## `src/` 目录结构
 - **`plugins/` 目录**: 存放不同功能模块的插件。
-  - **memory_system/**: 处理机器人的记忆功能。
   - **chat/**: 处理聊天相关的功能，如消息发送和接收。
-  - **memory/**: 具体实现记忆存储和检索的逻辑。
+  - **memory_system/**: 处理机器人的记忆功能。
+  - **knowledege/**: 知识库相关功能。
+  - **models/**: 模型相关工具。
   - **schedule/**: 处理日程管理的功能。
 
 - **`gui/` 目录**: 存放图形用户界面相关的代码。
@@ -18,146 +22,149 @@
 
 - **`common/` 目录**: 存放通用的工具和库。
   - **database.py**: 处理与数据库的交互，负责数据的存储和检索。
-  - **__init__.py**: 初始化模块.
+  - **__init__.py**: 初始化模块。
 
-### `src/plugins/chat/` 目录文件介绍
+## `config/` 目录
+- **bot_config_template.toml**: 机器人配置模板。
+- **auto_format.py**: 自动格式化工具。
+
+### `src/plugins/chat/` 目录文件详细介绍
 
 1. **`__init__.py`**: 
-   - 用于初始化 `chat` 模块，使其可以作为一个包被导入。
+   - 初始化 `chat` 模块，使其可以作为一个包被导入。
 
 2. **`bot.py`**: 
-   - 主要的聊天机器人逻辑实现，处理消息的接收和发送，管理聊天会话。
+   - 主要的聊天机器人逻辑实现，处理消息的接收、思考和回复。
+   - 包含 `ChatBot` 类，负责消息处理流程控制。
+   - 集成记忆系统和意愿管理。
 
-3. **`bot_config.toml`**: 
-   - 存储机器人的配置参数，使用 TOML 格式，便于管理和修改。
-
-4. **`config.py`**: 
+3. **`config.py`**: 
    - 配置文件，定义了聊天机器人的各种参数和设置。
+   - 包含 `BotConfig` 和全局配置对象 `global_config`。
 
-5. **`cq_code.py`**: 
+4. **`cq_code.py`**: 
    - 处理 CQ 码（CoolQ 码），用于发送和接收特定格式的消息。
 
-6. **`emoji_manager.py`**: 
-   - 管理表情包的发送和接收，根据消息内容选择合适的表情。
+5. **`emoji_manager.py`**: 
+   - 管理表情包的发送和接收，根据情感选择合适的表情。
+   - 提供根据情绪获取表情的方法。
 
-7. **`image_utils.py`**: 
-   - 处理与图像相关的功能，如图像的上传、下载和处理。
-
-8. **`llm_generator.py`**: 
+6. **`llm_generator.py`**: 
    - 生成基于大语言模型的回复，处理用户输入并生成相应的文本。
+   - 通过 `ResponseGenerator` 类实现回复生成。
 
-9. **`message.py`**: 
-   - 定义消息的结构和处理逻辑，负责消息的创建和解析。
+7. **`message.py`**: 
+   - 定义消息的结构和处理逻辑，包含多种消息类型：
+     - `Message`: 基础消息类
+     - `MessageSet`: 消息集合
+     - `Message_Sending`: 发送中的消息
+     - `Message_Thinking`: 思考状态的消息
 
-10. **`message_send_control.py`**: 
-    - 控制消息的发送逻辑，确保消息按照特定规则发送。
+8. **`message_sender.py`**: 
+   - 控制消息的发送逻辑，确保消息按照特定规则发送。
+   - 包含 `message_manager` 对象，用于管理消息队列。
 
-11. **`message_stream.py`**: 
-    - 处理消息流，管理实时消息的接收和发送。
+9. **`prompt_builder.py`**: 
+   - 构建用于生成回复的提示，优化机器人的响应质量。
 
-12. **`message_visualizer.py`**: 
-    - 可视化消息内容，提供用户友好的界面展示聊天记录。
-
-13. **`relationship_manager.py`**: 
+10. **`relationship_manager.py`**: 
     - 管理用户之间的关系，记录用户的互动和偏好。
+    - 提供更新关系和关系值的方法。
 
-14. **`storage.py`**: 
+11. **`Segment_builder.py`**: 
+    - 构建消息片段的工具。
+
+12. **`storage.py`**: 
     - 处理数据存储，负责将聊天记录和用户信息保存到数据库。
+    - 实现 `MessageStorage` 类管理消息存储。
 
-15. **`topic_identifier.py`**: 
+13. **`thinking_idea.py`**: 
+    - 实现机器人的思考机制。
+
+14. **`topic_identifier.py`**: 
     - 识别消息中的主题，帮助机器人理解用户的意图。
+    - 使用多种方法（LLM、jieba、snownlp）进行主题识别。
 
-16. **`utils.py`**: 
+15. **`utils.py`** 和 **`utils_*.py`** 系列文件: 
     - 存放各种工具函数，提供辅助功能以支持其他模块。
+    - 包括 `utils_cq.py`、`utils_image.py`、`utils_user.py` 等专门工具。
 
-17. **`utils_user.py`**: 
-    - 针对用户的工具函数，提供与用户相关的操作。
+16. **`willing_manager.py`**: 
+    - 管理机器人的回复意愿，动态调整回复概率。
+    - 通过多种因素（如被提及、话题兴趣度）影响回复决策。
 
-18. **`willing_manager.py`**: 
-    - 管理用户的意愿和偏好，帮助机器人做出更个性化的响应。
+### `src/plugins/memory_system/` 目录文件介绍
 
-19. **`prompt_builder.py`**: 
-    - 构建用于生成回复的提示，优化机器人的响应质量.
+1. **`memory.py`**: 
+   - 实现记忆管理核心功能，包含 `memory_graph` 对象。
+   - 提供相关项目检索，支持多层次记忆关联。
 
-### 发送逻辑
-- 机器人通过 `message_send_control.py` 文件中的控制逻辑来管理消息的发送。该模块确保消息按照特定的规则和格式发送，避免重复发送或发送不合适的内容。
-- 发送逻辑会根据消息的类型（如文本、图片、表情等）选择合适的发送方式，并通过 `bot.py` 中的接口将消息发送到目标用户或群组。
+2. **`draw_memory.py`**: 
+   - 记忆可视化工具。
 
-### 解析逻辑
-- 解析逻辑主要在 `message.py` 和 `cq_code.py` 中实现。`message.py` 定义了消息的结构，包括消息的内容、发送者、时间戳等信息。
-- 当接收到消息时，机器人会使用 `cq_code.py` 解析 CQ 码，将其转换为可处理的格式，以便后续的逻辑处理。
+3. **`memory_manual_build.py`**: 
+   - 手动构建记忆的工具。
 
-### 回复逻辑
-- 回复逻辑由 `llm_generator.py` 和 `bot.py` 共同实现。`llm_generator.py` 负责生成基于用户输入的回复，使用大语言模型来理解上下文并生成自然语言响应。
-- 在 `bot.py` 中，机器人会根据解析后的消息内容和生成的回复，决定如何将回复发送给用户。回复可以是文本、表情或其他类型的消息.
+4. **`offline_llm.py`**: 
+   - 离线大语言模型处理功能。
 
-# 发送逻辑详细介绍
+## 消息处理流程
 
-## 消息发送控制系统
+### 1. 消息接收与预处理
+- 通过 `ChatBot.handle_message()` 接收群消息。
+- 进行用户和群组的权限检查。
+- 更新用户关系信息。
+- 创建标准化的 `Message` 对象。
+- 对消息进行过滤和敏感词检测。
 
-### 1. 消息队列管理
-消息发送系统采用了三层架构设计：
-- **SendTemp**: 单个群组的临时消息队列管理器
-  - 维护每个群的消息队列
-  - 确保消息按时间顺序存储和发送
-  - 支持消息的添加、获取和清空操作
-  - 记录最后发送时间，控制发送频率
+### 2. 主题识别与决策
+- 使用 `topic_identifier` 识别消息主题。
+- 通过记忆系统检查对主题的兴趣度。
+- `willing_manager` 动态计算回复概率。
+- 根据概率决定是否回复消息。
 
-- **SendTempContainer**: 管理所有群组的消息缓存容器
-  - 管理多个群组的消息队列
-  - 提供群组消息的统一访问接口
-  - 支持消息的分发和更新
+### 3. 回复生成与发送
+- 如需回复，首先创建 `Message_Thinking` 对象表示思考状态。
+- 调用 `ResponseGenerator.generate_response()` 生成回复内容和情感状态。
+- 删除思考消息，创建 `MessageSet` 准备发送回复。
+- 计算模拟打字时间，设置消息发送时间点。
+- 可能附加情感相关的表情包。
+- 通过 `message_manager` 将消息加入发送队列。
 
-- **MessageSendControl**: 消息发送控制器
-  - 控制消息的发送速度和间隔
-  - 处理消息的重试机制
-  - 管理消息的存储和可视化
+### 消息发送控制系统
 
-### 2. 发送流程
-1. **消息预处理**:
-   - 消息进入队列前会被格式化和标准化
-   - 添加必要的元数据（时间戳、消息ID等）
-   - 根据消息类型（文本、图片、表情等）进行分类
+`message_sender.py` 中实现了消息发送控制系统，采用三层结构：
 
-2. **队列管理**:
-   - 消息按时间顺序存储在队列中
-   - 使用双端队列（deque）实现，支持高效的添加和删除操作
-   - 队列大小有限制，防止内存溢出
+1. **消息管理**:
+   - 支持单条消息和消息集合的发送。
+   - 处理思考状态消息，控制思考时间。
+   - 模拟人类打字速度，添加自然发送延迟。
 
-3. **发送控制**:
-   - 控制发送速度：模拟人类打字速度（0.1-0.3秒/字符）
-   - 消息间隔：多条消息之间保持0.5-1秒的间隔
-   - 超时处理：思考时间超过60秒的消息会被自动移除
-   - 失败重试：最多重试3次
+2. **情感表达**:
+   - 根据生成回复的情感状态选择匹配的表情包。
+   - 通过 `emoji_manager` 管理表情资源。
 
-### 3. 特殊功能
-1. **思考机制**:
-   - 支持"思考中"状态的消息
-   - 控制思考时间，避免响应过快或过慢
-   - 超时自动清理机制
+3. **记忆交互**:
+   - 通过 `memory_graph` 检索相关记忆。
+   - 根据记忆内容影响回复意愿和内容。
 
-2. **消息追踪**:
-   - 记录每条消息的发送状态
-   - 支持消息的可视化展示
-   - 提供发送时间统计
+## 系统特色功能
 
-3. **安全机制**:
-   - 消息发送频率限制
-   - 队列容量控制
-   - 异常处理和恢复
+1. **智能回复意愿系统**:
+   - 动态调整回复概率，模拟真实人类交流特性。
+   - 考虑多种因素：被提及、话题兴趣度、用户关系等。
 
-### 4. 优化特性
-1. **并发处理**:
-   - 支持多个群组消息的并行处理
-   - 使用异步机制提高效率
-   - 避免单个群组阻塞整体发送
+2. **记忆系统集成**:
+   - 支持多层次记忆关联和检索。
+   - 影响机器人的兴趣和回复内容。
 
-2. **智能排队**:
-   - 基于时间戳的消息排序
-   - 支持消息优先级
-   - 动态调整发送顺序
+3. **自然交流模拟**:
+   - 模拟思考和打字过程，添加合理延迟。
+   - 情感表达与表情包结合。
 
-3. **状态监控**:
-   - 实时监控消息队列状态
-   - 提供消息发送统计
-   - 支持发送过程可视化
+4. **多环境配置支持**:
+   - 支持开发环境和生产环境的不同配置。
+   - 通过环境变量和配置文件灵活管理设置。
+
+5. **Docker部署支持**:
+   - 提供容器化部署方案，简化安装和运行。