DD斩首
dbe8e33c4b
* feat(telegram): 添加媒体组（相册）支持 / add media group (album) support ## 功能说明 支持 Telegram 的媒体组消息（相册），将多张图片/视频合并为一条消息处理，而不是分散成多条消息。 ## 主要改动 ### 1. 初始化媒体组缓存 (__init__) - 添加 `media_group_cache` 字典存储待处理的媒体组消息 - 使用 2.5 秒超时收集媒体组消息（基于社区最佳实践） - 最大等待时间 10 秒（防止永久等待） ### 2. 消息处理流程 (message_handler) - 检测 `media_group_id` 判断是否为媒体组消息 - 媒体组消息走特殊处理流程，避免分散处理 ### 3. 媒体组消息缓存 (handle_media_group_message) - 缓存收到的媒体组消息 - 使用 APScheduler 实现防抖（debounce）机制 - 每收到新消息时重置超时计时器 - 超时后触发统一处理 ### 4. 媒体组合并处理 (process_media_group) - 从缓存中取出所有媒体项 - 使用第一条消息作为基础（保留文本、回复等信息） - 依次添加所有图片、视频、文档到消息链 - 将合并后的消息发送到处理流程 ## 技术方案论证 Telegram Bot API 在处理媒体组时的设计限制： 1. 将媒体组的每个消息作为独立的 update 发送 2. 每个 update 带有相同的 `media_group_id` 3. **不提供**组的总数、结束标志或一次性完整组的机制 因此，bot 必须自行收集消息，并通过硬编码超时（timeout/delay）等待可能延迟到达的消息。 这是目前唯一可靠的方案，被官方实现、主流框架和开发者社区广泛采用。 ### 官方和社区证据： - **Telegram Bot API 服务器实现（tdlib）**：明确指出缺少结束标志或总数信息 https://github.com/tdlib/telegram-bot-api/issues/643 - **Telegram Bot API 服务器 issue**：讨论媒体组处理的不便性，推荐使用超时机制 https://github.com/tdlib/telegram-bot-api/issues/339 - **Telegraf（Node.js 框架）**：专用媒体组中间件使用 timeout 控制等待时间 https://github.com/DieTime/telegraf-media-group - **StackOverflow 讨论**：无法一次性获取媒体组所有文件，必须手动收集 https://stackoverflow.com/questions/50180048/telegram-api-get-all-uploaded-photos-by-media-group-id - **python-telegram-bot 社区**：确认媒体组消息单独到达，需手动处理 https://github.com/python-telegram-bot/python-telegram-bot/discussions/3143 - **Telegram Bot API 官方文档**：仅定义 `media_group_id` 为可选字段，不提供获取完整组的接口 https://core.telegram.org/bots/api#message ## 实现细节 - 使用 2.5 秒超时收集媒体组消息（基于社区最佳实践） - 最大等待时间 10 秒（防止永久等待） - 采用防抖（debounce）机制：每收到新消息重置计时器 - 利用 APScheduler 实现延迟处理和任务调度 ## 测试验证 - ✅ 发送 5 张图片相册，成功合并为一条消息 - ✅ 保留原始文本说明和回复信息 - ✅ 支持图片、视频、文档混合的媒体组 - ✅ 日志显示 Processing media group <media_group_id> with 5 items ## 代码变更 - 文件：astrbot/core/platform/sources/telegram/tg_adapter.py - 新增代码：124 行 - 新增方法：handle_media_group_message(), process_media_group() Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * refactor(telegram): 优化媒体组处理性能和可靠性 根据代码审查反馈改进： 1. 实现 media_group_max_wait 防止无限延迟 - 跟踪媒体组创建时间，超过最大等待时间立即处理 - 最坏情况下 10 秒内必定处理，防止消息持续到达导致无限延迟 2. 移除手动 job 查找优化性能 - 删除 O(N) 的 get_jobs() 循环扫描 - 依赖 replace_existing=True 自动替换任务 3. 重用 convert_message 减少代码重复 - 统一所有媒体类型转换逻辑 - 未来添加新媒体类型只需修改一处 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix(telegram): handle missing message in media group processing and improve logging messages --------- Co-authored-by: Ubuntu <ubuntu@localhost.localdomain> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com> Co-authored-by: Soulter <905617992@qq.com>