feat(channels): 打通多媒体的端到端收发(文件 / 图片 / 音频 / 视频) #1

Open
opened 2026-11-09 12:42:58 +00:00 by openbot · 0 comments
Owner

背景

渠道层的内容模型与 WeCom 适配器的媒体收发已经实现,缺的是中间环节。现状盘点(均已核对代码):

能力 现状 位置
内容模型(文本/图片/视频/音频/文件) ✅ 已有,含 data/local_path/url 三级字节来源 channels/models.py:22-102
媒体字节解析(三级优先) ✅ 已有 load_media_bytes channels/base.py:613-639
远端下载 ⚠️ 已有,但无鉴权、无大小限制 channels/base.py:603-611
WeCom 入站解析(text/image/file/voice/video/mixed) ✅ 已有 channels/im/wecom.py:188-247
WeCom 出站媒体(上传 → reply_media / send_media_message) ✅ 已有,失败回退文本 channels/im/wecom.py:356-387
出站分发管线(MESSAGE 事件的媒体分片自动下发) ✅ 已就绪 channels/base.py:478-486

但媒体目前走不通——下面是四处断点。

断点

1. 入站媒体到不了智能体(P0,阻断)

flows/processor.py:100-103 和 flows/builtin.py:270-274 都是先取纯文本,取不到就回一句固定文案:

text = message.text.strip()
if not text:
    yield MessageEvent.error_event("(空消息,已忽略)" if not message.has_media else "暂仅支持文本消息")
    return

后果:用户发一张图(或一个文件、一条语音、一段视频),智能体收不到,用户收到"暂仅支持文本消息"。文本+图片混合的消息则只有文本进入模型,图片被静默丢弃。

2. 智能体无法产出媒体(P0,阻断)

出站管线(base.py:478-486)已经能把 MessageEvent 里的媒体分片下发,但没有任何构造入口:

  • MessageEvent.text() / error_event() 等工厂只构造 TextContent(models.py:216-249)
  • MediaContent 类型别名在 models.py:102 定义后,src/ 内零处引用(全仓 grep 只命中定义行)

即:智能体没有"发图片/发文件"的工具,也没有能带媒体的事件构造器。

3. WeCom 加密媒体拿不到明文(P1)

wecom.py:181-186 把每个媒体 URL 的 aeskey 记进 metadata["_media_aes_keys"](wecom.py:262),但没有任何地方用它解密:

  • fetch_remote_media(base.py:603)是普通 GET,不解密
  • _strip_ephemeral_push_meta(wecom.py:425)直接把 _media_aes_keys 丢掉
  • 全仓 grep aes 无任何解密实现

tests/test_channels_wecom.py:104-111 只断言 key 被记录,不验证解密。

⚠️ 未核实:aeskey 的存在是否意味着该 URL 返回密文,我无法从代码确认(需要真实 WeCom 消息样本或官方文档)。若确为密文,当前入站媒体下载会得到无法使用的字节。

4. 无资源护栏(P1)

load_media_bytes 把整个文件/响应读进内存(path.read_bytes() / resp.content),顶部无大小上限。全仓 grep max_size / limit.*bytes 只命中 queue_maxsize(消息条数)。一个 2GB 视频会直接打爆内存。同时无 mime 白名单、无下载超时、落盘路径未做隔离校验。

方案建议

P0|入站贯通

  1. 媒体分片在投递智能体前解析为多模态内容块:图片走 image_url(base64 或 URL),文档按可抽取文本处理,音视频先只传元信息 + 落盘路径。
  2. 解除 processor.py:100 / builtin.py:273 的"仅文本"门禁:文本为空但有媒体时继续走智能体,提示语改为媒体摘要。
  3. 媒体落盘到会话工作目录,智能体拿到路径而非字节,避免大对象进上下文。

P0|出站贯通
4. 新增智能体工具(如 send_file / send_image),产出带媒体分片的 MessageEvent,复用 base.py:478-486 现有下发路径。
5. 补充 MessageEvent 的媒体工厂方法。

P1|安全与正确性
6. 大小上限、mime 白名单、下载超时、落盘路径规范化(防 ../ 穿越),超限时降级为文本提示而不是抛异常。
7. WeCom aeskey 解密:先确认平台是否返回密文,再实现 AES-CBC 解密并接入 fetch_remote_media 覆写。

P2|其余
8. 历史持久化:当前 processor.py:116 把 content=text 存库,媒体不入历史。建议存引用(路径 + 类型 + 摘要),不存字节。
9. CLI 渠道 _send_media(cli.py:135-139)目前只打印占位行;补齐本地路径收发,便于无平台环境下调试。

验收标准

  • 单发一张图片 → 智能体在上下文中看到图片内容,并给出针对图片的回复
  • 文本 + 文件混合 → 两者都进入智能体上下文,无静默丢弃
  • 智能体调用工具发图片/文件 → 平台侧收到原生媒体消息(WeCom 走 media_id,CLI 走本地路径)
  • 超过大小上限的媒体 → 返回明确提示,内存不爆、不抛未捕获异常
  • 恶意文件名(含 ../)→ 落盘路径被限制在会话目录内
  • 上述 1-5 均有对应单测,且 pytest 全绿

非目标

  • 不做跨平台(Slack/飞书等)适配,本轮只打通 WeCom + CLI
  • 不做媒体转码、缩略图生成
  • 不把媒体字节存入 SQLite

风险

  • 改动集中在 processor.py / builtin.py 两条处理链,历史与流式逻辑耦合较紧,需回归 tests/test_processor.py、tests/test_builtin.py、tests/test_stream.py
  • 解除文本门禁会改变空消息语义,EMPTY_REPLY 分支的既有测试断言需要同步调整
## 背景 渠道层的内容模型与 WeCom 适配器的媒体收发**已经实现**,缺的是中间环节。现状盘点(均已核对代码): | 能力 | 现状 | 位置 | |---|---|---| | 内容模型(文本/图片/视频/音频/文件) | ✅ 已有,含 `data`/`local_path`/`url` 三级字节来源 | `channels/models.py:22-102` | | 媒体字节解析(三级优先) | ✅ 已有 `load_media_bytes` | `channels/base.py:613-639` | | 远端下载 | ⚠️ 已有,但无鉴权、无大小限制 | `channels/base.py:603-611` | | WeCom 入站解析(text/image/file/voice/video/mixed) | ✅ 已有 | `channels/im/wecom.py:188-247` | | WeCom 出站媒体(上传 → reply_media / send_media_message) | ✅ 已有,失败回退文本 | `channels/im/wecom.py:356-387` | | 出站分发管线(MESSAGE 事件的媒体分片自动下发) | ✅ 已就绪 | `channels/base.py:478-486` | **但媒体目前走不通**——下面是四处断点。 ## 断点 ### 1. 入站媒体到不了智能体(P0,阻断) `flows/processor.py:100-103` 和 `flows/builtin.py:270-274` 都是先取纯文本,取不到就回一句固定文案: ```python text = message.text.strip() if not text: yield MessageEvent.error_event("(空消息,已忽略)" if not message.has_media else "暂仅支持文本消息") return ``` 后果:用户发一张图(或一个文件、一条语音、一段视频),智能体**收不到**,用户收到"暂仅支持文本消息"。文本+图片混合的消息则只有文本进入模型,图片被静默丢弃。 ### 2. 智能体无法产出媒体(P0,阻断) 出站管线(`base.py:478-486`)已经能把 `MessageEvent` 里的媒体分片下发,但没有任何构造入口: - `MessageEvent.text()` / `error_event()` 等工厂只构造 `TextContent`(`models.py:216-249`) - `MediaContent` 类型别名在 `models.py:102` 定义后,`src/` 内**零处引用**(全仓 grep 只命中定义行) 即:智能体没有"发图片/发文件"的工具,也没有能带媒体的事件构造器。 ### 3. WeCom 加密媒体拿不到明文(P1) `wecom.py:181-186` 把每个媒体 URL 的 `aeskey` 记进 `metadata["_media_aes_keys"]`(`wecom.py:262`),但**没有任何地方用它解密**: - `fetch_remote_media`(`base.py:603`)是普通 GET,不解密 - `_strip_ephemeral_push_meta`(`wecom.py:425`)直接把 `_media_aes_keys` 丢掉 - 全仓 grep `aes` 无任何解密实现 `tests/test_channels_wecom.py:104-111` 只断言 key 被记录,不验证解密。 > ⚠️ 未核实:`aeskey` 的存在是否意味着该 URL 返回密文,我无法从代码确认(需要真实 WeCom 消息样本或官方文档)。若确为密文,当前入站媒体下载会得到无法使用的字节。 ### 4. 无资源护栏(P1) `load_media_bytes` 把整个文件/响应读进内存(`path.read_bytes()` / `resp.content`),顶部无大小上限。全仓 grep `max_size` / `limit.*bytes` 只命中 `queue_maxsize`(消息条数)。一个 2GB 视频会直接打爆内存。同时无 mime 白名单、无下载超时、落盘路径未做隔离校验。 ## 方案建议 **P0|入站贯通** 1. 媒体分片在投递智能体前解析为多模态内容块:图片走 `image_url`(base64 或 URL),文档按可抽取文本处理,音视频先只传元信息 + 落盘路径。 2. 解除 `processor.py:100` / `builtin.py:273` 的"仅文本"门禁:文本为空但有媒体时继续走智能体,提示语改为媒体摘要。 3. 媒体落盘到会话工作目录,智能体拿到路径而非字节,避免大对象进上下文。 **P0|出站贯通** 4. 新增智能体工具(如 `send_file` / `send_image`),产出带媒体分片的 `MessageEvent`,复用 `base.py:478-486` 现有下发路径。 5. 补充 `MessageEvent` 的媒体工厂方法。 **P1|安全与正确性** 6. 大小上限、mime 白名单、下载超时、落盘路径规范化(防 `../` 穿越),超限时降级为文本提示而不是抛异常。 7. WeCom `aeskey` 解密:先确认平台是否返回密文,再实现 AES-CBC 解密并接入 `fetch_remote_media` 覆写。 **P2|其余** 8. 历史持久化:当前 `processor.py:116` 把 `content=text` 存库,媒体不入历史。建议存引用(路径 + 类型 + 摘要),不存字节。 9. CLI 渠道 `_send_media`(`cli.py:135-139`)目前只打印占位行;补齐本地路径收发,便于无平台环境下调试。 ## 验收标准 - [ ] 单发一张图片 → 智能体在上下文中看到图片内容,并给出针对图片的回复 - [ ] 文本 + 文件混合 → 两者都进入智能体上下文,无静默丢弃 - [ ] 智能体调用工具发图片/文件 → 平台侧收到原生媒体消息(WeCom 走 media_id,CLI 走本地路径) - [ ] 超过大小上限的媒体 → 返回明确提示,内存不爆、不抛未捕获异常 - [ ] 恶意文件名(含 `../`)→ 落盘路径被限制在会话目录内 - [ ] 上述 1-5 均有对应单测,且 `pytest` 全绿 ## 非目标 - 不做跨平台(Slack/飞书等)适配,本轮只打通 WeCom + CLI - 不做媒体转码、缩略图生成 - 不把媒体字节存入 SQLite ## 风险 - 改动集中在 `processor.py` / `builtin.py` 两条处理链,历史与流式逻辑耦合较紧,需回归 `tests/test_processor.py`、`tests/test_builtin.py`、`tests/test_stream.py` - 解除文本门禁会改变空消息语义,`EMPTY_REPLY` 分支的既有测试断言需要同步调整
Sign in to join this conversation.
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: openbot/bot042#1