一个基于 C#/.NET 10 的多协议异步机器人开发框架 | 框架文档(还没写)
孩子们我睡醒了
新版本文档还没写,目前的文档大部分都是AI帮我写的,将就看看吧,真的懒得写文档了
新版框架不再会有CQ码支持
Sora 是一个以轻量和易用为核心目标的多协议异步机器人开发框架
与旧版 Sora 不同,新版从零重构,原生支持多种协议适配:
框架采用模块化架构,提供属性指令路由、事件分发、消息等待等功能,同时保持简单直接的 API 设计
Milky Adapter通过了较为较为完整的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已经算是历史遗留了
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 目前只接受 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 开发环境