Luolan.QQBot 1.3.0

Luolan.QQBot

<p align="center"> <img src="https://img.shields.io/nuget/v/Luolan.QQBot.svg" alt="NuGet"> <img src="https://img.shields.io/github/license/luolangaga/Luolan.QQBot" alt="License"> </p>

一个简洁、高效、深度集成 .NET 依赖注入体系的 QQ 官方机器人 SDK。旨在提供最符合 .NET 开发者直觉的开发体验。

🌟 特性

• ⚡ 极致简单 - 采用 Builder 模式，几行代码即可让机器人上线。
• 🔄 全自动管理 - Token 自动刷新、WebSocket 自动重连，开发者只需关注业务逻辑。
• 🧪 深度集成 - 完美支持 ASP.NET Core 依赖注入和 IHostedService。
• 🛡️ 强类型支持 - 完整的 API 模型定义，享受极致的 IDE 智能提示。
• 📡 事件驱动 - 清晰的事件分发机制，支持频道、群聊、私聊等多种场景。

🗺️ 快速导航

• 安装指南
• 快速开始
• 核心概念
• API 详细说明
  • 消息发送与回复
  • Markdown 与 互动键盘
  • 频道与成员管理
• 事件列表
• 高级配置
• 完整示例程序

📦 安装

通过 NuGet 安装核心包：

dotnet add package Luolan.QQBot

🚀 快速开始

1. 基础控制台模式

using Luolan.QQBot;

var bot = new QQBotClientBuilder()
    .WithAppId("你的AppId")
    .WithClientSecret("你的ClientSecret")
    .WithIntents(Intents.Default | Intents.GroupAtMessages)
    .Build();

bot.OnAtMessageCreate += async e => await bot.ReplyAsync(e.Message, "收到频道消息！");
bot.OnGroupAtMessageCreate += async e => await bot.ReplyGroupAsync(e.Message, "收到群消息！");

await bot.StartAsync();
await Task.Delay(-1);

2. ASP.NET Core 集成

builder.Services.AddQQBot(options => {
    options.AppId = "你的AppId";
    options.ClientSecret = "你的ClientSecret";
    options.Intents = Intents.Default;
});
builder.Services.AddQQBotHostedService();

💡 核心概念: Intents

订阅相应的 Intents 才能接收到对应类型的事件。

📖 API 详细说明

1. 消息发送与回复

// 自动解析来源并回复 (支持频道/群/C2C)
await bot.ReplyAsync(sourceMsg, "回复内容");
await bot.ReplyGroupAsync(sourceMsg, "回复群内容");
await bot.ReplyC2CAsync(sourceMsg, "回复私聊内容");

// 主动发送
await bot.SendChannelMessageAsync("channelId", "Hello!");
await bot.SendGroupMessageAsync("groupOpenId", "Hello Group!");
await bot.SendC2CMessageAsync("userOpenId", "Hello Private!");

2. Markdown 与 互动键盘

方式一：使用构建器 (推荐)

using Luolan.QQBot.Helpers;

// 1. 原生 Markdown 内容
var markdown = new MarkdownBuilder()
    .UseContent("# 标题\n这是**粗体**，这是*斜体*")
    .Build();

await bot.SendMarkdownAsync(channelId, markdown);

// 2. 使用 Markdown 模板
var markdownTemplate = new MarkdownBuilder()
    .UseTemplate("123456")  // 你的模板ID
    .AddParam("title", "欢迎")
    .AddParam("content", "这是模板内容")
    .Build();

// 3. 带按钮的互动键盘
var keyboard = new KeyboardBuilder()
    .NewRow()
        .AddButton("btn1", "按钮1")
        .AddButton("btn2", "按钮2")
    .NewRow()
        .AddLinkButton("btn3", "访问链接", "https://github.com")
    .Build();

await bot.SendMarkdownAsync(channelId, markdownTemplate, keyboard);

方式二：使用扩展方法 (最简洁)

using Luolan.QQBot.Extensions;

// 发送原生 Markdown
await bot.SendMarkdownContentAsync(channelId, "# Hello\n**World**");

// 发送模板消息
await bot.SendMarkdownTemplateAsync(channelId, "123456", new() {
    ["title"] = new[] { "标题" },
    ["content"] = new[] { "内容" }
});

// 回复消息时使用 Markdown
bot.OnAtMessageCreate += async e => {
    await bot.ReplyMarkdownTemplateAsync(e.Message, "123456", new() {
        ["name"] = new[] { e.Message.Author?.Username ?? "用户" }
    });
};

方式三：快捷方法

// 快速创建原生 Markdown
var md = MarkdownBuilder.FromContent("**Hello**");

// 快速创建模板
var md = MarkdownBuilder.FromTemplate("123456", new() { ["k"] = new[] { "v" } });

// 快速创建单行按钮
var keyboard = KeyboardBuilder.FromButtons(
    new Button { RenderData = new() { Label = "B1" }, Action = new() { Data = "D1" } }
);

3. 频道与成员管理

// 获取信息
var guilds = await bot.GetGuildsAsync();
var members = await bot.GetMembersAsync(guildId);

// 禁言
await bot.Api.MuteMemberAsync(guildId, userId, 60); // 60秒

// 角色管理
await bot.Api.CreateGuildRoleAsync(guildId, new() { Name = "新角色", Color = 0xFF0000 });

📡 事件列表

消息事件

• OnAtMessageCreate: 频道 @ 机器人
• OnMessageCreate: 频道全量消息 (私域)
• OnGroupAtMessageCreate: 群聊 @ 机器人
• OnC2CMessageCreate: C2C 私聊
• OnDirectMessageCreate: 频道私信

频道与管理事件

• OnGuildCreate / OnGuildDelete / OnGuildUpdate
• OnGuildMemberAdd / OnGuildMemberRemove
• OnInteractionCreate: 互动按钮点击
• OnGroupAddRobot / OnGroupDelRobot: 机器人进/出群
• OnFriendAdd / OnFriendDel: 好友变动
• OnMessageAuditPass / OnMessageAuditReject: 消息审核

🔧 高级配置

var bot = new QQBotClientBuilder()
    .WithAppId("你的AppId")
    .WithClientSecret("你的ClientSecret")
    .UseSandbox(true)                              // 沙箱环境
    .WithIntents(Intents.Default)                  // 事件订阅
    .WithTokenRefreshBeforeExpire(120)             // Token 提前刷新
    .WithWebSocketReconnectInterval(3000)          // 重连间隔
    .WithWebSocketMaxReconnectAttempts(20)         // 最大尝试次数
    .WithLoggerFactory(loggerFactory)              // 自定义日志
    .Build();

📋 完整示例

using Luolan.QQBot;
using Luolan.QQBot.Models;
using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(b => b.AddConsole().SetMinimumLevel(LogLevel.Debug));

var bot = new QQBotClientBuilder()
    .WithAppId(Environment.GetEnvironmentVariable("QQ_BOT_APP_ID")!)
    .WithClientSecret(Environment.GetEnvironmentVariable("QQ_BOT_CLIENT_SECRET")!)
    .WithIntents(Intents.Default | Intents.GroupAtMessages)
    .WithLoggerFactory(loggerFactory)
    .Build();

bot.OnReady += async e => Console.WriteLine($"机器人已上线: {e.User?.Username}");

bot.OnAtMessageCreate += async e => {
    var content = e.Message.Content?.Trim() ?? "";
    if (content.Contains("ping")) await bot.ReplyAsync(e.Message, "pong!");
    else await bot.ReplyAsync(e.Message, $"你说: {content}");
};

bot.OnGroupAtMessageCreate += async e => {
    await bot.ReplyGroupAsync(e.Message, $"群消息收到: {e.Message.Content}");
};

await bot.StartAsync();
Console.WriteLine("按下任意键退出...");
Console.ReadKey();
await bot.StopAsync();

🛡️ License & Feedback

• License: MIT
• Issues: Github Issues
• Official Docs: QQ 机器人官方文档