feat(channels): 平台解密、下载限长与 CLI 媒体命令(issue #1 P1)

P0 接好了链路与钩子抽象,但几个实际会让功能不可用的点没处理:企业微信的
aeskey 记录下来后被直接丢弃、远端下载把整份响应读进内存、没有真实平台时
无法造出媒体消息来调试。本次补齐这三块。

企业微信解密:
- WeComChannel.make_media_transform 按本条消息的 <media>.aeskey 构造闭包,
  用 SDK 的 decrypt_file 解密(IV 取密钥前 16 字节、PKCS#7 去填充)。
  不在本仓库重写密码学——那只会多出第二份可能与平台不一致的实现
- 没有对应 url 的密钥时原样返回字节,不猜、不抛:由 MIME 嗅探去判定
- SDK 缺失时抛 MediaRejected(含安装提示),不让 ImportError 冒泡打断整轮

下载限长:
- BaseChannel.fetch_remote_media 从 resp.content 整份读改成 client.stream
  按块累计,Content-Length 先预检、流式累计超限即中断
- 上限取各类型限制的最大值:此方法拿不到分片类型,宁可放到最宽的一档,
  精确的按类型判定仍由 store_media 负责

CLI 媒体入口:
- /image <路径>、/file <路径> 解析成本地附件分片,走与其他渠道同一套
  media.py 策略(存在性、大小上限、MIME 嗅探、文件名净化),不因为
  「本地」就跳过
- 拒绝时降级为一条说明文本而非抛异常:CLI 里抛异常会直接终止输入泵
- _send_media 从打印占位行改为回执真实字节的大小与 sha256 前缀。
  CLI 里不存在「发送」这回事,所以不打印「已发送」

顺带修的健壮性问题:
- store_media 的临时文件名加 uuid 后缀。原先固定 .part,同一会话并发落盘
  同名文件时会互相截断,且 try/finally 保证失败不留半份字节
- read_file_limited 的超限文案原先把同一个数写了两遍(「大于 8 MiB
  (上限 8 MiB)」),改为「文件大于 8 MiB(上限 8 MiB)」,并注明只多读了
  1 字节所以只能说「大于」
- cli.py 的 except Exception 收窄为 (OSError, ValueError, TypeError):
  CancelledError 必须能穿过这一层

测试:新增 tests/test_media_pipeline.py 43 条,按 issue 的六条验收标准逐条
对应(路径穿越与净化、读取与下载限长、MIME 魔数优先、outbox 上限与上下文
隔离、prepare_inbound 多模态与降级、CLI 收发)。文档 architecture.md 补
安全护栏、平台解密、CLI 入口三段。

未验证(见 PR 描述):
- 没有一条真实的企业微信加密媒体消息跑过解密路径,单测里这一环是桩
- 分块传输(Transfer-Encoding: chunked)未构造响应实测中断逻辑
This commit is contained in:
openbot committed 2026-11-10 09:47:30 +08:00
1 parent 2dde0d1160
commit 5ca40c6b0e
6 files changed
+736 -16

No files matched your search

+30 -4
View File
@@ -317,16 +317,42 @@ ChannelManager(
`supports_steer = True`。处理链路: `supports_steer = True`。处理链路:
``` ```
ChannelMessage → 校验文本(空文本/纯媒体给固定提示) ChannelMessage → prepare_inbound(附件落盘;小图内联成 image_url 块)
→ 无可用内容?→ 回「附件未能接收:<原因>」/「(无输出)」并结束
→ ensure_db → ensure_session → list_messages → build_history → ensure_db → ensure_session → list_messages → build_history
→ add_message(user) → add_message(user, 正文 + 附件清单)
→ 建 MediaOutbox(本轮出站信箱)
→ open_stream() ┬ 支持流式:update(ACK) → stream_task 边生成边覆盖 → finish → open_stream() ┬ 支持流式:update(ACK) → stream_task 边生成边覆盖 → finish
└ 不支持:run_task → send_text 一次性发送 │ → 媒体在文本定稿后单独补一条
└ 不支持:run_task → 有媒体走 send_content,否则 send_text
→ 补记插话(_persist_steered)→ add_message(assistant) → 补记插话(_persist_steered)→ add_message(assistant)
``` ```
媒体链路(issue #1 的 P0 部分):
- **入站**:`flows/media_input.prepare_inbound()` 把分片整理成多模态块——小图 base64
内联、大图与音视频退化为「路径 + 元信息」、文本类文件抽取正文;单个附件超限/类型
拒绝/下载失败只写进 `notes`,不打断整轮。字节落盘在 `home/data/inbound/<session>/`,
历史只存正文 + 附件清单,不存字节。
- **出站**:`agent/outbox.MediaOutbox` 是本轮的信箱,`send_image` / `send_file` 工具
往里登记分片;`run()` 结束后 `drain()` 出来,与正文合成**一条** `OutboundContent`,
由出站管线「先文本、再逐个媒体」下发,避免平台上出现两条消息。只有媒体没有正文时
不再补「(无输出)」;流式通道只送文本,媒体等文本定稿后单独补一条。
- **安全护栏**:所有字节来源(`data` / `local_path` / `url`)都经过
`channels/media.py` 的同一套策略——按类型的大小上限、魔数优先的 MIME 判定、
可执行扩展名拉黑、文件名净化与根目录约束;远端下载改为流式按块读取,
`Content-Length` 先预检、超限即中断,整份读进内存的路径已移除。
- **平台解密**:`BaseChannel.make_media_transform()` 按单条消息的 metadata 构造
解密钩子(密钥随消息而来,挂在渠道实例上会串台),企业微信用
`<media>.aeskey` 走 SDK 的 `decrypt_file`。解密在类型嗅探**之前**执行,并对
明文再量一次大小——密文没超不等于明文没超。
- **CLI 调试入口**:`/image <路径>`、`/file <路径>` 可以直接在无平台环境造出
媒体入站消息;出站 `_send_media` 不再打印占位行,改为回执真实字节的
大小与 sha256 前缀(CLI 里没有「已发送」这回事)。
`ChannelServices` 是它的运行期依赖(`channels` / `settings` / `db` / `hub` / `cache` / `ChannelServices` 是它的运行期依赖(`channels` / `settings` / `db` / `hub` / `cache` /
历史条数与字符预算 / 发送超时),由 `TaskRunner(deps=...)` 注入。 历史条数与字符预算 / 发送超时),由 `TaskRunner(deps=...)` 注入;`media_policy()` 从
渠道取媒体大小上限与下载请求头,未知渠道退回默认值(不因为查不到渠道就跳过校验)。
`on_error` 钩子会尽量回一句 `ERROR_REPLY`,发送失败只记日志(避免错误处理再次抛错)。 `on_error` 钩子会尽量回一句 `ERROR_REPLY`,发送失败只记日志(避免错误处理再次抛错)。
两个细节: 两个细节:
+24 -4
View File
@@ -643,14 +643,34 @@ class BaseChannel(ABC):
return self.media_transform return self.media_transform
async def fetch_remote_media(self, url: str) -> tuple[bytes, str]: async def fetch_remote_media(self, url: str) -> tuple[bytes, str]:
"""下载远端媒体并返回 ``(bytes, content_type)``;子类可覆写加平台鉴权。""" """下载远端媒体并返回 ``(bytes, content_type)``;子类可覆写加平台鉴权。
async with httpx.AsyncClient(follow_redirects=True) as client:
resp = await client.get(url) **带大小闸**:``resp.content`` 会把整份响应读进内存,平台给出的 URL
可能是任意大的文件,因此这里改为流式按块读取并在超限时中断。
"""
limits = self.media_limits
async with httpx.AsyncClient(
follow_redirects=True, timeout=limits.timeout
) as client, client.stream("GET", url) as resp:
resp.raise_for_status() resp.raise_for_status()
content_type = resp.headers.get("content-type") or ( content_type = resp.headers.get("content-type") or (
mimetypes.guess_type(url)[0] or "application/octet-stream" mimetypes.guess_type(url)[0] or "application/octet-stream"
) )
return resp.content, content_type budget = max(limits.image, limits.audio, limits.video, limits.file)
declared = resp.headers.get("content-length", "")
if declared.isdigit() and int(declared) > budget:
raise MediaRejected(
"媒体超过大小上限",
f"Content-Length {format_size(int(declared))} > {format_size(budget)}",
)
buffer = bytearray()
async for piece in resp.aiter_bytes(limits.chunk):
buffer.extend(piece)
if len(buffer) > budget:
raise MediaRejected(
"媒体超过大小上限", f"下载超过 {format_size(budget)} 已中断"
)
return bytes(buffer), content_type
async def load_media_bytes( async def load_media_bytes(
self, part: ContentPart, *, limits: MediaLimits | None = None self, part: ContentPart, *, limits: MediaLimits | None = None
+108 -5
View File
@@ -9,15 +9,26 @@ from __future__ import annotations
import asyncio import asyncio
import contextlib import contextlib
import hashlib
import logging import logging
import mimetypes
import sys import sys
from pathlib import Path
from typing import Any from typing import Any
from bot042.channels.base import BaseChannel from bot042.channels.base import BaseChannel
from bot042.channels.media import (
MediaRejected,
format_size,
read_file_limited,
sanitize_filename,
)
from bot042.channels.models import ( from bot042.channels.models import (
ChannelConfig, ChannelConfig,
ChannelSubject, ChannelSubject,
ContentPart, ContentPart,
FileContent,
ImageContent,
InboundMessage, InboundMessage,
MessageProcessor, MessageProcessor,
TextContent, TextContent,
@@ -29,6 +40,9 @@ logger = logging.getLogger(__name__)
_EXIT_WORDS = frozenset({"exit", "quit"}) _EXIT_WORDS = frozenset({"exit", "quit"})
_LOCAL_SUBJECT = "local" _LOCAL_SUBJECT = "local"
_MEDIA_COMMANDS = {"image": "image", "img": "image", "file": "file", "media": "file"}
"""``/image <路径>``、``/file <路径>``:无真实平台时用来调试媒体收发。"""
class CliConfig(ChannelConfig): class CliConfig(ChannelConfig):
"""CLI 渠道配置。""" """CLI 渠道配置。"""
@@ -105,9 +119,18 @@ class CliChannel(BaseChannel):
return False return False
def parse_inbound(self, raw_payload: Any) -> InboundMessage: def parse_inbound(self, raw_payload: Any) -> InboundMessage:
"""CLI 的原始负载就是一行文本(或已构建的 InboundMessage)。""" """CLI 的原始负载就是一行文本(或已构建的 InboundMessage)。
``/image <路径>`` 与 ``/file <路径>`` 会解析成本地附件分片,
路径校验(存在性、大小上限、类型嗅探)与其他渠道共用同一套
:mod:`bot042.channels.media` 策略,不因为「本地」就跳过。
"""
if isinstance(raw_payload, InboundMessage): if isinstance(raw_payload, InboundMessage):
return raw_payload return raw_payload
line = str(raw_payload)
parts = self._parse_media_command(line)
if parts is None:
parts = [TextContent(text=line)]
return InboundMessage( return InboundMessage(
channel_id=self.channel_id, channel_id=self.channel_id,
channel_type=self.channel_type, channel_type=self.channel_type,
@@ -117,9 +140,57 @@ class CliChannel(BaseChannel):
chat_type="direct", chat_type="direct",
), ),
channel_session_id=self.channel_type, channel_session_id=self.channel_type,
content=[TextContent(text=str(raw_payload))], content=parts,
) )
def _parse_media_command(self, line: str) -> list[ContentPart] | None:
"""解析 ``/image``、``/file`` 命令;不是命令时返回 ``None``。
附件被拒(超限、不存在、类型不符)时返回一条说明文本而不是抛异常:
CLI 里抛异常会直接终止输入泵,用户看到的是进程退出而不是提示。
"""
text = line.strip()
if not text.startswith("/"):
return None
head, _, rest = text[1:].partition(" ")
kind = _MEDIA_COMMANDS.get(head.lower())
if kind is None:
return None
path_text = rest.strip()
if not path_text:
return [TextContent(text=f"用法:/{head} <本地文件路径>")]
# 引号包裹的路径(含空格)直接剥掉两端引号
path_text = path_text.strip("\"'")
limits = self.media_limits
try:
path = Path(path_text).expanduser()
limit = limits.image if kind == "image" else limits.file
raw = read_file_limited(path, limit)
except MediaRejected as exc:
return [TextContent(text=f"附件未接收:{exc.player_reason}({exc.detail})")]
mime = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
if kind == "image":
if not mime.startswith("image/"):
return [
TextContent(
text=f"附件未接收:不是图片类型({mime}),如为普通文件请用 /file"
)
]
part: ContentPart = ImageContent(
local_path=str(path),
size=len(raw),
mime_type=mime,
alt_text=sanitize_filename(path.name),
)
else:
part = FileContent(
local_path=str(path),
filename=sanitize_filename(path.name),
size=len(raw),
mime_type=mime,
)
return [part]
# ----- 平台出站原语 ----- # ----- 平台出站原语 -----
async def _send_text(self, subject: ChannelSubject, text: str) -> None: async def _send_text(self, subject: ChannelSubject, text: str) -> None:
@@ -133,9 +204,41 @@ class CliChannel(BaseChannel):
await self._send_media(subject, part) await self._send_media(subject, part)
async def _send_media(self, subject: ChannelSubject, media: ContentPart) -> None: async def _send_media(self, subject: ChannelSubject, media: ContentPart) -> None:
name = getattr(media, "filename", "") or getattr(media, "alt_text", "") or media.type """CLI 无法真正投递媒体,改为回执:路径 + 大小 + sha256 前缀。
url = getattr(media, "url", "") or getattr(media, "local_path", "")
_safe_print(f"[媒体] {media.type}: {name} {url}".rstrip()) 回执要能被人当场验证,所以不打印「已发送」——CLI 里没有发送这回事。
存在性、大小上限与类型嗅探与其他渠道共用同一套策略;被拒时打印原因,
不抛异常(异常会让出站链路把整条回复判失败)。
"""
_ = subject
name = (
getattr(media, "filename", "")
or getattr(media, "alt_text", "")
or media.type
)
limits = self.media_limits
limit = limits.image if media.type == "image" else limits.file
try:
raw, _mime = await self.load_media_bytes(media)
if len(raw) > limit:
raise MediaRejected(
"媒体超过大小上限",
f"{format_size(len(raw))} > {format_size(limit)}",
)
except MediaRejected as exc:
_safe_print(f"[媒体被拒] {media.type} {name}:{exc.player_reason}({exc.detail})")
return
except (OSError, ValueError, TypeError) as exc:
# 下载/读取失败时只回执,不打断后续分片。这里不捕获 BaseException,
# 也不吞 CancelledError——取消必须能穿过这一层。
_safe_print(f"[媒体失败] {media.type} {name}:{type(exc).__name__}: {exc}")
return
digest = hashlib.sha256(raw).hexdigest()[:16]
where = getattr(media, "local_path", "") or getattr(media, "url", "") or "(内存)"
_safe_print(
f"[媒体回执] {media.type}: {name} {format_size(len(raw))} "
f"sha256:{digest} 来源 {where}"
)
register_channel("cli", CliChannel, CliConfig) register_channel("cli", CliChannel, CliConfig)
+34
View File
@@ -20,6 +20,7 @@ from typing import Any, ClassVar
import httpx import httpx
from bot042.channels.base import BaseChannel, ChannelCredentialsError from bot042.channels.base import BaseChannel, ChannelCredentialsError
from bot042.channels.media import MediaRejected, MediaTransform
from bot042.channels.models import ( from bot042.channels.models import (
AudioContent, AudioContent,
ChannelConfig, ChannelConfig,
@@ -408,6 +409,39 @@ class WeComChannel(BaseChannel):
filename = f"{media_type}{extension}" filename = f"{media_type}{extension}"
return media_type, filename or default_name return media_type, filename or default_name
# ----- 入站媒体解密 -----
def make_media_transform(self, metadata: dict[str, Any]) -> MediaTransform:
"""按本条的 ``aeskey`` 构造解密钩子(密钥随消息而来,不挂在实例上)。
企业微信推送的媒体 URL 返回的是 AES-256-CBC 密文,密钥在消息体的
``<media>.aeskey`` 里(``parse_inbound`` 记进 ``_media_aes_keys``)。
不传密钥时 SDK 的 ``download_file`` 只会原样返回密文,因此"记录了
aeskey 却不解密"等于入站图片全是不可用的字节。
解密用 SDK 自带的 ``decrypt_file``(IV 取密钥前 16 字节,PKCS#7 去填充),
不在这里重新实现一遍密码学——那只会多出一份可能与平台不一致的实现。
"""
keys = metadata.get("_media_aes_keys") or {}
if not isinstance(keys, dict) or not keys:
return super().media_transform
def _decrypt(part: ContentPart, raw: bytes) -> bytes:
url = getattr(part, "url", "") or ""
aes_key = keys.get(url)
if not aes_key:
# 没有密钥就是没有密钥,不要猜:返回原字节,由 MIME 嗅探去判定
return raw
try:
from wecom_aibot_sdk import decrypt_file
except ImportError as exc: # pragma: no cover - SDK 是可选依赖
raise MediaRejected(
"媒体解密不可用", "需要 wecom-aibot-sdk(含 cryptography)"
) from exc
return decrypt_file(raw, aes_key)
return _decrypt
# ----- 主动推送路由辅助 ----- # ----- 主动推送路由辅助 -----
def _enrich_push_metadata( def _enrich_push_metadata(
+9 -3
View File
@@ -24,6 +24,7 @@ import hashlib
import mimetypes import mimetypes
import re import re
import unicodedata import unicodedata
import uuid
from collections.abc import Callable from collections.abc import Callable
from dataclasses import dataclass from dataclasses import dataclass
from pathlib import Path from pathlib import Path
@@ -300,8 +301,9 @@ def read_file_limited(path: Path, limit: int) -> bytes:
with path.open("rb") as handle: with path.open("rb") as handle:
data = handle.read(limit + 1) data = handle.read(limit + 1)
if len(data) > limit: if len(data) > limit:
# 只多读了 1 字节,所以这里只能说「大于」,说不出真实大小
raise MediaRejected( raise MediaRejected(
"媒体超过大小上限", f"大于 {format_size(limit)}(上限 {format_size(limit)})" "媒体超过大小上限", f"文件大于 {format_size(limit)}(上限 {format_size(limit)})"
) )
return data return data
@@ -535,10 +537,14 @@ async def store_media(
if target.exists(): if target.exists():
target = safe_join(folder, f"{digest[:12]}-{target.name}") target = safe_join(folder, f"{digest[:12]}-{target.name}")
# 写临时文件再原子改名:中途失败不会留下半份字节 # 写临时文件再原子改名:中途失败不会留下半份字节。
temp = target.with_name(target.name + ".part") # 临时名带 uuid:同一会话并发落盘同名文件时,共用一个 ".part" 会互相截断。
temp = target.with_name(f"{target.name}.{uuid.uuid4().hex[:8]}.part")
try:
temp.write_bytes(raw) temp.write_bytes(raw)
temp.replace(target) temp.replace(target)
finally:
temp.unlink(missing_ok=True)
updated = part.model_copy( updated = part.model_copy(
update={ update={
+531
View File
@@ -0,0 +1,531 @@
"""issue #1 验收:媒体链路的接入、护栏与安全边界。
对应 issue 的验收标准(`docs` 与本文件一一对应):
1. 媒体能进上下文 —— `test_image_reaches_agent_context` 等;
2. 文本 + 文件混合不丢 —— `test_text_and_file_both_reach_agent`;
3. 智能体发媒体走原生下发 —— `test_outbox_part_flows_to_channel`;
4. 超限被拒且不炸内存 —— `test_oversize_*`;
5. 恶意文件名不越界 —— `test_sanitize_*` / `test_safe_join_*`;
6. 以上均有单测且 pytest 全绿。
本文件只测**媒体策略与链路**,不重复测 AgentReply 的会话/落库语义
(见 `tests/test_builtin.py`)。
"""
from __future__ import annotations
import asyncio
import base64
import sys
import types
from pathlib import Path
import pytest
from bot042.agent.outbox import (
MediaOutbox,
bind,
current_outbox,
make_file_part,
make_image_part,
unbind,
)
from bot042.channels.cli import CliChannel
from bot042.channels.manager import ChannelManager
from bot042.channels.media import (
MediaLimits,
MediaRejected,
check_mime,
decode_base64_limited,
read_file_limited,
safe_join,
sanitize_filename,
store_media,
)
from bot042.channels.models import (
ChannelSubject,
FileContent,
ImageContent,
InboundMessage,
TextContent,
)
from bot042.config import Settings
from bot042.flows.builtin import ChannelServices
from bot042.flows.media_input import prepare_inbound
PNG_HEAD = b"\x89PNG\r\n\x1a\n" + b"\x00" * 64
PDF_HEAD = b"%PDF-1.4\n" + b"\x00" * 64
# ---------------------------------------------------------------------------
# 5. 路径安全:文件名净化与根目录约束
# ---------------------------------------------------------------------------
@pytest.mark.parametrize(
"hostile",
[
"../../etc/passwd",
"..\\..\\Windows\\System32\\config",
"/etc/shadow",
"C:\\Windows\\system.ini",
"....//....//evil.sh",
"a/../../../b.png",
],
)
def test_sanitize_filename_never_escapes(hostile: str) -> None:
"""恶意文件名净化后不得含路径分隔符,也不得是 . 或 .."""
cleaned = sanitize_filename(hostile)
assert "/" not in cleaned and "\\" not in cleaned
assert cleaned not in {".", ".."}
assert not cleaned.startswith(".")
def test_safe_join_keeps_target_inside_root(tmp_path: Path) -> None:
"""即使传入穿越片段,落点也必须在 root 之内。"""
root = tmp_path / "session"
root.mkdir()
target = safe_join(root, sanitize_filename("../../escape.png"))
assert target.parent == root
assert root in target.parents
def test_store_media_lands_inside_session_dir(tmp_path: Path) -> None:
"""落盘路径由会话键决定:会话键里的 .. 会被净化,不会跳出 root。"""
part = ImageContent(mime_type="image/png").model_copy(
update={"data": base64.b64encode(PNG_HEAD).decode()}
)
stored = asyncio.run(store_media(part, root=tmp_path, session_key="../s"))
assert tmp_path in stored.path.parents
assert ".." not in str(stored.path.relative_to(tmp_path))
# 会话键被净化成单个目录段,不是嵌套路径
assert stored.path.parent.parent == tmp_path
def test_store_media_dedupes_same_name(tmp_path: Path) -> None:
"""同名不同内容不得互相覆盖(后到的加哈希前缀)。"""
first = ImageContent(mime_type="image/png").model_copy(
update={"data": base64.b64encode(PNG_HEAD).decode()}
)
second = ImageContent(mime_type="image/png").model_copy(
update={"data": base64.b64encode(PNG_HEAD + b"other").decode()}
)
a = asyncio.run(store_media(first, root=tmp_path, session_key="s"))
b = asyncio.run(store_media(second, root=tmp_path, session_key="s"))
assert a.path != b.path
assert a.path.read_bytes() == PNG_HEAD
# ---------------------------------------------------------------------------
# 4. 大小护栏:本地读取、base64 解码、下载
# ---------------------------------------------------------------------------
def test_read_file_limited_rejects_oversize(tmp_path: Path) -> None:
big = tmp_path / "big.bin"
big.write_bytes(b"x" * 2048)
with pytest.raises(MediaRejected) as err:
read_file_limited(big, 1024)
assert "超过大小上限" in err.value.reason
def test_read_file_limited_reads_at_most_limit_plus_one(tmp_path: Path) -> None:
"""判定越界只需多读 1 字节,不得把整个超大文件读进内存。"""
big = tmp_path / "huge.bin"
big.write_bytes(b"x" * (8 * 1024 * 1024))
with pytest.raises(MediaRejected):
read_file_limited(big, 1024)
def test_read_file_limited_missing_file(tmp_path: Path) -> None:
with pytest.raises(MediaRejected) as err:
read_file_limited(tmp_path / "nope.bin", 1024)
assert err.value.reason == "文件不存在"
def test_decode_base64_limited_rejects_oversize() -> None:
payload = base64.b64encode(b"x" * 4096).decode()
with pytest.raises(MediaRejected):
decode_base64_limited(payload, 1024)
def test_decode_base64_limited_invalid() -> None:
with pytest.raises(MediaRejected):
decode_base64_limited("!!!not-base64!!!", 1024)
@pytest.mark.parametrize(
("declared", "head", "expected"),
[
("image/png", PNG_HEAD, "image/png"),
# 声明撒谎:实际是 PNG,按魔数修正(改扩展名绕不过类型限制)
("text/plain", PNG_HEAD, "image/png"),
("image/jpeg", PNG_HEAD, "image/png"),
],
)
def test_check_mime_prefers_magic_bytes(declared: str, head: bytes, expected: str) -> None:
"""声明类型与魔数冲突时以魔数为准。"""
got = check_mime(ImageContent(), declared, head)
assert got == expected
def test_check_mime_file_accepts_pdf() -> None:
"""非图片类文件走 FileContent,PDF 应放行并采信魔数。"""
got = check_mime(FileContent(filename="a.pdf"), "", PDF_HEAD)
assert got == "application/pdf"
def test_check_mime_image_rejects_pdf() -> None:
"""把 PDF 当图片投递:必须拒绝,而不是带着错误 MIME 继续。"""
with pytest.raises(MediaRejected) as err:
check_mime(ImageContent(), "application/pdf", PDF_HEAD)
assert "不被接受" in err.value.reason
def test_check_mime_rejects_executable() -> None:
"""可执行文件按扩展名拒绝:智能体读到的文件不该原样推给对方。"""
with pytest.raises(MediaRejected):
check_mime(FileContent(filename="virus.exe"), "", b"MZ")
def test_media_limits_per_type_is_ordered() -> None:
limits = MediaLimits()
assert limits.image <= limits.file
assert limits.for_part(ImageContent()).__class__ is int
# ---------------------------------------------------------------------------
# 3. 出站:outbox 的工具入口
# ---------------------------------------------------------------------------
def test_make_image_part_validates_type(tmp_path: Path) -> None:
fake = tmp_path / "notimage.png"
fake.write_bytes(b"plain text, not a png at all")
with pytest.raises(MediaRejected):
make_image_part(str(fake))
def test_make_image_part_ok(tmp_path: Path) -> None:
picture = tmp_path / "cat.png"
picture.write_bytes(PNG_HEAD)
part = make_image_part(str(picture), caption="猫")
assert isinstance(part, ImageContent)
assert part.size == len(PNG_HEAD)
assert part.mime_type == "image/png"
assert part.alt_text == "猫"
def test_make_file_part_rejects_missing(tmp_path: Path) -> None:
with pytest.raises(MediaRejected) as err:
make_file_part(str(tmp_path / "ghost.pdf"))
assert "不存在" in err.value.reason
def test_outbox_caps_pending_count() -> None:
"""单轮附件数量设上限,避免模型刷屏式调用把平台打爆。"""
box = MediaOutbox(max_pending=2)
part = ImageContent(mime_type="image/png")
box.push(part)
box.push(part)
with pytest.raises(MediaRejected):
box.push(part)
assert len(box.drain()) == 2
assert len(box) == 0
def test_outbox_context_binding_is_isolated() -> None:
box = MediaOutbox()
assert current_outbox() is None
token = bind(box)
try:
assert current_outbox() is box
finally:
unbind(token)
assert current_outbox() is None
# ---------------------------------------------------------------------------
# 1 & 2. 入站:多模态块构建与降级
# ---------------------------------------------------------------------------
def _prepare(**kwargs):
from bot042.flows.media_input import prepare_inbound
return prepare_inbound
def test_prepare_inbound_inlines_small_image(tmp_path: Path) -> None:
from bot042.channels.models import ChannelSubject, InboundMessage
from bot042.flows.media_input import prepare_inbound
picture = tmp_path / "cat.png"
picture.write_bytes(PNG_HEAD)
message = InboundMessage(
channel_id="c1",
channel_type="cli",
channel_subject=ChannelSubject(subject_id="u1"),
content=[
TextContent(text="这是什么"),
ImageContent(local_path=str(picture), mime_type="image/png"),
],
)
prepared = asyncio.run(prepare_inbound(message, root=tmp_path / "in"))
kinds = [b["type"] for b in prepared.blocks]
assert kinds == ["text", "image_url"]
assert prepared.blocks[1]["image_url"]["url"].startswith("data:image/png;base64,")
assert prepared.is_multimodal
# 摘要里带附件清单,且不含 base64
assert "[附件]" in prepared.summary
assert "base64" not in prepared.summary
def test_prepare_inbound_text_and_file_both_kept(tmp_path: Path) -> None:
"""文本 + 文件混合:两者都进上下文,不静默丢弃任何一个。"""
from bot042.channels.models import ChannelSubject, InboundMessage
from bot042.flows.media_input import prepare_inbound
note = tmp_path / "notes.txt"
note.write_text("第一行\n第二行\n", encoding="utf-8")
message = InboundMessage(
channel_id="c1",
channel_type="cli",
channel_subject=ChannelSubject(subject_id="u1"),
content=[
TextContent(text="帮我看看这个文件"),
FileContent(local_path=str(note), filename="notes.txt", mime_type="text/plain"),
],
)
prepared = asyncio.run(prepare_inbound(message, root=tmp_path / "in"))
joined = "\n".join(b.get("text", "") for b in prepared.blocks)
assert "帮我看看这个文件" in joined
assert "第一行" in joined # 文本文件内容被抽取进上下文
assert len(prepared.stored) == 1
def test_prepare_inbound_oversize_degrades_to_note(tmp_path: Path) -> None:
"""超限附件降级成一条说明,不抛异常、不中断其余内容。"""
from bot042.channels.models import ChannelSubject, InboundMessage
from bot042.flows.media_input import prepare_inbound
big = tmp_path / "big.png"
big.write_bytes(PNG_HEAD + b"\x00" * 4096)
message = InboundMessage(
channel_id="c1",
channel_type="cli",
channel_subject=ChannelSubject(subject_id="u1"),
content=[
TextContent(text="看图"),
ImageContent(local_path=str(big), mime_type="image/png"),
],
)
prepared = asyncio.run(
prepare_inbound(
message, root=tmp_path / "in", limits=MediaLimits(image=128, file=128)
)
)
assert prepared.has_content
assert prepared.notes
assert any("上限" in n or "超过" in n for n in prepared.notes)
def test_prepare_inbound_missing_file_is_noted(tmp_path: Path) -> None:
from bot042.channels.models import ChannelSubject, InboundMessage
from bot042.flows.media_input import prepare_inbound
message = InboundMessage(
channel_id="c1",
channel_type="cli",
channel_subject=ChannelSubject(subject_id="u1"),
content=[FileContent(local_path=str(tmp_path / "ghost.pdf"), filename="ghost.pdf")],
)
prepared = asyncio.run(prepare_inbound(message, root=tmp_path / "in"))
assert prepared.notes
assert not prepared.stored
# ---------------------------------------------------------------------------
# CLI 渠道:无平台时的收发调试入口
# ---------------------------------------------------------------------------
def test_cli_image_command(tmp_path: Path) -> None:
picture = tmp_path / "cat.png"
picture.write_bytes(PNG_HEAD)
channel = CliChannel()
message = channel.parse_inbound(f"/image {picture}")
assert isinstance(message.content[0], ImageContent)
assert message.content[0].mime_type == "image/png"
def test_cli_file_command(tmp_path: Path) -> None:
note = tmp_path / "a.txt"
note.write_text("hi", encoding="utf-8")
channel = CliChannel()
message = channel.parse_inbound(f"/file {note}")
assert isinstance(message.content[0], FileContent)
assert message.content[0].filename == "a.txt"
def test_cli_image_command_rejects_oversize(tmp_path: Path) -> None:
picture = tmp_path / "cat.png"
picture.write_bytes(PNG_HEAD + b"\x00" * 4096)
channel = CliChannel()
channel._media_limits = MediaLimits(image=64, file=64)
message = channel.parse_inbound(f"/image {picture}")
assert isinstance(message.content[0], TextContent)
assert "未接收" in message.content[0].text
def test_cli_image_command_wrong_type(tmp_path: Path) -> None:
note = tmp_path / "a.txt"
note.write_text("hi", encoding="utf-8")
channel = CliChannel()
message = channel.parse_inbound(f"/image {note}")
assert isinstance(message.content[0], TextContent)
assert "不是图片" in message.content[0].text
def test_cli_plain_text_unchanged() -> None:
channel = CliChannel()
message = channel.parse_inbound("你好")
assert isinstance(message.content[0], TextContent)
assert message.content[0].text == "你好"
def test_cli_send_media_reports_real_bytes(tmp_path: Path, capsys) -> None:
"""出站回执必须来自真实读取:给出大小与 sha256 前缀,而不是「已发送」。"""
picture = tmp_path / "cat.png"
picture.write_bytes(PNG_HEAD)
channel = CliChannel()
asyncio.run(
channel._send_media(None, ImageContent(local_path=str(picture), mime_type="image/png"))
)
out = capsys.readouterr().out
assert "媒体回执" in out
assert str(len(PNG_HEAD)) in out
assert "sha256:" in out
def test_cli_send_media_missing_file_is_reported(tmp_path: Path, capsys) -> None:
channel = CliChannel()
asyncio.run(
channel._send_media(
None, ImageContent(local_path=str(tmp_path / "ghost.png"), mime_type="image/png")
)
)
out = capsys.readouterr().out
assert "媒体" in out and ("被拒" in out or "失败" in out)
# ---------------------------------------------------------------------------
# 平台解密钩子:接线必须真的到达 store_media(不只是签名吻合)
# ---------------------------------------------------------------------------
def test_store_media_applies_transform_before_sniffing(tmp_path: Path) -> None:
"""transform 必须在类型嗅探**之前**执行:密文嗅魔数只会得到 octet-stream。"""
ciphertext = b"\x00\x01\x02\x03cipher-not-a-png" * 4
calls: list[tuple[str, int]] = []
def fake_decrypt(part, raw: bytes) -> bytes:
calls.append((part.type, len(raw)))
return PNG_HEAD
# 用内联字节而非 url:这条测的是 transform 与嗅探的顺序,不该触发网络
part = ImageContent(mime_type="application/octet-stream").model_copy(
update={"data": base64.b64encode(ciphertext).decode()}
)
stored = asyncio.run(store_media(part, root=tmp_path, transform=fake_decrypt))
assert calls == [("image", len(ciphertext))]
# 明文是 PNG,所以最终类型由**明文**魔数决定
assert stored.mime == "image/png"
assert stored.path.read_bytes() == PNG_HEAD
def test_store_media_rechecks_size_after_transform(tmp_path: Path) -> None:
"""密文没超不等于明文没超:转换后必须再量一次。"""
limits = MediaLimits(image=64)
def expand(part, raw: bytes) -> bytes:
return b"\x00" * (limits.image + 1)
part = ImageContent(mime_type="application/octet-stream").model_copy(
update={"data": base64.b64encode(b"small-cipher").decode()}
)
with pytest.raises(MediaRejected) as excinfo:
asyncio.run(store_media(part, root=tmp_path, limits=limits, transform=expand))
assert "解密后" in excinfo.value.detail
def test_store_media_transform_failure_becomes_rejection(tmp_path: Path) -> None:
"""解密异常要转成 MediaRejected,不能冒泡成未捕获异常打断整轮。"""
def broken(part, raw: bytes) -> bytes:
raise ValueError("bad padding")
part = ImageContent(mime_type="application/octet-stream").model_copy(
update={"data": base64.b64encode(b"cipher").decode()}
)
with pytest.raises(MediaRejected) as excinfo:
asyncio.run(store_media(part, root=tmp_path, transform=broken))
assert "解密失败" in excinfo.value.reason
def test_prepare_inbound_passes_transform_through(tmp_path: Path) -> None:
"""prepare_inbound 必须把 transform 透传到 store_media,否则解密形同虚设。"""
seen: list[int] = []
def fake_decrypt(part, raw: bytes) -> bytes:
seen.append(len(raw))
return PNG_HEAD
message = InboundMessage(
channel_id="c1",
channel_type="t",
channel_subject=ChannelSubject(subject_id="u1"),
content=[ImageContent(data=base64.b64encode(b"cipher-bytes").decode())],
)
prepared = asyncio.run(
prepare_inbound(message, root=tmp_path / "in", transform=fake_decrypt)
)
assert seen == [len(b"cipher-bytes")]
assert prepared.stored and prepared.stored[0].read_bytes() == PNG_HEAD
def test_wecom_media_transform_uses_per_message_aeskey(monkeypatch) -> None:
"""企业微信的解密钩子按本条消息的 url 取密钥;没有密钥时原样返回。"""
from bot042.channels.im import wecom as wecom_mod
calls: list[tuple[bytes, str]] = []
def fake_decrypt_file(raw: bytes, key: str) -> bytes:
calls.append((raw, key))
return PNG_HEAD
fake_sdk = types.SimpleNamespace(decrypt_file=fake_decrypt_file)
monkeypatch.setitem(sys.modules, "wecom_aibot_sdk", fake_sdk)
channel = wecom_mod.WeComChannel()
url = "https://example.invalid/media/1"
transform = channel.make_media_transform({"_media_aes_keys": {url: "k" * 43}})
part = ImageContent(url=url)
assert transform(part, b"cipher") == PNG_HEAD
assert calls == [(b"cipher", "k" * 43)]
# 没有对应 url 的密钥:返回原字节,不猜、不抛
other = ImageContent(url="https://example.invalid/media/2")
assert transform(other, b"cipher") == b"cipher"
def test_channel_services_media_transform_none_for_unknown_channel(tmp_path: Path) -> None:
"""渠道未注册时返回 None(不解密),不抛异常也不跳过后续校验。"""
services = ChannelServices(
channels=ChannelManager(), settings=Settings(home=tmp_path), db=tmp_path / "b.db"
)
assert services.media_transform("no-such-channel", {}) is None