MiraiCore

万物皆插件的 AI 机器人框架

特性

• 🔌 万物皆插件：所有功能都是插件，插件可以注册工具给 AI 调用
• 🤖 AI 驱动：集成 AI 对话能力，支持工具调用
• 💬 QQ Bot 支持：支持 QQ 官方机器人 API
• 📝 上下文管理：自动管理对话历史和上下文
• ⚡ 异步架构：基于 asyncio 的高性能异步框架
• 🌐 WebUI 管理：可视化管理界面，轻松配置和监控

快速开始

1. 克隆项目

git clone https://github.com/MiraiFrame/MiraiCore.git
cd MiraiCore

2. 配置

复制配置文件模板：

cp config/config.json.example config/config.json

编辑 config/config.json，填入你的 Bot 信息和 AI API 配置。

3. 运行

方式一：命令行模式

使用 uv（推荐）：

uv run core

uv 会自动创建虚拟环境并安装依赖，无需手动安装。

或使用传统方式：

pip install -e .
python -m core.application

方式二：WebUI 模式

启动 WebUI 管理面板：

uv run webui

然后访问 http://localhost:8080 进行可视化管理。

首次使用：

1. 使用配置文件中的 register_code（默认：miraicore）注册管理员账号
2. 登录后可以在线配置 Bot、AI、插件等

目录结构

MiraiCore/
├── core/                   # 核心模块
│   ├── application.py     # 应用主类
│   ├── bot/               # Bot 管理
│   │   └── registry.py    # Bot 注册表
│   ├── message/           # 消息处理
│   │   ├── event.py       # 消息事件
│   │   ├── parser.py      # 消息解析
│   │   └── sender.py      # 消息发送
│   ├── plugin/            # 插件系统
│   │   ├── base.py        # 插件基类和装饰器
│   │   └── manager.py     # 插件管理器
│   ├── ai/                # AI 功能
│   │   └── session_manager.py  # AI 会话管理
│   ├── storage/           # 存储
│   │   └── message_history.py  # 消息历史
│   └── config/            # 配置
│       └── loader.py      # 配置加载器
├── webui/                 # WebUI 管理面板
│   ├── backend/           # 后端 API
│   │   ├── __init__.py    # FastAPI 应用
│   │   ├── auth.py        # 认证路由
│   │   ├── dashboard.py   # 仪表板路由
│   │   ├── database.py    # 数据库模型
│   │   └── utils.py       # 工具函数
│   └── frontend/          # 前端页面
│       └── index.html     # 管理界面
├── plugins/               # 插件目录
│   ├── weather.py         # 天气查询插件示例
│   └── basic_chat.py      # 基础对话插件
├── config/                # 配置文件
│   └── config.json        # 主配置文件
├── data/                  # 数据存储
│   ├── history.db         # 消息历史数据库
│   └── miraicore.db       # WebUI 数据库
├── webui_main.py          # WebUI 启动文件
└── pyproject.toml         # 项目配置

编写插件

示例 1：消息处理器

from core.plugin.base import handler, on_load

@on_load
async def plugin_loaded():
    print("插件已加载")

@handler(
    pattern=r"你好",
    name="问候",
    priority=10,
    require_at=True  # 群聊需要 @ 才触发
)
async def handle_greeting(event, sender):
    await sender.reply(event, "你好！")
    return True  # 返回 True 表示已处理，停止后续处理器

示例 2：注册 AI 工具

from core.plugin.base import tool

@tool(
    name="get_weather",
    description="获取天气信息",
    parameters={
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "城市名称"}
        },
        "required": ["city"]
    }
)
async def get_weather(city: str) -> dict:
    # 调用天气 API
    return {
        "city": city,
        "temperature": "25°C",
        "weather": "晴"
    }

配置说明

Bot 配置

{
  "bots": [
    {
      "appid": "你的机器人 AppID",
      "token": "你的机器人 Token",
      "name": "机器人名称"
    }
  ]
}

AI 配置

{
  "ai": {
    "api_base": "AI API 地址",
    "api_key": "API Key",
    "model": "模型名称",
    "system_prompt": "系统提示词",
    "max_context_messages": 10,
    "max_context_tokens": 4000
  }
}

WebUI 配置

{
  "webui": {
    "enabled": true,           # 是否启用 WebUI
    "port": 8080,              # WebUI 端口
    "register_code": "miraicore"  # 注册码，用于首次注册管理员
  }
}

安全提示：

• 首次部署后请立即修改 register_code
• WebUI 使用 JWT Token 认证
• 建议在生产环境配置 HTTPS 反向代理

License

MIT