Skip to content
Hoshikawa-KaguyaPublic

About

.Net 10异步机器人框架,跨平台,Milky协议,在兼容协议的同时主要为LLBot提供支持

Topics

Resources

Stars

185 stars

Watchers

5 watching

Forks

Repository files navigation


LOGO
Sora

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

关于本框架

孩子们我睡醒了

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

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

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

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

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

项目结构

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

jetbrains jetbrains

About

.Net 10异步机器人框架,跨平台,Milky协议,在兼容协议的同时主要为LLBot提供支持

Topics

Resources

Stars

185 stars

Watchers

5 watching

Forks

Contributors

Languages