一个基于 C#/.NET 10 的多协议异步机器人开发框架 | 框架文档（还没写）
孩子们我睡醒了
新版本文档还没写，目前的文档大部分都是AI帮我写的，将就看看吧，真的懒得写文档了
新版框架不再会有CQ码支持
Sora 是一个以轻量和易用为核心目标的多协议异步机器人开发框架
与旧版 Sora 不同，新版从零重构，原生支持多种协议适配：
框架采用模块化架构，提供属性指令路由、事件分发、消息等待等功能，同时保持简单直接的 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 |
 |
OneBot v11 协议适配器 |
Milky 和 OneBot v11 均通过了较为较为完整的E2E测试
部分破坏性API/Event由于风控未作测试
这个框架基于 LuckyLilliaBot 完成开发调试，目前测试只使用了 LuckyLilliaBot 进行测试
基于 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可能会遇到很多不兼容或者意想不到的情况
这个adapter目前只对LLBot做了测试，不再推荐使用OneBot v11协议
基于 OneBot v11 的适配器，支持正向/反向 WebSocket。只支持Array格式上报
Note: 由于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 协议
dotnet add package HoshikawaKaguya.Sora.Adapter.OneBot11 # 或 OneBot v11 协议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);
}
}
// 注册指令
service.Commands.ScanAssembly(typeof(Program).Assembly);这些文档均由opus 4.6生成和
少量人工修改，可能存在不准确的问题
懒得自己写文档了，好费劲
| 文档 | 说明 |
|---|---|
| 测试说明 | 双机器人测试架构、环境变量、Run-Tests.ps1 用法 |
| 本地测试配置 | 本地环境快速配置参考 |
| 日志配置 | Serilog 默认日志、自定义 LoggerFactory、日志级别 |
| Adapter 开发指南 | 第三方协议适配器开发详细指南 |
| 功能测试目录 | 所有 E2E 测试的完整清单 |
| 已移除测试 | 无法自动化的测试及移除原因 |
| 从 1.x 迁移到 2.0 | 1.x → 2.0 完整迁移指南 |
开源协议
本项目使用了 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" --no-build
# 运行所有测试（需要配置测试环境变量）
pwsh tests/scripts/Run-Tests.ps1 -Category All功能测试采用双机器人完成E2E验证，需要配置 SORA_TEST_* 环境变量。部分破坏性API/Event并未测试（容易触发风控）
详见 测试说明。
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 开发环境
