# 快速开始

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

## 步骤 1：设置项目

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

```bash
cargo new my-first-bot
cd my-first-bot
```

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

```toml
[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 频道开发者门户](https://bot.q.qq.com/)
2. 创建新应用程序或选择现有应用程序
3. 复制您的**应用 ID** 和**密钥**

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

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

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

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

```rust
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：运行机器人

现在运行您的机器人：

```bash
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` - 机器人应该显示可用命令

## 理解代码

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

### 事件处理器
```rust
struct MyBot;

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

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

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

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

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

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

### Intent
```rust
let intents = Intents::default()
    .with_public_guild_messages()
    .with_guilds();
```

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

## 下一步

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

### 添加更多命令
```rust
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),
    // ... 更多命令
};
```

### 处理不同消息类型
```rust
// 处理群消息
async fn group_message_create(&self, ctx: Context, message: GroupMessage) {
    // 处理群聊消息
}

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

### 发送富文本消息
```rust
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. 查看[示例](/zh/examples/getting-started)获取更多代码示例
2. 阅读 [API 参考](/zh/api/client)获取详细文档
3. 访问 [GitHub 仓库](https://github.com/YinMo19/botrs)获取问题和讨论

## 接下来做什么？

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

- **[配置](/zh/guide/configuration)** - 了解高级配置选项
- **[消息与回复](/zh/guide/messages)** - 发现发送消息的所有方式
- **[错误处理](/zh/guide/error-handling)** - 构建健壮的生产就绪机器人
- **[示例](/zh/examples/getting-started)** - 查看更复杂的机器人实现

愉快的机器人构建！🤖✨