From 8ff7bb6f88b400f972641b3c5c6499b48d020eb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=A5=E6=B2=B3=E6=99=B4?= Date: Mon, 10 Mar 2025 14:50:15 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=8C=E4=BF=AE=E6=AD=A3=E6=A0=BC=E5=BC=8F=E5=B9=B6=E6=B7=BB?= =?UTF-8?q?=E5=8A=A0=E5=BF=85=E8=A6=81=E7=9A=84=E6=8D=A2=E8=A1=8C=E7=AC=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/doc1.md | 48 ++++++++++++++++++++--------------- docs/docker_deploy.md | 21 ++++++++------- docs/manual_deploy_linux.md | 22 +++++++++++++--- docs/manual_deploy_windows.md | 14 ++++++++-- 4 files changed, 67 insertions(+), 38 deletions(-) diff --git a/docs/doc1.md b/docs/doc1.md index 158136b9c..e8aa0f0d6 100644 --- a/docs/doc1.md +++ b/docs/doc1.md @@ -1,6 +1,7 @@ # 📂 文件及功能介绍 (2025年更新) ## 根目录 + - **README.md**: 项目的概述和使用说明。 - **requirements.txt**: 项目所需的Python依赖包列表。 - **bot.py**: 主启动文件，负责环境配置加载和NoneBot初始化。 @@ -10,6 +11,7 @@ - **run_*.bat**: 各种启动脚本，包括数据库、maimai和thinking功能。 ## `src/` 目录结构 + - **`plugins/` 目录**: 存放不同功能模块的插件。 - **chat/**: 处理聊天相关的功能，如消息发送和接收。 - **memory_system/**: 处理机器人的记忆功能。 @@ -22,94 +24,96 @@ - **`common/` 目录**: 存放通用的工具和库。 - **database.py**: 处理与数据库的交互，负责数据的存储和检索。 - - **__init__.py**: 初始化模块。 + - ****init**.py**: 初始化模块。 ## `config/` 目录 + - **bot_config_template.toml**: 机器人配置模板。 - **auto_format.py**: 自动格式化工具。 ### `src/plugins/chat/` 目录文件详细介绍 -1. **`__init__.py`**: +1. **`__init__.py`**: - 初始化 `chat` 模块，使其可以作为一个包被导入。 -2. **`bot.py`**: +2. **`bot.py`**: - 主要的聊天机器人逻辑实现，处理消息的接收、思考和回复。 - 包含 `ChatBot` 类，负责消息处理流程控制。 - 集成记忆系统和意愿管理。 -3. **`config.py`**: +3. **`config.py`**: - 配置文件，定义了聊天机器人的各种参数和设置。 - 包含 `BotConfig` 和全局配置对象 `global_config`。 -4. **`cq_code.py`**: +4. **`cq_code.py`**: - 处理 CQ 码（CoolQ 码），用于发送和接收特定格式的消息。 -5. **`emoji_manager.py`**: +5. **`emoji_manager.py`**: - 管理表情包的发送和接收，根据情感选择合适的表情。 - 提供根据情绪获取表情的方法。 -6. **`llm_generator.py`**: +6. **`llm_generator.py`**: - 生成基于大语言模型的回复，处理用户输入并生成相应的文本。 - 通过 `ResponseGenerator` 类实现回复生成。 -7. **`message.py`**: +7. **`message.py`**: - 定义消息的结构和处理逻辑，包含多种消息类型： - `Message`: 基础消息类 - `MessageSet`: 消息集合 - `Message_Sending`: 发送中的消息 - `Message_Thinking`: 思考状态的消息 -8. **`message_sender.py`**: +8. **`message_sender.py`**: - 控制消息的发送逻辑，确保消息按照特定规则发送。 - 包含 `message_manager` 对象，用于管理消息队列。 -9. **`prompt_builder.py`**: +9. **`prompt_builder.py`**: - 构建用于生成回复的提示，优化机器人的响应质量。 -10. **`relationship_manager.py`**: +10. **`relationship_manager.py`**: - 管理用户之间的关系，记录用户的互动和偏好。 - 提供更新关系和关系值的方法。 -11. **`Segment_builder.py`**: +11. **`Segment_builder.py`**: - 构建消息片段的工具。 -12. **`storage.py`**: +12. **`storage.py`**: - 处理数据存储，负责将聊天记录和用户信息保存到数据库。 - 实现 `MessageStorage` 类管理消息存储。 -13. **`thinking_idea.py`**: +13. **`thinking_idea.py`**: - 实现机器人的思考机制。 -14. **`topic_identifier.py`**: +14. **`topic_identifier.py`**: - 识别消息中的主题，帮助机器人理解用户的意图。 -15. **`utils.py`** 和 **`utils_*.py`** 系列文件: +15. **`utils.py`** 和 **`utils_*.py`** 系列文件: - 存放各种工具函数，提供辅助功能以支持其他模块。 - 包括 `utils_cq.py`、`utils_image.py`、`utils_user.py` 等专门工具。 -16. **`willing_manager.py`**: +16. **`willing_manager.py`**: - 管理机器人的回复意愿，动态调整回复概率。 - 通过多种因素（如被提及、话题兴趣度）影响回复决策。 ### `src/plugins/memory_system/` 目录文件介绍 -1. **`memory.py`**: +1. **`memory.py`**: - 实现记忆管理核心功能，包含 `memory_graph` 对象。 - 提供相关项目检索，支持多层次记忆关联。 -2. **`draw_memory.py`**: +2. **`draw_memory.py`**: - 记忆可视化工具。 -3. **`memory_manual_build.py`**: +3. **`memory_manual_build.py`**: - 手动构建记忆的工具。 -4. **`offline_llm.py`**: +4. **`offline_llm.py`**: - 离线大语言模型处理功能。 ## 消息处理流程 ### 1. 消息接收与预处理 + - 通过 `ChatBot.handle_message()` 接收群消息。 - 进行用户和群组的权限检查。 - 更新用户关系信息。 @@ -117,12 +121,14 @@ - 对消息进行过滤和敏感词检测。 ### 2. 主题识别与决策 + - 使用 `topic_identifier` 识别消息主题。 - 通过记忆系统检查对主题的兴趣度。 - `willing_manager` 动态计算回复概率。 - 根据概率决定是否回复消息。 ### 3. 回复生成与发送 + - 如需回复，首先创建 `Message_Thinking` 对象表示思考状态。 - 调用 `ResponseGenerator.generate_response()` 生成回复内容和情感状态。 - 删除思考消息，创建 `MessageSet` 准备发送回复。 diff --git a/docs/docker_deploy.md b/docs/docker_deploy.md index 3958d2fc4..e33cc6144 100644 --- a/docs/docker_deploy.md +++ b/docs/docker_deploy.md @@ -2,8 +2,7 @@ ## 部署步骤（推荐，但不一定是最新） - -### 1. 获取Docker配置文件: +### 1. 获取Docker配置文件 ```bash wget https://raw.githubusercontent.com/SengokuCola/MaiMBot/main/docker-compose.yml -O docker-compose.yml @@ -12,56 +11,56 @@ wget https://raw.githubusercontent.com/SengokuCola/MaiMBot/main/docker-compose.y - 若需要启用MongoDB数据库的用户名和密码，可进入docker-compose.yml，取消MongoDB处的注释并修改变量`=`后方的值为你的用户名和密码\ 修改后请注意在之后配置`.env.prod`文件时指定MongoDB数据库的用户名密码 - -### 2. 启动服务: +### 2. 启动服务 - **!!! 请在第一次启动前确保当前工作目录下`.env.prod`与`bot_config.toml`文件存在 !!!**\ 由于Docker文件映射行为的特殊性，若宿主机的映射路径不存在，可能导致意外的目录创建，而不会创建文件，由于此处需要文件映射到文件，需提前确保文件存在且路径正确，可使用如下命令: + ```bash touch .env.prod touch bot_config.toml ``` - 启动Docker容器: + ```bash NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker compose up -d ``` - 旧版Docker中可能找不到docker compose，请使用docker-compose工具替代 - -### 3. 修改配置并重启Docker: +### 3. 修改配置并重启Docker - 请前往 [🎀 新手配置指南](docs/installation_cute.md) 或 [⚙️ 标准配置指南](docs/installation_standard.md) 完成`.env.prod`与`bot_config.toml`配置文件的编写\ **需要注意`.env.prod`中HOST处IP的填写，Docker中部署和系统中直接安装的配置会有所不同** - 重启Docker容器: + ```bash docker restart maimbot # 若修改过容器名称则替换maimbot为你自定的名臣 ``` - 下方命令可以但不推荐，只是同时重启NapCat、MongoDB、MaiMBot三个服务 + ```bash NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker compose restart ``` - 旧版Docker中可能找不到docker compose，请使用docker-compose工具替代 - ### 4. 登入NapCat管理页添加反向WebSocket - 在浏览器地址栏输入`http://<宿主机IP>:6099/`进入NapCat的管理Web页，添加一个Websocket客户端 + > 网络配置 -> 新建 -> Websocket客户端 - Websocket客户端的名称自定，URL栏填入`ws://maimbot:8080/onebot/v11/ws`，启用并保存即可\ (若修改过容器名称则替换maimbot为你自定的名称) - -### 5. 愉快地和麦麦对话吧! - +### 5. 愉快地和麦麦对话吧 ## ⚠️ 注意事项 - 目前部署方案仍在测试中，可能存在未知问题 - 配置文件中的API密钥请妥善保管，不要泄露 -- 建议先在测试环境中运行，确认无误后再部署到生产环境 \ No newline at end of file +- 建议先在测试环境中运行，确认无误后再部署到生产环境 diff --git a/docs/manual_deploy_linux.md b/docs/manual_deploy_linux.md index d310ffc59..a859a30e7 100644 --- a/docs/manual_deploy_linux.md +++ b/docs/manual_deploy_linux.md @@ -1,6 +1,7 @@ # 📦 Linux系统如何手动部署MaiMbot麦麦？ ## 准备工作 + - 一台联网的Linux设备（本教程以Ubuntu/Debian系为例） - QQ小号（QQ框架的使用可能导致qq被风控，严重（小概率）可能会导致账号封禁，强烈不推荐使用大号） - 可用的大模型API @@ -20,6 +21,7 @@ - 数据库是什么？如何安装并启动MongoDB - 如何运行一个QQ机器人，以及NapCat框架是什么 + --- ## 环境配置 @@ -33,7 +35,9 @@ python --version # 或 python3 --version ``` + 如果版本低于3.9，请更新Python版本。 + ```bash # Ubuntu/Debian sudo apt update @@ -45,6 +49,7 @@ sudo update-alternatives --config python3 ``` ### 2️⃣ **创建虚拟环境** + ```bash # 方法1：使用venv(推荐) python3 -m venv maimbot @@ -65,32 +70,39 @@ pip install -r requirements.txt --- ## 数据库配置 + ### 3️⃣ **安装并启动MongoDB** + - 安装与启动：Debian参考[官方文档](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-debian/)，Ubuntu参考[官方文档](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/) - 默认连接本地27017端口 + --- ## NapCat配置 + ### 4️⃣ **安装NapCat框架** - 参考[NapCat官方文档](https://www.napcat.wiki/guide/boot/Shell#napcat-installer-linux%E4%B8%80%E9%94%AE%E4%BD%BF%E7%94%A8%E8%84%9A%E6%9C%AC-%E6%94%AF%E6%8C%81ubuntu-20-debian-10-centos9)安装 -- 使用QQ小号登录，添加反向WS地址： +- 使用QQ小号登录，添加反向WS地址： `ws://127.0.0.1:8080/onebot/v11/ws` --- ## 配置文件设置 + ### 5️⃣ **配置文件设置，让麦麦Bot正常工作** + - 修改环境配置文件：`.env.prod` - 修改机器人配置文件：`bot_config.toml` - --- ## 启动机器人 + ### 6️⃣ **启动麦麦机器人** + ```bash # 在项目目录下操作 nb run @@ -101,16 +113,18 @@ python3 bot.py --- ## **其他组件(可选)** -- 直接运行 knowledge.py生成知识库 +- 直接运行 knowledge.py生成知识库 --- ## 常见问题 + 🔧 权限问题：在命令前加`sudo` 🔌 端口占用：使用`sudo lsof -i :8080`查看端口占用 🛡️ 防火墙：确保8080/27017端口开放 + ```bash sudo ufw allow 8080/tcp sudo ufw allow 27017/tcp -``` \ No newline at end of file +``` diff --git a/docs/manual_deploy_windows.md b/docs/manual_deploy_windows.md index 86238bcd4..bca46962a 100644 --- a/docs/manual_deploy_windows.md +++ b/docs/manual_deploy_windows.md @@ -30,12 +30,13 @@ 在创建虚拟环境之前，请确保你的电脑上安装了Python 3.9及以上版本。如果没有，可以按以下步骤安装： -1. 访问Python官网下载页面：https://www.python.org/downloads/release/python-3913/ +1. 访问Python官网下载页面： 2. 下载Windows安装程序 (64-bit): `python-3.9.13-amd64.exe` 3. 运行安装程序，并确保勾选"Add Python 3.9 to PATH"选项 4. 点击"Install Now"开始安装 或者使用PowerShell自动下载安装（需要管理员权限）： + ```powershell # 下载并安装Python 3.9.13 $pythonUrl = "https://www.python.org/ftp/python/3.9.13/python-3.9.13-amd64.exe" @@ -46,7 +47,7 @@ Start-Process -Wait -FilePath $pythonInstaller -ArgumentList "/quiet", "InstallA ### 2️⃣ **创建Python虚拟环境来运行程序** - 你可以选择使用以下两种方法之一来创建Python环境： +> 你可以选择使用以下两种方法之一来创建Python环境： ```bash # ---方法1：使用venv（Python自带） @@ -60,6 +61,7 @@ maimbot\\Scripts\\activate # 安装依赖 pip install -r requirements.txt ``` + ```bash # ---方法2：使用conda # 创建一个新的conda环境（环境名为maimbot） @@ -74,27 +76,35 @@ pip install -r requirements.txt ``` ### 2️⃣ **然后你需要启动MongoDB数据库，来存储信息** + - 安装并启动MongoDB服务 - 默认连接本地27017端口 ### 3️⃣ **配置NapCat，让麦麦bot与qq取得联系** + - 安装并登录NapCat（用你的qq小号） - 添加反向WS：`ws://127.0.0.1:8080/onebot/v11/ws` ### 4️⃣ **配置文件设置，让麦麦Bot正常工作** + - 修改环境配置文件：`.env.prod` - 修改机器人配置文件：`bot_config.toml` ### 5️⃣ **启动麦麦机器人** + - 打开命令行，cd到对应路径 + ```bash nb run ``` + - 或者cd到对应路径后 + ```bash python bot.py ``` ### 6️⃣ **其他组件(可选)** + - `run_thingking.bat`: 启动可视化推理界面（未完善） - 直接运行 knowledge.py生成知识库