开发指南
MaiBot（麦麦 / MaiSaka）是基于大语言模型的可交互智能体。本节面向希望参与开发或编写插件的开发者，介绍项目的技术栈、目录结构与开发环境搭建。
技术栈
| 类别 | 技术 |
|---|---|
| 语言 | Python 3.10+ |
| Web 框架 | FastAPI |
| ORM | SQLModel |
| ASGI 服务器 | Uvicorn |
| 配置管理 | Pydantic + TOML + 热重载 |
| 插件 IPC | msgpack over UDS / TCP / Named Pipe |
| 包管理 | uv |
| 代码检查 | Ruff |
| 许可证 | GPL-3.0 |
项目结构
MaiBot/
├── src/ # 核心源码
│ ├── config/ # 配置管理（TOML + Pydantic + 热重载）
│ ├── chat/ # 聊天处理、心流引擎、回复生成
│ ├── maisaka/ # 核心 AI 运行时（规划器、推理引擎、工具调用）
│ ├── A_memorix/ # 长期记忆引擎
│ ├── plugin_runtime/ # 插件运行时（Host/Runner IPC 架构）
│ ├── platform_io/ # 平台抽象层（路由、驱动、去重）
│ ├── llm_models/ # LLM 客户端实现
│ ├── services/ # 业务服务层（发送服务、记忆流等）
│ ├── webui/ # FastAPI Web 管理后端
│ ├── learners/ # 表达方式学习与黑话挖掘
│ ├── emoji_system/ # Emoji 管理
│ ├── mcp_module/ # Model Context Protocol 集成
│ ├── common/ # 共享工具（数据库、日志、i18n、消息模型）
│ ├── prompt/ # Prompt 模板管理
│ └── core/ # 核心类型定义、事件总线、工具注册
├── dashboard/ # 前端（独立仓库构建，禁止修改）
├── plugins/ # 第三方插件目录
├── src/plugins/built_in/ # 内置插件目录
├── pytests/ # 测试
└── data/ # 运行时数据（gitignore）核心模块说明
- config/：使用 Pydantic 模型管理配置，支持 TOML 文件热重载，配置修改通过模版+版本号方式发布，不直接编辑运行时配置。
- chat/：聊天消息入口与主链路调度。包含
ChatBot（消息处理入口）、ChatManager（会话管理）、HeartFlow（心流消息处理器）等。 - maisaka/：核心 AI 运行时。以
ChatLoopService为中心，负责 LLM 对话循环、工具调用规划、上下文消息管理等。 - A_memorix/：长期记忆引擎，负责持久化用户偏好、对话记忆等心理学维度数据。
- plugin_runtime/：插件运行时系统。采用 Host（主进程）/ Runner（子进程）IPC 架构，使用 msgpack 编解码，支持 Hook 机制、组件注册与热重载。
- platform_io/：平台抽象层。通过
RouteKey路由机制实现多平台消息收发的统一管理，支持驱动的注册、路由绑定、入站去重与出站跟踪。 - llm_models/：LLM 客户端实现，封装各模型 API 的调用逻辑。
- services/：业务服务层，包含
SendService（出站消息发送）等核心服务。 - webui/：FastAPI 驱动的 Web 管理后端，提供插件管理、配置编辑、认证鉴权等功能，默认绑定
0.0.0.0:8001。 - core/：核心类型定义，包括
ComponentType、ActionInfo、CommandInfo、ToolInfo、MaiMessages等。
开发环境搭建
前置条件
- Python 3.10 或更高版本
- uv 包管理工具
安装依赖
bash
uv sync启动项目
bash
uv run python bot.pybot.py 采用 Runner/Worker 双进程模型：Runner 进程负责守护与重启（退出码 42 触发重启），Worker 进程执行实际的 MainSystem 初始化与任务调度。
运行测试
bash
uv run pytest代码检查与格式化
bash
# Lint 检查
uv run ruff check .
# 自动格式化
uv run ruff format .架构详解
深入了解各子系统的内部架构和实现原理：
- 消息管线：入站消息的完整处理流程——从平台适配器到 Hook 拦截、过滤、命令分发、HeartFlow 和出站发送
- Maisaka 推理引擎：对话推理的核心——Timing Gate 节奏控制、Planner 规划循环、工具调用和打断机制
- 记忆系统：A-Memorix 长期记忆引擎——双路检索、存储层、记忆策略和人物画像
- WebUI 内部机制：FastAPI 后端架构——认证安全、WebSocket 通信、插件管理和配置热重载