更新日志

约 3908 字大约 13 分钟

所有版本变更记录，按照版本分组，基于 git 提交记录整理。

[v1.0.4] - 2026-04-22

✨ 新增功能

消息模型（`easybot/models.py`）

消息快捷访问属性：为 GuildMessage、GroupMessage、C2CMessage、DirectMessage 新增 session 和 bot 属性，可直接通过消息对象访问会话管理器和 Bot 实例
消息引用结构：新增 MessageScene、MessageElement、MessageReference 数据结构，支持消息引用场景
消息引用字段：为各类消息类型添加 author、message_reference、seq、seq_in_thread 等引用相关字段

会话管理（`easybot/session.py`）

wait_for 自动更新 msg_id：在 wait_for 方法中自动更新绑定对象的 msg_id，解决多轮对话中被动回复限制问题
清理逻辑优化：提取公共清理方法 _cleanup_expired_sessions()，减少重复代码

🔧 改进优化

HTTP 客户端（`easybot/_internal/http_client.py`）

禁用代理自动检测：设置 trust_env=False，避免系统代理环境干扰 API 请求

消息去重（`easybot/_internal/event_dispatcher.py`）

键生成优化：优化消息去重的键生成方式，提升去重准确性

🐛 问题修复

会话管理（`easybot/session.py`）

超时回复逻辑嵌套问题：修复超时回复逻辑中的嵌套问题，确保超时处理正确执行

数据模型（`easybot/models.py`）

from_dict 方法健壮性：允许 from_dict 方法接收 None 参数并返回 None，提升容错能力

📝 文档更新

更新 SDK 组件文档，补充消息快捷访问属性说明
更新 API 参考文档，完善方法签名和参数说明
更新会话管理器文档，补充 wait_for 高级用法
更新 Model 库文档，补充新增的消息引用结构

[v1.0.3] - 2026-04-09

🔒 安全修复

HTTP 客户端（`easybot/_internal/http_client.py`）

Webhook 签名验证绕过：修复 _verify_signature() 方法中当请求缺少 X-Signature-Ed25519 或 X-Signature-Timestamp 头时错误返回 True 的问题，改为返回 False 并记录警告日志，防止攻击者通过省略签名头绕过验证
远程 Webhook 签名时序攻击：将 verify_remote_signature() 中的签名字符串比较从 == 替换为 hmac.compare_digest() 恒定时间比较，防止攻击者通过测量响应时间逐字节推断正确签名

Bot 核心模块（`easybot/bot.py`）

事件循环断裂修复：重构 start() / start_async() 的资源清理逻辑
- 将 stop_async() 调用从 start() 的 finally 块移至 start_async() 内部的 try/finally 中
- 修复原实现中 asyncio.run(self.stop_async()) 创建新事件循环导致无法正确清理原始循环上绑定的资源（WebSocket 连接、HTTP Session、asyncio.Task 等）的问题
- 消除资源泄漏、异常吞没和 Windows 端口占用风险

📝 文档改进

文档首页优化：优化首页核心功能展示，改进表格和列表格式

✨ 新增文档

新增独立文档：docs/11_更新日志.md - 独立的更新日志文档页面

📝 开发规范新增

开发规范文档：.trae/rules/ 目录下新增完整的开发规范体系
- architecture-design.md - 架构设计原则
- async-patterns.md - 异步编程规范
- coding-style.md - 代码格式与风格规范
- logging-standards.md - 日志系统使用规范
- python-conventions.md - Python 语言约定
新增技能文档：.trae/skills/easybot-assistant/SKILL.md - EasyBot 开发助手技能定义
技能示例资源：.trae/skills/easybot-assistant/assets/examples/ - 新增多个示例项目文档
技能参考文档：.trae/skills/easybot-assistant/references/ - 新增多个参考文档
- api-reference.md - API 参考
- best-practices.md - 最佳实践指南
- message-builders.md - 消息构建器使用说明
- plugin-system.md - 插件系统开发文档
- session-management.md - 会话管理完整指南
- troubleshooting.md - 故障排查手册

🎉 新增示例

新增示例文件：
- examples/14_send_api_matrix.py - API 矩阵发送示例
- examples/15_large_file_upload.py - 大文件上传机器人示例

🔧 核心改进

事件分发器（`easybot/_internal/event_dispatcher.py`）

并发控制机制：新增基于 asyncio.Semaphore 的并发控制，默认最大并发数为 64，防止消息洪峰时突发创建过多协程导致事件循环过载
任务追踪管理：新增 _active_tasks 集合追踪所有由分发器创建的异步任务，配合 cancel_all() 方法支持优雅关闭时统一取消所有任务，防止孤儿任务泄露
命令匹配逻辑重构：优化 treat_msg 处理逻辑，将命令匹配后的内容截取逻辑统一后置到最佳命令确定后执行，避免重复修改模型状态
类型注解完善：将多处 Any 类型替换为具体的 BaseModel 和 BotCommandObject 类型，提升代码类型安全性
处理器执行保护：_safe_call_handler 和 _execute_command_async 方法均通过 Semaphore 控制并发，确保在高并发场景下的稳定性

消息去重器（`easybot/_internal/dedup.py`）

LRU 时间戳同步：修复 is_new() 和 is_duplicate() 方法，当消息已存在于缓存时，刷新其时间戳并移至 LRU 末尾，避免因 LRU 顺序与时间戳不一致导致过期清理遗漏
文档注释完善：为 _cleanup_expired() 方法添加详细注释，说明其利用 OrderedDict 按"最后访问时间"升序排列的特性，从头部开始收集过期条目，遇到第一个未过期元素即停止的清理策略

HTTP 客户端（`easybot/_internal/http_client.py`）

连接器引用计数：新增 _has_connector_ref 标志位，确保只有在当前客户端创建了连接器引用时才执行释放操作，避免重复释放共享连接器
Webhook 异常捕获：为 Webhook 事件分发任务添加完成回调 _on_dispatch_task_done，捕获并记录分发任务中未处理的异常，提升错误诊断能力
文档注释修正：移除 generate_remote_signature 函数中关于与 qg_botsdk 兼容性的过时注释

回复策略（`easybot/_internal/reply_strategy.py`）

参数扩展：reply() 方法新增 image、file_image、media_file_info、msg_type、is_wakeup 等参数，支持更丰富的消息发送场景
策略逻辑优化：明确优先使用 msg_id 进行被动回复，仅当事件没有 msg_id 时才回退到 event_id，确保回复的准确性
类型注解改进：使用 Python 3.10+ 的联合类型语法（|）替代 Union，简化类型注解表达

生命周期管理（`easybot/_internal/lifecycle.py`）

类型注解精确化：将 logger 参数类型从 Any 精确指定为 Logger 类型，将事件参数类型从 Any 精确指定为 StartupEvent | ShutdownEvent | TimerEvent 联合类型

常量模块（`easybot/_internal/constants.py`）

返回类型修正：convert_to_model() 函数的返回类型从 Any 修正为 BaseModel | None，提高类型安全性

WebSocket 基类（`easybot/_internal/ws_base.py`）

类型注解精确化：将 logger 参数类型从 Any 精确指定为 Logger 类型

API 模块（`easybot/api.py`）

大文件分片上传实现：新增 upload_large_file() 方法，实现完整的分片上传流程
- 自动计算文件 MD5、SHA1 和前 10MB MD5
- 调用 upload_prepare() 申请上传任务，获取分片信息
- 使用信号量控制并发数上传所有分片
- 调用 upload_complete() 完成上传，返回文件 UUID
- 详细的分片级日志记录，便于调试
新增上传相关模型：在 Model 类中添加 UploadPart 和 UploadPrepareResponse 类型别名

Bot 核心模块（`easybot/bot.py`）

Intent 注册优化：重构 _update_intents_for_scenes() 方法
- 移除了通过注册 dummy handler 来更新 Intent 的方式
- 改为直接操作 _intents 位掩码和 _intent_calculator
- 避免产生误导性日志和 handler 覆盖问题
- 支持预处理器（before_command）的 Intent 更新

插件系统（`easybot/plugins.py`）

命令斜杠归一化：BotCommandObject 初始化时自动去除命令开头的斜杠 /
- 用户无论注册 /hi 还是 hi 都能正常工作
- 统一内部处理逻辑，简化命令匹配
热重载增强：
- reload_plugin() 方法文档说明扩展，支持同时重载 @Plugins.on_command 和 @Plugins.before_command 注册的内容
- unload_plugin() 方法改用对象 id 匹配而非函数名，避免不同插件中同名函数的冲突
- 新增 _module_command_objs 和 _module_preprocessor_objs 字典追踪模块内的命令和预处理器对象
类型定义完善：
- 新增 PluginStats TypedDict 定义卸载/统计结果结构
- 新增 PluginReloadResult TypedDict 定义重载结果结构
- clear_all_plugins() 返回类型从 dict[str, int] 改为 PluginStats
before_command 增强：before_command 装饰器支持显式传入 _module_name 参数，由 Bot.before_command 传入以支持主程序中注册预处理器

会话管理（`easybot/session.py`）

wait_for 增强：
- command 参数支持直接传入 BotCommandObject，可使用全部参数（at、admin、treat、is_require_bot_admin 等）
- 保持对快捷方式的兼容（str、list、Pattern），内部自动包装为 BotCommandObject
- 新增完整的使用示例，包括高级用法演示
优雅关闭机制：
- 新增 stop() 方法，支持停止会话管理器的后台任务
- 停止前自动持久化会话数据，确保数据不丢失
- 改用 asyncio.Event + wait_for(event.wait(), timeout) 模式替代 sleep()，支持即时响应退出信号
- 新增 __stop_event、__manager_task、__fetch_task 等内部状态追踪
超时回复异常处理：为超时回复的异步任务添加完成回调 _on_timeout_reply_done，捕获并记录异步执行中的异常
类型注解完善：
- 将 Optional[...] 替换为 ... | None 语法
- BoundSession 的 obj 参数类型从 Any 精确指定为 Model.Message
- register_wait_for / check_wait_for / del_wait_for 等方法的参数类型精确化

数据模型（`easybot/models.py`）

Model 类类型别名整理：精简 Model 类的类型别名定义
- 移除中间层类型别名（如 ThreadInfo、RichText、MessageEmbed 等），用户直接使用具体类型
- 新增 Message 作为 GuildMessage | GroupMessage | C2CMessage | DirectMessage 的联合类型别名
- 保持核心类型别名（如 Guild、Channel、Role 等）
新增上传相关模型：
- UploadPart：分片信息对象，包含 index 和 presigned_url
- UploadPrepareResponse：分片上传申请响应，包含 upload_id、block_size、parts、concurrency、retry_timeout
AuditResult 新增常量：添加 TYPE_PUBLISH_THREAD、TYPE_PUBLISH_POST、TYPE_PUBLISH_REPLY 常量
类型注解现代化：将 Optional[...] 替换为 ... | None 语法

消息构建器（`easybot/builders.py`）

Message 构建类简化：
- 移除 message_reference_id、ignore_message_reference_error、is_wakeup 参数
- 这些参数现在由 reply() / send_xxx_message() 方法直接接收
- 简化为"仅负责构建普通消息体，不承载任何接口级参数"
Markdown 构建器文档完善：补充 build() 方法的 Notes 说明，明确 content/template_id/key_values 等参数的约束关系
TextChainBuilder 按钮注释修正：show 参数的说明从"默认取 text 值"改为"为 None 时不输出 show 属性"

🐛 内部修复

WebSocket 客户端（`easybot/_internal/ws_client.py`）

SessionLimiter 锁内 sleep 串行化修复：将 acquire() 方法中的 asyncio.sleep() 从锁内移至锁外
- 原实现持有 _lock 期间调用 sleep()，阻塞所有其他 Session 的 acquire() 调用，多分片连接时完全串行化
- 新实现在锁内计算等待时间并预约时间戳（_last_acquire_time = now + wait_time），释放锁后再 sleep，多个分片可并行等待
限制器状态实例化：将 _LimiterState 从类变量改为按 Bot 实例独立存储，避免多 Bot 实例共享同一组 asyncio 原语导致互相干扰

HTTP 客户端（`easybot/_internal/http_client.py`）

WebhookServer.stop() 移除 aiohttp 私有 API 依赖：删除对 self._site._stop_serving 私有属性的检查，直接调用 self._site.stop() 并用 try/except 兜底，避免依赖可能随时变更的内部 API
WebhookServer.run() 即时停止响应：将主循环从 await asyncio.sleep(1) 轮询改为 await self._stop_event.wait()，停止信号响应延迟从最多 1 秒降低为近乎即时
连接器状态实例化：新增 _ConnectorState 类，将共享连接器的 asyncio 原语（Lock、connector、ref_count、loop_id）从类变量改为按 Bot 实例独立存储

日志模块（`easybot/logger.py`）

LoggerManager handler 日期键修复：文件 handler 的缓存键从日期文件名（如 logs/bot1/2026-04-10.log）改为稳定的 bot_id:log_dir 组合
- 原实现程序跨天运行时，TimedRotatingFileHandler 自动轮转到新文件但旧 key 仍指向旧日期，导致创建重复 handler 写入不同文件
- 新实现同一 bot_id+log_dir 共享一个 handler 实例，由 TimedRotatingFileHandler 自身处理日期轮转

会话管理（`easybot/session.py`）

SessionManager 并发安全加固：新增 _sessions_lock（asyncio.Lock）保护 _sessions 字典的所有访问
- 所有会话操作（_new/_get/_update/remove）均受锁保护
- GC 和超时检查的迭代过程受锁保护，消除 RuntimeError: dictionary changed size during iteration 风险
- commit_data() 在锁内同步完成 pickle.dumps() 快照，确保序列化数据一致性，再在锁外执行异步 I/O 写入
- fetch_data() 替换 _sessions 时受锁保护
- 移除 _gc_sessions 和 _check_session_timeouts 中的 yield sleep(0) 让出点（锁保护已替代其必要性）

[v1.0.2] - 2026-04-07

🐛 修复改进

事件分发器优化：进一步完善命令匹配和执行逻辑，提升事件处理的健壮性 (10f71f0)
代码质量提升：使用 Black 和 isort 自动格式化代码 (30b8c8e, 4c30a25, e6a7f9b)
插件系统增强：完善插件热重载功能，优化命令查找逻辑 (a817772, fb93117)

[v1.0.1] - 2026-04-07

✨ 新增功能

消息构建器重构：将 messages_model.py 重构为 builders.py
- 新增 ThreadContentBuilder 和 ParagraphBuilder 用于构建 JSON 格式帖子内容 (c3f4b27)
- 支持 ThreadContent（帖子内容）和 Paragraph（段落）的链式构建
- 新增 Elem 等富文本元素模型定义
- API.create_thread() 方法支持 JSON 格式帖子发送
- Model 类新增 to_dict() 方法用于序列化
EasyBot 开发助手 Skill：添加完整的开发辅助技能模块 (818b009)
- API 参考文档（API Reference）
- 最佳实践指南（Best Practices）
- 消息构建器使用说明
- 会话管理完整指南
- 插件系统开发文档
- 故障排查手册
- 多个示例项目：客服机器人、猜数字游戏、待办事项机器人
项目开发规范体系：建立完整的开发规范文档体系 (c8556ff, 5891ebe)
- 架构设计原则（SOLID、设计模式、公共 API 设计）
- 代码格式与风格规范（Black/isort 配置、命名规范）
- Python 语言约定（Dataclass、异常体系、类型系统）
- 异步编程规范（asyncio 使用、资源管理、并发控制）
- 日志系统使用规范（级别选择、格式要求）
- 测试编写规范（TDD 流程、pytest 使用）
文档站点：搭建 VuePress 文档站点 (ae6ef42)
- 添加 GitHub Actions CI 自动部署工作流
- 配置站点主题、导航和资源文件
插件热重载功能：大幅增强插件系统的运行时管理能力 (fb93117)
- Bot 类新增 reload_plugin()、reload_all_plugins()、unload_plugin() 等热重载 API
- Bot 类新增 enable_command()、disable_command()、remove_command() 命令动态管理接口
- Plugins 类扩展，支持命令启用/禁用、插件卸载/重载、完整查询接口
- 新增 clear_all_plugins() 一键清空所有已加载插件
- 事件分发器优化，支持更灵活的事件处理和调度
- 新增 examples/13_hot_reload.py 完整示例

🔧 改进优化

消息类型处理优化：将 MessageBase 抽象基类替换为具体消息类型的联合类型（Union），提升类型安全性和代码可读性 (b105125)
会话管理优化：优化会话管理逻辑，支持多作用域匹配，改进 wait_for 方法 (b105125)
SDK 启动链路优化：分析并重构 Bot 类启动流程，优化 WebSocket 客户端连接管理 (427cde3, fafe3e5, df41de5, 3c145ca, 36b0cc9, 1bfa041, 779f310, 6022156, c5fb13a, 72a33f1, 930d332, bfdce3f)
频道类型常量更新：更新 Channel 模型中的频道类型常量值，确保与最新接口保持一致 (5891ebe)
代码格式统一：使用 Black 和 isort 对全项目代码进行自动格式化 (e6a7f9b)