更新日志¶

v3.1.3¶

⏩变更¶

[core] 内部分发过程，现在提供更清晰的调试日志 (f3178fc, 50d7449)
[core] 插件管理器初始化时的 PluginInfo 对象，现在不再需要 version 参数。插件版本由 PluginPlanner 初始化的第一参数唯一确定 (03ad408)

✨新增¶

[core] 新增上下文动态变量，可以在合适的场景中 import 它们来使用，免去调用 get_xxx() 方法的麻烦 (89e4e1f)。但注意 import 时，上下文中必须已经存在对应类型的对象。新增的变量有：bot, f_records, f_store, event, session, s_store, rule, logger
[core] 插件初始化现在可以把插件版本、插件作者等元信息，自动生成到 __init__.py 中。此外插件目录模块现在拥有 __plugin_info__ 属性，可返回插件管理器中的 PluginInfo 对象 (03ad408)

👍修复¶

[core] 改进了调试日志中，事件循环策略对象打印的方式。现在更加直观清晰 (e78dbcc)
[core] 加载插件时，如果插件目录不存在，现在显示合理的错误提示信息 (adc43b0)
[core] 修复了会话的“自动完成”功能，现在已按预期工作 (0e23432)
[core] 修复了 singleton() 函数在装饰类时，类型注解丢失的问题 (245b14a)
[OneBot] 修复了 GetForwardMsgEcho 的类型注解 (dbf0de4)

v3.1.2¶

⏩变更¶

[core] 移除所有原本预计在 3.1.1 版本移除的组件 (4b14ed5)
[core] 内置日志器现在启用 two_steam，warning 级别的日志也将被分流到 xxxxx.err.log 中 (8a2f1d7)
[core] 更新了插件共享对象获取的逻辑，无需更新任何代码。但新的插件初始化过程生成的 __init__.py 将采用新的运行逻辑 (a207f27)
[OneBot] 现在 HttpIO 的初始化参数 onebot_host 和 onebot_port 已移除，改为使用 onebot_url。这有利于更自由的提供 http 服务的 url (5a2cbb6)

👍修复¶

[OneBot] 修复创建自定义消息段类型的方法 add_type() 的类型注解问题，并更新了相关文档 (e2175d1)。无需更新任何代码。文档被更新处：自定义消息段的构造
[Docs] 文档笔误修复 (23076b8, b37874e)

⚙️内部¶

[core] 开发项目时不再使用 pylint 监测代码质量 (1b49dfb)

v3.1.1¶

⏩变更¶

[OneBot] 所有消息段内的 str 类型参数，现在不再进行除类型判断以外的校验。现在你必须自行验证这些字符串是否非空，以及是否符合特定格式（例如 url 格式）(f6b5a56)

👍修复¶

[core] 异常日志过于冗杂，且输出过多敏感信息 (0154d2e)
[OneBot] 部分消息段的初始化失败问题、to_dict() 或 to_json() 转换失败问题 (#36 -> f6b5a56)

v3.1.0¶

⏩变更¶

[core] 改进了内部事件分发机制，现在所有情况下的事件处理都不再阻塞分发。原始的处理流优先级枚举 HandleLevel 已移除，现在通过 int 值定义优先级，默认处理流优先级为 0 (e2aaa72)
[core] async_later() 和 async_at() 现在返回 Task 而不是 Future (3b7bea2)
[core] 现在插件的 PluginLifeSpan.INITED 生命周期钩子结束前，该插件所有处理流不会生效。避免通过此钩子运行异步初始化，初始化未完成处理流就先启动的不合理现象。如果需要避免额外的等待，请在钩子函数内使用 create_task() (ca06a05)
[All] 绝大多数只支持 AsyncCallable 参数的接口，现在变更为支持 SyncOrAsyncCallable，参数可接受同步或异步的可调用对象 (b6c7f24)
[All] 为避免依赖注入出现问题，现在不能在 on_xxx 函数下方使用装饰器 (9ba2265)，必须通过 decos 参数：

# 现在不能再使用以下形式：
@on_xxx(...)
@aaa(...)
@bbb(...)
async def _(): ...

# 需要换为：
@on_xxx(..., decos=[aaa(...), bbb(...)])
async def _(): ...

[OneBot] 移除了有严重问题而无法修复的 msg_session 函数 (1a372de)，推荐使用 DefaultRule 或 legacy_session 参数或 rule 参数替代：

# 原始用法
with msg_session(): ...

# 现在的替代方法：

_RULE = DefaultRule()
# 注意不要直接在 enter_session 中初始化
# 这样会导致每次生成一个新的 rule
with enter_session(_RULE): ...

# 或者

# 对于 on_xxx 接口，如有 legacy_session 参数，
# 置为 True 实现类似 msg_session 效果
@on_xxx(..., legacy_session=True)
async def _():
    # 注意进入会话在所有 decos 装饰器之前
    # 如果这个顺序不符合你的需求，还是建议在 decos 中使用 unfold_ctx(enter_session(...))
    ...

# 或者

class MyRule(Rule): ...
# 对于 on_xxx 接口，如有 rule 参数
# 可以直接在这里初始化规则，并提供
@on_xxx(..., rule=MyRule())
async def _():
    # 注意进入会话在所有 decos 装饰器之前
    ...

[OneBot] 部分 api 已并入 melobot core。尝试按原样导入并使用这些 api 依然可以工作，但会发出弃用警告。兼容原样导入的行为将在 3.1.1 移除 (841eddd)，请及时迁移。我们强烈建议您重新阅读一遍相关使用方法来了解新 api 的使用技巧。以下是变动的 api：

# 原始位置 (onebot 模块是 melobot.protocols.onebot) -> 新位置
onebot.v11.utils.Checker           ->  melobot.utils.check.Checker

onebot.v11.utils.Matcher           ->  melobot.utils.match.Matcher
onebot.v11.utils.StartMatcher      ->  melobot.utils.match.StartMatcher
onebot.v11.utils.ContainMatcher    ->  melobot.utils.match.ContainMatcher
onebot.v11.utils.EndMatcher        ->  melobot.utils.match.EndMatcher
onebot.v11.utils.FullMatcher       ->  melobot.utils.match.FullMatcher
onebot.v11.utils.RegexMatcher      ->  melobot.utils.match.RegexMatcher

onebot.v11.utils.Parser            ->  melobot.utils.parse.Parser
onebot.v11.utils.ParseArgs         ->  melobot.utils.parse.CmdArgs
onebot.v11.utils.CmdParser         ->  melobot.utils.parse.CmdParser
onebot.v11.utils.CmdParserFactory  ->  melobot.utils.parse.CmdParserFactory
onebot.v11.utils.CmdArgFormatter   ->  melobot.utils.parse.CmdArgFormatter
onebot.v11.utils.FormatInfo        ->  melobot.utils.parse.CmdArgFormatInfo

onebot.v11.handle.on_start_match   ->  melobot.handle.on_start_match
onebot.v11.handle.on_contain_match ->  melobot.handle.on_contain_match
onebot.v11.handle.on_end_match     ->  melobot.handle.on_end_match
onebot.v11.handle.on_full_match    ->  melobot.handle.on_full_match
onebot.v11.handle.on_regex_match   ->  melobot.handle.on_regex_match
onebot.v11.handle.on_command       ->  melobot.handle.on_command

# 特别注意，此 api 原本用作默认值，表示需要一个解析参数。但现在只需要注解类型即可
# 但此 api 依然可以使用，但下一版本直接删除，在整个项目中将完全不存在
onebot.v11.handle.GetParseArgs     ->  melobot.handle.GetParseArgs

[OneBot] 除以上变更的 api 外，其余 onebot 协议支持部分的公开接口可以从 melobot.protocols.onebot.v11 直接导入 (e2aaa72)

✨ 新增¶

[core] Rule 现在支持两种抽象方法 compare() 与 compare_with() （提供更有用的对比信息），二选一实现即可 (ef173c6)
[core] SessionStore 现在可以使用 set 方法设置值，方便链式调用 (36b555e)

# 等价于 store[key] = value
store.set(key, value)

[core] 现在会话可以被直接依赖注入，或在当前上下文通过 get_session() 获取 (e2aaa72)。例如：

from melobot.session import Session, get_session

@on_xxx(...)
async def _(session: Session, ...): ...

# 或者

@on_xxx(...)
async def _(...):
    # 获取当前上下文中的会话对象
    session = get_session()

[core] 新增接口兼容装饰器函数 to_sync()，非常不常用。极少数需要兼容同步接口时使用 (ca06a05)
[core] if_not() 现在支持新参数 accept，作为条件为真时执行的回调 (d89d62e)
[core] 新增了跨协议的 on_xxx 方法：on_event()（用于绑定任意协议的任意事件处理方法）和 on_text()（用于绑定任意文本事件处理方法）(841eddd)
[core] 现在 CmdParser 支持初始化参数 tag (a7a183e, 9fdde3b)，该值会传递给解析参数，用于标识：

parser = CmdParser(cmd_start=".", cmd_sep=" ", targets=["echo", "回显"], tag="bar")
args = await parser.parse(".回显 hi")
if args is not None:
    assert args.name == "回显"
    assert args.tag == "bar"

# 不指定 tag 时，自动设置为 targets 第一元素，或 targets 本身（如果为字符串）
parser = CmdParser(cmd_start=".", cmd_sep=" ", targets=["echo", "回显"])
args = await parser.parse(".回显 你好呀")
if args is not None:
    assert args.name == "回显"
    assert args.tag == "echo"

[core] 新增了用于合并检查器序列的函数 checker_join()。相比于使用 | & ^ ~ 运算符，此函数可以接受检查器序列，并返回一个合并检查器。检查器序列可以为检查器对象，检查函数或空值 (841eddd)
[core] 现在支持动态增加、删除处理流，以及变更处理流的优先级 (e2aaa72)。例如：

# 在 BotLifeSpan.STARTED 生命周期之后，可以动态的增加处理流：
bot.add_flows(...)

# 在任何时候拿到处理流对象后，可以移除该处理流
# 如果在某处理流内部移除此处理流，依然不影响本次处理过程
flow.dismiss()

# 在任何时候拿到处理流对象后，可以更新优先级
# 如果在某处理流内部更新此处理流优先级，依然不影响本次处理过程
flow.update_priority(priority=3)

[core] 新增了一些 mixin 类，主要提供给协议支持的开发者，参考文档中的 melobot.mixin 部分。插件与 bot 开发者无需关心 (e2aaa72, 6f8253e)
[All] 多数 on_xxx 接口提供了新参数 rule，用于在内部自动展开会话 (52a1e7b)。先前已有示例，此处不再演示。
[OneBot] 新增 get_group_role() 和 get_level_role() 用于获取权限等级 (65d447e)
[OneBot] 新增 OneBotV11Protocol 协议栈对象，启动代码现在更为简洁 (6f8253e)，例如：

from melobot import Bot
from melobot.protocols.onebot.v11 import ForwardWebSocketIO, OneBotV11Protocol

bot = Bot()
# 无需再手动添加适配器
bot.add_protocol(OneBotV11Protocol(ForwardWebSocketIO(...)))
bot.load_plugin(...)
...
bot.run()

👍修复¶

[core] 通过依赖注入获取适配器时，返回值可能为空的错误 (1c7d170)
[core] 更改部分内置数据结构为集合，避免重复添加元素导致未定义行为 (7ec9709)
[All] 小幅度提升异步任务创建的性能，修复一些异步任务序列为空可能导致的错误，以及更好的异常提示 (33c1c68)
[OneBot] 优化了 event, action 和 echo 对象的 repr 显示。在调试时或错误日志中，repr 不再显示为超长字符串 (33c1c68)
[OneBot] 现在使用更安全的校验。意外传递反射依赖项到 checker 不再会导致校验默认通过 (dcf782f)
[OneBot] 小幅度提升了 event 与 echo 验证错误时的回调的执行性能 (4af5422)

v3.0.0¶

⚠️特别：¶

melobot v3 是跨平台、跨协议、支持多路 IO 及其他高级特性的 bot 开发框架，与 v2 完全不兼容。
v3 文档教程：melobot docs

特色	描述
实用接口	封装高频使用的异步逻辑，使业务开发更简洁
插件管理	低耦合度、无序的插件加载与通信
处理流设计	可自由组合“处理中间件”为处理流，提升了各组件的复用率
热插拔/重启	处理流支持动态热插拔，支持 bot 级别的重启
会话支持	可在处理流中自动传递的、可自定义的会话上下文
协议支持	所有协议被描述为 IO 过程，因此支持各类协议
跨平台	更简洁的跨平台接口，便捷实现跨平台插件开发
跨协议 IO	支持多个协议实现端同时输入，自由输出到指定协议实现端
日志支持	日志记录兼容标准库和绝大多数日志框架，可自行选择

对比上一预发布版本 3.0.0rc21，主要有：

⏩变更¶

[core] 移除计划移除的 api 和组件（移除了方法 Args, Context.in_ctx 与传统插件类 Plugin）(ec518f5)
[core] 改进了 io 层的 packet 限制，现在所有 packet 不再是 frozen 的 (88eeb85)
[core] 改进了 adapter 层的组件，现在钩子 BEFORE_EVENT 重命名为 BEFORE_EVENT_CREATE，钩子 BEFORE_ACTION 重命名为 BEFORE_ACTION_EXEC (d50d3a3)

✨ 新增¶

[core] 内置日志器添加 yellow_warn 参数，可在智能着色模式下强制警告消息为醒目的黄色 (0dae81d)
[core] 现在使用 PluginPlanner 声明插件及各种插件功能 (4508081)
[core] PluginPlanner 现在支持使用 use() 装饰器来收集各种插件组件（处理流、共享对象与导出函数）(ecec685)
[OneBot] 添加了用于处理 OneBot v11 实体（事件、动作与回应）数据模型验证异常的 OneBot v11 适配器接口 when_validate_error() (4bddb6a, 0589f3a, a4d35b3)

👍修复¶

[OneBot] 自定义消息段类型创建和解析 (3026543, 51f7cbe, f006ee0, 819489f)
[OneBot] 正向 websocket IO 源忽略 bot 停止信号 (da0e3df)
[All] 项目各处类型注解的改进 (1bd8760)
[All] 文档与内置异常提示更正

♥️新贡献者¶

@Asankilp 首次提交 #14
@NingmengLemon 首次提交 #15