gardel/Mofox-Core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新CLAUDE.md为高信息密度项目文档

Browse Source 
- 添加mermaid系统架构图和模块依赖图
- 添加核心文件索引和类功能表格
- 添加消息处理流程图
- 重组常见修改点便于导航
- 优化文档结构以提高信息密度

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
春河晴
2025-03-17 14:59:21 +09:00
parent bb8ce1b59d
commit 9a5bfa3b65
1 changed files with 211 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
CLAUDE.md
View File

@@ -1,6 +1,196 @@
# MaiMBot 开发指南
# MaiMBot 开发文档
## 🛠️ 常用命令
## 📊 系统架构图
```mermaid
graph TD
A[入口点] --> B[核心模块]
A --> C[插件系统]
B --> D[通用功能]
C --> E[聊天系统]
C --> F[记忆系统]
C --> G[情绪系统]
C --> H[意愿系统]
C --> I[其他插件]
%% 入口点
A1[bot.py] --> A
A2[run.py] --> A
A3[webui.py] --> A
%% 核心模块
B1[src/common/logger.py] --> B
B2[src/common/database.py] --> B
%% 通用功能
D1[日志系统] --> D
D2[数据库连接] --> D
D3[配置管理] --> D
%% 聊天系统
E1[消息处理] --> E
E2[提示构建] --> E
E3[LLM生成] --> E
E4[关系管理] --> E
%% 记忆系统
F1[记忆图] --> F
F2[记忆构建] --> F
F3[记忆检索] --> F
F4[记忆遗忘] --> F
%% 情绪系统
G1[情绪状态] --> G
G2[情绪更新] --> G
G3[情绪衰减] --> G
%% 意愿系统
H1[回复意愿] --> H
H2[意愿模式] --> H
H3[概率控制] --> H
%% 其他插件
I1[远程统计] --> I
I2[配置重载] --> I
I3[日程生成] --> I
```
## 📁 核心文件索引
| 功能 | 文件路径 | 描述 |
|------|----------|------|
| **入口点** | `/bot.py` | 主入口，初始化环境和启动服务 |
| | `/run.py` | 安装管理脚本，主要用于Windows |
| | `/webui.py` | Gradio基础的配置UI |
| **配置** | `/template.env` | 环境变量模板 |
| | `/template/bot_config_template.toml` | 机器人配置模板 |
| **核心基础** | `/src/common/database.py` | MongoDB连接管理 |
| | `/src/common/logger.py` | 基于loguru的日志系统 |
| **聊天系统** | `/src/plugins/chat/bot.py` | 消息处理核心逻辑 |
| | `/src/plugins/chat/config.py` | 配置管理与验证 |
| | `/src/plugins/chat/llm_generator.py` | LLM响应生成 |
| | `/src/plugins/chat/prompt_builder.py` | LLM提示构建 |
| **记忆系统** | `/src/plugins/memory_system/memory.py` | 图结构记忆实现 |
| | `/src/plugins/memory_system/draw_memory.py` | 记忆可视化 |
| **情绪系统** | `/src/plugins/moods/moods.py` | 情绪状态管理 |
| **意愿系统** | `/src/plugins/willing/willing_manager.py` | 回复意愿管理 |
| | `/src/plugins/willing/mode_classical.py` | 经典意愿模式 |
| | `/src/plugins/willing/mode_dynamic.py` | 动态意愿模式 |
| | `/src/plugins/willing/mode_custom.py` | 自定义意愿模式 |
## 🔄 模块依赖关系
```mermaid
flowchart TD
A[bot.py] --> B[src/common/logger.py]
A --> C[src/plugins/chat/bot.py]
C --> D[src/plugins/chat/config.py]
C --> E[src/plugins/chat/llm_generator.py]
C --> F[src/plugins/memory_system/memory.py]
C --> G[src/plugins/moods/moods.py]
C --> H[src/plugins/willing/willing_manager.py]
E --> D
E --> I[src/plugins/chat/prompt_builder.py]
E --> J[src/plugins/models/utils_model.py]
F --> B
F --> D
F --> J
G --> D
H --> B
H --> D
H --> K[src/plugins/willing/mode_classical.py]
H --> L[src/plugins/willing/mode_dynamic.py]
H --> M[src/plugins/willing/mode_custom.py]
I --> B
I --> F
I --> G
J --> B
```
## 🔄 消息处理流程
```mermaid
sequenceDiagram
participant User
participant ChatBot
participant WillingManager
participant Memory
participant PromptBuilder
participant LLMGenerator
participant MoodManager
User->>ChatBot: 发送消息
ChatBot->>ChatBot: 消息预处理
ChatBot->>Memory: 记忆激活
Memory-->>ChatBot: 激活度
ChatBot->>WillingManager: 更新回复意愿
WillingManager-->>ChatBot: 回复决策
alt 决定回复
ChatBot->>PromptBuilder: 构建提示
PromptBuilder->>Memory: 获取相关记忆
Memory-->>PromptBuilder: 相关记忆
PromptBuilder->>MoodManager: 获取情绪状态
MoodManager-->>PromptBuilder: 情绪状态
PromptBuilder-->>ChatBot: 完整提示
ChatBot->>LLMGenerator: 生成回复
LLMGenerator-->>ChatBot: AI回复
ChatBot->>MoodManager: 更新情绪
ChatBot->>User: 发送回复
else 不回复
ChatBot->>WillingManager: 更新未回复状态
end
```
## 📋 类和功能清单
### 🤖 聊天系统 (`src/plugins/chat/`)
| 类/功能 | 文件 | 描述 |
|--------|------|------|
| `ChatBot` | `bot.py` | 消息处理主类 |
| `ResponseGenerator` | `llm_generator.py` | 响应生成器 |
| `PromptBuilder` | `prompt_builder.py` | 提示构建器 |
| `Message`系列 | `message.py` | 消息表示类 |
| `RelationshipManager` | `relationship_manager.py` | 用户关系管理 |
| `EmojiManager` | `emoji_manager.py` | 表情符号管理 |
### 🧠 记忆系统 (`src/plugins/memory_system/`)
| 类/功能 | 文件 | 描述 |
|--------|------|------|
| `Memory_graph` | `memory.py` | 图结构记忆存储 |
| `Hippocampus` | `memory.py` | 记忆管理主类 |
| `memory_compress()` | `memory.py` | 记忆压缩函数 |
| `get_relevant_memories()` | `memory.py` | 记忆检索函数 |
| `operation_forget_topic()` | `memory.py` | 记忆遗忘函数 |
### 😊 情绪系统 (`src/plugins/moods/`)
| 类/功能 | 文件 | 描述 |
|--------|------|------|
| `MoodManager` | `moods.py` | 情绪管理器单例 |
| `MoodState` | `moods.py` | 情绪状态数据类 |
| `update_mood_from_emotion()` | `moods.py` | 情绪更新函数 |
| `_apply_decay()` | `moods.py` | 情绪衰减函数 |
### 🤔 意愿系统 (`src/plugins/willing/`)
| 类/功能 | 文件 | 描述 |
|--------|------|------|
| `WillingManager` | `willing_manager.py` | 意愿管理工厂类 |
| `ClassicalWillingManager` | `mode_classical.py` | 经典意愿模式 |
| `DynamicWillingManager` | `mode_dynamic.py` | 动态意愿模式 |
| `CustomWillingManager` | `mode_custom.py` | 自定义意愿模式 |
## 🔧 常用命令
- **运行机器人**: `python run.py` 或 `python bot.py`
- **安装依赖**: `pip install --upgrade -r requirements.txt`
@@ -30,19 +220,25 @@
- **错误处理**: 使用带有具体异常的try/except
- **文档**: 为类和公共函数编写docstrings
## 🧩 系统架构
## 📋 常见修改点
- **框架**: NoneBot2框架与插件架构
- **数据库**: MongoDB持久化存储
- **设计模式**: 工厂模式和单例管理器
- **配置管理**: 使用环境变量和TOML文件
- **内存系统**: 基于图的记忆结构，支持记忆构建、压缩、检索和遗忘
- **情绪系统**: 情绪模拟与概率权重
- **LLM集成**: 支持多个LLM服务提供商(ChatAnywhere, SiliconFlow, DeepSeek)
### 配置修改
- **机器人配置**: `/template/bot_config_template.toml`
- **环境变量**: `/template.env`
## ⚙️ 环境配置
### 行为定制
- **个性调整**: `src/plugins/chat/config.py` 中的 BotConfig 类
- **回复意愿算法**: `src/plugins/willing/mode_classical.py`
- **情绪反应模式**: `src/plugins/moods/moods.py`
- 使用`template.env`作为环境变量模板
- 使用`template/bot_config_template.toml`作为机器人配置模板
- MongoDB配置: 主机、端口、数据库名
- API密钥配置: 各LLM提供商的API密钥
### 消息处理
- **消息管道**: `src/plugins/chat/message.py`
- **话题识别**: `src/plugins/chat/topic_identifier.py`
### 记忆与学习
- **记忆算法**: `src/plugins/memory_system/memory.py`
- **手动记忆构建**: `src/plugins/memory_system/memory_manual_build.py`
### LLM集成
- **LLM提供商**: `src/plugins/chat/llm_generator.py`
- **模型参数**: `template/bot_config_template.toml` 的 [model] 部分