flandrebot / flandre Goto Github PK

Describe the problem related to the feature request

允许指令重载可以提高指令定义的灵活度

Describe the solution you'd like

同一个指令，接受数种不同的参数列表，并自动判断使用不同的处理函数。
定义时通过指定同一条指令实现：

[Command("cmd")]
public MessageContent OnOverload1(CommandContext ctx, bool arg1) { /* ... */ }

// 重载指令
[Command("cmd")]
public MessageContent OnOverload2(CommandContext ctx, int arg1, int arg2) { /* ... */ }

如果没有符合提供参数的重载，将产生一条错误提供给用户。

Describe alternatives you've considered

No response

Additional context

No response

可以加入新类型 Middleware，支持在消息执行前/指令执行前截断执行。这样就可以方便地做出条件判断，例如用户被 ban 时不响应消息/指令。

相比直接使用事件，中间件提供了截断处理的能力，但相比直接重写方法更加麻烦（需要实现一个类）

现在仅仅只能解析 face, record, image 三种，转换为 CQ 码也只支持文字，远远不够

Describe the problem related to the feature request

创建一个模板有助于帮助用户快速上手

Describe the solution you'd like

创建一个模板，实现效果

dotnet new flandre

内含一个 Flandre.Framework 应用的基本框架、中间件注册、示例插件。

Describe alternatives you've considered

No response

Additional context

No response

Describe the problem related to the feature request

目前 RegexShortcut 支持仍处于 TODO 阶段，需要尽快完善。

Describe the solution you'd like

支持基于正则表达式的 shortcut

Describe alternatives you've considered

No response

Additional context

No response

注：本 issue 内容为草案，可能随时发生更改。

新系统为大型的非兼容性更改，先前的指令定义方法均需进行修改。

指令定义

当前的指令定义方式：

[Command("cmd <arg1:string> [arg2:int]")]
[Option("opt", "-o <opt:double>")]
[Alias("abc")]
public MessageContent OnCmd(CommandContext ctx, ParsedArgs args)
{
    var arg1 = args.GetArgument<string>("arg1");
    var opt = args.GetOption<double>("opt");
    // ...
}

这种依赖字符串解析的方式没有强类型支持，容易出错，并且不易维护。

计划中的全新指令定义方式，直接转换为方法参数：

[Command("cmd", "abc")]
public MessageContent OnCmd(CommandContext ctx, string arg1, int arg2, [Option('o')] double opt)
{
    // ...
}

Fluent API（待定）

新的 Fluent API 支持，带来流式的指令定义方法：

public override OnLoading(PluginLoadContext ctx)
{
    ctx.AddCommand("aaa", aaa => aaa
        .AddParameter<string>("arg1")
        .AddSubCommand("bbb", bbb => bbb
            .AddOption<bool>("opt"))
        .WithAction<string>((ctx, arg1) => { /* do action... */ }));
}

问题：

• AddParameter 和 AddOption 中名称和方法参数名称冲突如何解决
• 调用指令方法时仍需通过方法的参数定义来为参数赋值，那为什么不直接用 Attribute 写

当前框架内所有异步方法的命名都没有遵循 .NET 异步方法命名规范：

添加“Async”作为编写的每个异步方法名称的后缀。
这是 .NET 中的惯例，以便更为轻松地区分同步和异步方法。 未由代码显式调用的某些方法（如事件处理程序或 Web 控制器方法）并不一定适用。 由于它们未由代码显式调用，因此对其显式命名并不重要。

考虑到在标准库和社区库中绝大部分都遵循了此规范，Flandre 也需做出调整，以带来一致的开发体验。

由于涉及到整个框架方方面面 API 的重命名，会造成大规模的不向下兼容。但考虑到当前使用用户不多，可能是一个好的机会来修正这个问题。

目前已经有定义相关的事件，将其注册即可

Describe the problem related to the feature request

指令解析可以分为多个严格程度。例如：

• 严格 - 不允许多余的参数、选项
• 警告 - 允许多余的参数和选项，但是发出警告
• 宽松 - 允许多余的参数和选项，且不发出警告

Describe the solution you'd like

在指令解析中根据严格程度控制错误去向

Describe alternatives you've considered

No response

Additional context

No response

添加两种修饰指令的方法：

• Shortcut: 快捷调用指令，可以自定义参数。例如：

[Command("test")]
[Option("tst", "-t <:bool>")]
[Shortcut("测试", "test -t")]

此时输入测试 等同于输入 test -t

• Alias: 添加指令别名。例如

[Command("test")]
[Alias("teest")]

此时 teest 和 test 视作同一条指令。

Describe the problem related to the feature request

框架需要提供自动生成帮助信息的功能。

Describe the solution you'd like

构造 FlandreApp 实例时，自动根据已有插件生成帮助信息
通过 help 指令获取

例如：
help aaa
help aaa.bbb（应等同于 help aaa bbb）

输出的帮助信息应该包含：参数名称、类型，选项名称、短名称、类型，以及各种 Description

默认生成 help 指令的行为可以被取消，需要在 FlandreAppOptions 中添加配置项

Describe alternatives you've considered

No response

Additional context

No response

Describe which part of the docs is problematic

整个文档

Describe the problem related to this part of the docs

• 没有一个完善的用户引导
• 大部分框架内容都没有进行解释
• 缺少 API 文档（也许可以通过 XML 文档解决）

Additional context

No response

例如这样注册

[Command("example")]
[Option("alpha", "-a")]
[Option("beta", "-b")]

支持调用 example -ab 等效于调用 example -a -b

目前能接收的事件比较有限，只有以下 7 种：

• AppReadyEvent
• AppStartingEvent
• AppStoppedEvent
• BotFriendRequestedEvent
• BotGuildInvitedEvent
• BotGuildRequestedEvent
• BotMessageReceivedEvent

计划添加以下事件：

• BotGuildJoinedEvent - Bot 加入群组
• BotGuildLeftEvent - Bot 退出群组
• BotGuildMemberJoinedEvent - 群组成员增加
• BotGuildMemberLeftEvent - 群组成员减少
• CommandParsingEvent - 指令解析前
• CommandParsedEvent - 指令解析后
• CommandInvokingEvent - 指令调用前
• CommandInvokedEvent - 指令调用后
• LoggerLoggingEvent - 日志记录前

可以在对应的事件中添加相关方法（如 CancelInvocation）来阻断事件，这样就可以替代 #13 中的中间件概念。

已经使用 IsCancelled 属性替代，设置为 true 即可取消事件。

目前指令只支持两级拼接，一是 Plugin.BaseCommand，二是定义 Command 时的根指令。

可以扩展 Command 定义方法，支持定义用 . 分隔的多级指令。

例如：

[Command("alpha.beta.gamma")]

[Command("apple.banana")]

结果层级：

• alpha
  • beta
    • gamma
• apple
  • banana

当前同时只能使用一个指令前缀，定义在 FlandreAppConfig.CommandPrefix 里

添加一个 CommandPrefixes 配置项，接受一个 IEnumerable<string>?，不为 null 时优先级大于 CommandPrefix。

为插件添加生命周期函数（Start() / Stop()），这样就可以支持初始化和热重载

同时添加事件：

• PluginStartingEvent
• PluginStoppedEvent

https://flandredevs.github.io/start/create-first-bot.html
demo报错啦

Describe the problem related to the feature request

定义指令时如果不需要 CommandContext 可以不用写，简化定义过程

Describe the solution you'd like

当前行为：跳过第一个参数再逐个赋值
目标行为：逐个检查每个参数，如果类型为 CommandContext 则跳过

Describe alternatives you've considered

No response

Additional context

No response