Flandre.Core 0.6.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Flandre.Core --version 0.6.0
NuGet\Install-Package Flandre.Core -Version 0.6.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Flandre.Core" Version="0.6.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Flandre.Core --version 0.6.0
#r "nuget: Flandre.Core, 0.6.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Flandre.Core as a Cake Addin
#addin nuget:?package=Flandre.Core&version=0.6.0

// Install Flandre.Core as a Cake Tool
#tool nuget:?package=Flandre.Core&version=0.6.0

Flandre

.NET 6 实现的跨平台,低耦合的聊天机器人框架
一次编写,多处运行

License Stars Contributors NuGet NuGet Downloads .NET Version Codecov

· 使用文档 ·

本项目的名称来源于东方 Project 中的角色芙兰朵露 · 斯卡雷特 (Flandre Scarlet) (番茄炒蛋)


项目仍在早期开发阶段,功能尚未完善,且处于快速迭代过程中。
如果您对项目的开发感兴趣,诚挚欢迎您的改进建议或 PR 贡献。

1.0 版本发布前随时可能发生 API 的非兼容性变更,不建议用于生产环境。

特性

跨平台

Flandre 自设计之初就是为了跨平台,对聊天平台的结构进行抽象化,采用适配器模式兼容各大聊天平台,同时提供了良好的开发体验。

目前已经实现的适配器:

指令系统

得益于内置的指令解析系统,开发者可以方便地掌控指令的参数信息,包括但不限于参数数量检查,类型检查,参数默认值等等。而所有的定义可以在一个字符串内完成,例如:

[Command("example <foo:string> [bar:double] [baz:int=114514]")]

事件驱动

Flandre 内部采用各类事件控制,开发者可以轻松地通过订阅事件/重写相关方法的方式控制应用的运行流程。
注:事件系统仍在完善当中

才发布没多久的项目再吹就吹过了

起步

遵循不知道哪里来的惯例,我们以一个复读小程序开始:

using Flandre.Core;
using Flandre.Adapters.Konata;
using Konata.Core.Common;

var app = new FlandreApp();

var config = new KonataAdapterConfig();
config.Bots.Add(new KonataBotConfig
{
    KeyStore = new BotKeyStore("<QQ 号>", "<密码>")
});

class ExamplePlugin : Plugin
{
    public override void OnMessageReceived(MessageContext ctx)
        => ctx.Bot.SendMessage(ctx.Message);
}

app
    .UseKonataAdapter(config)
    .Use(new ExamplePlugin())
    .Start();

运行程序,向我们 bot 的 QQ 号发送一条消息,bot 会将消息原封不动地发回来。 复读不仅仅是人类的本质.jpg

基本指令解析

来个高级点的例子,我们定义一条指令:

class ExamplePlugin2 : Plugin
{
    [Command("example <foo> [bar]")]
    public MessageContent OnExample(MessageContext ctx, ParsedArgs args)
    {
        var foo = args.GetArgument<string>("foo");
        var bar = args.GetArgument<string>("bar");
        
        if (string.IsNullOrWhiteSpace(bar))
            bar = "(empty)";

        var mb = new MessageBuilder();

        mb.Text($"Foo: {foo}, ")
            .Text($"Bar: {bar}");

        return mb;
    }
}

这个插件包含一条有两个参数的指令,类型都为 string,其中 foo 为必选参数,bar 为可选参数。如果调用指令时未提供可选参数,参数将被初始化为类型默认值;如果为提供必选参数,bot 将向其发送一条提示信息并停止执行指令。

向 bot 发送 example qwq ovo随便什么),bot 会将参数的值发送回来。

类型约束

如果我们不对指令的参数进行类型约束,那么参数的类型将默认为 string。如要添加参数,可以在参数名称后添加 : 号和类型名称。类型名称支持 C# 中绝大多数的基本类型,如 int, double, long, bool 等等,在解析过程中会自动进行类型检查和转换。

举个例子:

[Command("example <foo:double> <bar:bool>")]
public MessageContent? OnExample(MessageContext ctx, ParsedArgs args)
{
    var foo = args.GetArgument<double>("foo");
    var bar = args.GetArgument<bool>("bar");

    Logger.Info(foo.GetType().Name);   // Double
    Logger.Info(bar.GetType().Name);   // Boolean

    return null;
}

参数默认值

有时我们需要对参数指定默认值,可以在定义中使用 = 号:

[Command("example [foo:int=1145] [bar:bool=true]")]

如果不人为指定默认值,参数将被初始化为 C# 中的类型默认值(即 default(T))。string 比较特殊,在参数中它的默认值是空字符串,而不是 null

灵活的表现形式

Flandre 内置的指令解析器允许留下空格。如果你觉得参数的各种定义挤在一起乱糟糟的,可以适度空开:

[Command("example [foo: int = 1145] [bar: bool = true]")]

这样写的缺点是可能导致指令定义过于冗长,可以结合实际情况选择。

分支说明

项目目前有两个主要分支:

  • main 分支 - 包含上一个发布版本的源代码,dev 分支会在版本发布时合并过来
  • dev 分支 - 开发分支,包含最新更改,但可能不稳定。

向仓库贡献代码时,请确保目前正处于 dev 分支上。

致谢

项目编写过程中参考了许多开源项目,没有它们就没有 Flandre 的诞生:

(按字母排序)

License

本项目以 MIT 许可证 开源 (′▽`)╭(′▽`)╯

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.

NuGet packages (6)

Showing the top 5 NuGet packages that depend on Flandre.Core:

Package Downloads
Flandre.Framework

现代化、跨平台的聊天机器人框架,一次编写,多处运行。

Flandre.Adapters.Mock

Mock client for Project Flandre.

Flandre.Adapters.Konata

Konata.Core (QQ Protocol) adapter for Flandre project.

Flandre.Adapters.OneBot

OneBot protocol adapter for Flandre project.

Flandre.Core.Reactive

Reactive Extensions (Rx.NET) support for Flandre.Core.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0-rc.4 79 6/15/2023
1.0.0-rc.3 73 6/4/2023
1.0.0-rc.2 87 4/19/2023
1.0.0-rc.1 110 3/12/2023
1.0.0-alpha.4 85 3/4/2023
1.0.0-alpha.3 80 3/2/2023
1.0.0-alpha.2 87 2/26/2023
1.0.0-alpha.1 82 2/24/2023
0.8.0 447 1/9/2023
0.7.0 936 11/29/2022
0.6.0 314 11/27/2022
0.5.0 689 11/5/2022
0.4.0 360 10/15/2022
0.3.0 504 10/7/2022
0.2.0-alpha 165 9/23/2022
0.1.0-alpha 186 9/21/2022