GitHub - g1331/xiaomai-bot: 以Graia Ariadne框架为基础的战地1QQ机器人

 ___  ___  _____ ______   ________  ________  ___  ___          ________  ________  _________   
|\  \|\  \|\   _ \  _   \|\   __  \|\   __  \|\  \|\  \        |\   __  \|\   __  \|\___   ___\ 
\ \  \\\  \ \  \\\__\ \  \ \  \|\  \ \  \|\  \ \  \\\  \       \ \  \|\ /\ \  \|\  \|___ \  \_| 
 \ \  \\\  \ \  \\|__| \  \ \   __  \ \   _  _\ \  \\\  \       \ \   __  \ \  \\\  \   \ \  \  
  \ \  \\\  \ \  \    \ \  \ \  \ \  \ \  \\  \\ \  \\\  \       \ \  \|\  \ \  \\\  \   \ \  \ 
   \ \_______\ \__\    \ \__\ \__\ \__\ \__\\ _\\ \_______\       \ \_______\ \_______\   \ \__\
    \|_______|\|__|     \|__|\|__|\|__|\|__|\|__|\|_______|        \|_______|\|_______|    \|__|

一个基于 Graia Ariadne 框架的 QQ 机器人

若您在使用过程中发现了 bug 或有建议，欢迎提出 Issue、PR 或加入 QQ 群聊：749094683

📊 状态

✨ 功能简览

注意！ 当前 BOT 还有许多不完善之处，处于持续开发更新状态中~

🔧 主要功能

🤖 AI 聊天对话：支持 OpenAI/DeepSeek 等多种 AI 提供商，具备工具调用、多模态输入等高级功能
🎮 战地一功能：战绩查询、服务器管理、玩家统计等完整的战地一生态
🖼️ 图片功能：识图搜索、随机图片、头像趣图、风格图片生成等
🎯 娱乐功能：随机老婆、塔罗牌、ASCII艺术生成、表情包制作等
⚙️ 管理功能：权限管理、插件管理、群管理、自动更新等
🔧 工具功能：Steam游戏查询、GitHub卡片、MC服务器状态等

更多功能请查看 modules 文件夹中的各个插件

🛠️ 待办事项

分群组的 alias 自定义指令前缀处理
~~抄其他 bot 的功能~~

🚀 快速搭建步骤

快速启动：Windows 使用 run.bat，Linux 使用 run.sh

1. 安装 Mirai

下载 MCL 2.1.0
配置 Mirai API HTTP (MAH)

2. 设置 Python 环境

本项目需要 Python >=3.10, <3.13 (即 3.10, 3.11, 3.12) 版本。推荐使用 uv 作为 Python 的依赖包管理工具，并通过 uv 创建虚拟环境，安装依赖包。

2.1 安装 `uv`

Windows 用户：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux 用户：

curl -LsSf https://astral.sh/uv/install.sh | sh

验证安装：
```
uv help
```

2.2 安装 `Python`

如果尚未安装 Python，可通过 uv 安装：

列出可用的 Python 版本：
```
uv python list
```
安装指定版本（例如 3.11.10）：
```
uv python install 3.12
```

（您可以选择满足 >=3.10,<3.13 范围的任何兼容 Python 版本进行安装。）

查找系统中已安装的 Python 路径：
```
uv python find
```

2.3 创建虚拟环境

使用指定版本的 Python 创建虚拟环境：

uv venv --python 3.12

（建议使用您计划为此项目开发和运行所对应的 Python 版本，需满足 >=3.10,<3.13 要求。）

2.4 安装依赖

从 pyproject.toml 安装依赖：

uv sync

2.5 运行项目

uv run main.py

3. 配置文件

打开 config_demo.yaml 文件填写配置信息
填写完成后重命名为 config.yaml

4. 启动 Bot

在 Bot 根目录下运行：

uv run main.py

5. 处理报错

根据报错信息进行相应处理。

🔐 使用环境变量初始化

变量名称	解释	示例
`bot_accounts`	Bot 使用的账户，逗号分隔	`1111111111,222222222`
`default_account`	默认 Bot 账户	`1111111111`
`Master`	Bot 管理者账户	`3333333333`
`mirai_host`	MAH 服务器地址	`http://localhost:8080`
`verify_key`	MAH 服务器验证 token	`123456789`
`test_group`	发送调试信息的群组	`5555555555`
`db_link`	SQLite3 数据库位置	`sqlite+aiosqlite:///data.db`

Docker 及 Docker Compose 部署请使用环境变量进行配置。

🐳 使用 Docker 部署

安装 Docker

克隆项目并构建镜像

git clone https://github.com/g1331/xiaomai-bot
cd xiaomai-bot
docker build -t xiaomai-bot .

配置文件 （注意：请确保您在项目的根目录下执行这些命令。）

cp config/config_demo.yaml config/config.yaml
# 手动创建数据库 (如果需要)
sqlite3 data.db
sqlite> .database
sqlite> .quit

运行容器 （注意：请确保您在项目的根目录下执行此命令，或者将 $(pwd) 替换为您的项目根目录的绝对路径。）
```
docker run -d --name xiaomai-bot \
  --net=host \
  -v $(pwd)/config/config.yaml:/xiaomai-bot/config/config.yaml \
  -v $(pwd)/data.db:/xiaomai-bot/data.db \
  -v $(pwd)/data:/xiaomai-bot/data \
  -v $(pwd)/statics:/xiaomai-bot/statics \
  xiaomai-bot
```
提示：根据需要添加环境变量，例如：

-e bot_accounts=1111111111,222222222

-e default_account=1111111111

-e Master=3333333333

-e mirai_host=http://localhost:8080

-e verify_key=123456789

-e test_group=5555555555

-e db_link=sqlite+aiosqlite:///data.db

🐳 使用 Docker Compose 部署

安装 Docker 与 Docker Compose

克隆项目并设置数据库 （注意：请确保您在克隆后的项目根目录下执行这些命令。）

git clone https://github.com/g1331/xiaomai-bot
cd xiaomai-bot
cp config/config_demo.yaml config/config.yaml
# 手动创建数据库 (如果需要)
sqlite3 data.db
sqlite> .database
sqlite> .quit

启动服务
```
docker-compose up -d
```

📂 项目结构与核心内容

项目结构

xiaomai-bot/
├── core/                   # 核心 - 机器人配置与信息
│   ├── orm/                # 对象关系映射 - 数据库处理
│   │   ├── __init__.py
│   │   └── tables.py       # 内置表
│   ├── models/             # 辅助控制组件
│   │   └── ...
│   ├── bot.py              # 机器人核心代码 - 统一调度资源
│   ├── config.py           # 机器人配置访问接口
│   ├── control.py          # 控制组件 - 鉴权、开关前置、冷却
│   └── ...
├── data/                   # 存放数据文件
│   └── ...
├── statics/                # 存放项目静态资源
│   └── ...
├── utils/                  # 存放运行工具
│   └── ...
├── log/                    # 机器人日志目录
│   ├── xxxx-xx-xx/
│   │   ├── common.log      # 常规日志
│   │   └── error.log       # 错误日志
│   └── ...
├── modules/                # 机器人插件目录
│   ├── required/           # 必须插件
│   │   └── ...
│   ├── self_contained/     # 内置插件
│   │   └── ...
│   └── ...
├── config.yaml             # 机器人主配置文件
├── main.py                 # 应用执行入口
├── pyproject.toml          # 项目依赖关系和打包信息
├── uv.lock                 # 依赖锁文件
├── README.md               # 项目说明文件
└── ...

核心模块

🗄️ ORM

AsyncORM：异步对象关系映射工具

⚙️ 配置

Bot 基础配置：

bot_accounts: 机器人账号列表
default_account: 默认账户
Master: 管理者 QQ
mirai_host: Mirai HTTP 服务器地址
verify_key: Mirai HTTP 验证密钥
db_link: 数据库连接字符串

🔒 控制组件（Control）

权限判断（Permission）

成员权限判断
群权限判断

频率限制（Frequency）

当前权重 / 总权重

配置判断（Config）

需要的配置信息

消息分发（Distribute）

分发需求
多账户响应模式：
- 随机响应（默认）
- 指定 Bot 响应

功能开关（Function）

开关判断：Function.require("模块名")

🔌 插件结构

`metadata.json`

{
  "level": "插件等级1/2/3",
  "name": "文件名",
  "display_name": "显示名字",
  "version": "0.0.1",
  "authors": [
    "作者"
  ],
  "description": "描述",
  "usage": [
    "用法"
  ],
  "example": [
    "例子"
  ],
  "default_switch": true,
  "default_notice": false
}

`modules` 配置

modules = {
    "module_name": {
        "groups": {
            "group_id": {
                "switch": bool,
                "notice": bool
            }
        },
        "available": bool
    }
}

🛠️ 内置插件 (`modules.required`)

🔄 auto_upgrade（自动检测更新）

自动检测 GitHub 仓库更新
手动指令执行 git pull

🧩 saya_manager（插件管理）

插件列表
已加载插件
未加载插件
加载插件
卸载插件
重载插件
开启插件
关闭插件

🔐 perm_manager（权限管理）

管理与查询权限：

更改用户权限
查询用户权限
更改群权限
查询群权限
增删 Bot 管理

🔁 response_manager（响应管理）

管理与查询多账户响应模式：

查询 Bot 列表
查询指定群的 Bot
设定多账户响应模式（随机 / 指定 Bot）
设定指定响应 Bot

🆘 helper（帮助菜单/功能管理）

生成帮助菜单，开启/关闭群功能：

帮助
开启功能
关闭功能

📈 status（运行状态）

查询 Bot 运行状态

🙏 鸣谢 & 相关项目

感谢

mirai & mirai-console：一个跨平台运行，支持 QQ Android 和 TIM PC 协议的高效机器人框架
GraiaProject 提供的项目：
- Broadcast Control：高性能、高可扩展性，基于 asyncio 的事件系统
- Ariadne：设计精巧、协议实现完备，基于 mirai-api-http v2 的即时聊天软件自动化框架
- Saya：简洁的模块管理系统
- Scheduler：基于 asyncio 的定时任务实现
- Application：Ariadne 的前身，基于 mirai-api-http 的即时聊天软件自动化框架

参考项目

本 BOT 在开发中参考了以下项目：

SAGIRI BOT：基于 Mirai 和 Graia-Ariadne 的 QQ 机器人
ABot：使用 Graia-Ariadne 搭建的功能性机器人
redbot：基于 Graia Ariadne 框架的 QQ 机器人

Name		Name	Last commit message	Last commit date
Latest commit History 1,501 Commits
.github		.github
config		config
core		core
docs		docs
modules		modules
scripts		scripts
statics		statics
tests		tests
utils		utils
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
diagram.svg		diagram.svg
docker-compose.yaml		docker-compose.yaml
main.py		main.py
openssl.conf		openssl.conf
pyproject.toml		pyproject.toml
run.bat		run.bat
run.sh		run.sh
uv.lock		uv.lock

License

g1331/xiaomai-bot

Folders and files

Latest commit

History

Repository files navigation