Sora

Sora

一个基于 C#/.NET 10 的多协议异步机器人开发框架 | 框架文档（还没写）

关于本框架

孩子们我睡醒了

新版本文档还没写，目前的文档大部分都是AI帮我写的，将就看看吧，真的懒得写文档了

新版框架不再会有CQ码支持

Sora 是一个以轻量和易用为核心目标的多协议异步机器人开发框架

与旧版 Sora 不同，新版从零重构，原生支持多种协议适配：

• Milky
• OneBot v11

框架采用模块化架构，提供属性指令路由、事件分发、消息等待等功能，同时保持简单直接的 API 设计

项目结构

NuGet 包	版本	说明
HoshikawaKaguya.Sora		框架顶层 — SoraService、SoraServiceFactory、日志初始化
HoshikawaKaguya.Sora.Entities		共享实体 — 事件、消息段、信息类型、API 接口
HoshikawaKaguya.Sora.Core		核心工具 — 枚举、扩展方法、通用基础设施
HoshikawaKaguya.Sora.Command		属性指令路由 — [CommandGroup] + [Command] 声明式指令
HoshikawaKaguya.Sora.Adapter.Milky		Milky 协议适配器
HoshikawaKaguya.Sora.Adapter.OneBot11 [Deprecated]		OneBot v11 协议适配器

原生实现的 Protocol Adapter

Milky Adapter通过了较为较为完整的E2E测试

部分破坏性API/Event由于风控未作测试

这个框架基于 LuckyLilliaBot 完成开发调试，目前测试只使用了 LuckyLilliaBot 进行测试

Milky

基于 Milky HTTP API 的适配器，推荐优先使用。

Milky协议100%支持，并且这个框架目前是基于Milky在调试和开发

特性	说明
事件传输	SSE / WebSocket / WebHook 三选一（默认 WebSocket）
API 调用	HTTP REST
TLS	支持（含客户端证书）
自动重连	支持（SSE / WebSocket）

SoraService service = SoraServiceFactory.Instance.CreateMilkyService(
    new MilkyConfig { Host = "127.0.0.1", Port = 3000, AccessToken = "your-token" });

OneBot v11（已废弃）

由于OneBot v11常年无人维护且各家协议端实现都不一样 群魔乱舞，使用OneBot v11可能会遇到很多不兼容或者意想不到的情况

这个adapter目前只对LLBot做了测试，不再推荐使用OneBot v11协议，OneBot v11已经算是历史遗留了

HoshikawaKaguya.Sora.Adapter.OneBot11 的支持范围截至 Sora 2.2；后续版本停止维护，并退出构建、测试和发布。源码、专属测试和示例仅作历史参考，使用 OB11 的项目应固定在 Sora 2.2 或迁移到 Milky。

推荐直接drop ob11协议的使用，如果你的是老项目建议尽早迁移

基于 OneBot v11 的适配器，支持正向/反向 WebSocket。只支持Array格式上报

由于OneBot v11目前各协议端实现比较自由，所以有部分扩展API/Event并不支持（覆盖率在85%左右）

特性	说明
连接模式	正向 WS（Sora → OB11 Server）/ 反向 WS（OB11 Server → Sora）
TLS	支持
心跳检测	支持
自动重连	支持（正向 WS）

SoraService service = SoraServiceFactory.Instance.CreateOneBot11Service(
    new OneBot11Config { Host = "127.0.0.1", Port = 6700, AccessToken = "your-token" });

需要开发自定义适配器？请参阅 Adapter 开发指南

快速开始

安装

dotnet add package HoshikawaKaguya.Sora
dotnet add package HoshikawaKaguya.Sora.Adapter.Milky    # Milky 协议

最小示例

using Sora;
using Sora.Adapter.Milky;

// 创建 Milky 协议服务
SoraService service = SoraServiceFactory.Instance.CreateMilkyService(
    new MilkyConfig
        {
            Host        = "localhost",
            Port        = 3010,
            AccessToken = "your-token"
        });

// 注册消息事件
service.Events.OnMessageReceived += async e =>
{
    string text = e.Message.Body.GetText();
    if (text == "ping")
    {
        await e.Api.SendGroupMessageAsync(
            e.Message.GroupId,
            new MessageBody("pong"));
    }
};

// 启动服务
await service.StartAsync();
await Task.Delay(-1);

属性指令

[CommandGroup(Name = "example", Prefix = "/")]
public static class MyCommands
{
    [Command(Expressions = ["hello"], MatchType = MatchType.Full, Description = "Say hello")]
    public static async ValueTask Hello(MessageReceivedEvent e)
    {
        MessageBody reply = new("Hello! 你好！");
        if (e.Message.SourceType == MessageSourceType.Group)
            await e.Api.SendGroupMessageAsync(e.Message.GroupId, reply);
        else
            await e.Api.SendFriendMessageAsync(e.Message.SenderId, reply);
    }
}

// 注册程序集并扫描指令
AssemblyRegistration commands = service.Commands.RegisterAssembly(typeof(Program).Assembly);
commands.ScanCommandGroups();

// 动态指令：归属本程序集中的类型
commands.Registrar.RegisterDynamicCommand(typeof(MyCommands), async e => { /* ... */ }, ["ping"]);

指令以程序集为单位注册：多个程序集（例如外部插件）先按程序集优先级排序，再在每个程序集内按指令优先级执行，并可按程序集或类型动态启停、调整优先级和注销。完整说明见指令模块文档；从 2.x 升级见 V2 → V3 迁移指南。

配置 BlockUsers 后，框架在自动已读、连续对话和过滤器之前忽略该触发者的事件。SuperUsers 为对应事件设置 IsSuperUser；命令可用 [Command(SuperUserOnly = true)] 或动态注册的 superUserOnly: true 限制执行，群角色 PermissionLevel 仍需满足。框架从事件已有字段识别触发者，详见适配器与管线文档。

可以简单参考的文档

这些文档均由opus 4.6/GPT 6 Astra生成和少量人工修改，可能存在不准确的问题

懒得自己写文档了，好费劲

文档	说明
测试说明	双机器人测试架构、环境变量、Run-Tests.ps1 用法
本地测试配置	本地环境快速配置参考
日志配置	Serilog 默认日志、自定义 LoggerFactory、日志级别
指令模块	指令注册、两级执行顺序、启停、动态指令与插件卸载
消息记录	记录 bot 收发的全部聊天消息、记录器队列与顺序
Adapter 开发指南	第三方协议适配器开发详细指南
功能测试目录	所有 E2E 测试的完整清单
已移除测试	无法自动化的测试及移除原因
从 1.x 迁移到 2.0	1.x → 2.0 完整迁移指南
迁移到 3.0	2.x → 3.0 指令注册变更，以及 1.x → 3.0 直接迁移

Agent 开发入口：项目级规范见 AGENTS.md，源码和测试分别见 src/AGENTS.md 与 tests/AGENTS.md。协议/测试审计工作流位于 .agents/skills/，可执行 CLI 用法见 tools/agent-audit/README.md。

开发注意事项

开源协议

本项目使用了 Apache-2.0 开源协议

这意味着在引用/修改本类库时需要遵守相关的协议规定

构建要求

• .NET 10 SDK
• C# 预览版语言特性（LangVersion = preview）

dotnet build Sora.slnx --configuration Release

测试

我vibe了90%的测试工程，但都经过了实际的验证测试，但可能还有我没发现的问题

好懒不想写这么多测试，好像1.x版本就压根没写

项目包含单元测试和功能测试（E2E），使用 xUnit v3 框架：

# 运行单元测试（无需外部依赖）
dotnet test Sora.slnx --filter "Category=Unit&FullyQualifiedName!~OneBot11" --no-build

# 运行公共能力与 Milky 测试（需要配置测试环境变量）
pwsh tests/scripts/Run-Tests.ps1 -Category All -Filter "FullyQualifiedName!~OneBot11"

功能测试采用双机器人完成E2E验证，需要配置 SORA_TEST_* 环境变量。部分破坏性API/Event并未测试（容易触发风控）

详见 测试说明。

关于 ISSUE

ISSUE 目前只接受 bug 的提交和新功能的建议

如果有使用问题或者不确定的问题请使用Discussions

请注意，开发者并没有义务回复您的问题。您应该具备基本的提问技巧。

如果不知道该怎么样提问，那么请在提问前阅读 提问的智慧

以下 ISSUE 会被直接关闭

• 提交 BUG 时没有使用 Template
• 提交当前版本下已经被修复的 BUG
• 询问问题

关于命名

Sora 这个名字来源于日语中"空"的罗马音

一拍脑袋想的.jpg

鸣谢

使用到的开源库

Newtonsoft.Json | Json 序列化/反序列化

Mapster | 对象映射

Serilog | 结构化日志

以下的依赖只被Onebot 11 adapter所使用

Fleck | 反向 WS 服务器

Websocket.Client | 正向 WS 客户端

System.Reactive | 响应式异步 API 支持

感谢 JetBrains 为开源项目提供免费的全家桶授权

本项目使用了 Rider 开发环境