Luolan.QQBot.OneBot 2.0.0

Luolan.QQBot

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

一个模块化、可扩展的 QQ 机器人 SDK，支持多协议切换。只需更换实现包，即可在官方 API 和 OneBot 12 协议之间无缝切换！

🌟 v2.0 新特性

• 🔌 可插拔协议层 - 核心抽象与协议实现分离，一套代码适配多种协议
• 🤖 官方 API 支持 - 完整支持 QQ 官方机器人 API
• 📡 OneBot 12 支持 - 兼容 Napcat、Lagrange.OneBot 等实现
• 🎮 统一的 MVC 控制器 - 与协议无关的命令处理模式
• 🔄 无缝切换 - 只需更换 NuGet 包即可切换协议

📦 包结构

🚀 快速开始

使用官方 API

dotnet add package Luolan.QQBot.Core
dotnet add package Luolan.QQBot.Official

using Luolan.QQBot.Official;
using Luolan.QQBot.Core.Extensions;

// 创建官方机器人客户端
var bot = new OfficialBotClientBuilder()
    .WithAppId("你的AppId")
    .WithClientSecret("你的ClientSecret")
    .WithIntents(Intents.Default | Intents.GroupAtMessages)
    .Build();

// 监听消息事件
bot.Events.OnMessageReceived += async e =>
{
    Console.WriteLine($"收到消息: {e.Message.Content}");
    await bot.ReplyAsync(e.Message, "收到！");
};

// 启用控制器模式
bot.UseControllers();

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

方式二：使用 OneBot 实现 (NapCat / Lagrange)

支持 OneBot 11 (NapCat/CQHTTP) 和 OneBot 12 (Lagrange) 两种协议

dotnet add package Luolan.QQBot.Core
dotnet add package Luolan.QQBot.OneBot

NapCat (OneBot 11) 示例

using Luolan.QQBot.Core.Abstractions;
using Luolan.QQBot.OneBot;

var bot = new OneBotClientBuilder()
    .UseWebSocket("ws://127.0.0.1:6700")  // NapCat 默认端口
    .WithAccessToken("your_token")         // 可选
    .Build();  // 自动检测协议版本

bot.Events.OnReady += async e => Console.WriteLine("✅ 上线成功！");

bot.Events.OnMessageReceived += async e =>
{
    if (e.Message.Content == "/ping")
        await bot.ReplyAsync(e.Message, "Pong!");
};

bot.UseControllers();
await bot.StartAsync();

Lagrange (OneBot 12) 示例

var bot = new OneBotClientBuilder()
    .UseWebSocket("ws://127.0.0.1:3001")  // Lagrange 默认端口
    .WithProtocolVersion(OneBotVersion.V12)  // 可选：显式指定
    .Build();

// 事件处理代码完全相同，切换协议无需修改业务代码！
await bot.StartAsync();

💡 提示：协议切换只需修改端口和地址，代码无需改动！

更多详情请查看 OneBot 包文档。

🔄 协议切换

核心优势：你的业务代码完全不需要修改！

// ===== 官方 API =====
using Luolan.QQBot.Official;
var bot = new OfficialBotClientBuilder()
    .WithAppId("xxx").WithClientSecret("xxx")
    .Build();

// ===== OneBot 12 =====
using Luolan.QQBot.OneBot;
var bot = new OneBotClientBuilder()
    .UseWebSocket("ws://127.0.0.1:3001")
    .Build();

// ===== 以下代码完全相同 =====
bot.Events.OnMessageReceived += async e =>
{
    await bot.Messages.SendTextAsync(e.Message.Source, "Hello!");
};

bot.UseControllers();
await bot.StartAsync();

🛠️ 消息构建器 (Builder 模式)

使用 MessageBuilder 以流式方式构建复杂消息：

var message = MessageBuilder.Create()
    .At(userId)
    .Text(" 这是一个测试消息 ")
    .Image("https://example.com/image.jpg")
    .Build();

await bot.ReplyAsync(e.Message, message);

或者直接传入 Builder（因为它实现了 IEnumerable<MessageSegment>）：

await bot.Messages.SendMessageAsync(target, MessageBuilder.Create()
    .Text("Hello ")
    .Face("101")
);

🎮 MVC 控制器模式

控制器模式与协议无关，可以在任何实现上工作：

using Luolan.QQBot.Core.Controllers;

public class MyController : BotController
{
    // 基础命令
    // 用户发送: /hello world
    [Command("hello")]
    public string Hello(string name)
    {
        return $"Hello {name}!";
    }

    // 参数自动转换
    // 用户发送: /add 10 20
    [Command("add")]
    public string Add(int a, int b)
    {
        return $"Result: {a + b}";
    }

    // 返回图片
    [Command("image")]
    public ImageResult GetImage()
    {
        return new ImageResult("https://example.com/image.jpg");
    }

    // 异步方法
    [Command("async")]
    public async Task<string> AsyncWork()
    {
        await Task.Delay(1000);
        return "Done!";
    }

    // 访问上下文
    [Command("info")]
    public string Info()
    {
        return $"Sender: {Sender?.Username}, MessageId: {Message.Id}";
    }
}

📡 OneBot 12 连接模式

OneBot 实现支持多种连接方式：

// 正向 WebSocket（推荐）
var bot = new OneBotClientBuilder()
    .UseWebSocket("ws://127.0.0.1:3001")
    .Build();

// HTTP 模式
var bot = new OneBotClientBuilder()
    .UseHttp("http://127.0.0.1:3000")
    .Build();

// 反向 WebSocket（即将支持）
var bot = new OneBotClientBuilder()
    .UseReverseWebSocket(port: 8080, path: "/onebot/v12/ws")
    .Build();

支持的 OneBot 实现

• ✅ Napcat
• ✅ Lagrange.OneBot
• ✅ 其他 OneBot 12 兼容实现

🔧 统一接口

IBotClient - 机器人客户端接口

public interface IBotClient
{
    bool IsConnected { get; }
    BotUser? CurrentUser { get; }
    IEventDispatcher Events { get; }
    IMessageSender Messages { get; }
    
    Task StartAsync(CancellationToken cancellationToken = default);
    Task StopAsync();
}

IMessageSender - 消息发送接口

// 发送文本
await bot.Messages.SendTextAsync(target, "Hello!");

// 发送图片
await bot.Messages.SendImageAsync(target, "https://example.com/image.jpg");

// 发送复合消息
await bot.Messages.SendMessageAsync(target, new[]
{
    MessageSegment.Text("Hello "),
    MessageSegment.At("123456"),
    MessageSegment.Text("!")
});

统一的消息目标

// 群消息
var target = MessageTarget.Group("group_id");

// 私聊消息
var target = MessageTarget.Private("user_id");

// 频道消息
var target = MessageTarget.Channel("guild_id", "channel_id");

📡 事件系统

统一的事件接口，所有协议实现都使用相同的事件模型：

// 消息事件
bot.Events.OnMessageReceived += async e =>
{
    Console.WriteLine($"消息来源: {e.SourceType}");
    Console.WriteLine($"发送者: {e.Message.Sender?.Username}");
    Console.WriteLine($"内容: {e.Message.Content}");
};

// 连接就绪事件
bot.Events.OnReady += async e =>
{
    Console.WriteLine($"机器人已上线: {e.Self?.Username}");
};

// 成员变动事件
bot.Events.OnMemberChanged += async e =>
{
    Console.WriteLine($"成员变动: {e.ChangeType}");
};

// 原始事件（访问协议特定数据）
bot.Events.OnRawEvent += async e =>
{
    Console.WriteLine($"原始事件: {e.EventType}");
};

🛠️ 高级用法

官方 API 特定功能

var officialBot = bot as OfficialBotClient;

// 访问官方特定 API
await officialBot!.Api.GetGuildAsync("guild_id");
await officialBot.Api.MuteMemberAsync("guild_id", "user_id", 60);

OneBot 特定功能

var oneBotClient = bot as OneBotClient;

// 调用 OneBot Action
await oneBotClient!.Actions.GetGroupListAsync();
await oneBotClient.Actions.BanGroupMemberAsync("group_id", "user_id", 60);

💡 从 v1.x 迁移

如果你正在使用 v1.x 版本，可以逐步迁移：

1. 保持兼容 - 旧的 Luolan.QQBot 包仍然可用
2. 新项目推荐 - 使用新架构 Luolan.QQBot.Official
3. 迁移步骤:
   • 将 QQBotClient 改为 OfficialBotClient
   • 将 QQBotClientBuilder 改为 OfficialBotClientBuilder
   • 事件监听使用统一的 Events.OnMessageReceived

🛡️ License & Feedback

• License: MIT
• Issues: Github Issues
• QQ 官方文档: QQ 机器人官方文档
• OneBot 12 标准: OneBot 12 文档