快速开始

本指南将帮助您在几分钟内使用 BotRS 创建您的第一个 QQ 频道机器人。在本教程结束时，您将拥有一个可以响应消息的工作机器人。

步骤 1：设置项目

首先，创建一个新的 Rust 项目并添加必要的依赖项：

cargo new my-first-bot
cd my-first-bot

编辑您的 Cargo.toml 以包含 BotRS 及其依赖项：

[package]
name = "my-first-bot"
version = "0.1.0"
edition = "2021"

[dependencies]
botrs = "0.2.5"
tokio = { version = "1.0", features = ["full"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
async-trait = "0.1"

步骤 2：获取机器人凭据

在编写代码之前，您需要从 QQ 频道开发者门户获取凭据：

1. 访问 QQ 频道开发者门户
2. 创建新应用程序或选择现有应用程序
3. 复制您的应用 ID 和密钥

对于本教程，您可以将它们设置为环境变量：

export QQ_BOT_APP_ID="你的应用ID"
export QQ_BOT_SECRET="你的密钥"

步骤 3：编写您的第一个机器人

将 src/main.rs 的内容替换为以下代码：

use botrs::{Client, Context, EventHandler, Intents, Message, Ready, Token};
use tracing::{info, warn};

// 定义机器人的事件处理器
struct MyBot;

#[async_trait::async_trait]
impl EventHandler for MyBot {
    // 当机器人成功连接时调用
    async fn ready(&self, _ctx: Context, ready: Ready) {
        info!("🤖 机器人已就绪！登录为：{}", ready.user.username);
    }

    // 当有人在消息中提及您的机器人时调用
    async fn message_create(&self, ctx: Context, message: Message) {
        // 忽略来自其他机器人的消息
        if message.is_from_bot() {
            return;
        }

        // 获取消息内容
        let content = match &message.content {
            Some(content) => content,
            None => return,
        };

        info!("📨 收到消息：{}", content);

        // 响应不同的命令
        let response = match content.trim() {
            "!ping" => "🏓 Pong!",
            "!hello" => "👋 你好！",
            "!help" => "🤖 可用命令：!ping, !hello, !help, !about",
            "!about" => "🦀 我是用 BotRS 构建的 QQ 机器人 - 一个用于 QQ 频道机器人的 Rust 框架！",
            _ => return, // 不回应其他消息
        };

        // 发送回复
        match message.reply(&ctx.api, &ctx.token, response).await {
            Ok(_) => info!("✅ 回复发送成功"),
            Err(e) => warn!("❌ 发送回复失败：{}", e),
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 初始化日志记录
    tracing_subscriber::fmt()
        .with_env_filter("botrs=info,my_first_bot=info")
        .init();

    info!("🚀 启动机器人...");

    // 从环境变量获取凭据
    let app_id = std::env::var("QQ_BOT_APP_ID")
        .expect("未设置 QQ_BOT_APP_ID 环境变量");
    let secret = std::env::var("QQ_BOT_SECRET")
        .expect("未设置 QQ_BOT_SECRET 环境变量");

    // 创建身份验证令牌
    let token = Token::new(app_id, secret);

    // 配置机器人想要接收的事件
    let intents = Intents::default()
        .with_public_guild_messages()  // 接收 @ 提及
        .with_guilds();                // 接收频道事件

    // 创建机器人客户端
    let mut client = Client::new(token, intents, MyBot, true)?;

    info!("🔌 连接到 QQ 频道...");

    // 启动机器人（这将运行直到程序停止）
    client.start().await?;

    Ok(())
}

步骤 4：运行机器人

现在运行您的机器人：

cargo run

您应该看到类似以下的输出：

2024-01-01T12:00:00.000Z  INFO my_first_bot: 🚀 启动机器人...
2024-01-01T12:00:00.100Z  INFO my_first_bot: 🔌 连接到 QQ 频道...
2024-01-01T12:00:01.200Z  INFO my_first_bot: 🤖 机器人已就绪！登录为：MyBot

步骤 5：测试机器人

1. 将机器人添加到 QQ 频道（服务器）
2. 在机器人有权限的频道中，尝试这些命令：
   • @您的机器人 !ping - 机器人应该回复 "🏓 Pong!"
   • @您的机器人 !hello - 机器人应该回复 "👋 你好！"
   • @您的机器人 !help - 机器人应该显示可用命令

理解代码

让我们分解机器人中发生的事情：

事件处理器

struct MyBot;

#[async_trait::async_trait]
impl EventHandler for MyBot {
    // 您的事件处理方法放在这里
}

EventHandler trait 定义了机器人如何响应不同事件。您只需要实现您关心的事件。

Ready 事件

async fn ready(&self, _ctx: Context, ready: Ready) {
    info!("🤖 机器人已就绪！登录为：{}", ready.user.username);
}

当机器人成功连接并准备接收事件时调用一次。

消息事件

async fn message_create(&self, ctx: Context, message: Message) {
    // 处理传入的消息
}

当有人在消息中提及您的机器人时调用。ctx 参数提供对 API 客户端和身份验证令牌的访问。

Intent

let intents = Intents::default()
    .with_public_guild_messages()
    .with_guilds();

Intent 控制机器人接收哪些事件。这有助于通过只订阅您需要的事件来优化性能。

下一步

恭喜！您已经使用 BotRS 创建了您的第一个 QQ 频道机器人。以下是扩展机器人的一些想法：

添加更多命令

let response = match content.trim() {
    "!ping" => "🏓 Pong!",
    "!time" => &format!("⏰ 当前时间：{}", chrono::Utc::now().format("%Y-%m-%d %H:%M:%S UTC")),
    "!random" => &format!("🎲 随机数：{}", rand::random::<u32>() % 100),
    // ... 更多命令
};

处理不同消息类型

// 处理群消息
async fn group_message_create(&self, ctx: Context, message: GroupMessage) {
    // 处理群聊消息
}

// 处理私信
async fn direct_message_create(&self, ctx: Context, message: DirectMessage) {
    // 处理私人消息
}

发送富文本消息

use botrs::models::message::{MessageParams, MessageEmbed};

let embed = MessageEmbed {
    title: Some("来自 BotRS 的问候！".to_string()),
    description: Some("这是一个富文本嵌入消息".to_string()),
    color: Some(0x00ff00),
    ..Default::default()
};

let params = MessageParams::new_embed(embed);
ctx.api.post_message_with_params(&ctx.token, &channel_id, params).await?;

故障排除

常见问题

机器人不响应消息：

• 确保机器人在频道中有适当的权限
• 验证您是否在提及机器人（@机器人名称 命令）
• 检查 public_guild_messages intent 是否已启用

身份验证错误：

• 仔细检查您的应用 ID 和密钥
• 确保环境变量设置正确
• 验证机器人在 QQ 频道开发者门户中正确配置

连接问题：

• 检查您的网络连接
• 验证 QQ 频道服务是否正常运行
• 查找防火墙或代理问题

获取帮助

如果遇到问题：

1. 查看示例获取更多代码示例
2. 阅读 API 参考获取详细文档
3. 访问 GitHub 仓库获取问题和讨论

接下来做什么？

现在您有了一个基本的机器人运行，探索这些指南以了解更多：

• 配置 - 了解高级配置选项
• 消息与回复 - 发现发送消息的所有方式
• 错误处理 - 构建健壮的生产就绪机器人
• 示例 - 查看更复杂的机器人实现

愉快的机器人构建！🤖✨