diff --git a/src/bot042/agent/outbox.py b/src/bot042/agent/outbox.py new file mode 100644 index 0000000..77452dc --- /dev/null +++ b/src/bot042/agent/outbox.py @@ -0,0 +1,169 @@ +"""出站媒体信箱:让智能体在回复过程中登记要发给用户的媒体。 + +问题:智能体跑在 langgraph 里,工具是被模型调用的普通函数,拿不到渠道路由 +(``channel_id`` / ``subject_id`` / 被动回复帧)。而渠道那一层又只能拿到 +"智能体跑完后的最终文本"。 + +做法与 :mod:`bot042.agent.middlewares.steering` 同构:用 ``contextvars`` 放一个 +每轮一次的**信箱**,工具往里放分片,流程层在 ``run_task`` 之后取走并通过 +``channel.send`` RPC 下发。用 contextvar 而不是模块级单例,是因为同一张图会被 +多个会话复用,实例属性会串台。 + +安全边界(明确写出来): + +- 大小与类型在**这里**和渠道层各校验一次,任一处拒绝都不会上传; +- 路径限制(``allowed_roots``)默认不启用:智能体本来就有宿主机 shell 权限, + 文件路径白名单挡不住它读任何文件,给了只会是"看起来安全"。要收紧应该从 + 工具权限入手(``interrupt_on`` / 去掉 ``execute``),而不是在这里假装设防; +- 真正有效的是**大小上限**与**可执行扩展名拒绝**,它们限制了"一次误操作能造成 + 多大外泄"以及"会不会把可执行文件推到对方机器上"。 +""" + +from __future__ import annotations + +import contextvars +from collections import deque +from dataclasses import dataclass, field +from pathlib import Path +from typing import Final + +from bot042.channels.media import ( + MediaLimits, + MediaRejected, + check_mime, + read_file_limited, + sanitize_filename, +) +from bot042.channels.models import ( + ContentPart, + FileContent, + ImageContent, +) + +__all__ = [ + "MediaOutbox", + "Outbox", + "bind", + "current_outbox", + "make_file_part", + "make_image_part", + "unbind", +] + +MAX_PENDING: Final[int] = 8 +"""单轮回复最多登记多少个附件;超过的直接拒绝,避免模型刷屏式调用。""" + + +@dataclass +class MediaOutbox: + """一轮回复期间登记的待发媒体(绑定单个 asyncio 上下文)。""" + + limits: MediaLimits = field(default_factory=MediaLimits) + allowed_roots: tuple[Path, ...] | None = None + max_pending: int = MAX_PENDING + _items: deque[ContentPart] = field(default_factory=deque, repr=False) + + def push(self, part: ContentPart) -> None: + """登记一个分片;超过 ``max_pending`` 抛 :class:`MediaRejected`。""" + if len(self._items) >= self.max_pending: + raise MediaRejected( + "本轮附件数量超限", + f"最多 {self.max_pending} 个,已拒绝额外的 {part.type}", + ) + self._items.append(part) + + def drain(self) -> list[ContentPart]: + """取走并清空全部已登记分片。""" + items = list(self._items) + self._items.clear() + return items + + def __len__(self) -> int: + return len(self._items) + + def __bool__(self) -> bool: + return bool(self._items) + + +Outbox = MediaOutbox +"""别名:与 ``MediaOutbox`` 同一类型,供调用方用更短的写法。""" + +_current: contextvars.ContextVar[MediaOutbox | None] = contextvars.ContextVar( + "bot042_outbox", default=None +) + + +def current_outbox() -> MediaOutbox | None: + """当前上下文的信箱(无运行中回复时为 ``None``)。""" + return _current.get() + + +def bind(outbox: MediaOutbox) -> contextvars.Token: + """把信箱绑定到当前上下文,返回用于还原的 token。""" + return _current.set(outbox) + + +def unbind(token: contextvars.Token) -> None: + """还原上下文绑定。""" + _current.reset(token) + + +def _resolve(path_text: str, allowed_roots: tuple[Path, ...] | None) -> Path: + """解析并校验待发文件路径(存在性 + 可选根目录限制)。""" + raw = (path_text or "").strip() + if not raw: + raise MediaRejected("文件路径为空", "") + path = Path(raw).expanduser() + try: + resolved = path.resolve(strict=True) + except (OSError, RuntimeError) as exc: + raise MediaRejected("文件不存在或不可访问", f"{raw}: {exc}") from exc + if not resolved.is_file(): + raise MediaRejected("不是普通文件", str(resolved)) + if allowed_roots and not any( + resolved == root or root in resolved.parents + for root in (r.resolve() for r in allowed_roots) + ): + raise MediaRejected("路径不在允许的目录内", str(resolved)) + return resolved + + +def make_image_part( + path_text: str, + *, + limits: MediaLimits | None = None, + allowed_roots: tuple[Path, ...] | None = None, + caption: str = "", +) -> ImageContent: + """把本地图片文件做成 :class:`ImageContent` 分片(校验大小与类型)。""" + limits = limits or MediaLimits() + path = _resolve(path_text, allowed_roots) + raw = read_file_limited(path, limits.image) + mime = check_mime(ImageContent(), "", raw[:32]) + return ImageContent( + local_path=str(path), + size=len(raw), + mime_type=mime, + alt_text=caption, + ) + + +def make_file_part( + path_text: str, + *, + limits: MediaLimits | None = None, + allowed_roots: tuple[Path, ...] | None = None, + filename: str = "", +) -> FileContent: + """把本地文件做成 :class:`FileContent` 分片(校验大小与类型)。""" + limits = limits or MediaLimits() + path = _resolve(path_text, allowed_roots) + raw = read_file_limited(path, limits.file) + name = sanitize_filename(filename or path.name) + mime = check_mime(FileContent(filename=name), "", raw[:32]) + return FileContent( + local_path=str(path), + filename=name, + size=len(raw), + mime_type=mime, + ) diff --git a/src/bot042/agent/tools.py b/src/bot042/agent/tools.py index 1e8c64c..7d1d2f0 100644 --- a/src/bot042/agent/tools.py +++ b/src/bot042/agent/tools.py @@ -8,7 +8,13 @@ from typing import Any from langchain_core.tools import tool from bot042.agent.execution import run_python +from bot042.agent.outbox import ( + current_outbox, + make_file_part, + make_image_part, +) from bot042.agent.web import get_web_tools +from bot042.channels.media import MediaRejected, format_size _VALID_DIRECTIONS = ("north", "south", "east", "west") _VALID_DIRECTIONS_CN = {"北": "north", "南": "south", "东": "east", "西": "west"} @@ -84,13 +90,66 @@ async def speak(text: str) -> str: return f"[播报] {text}" +@tool +async def send_image(path: str, caption: str = "") -> str: + """把本地图片发给用户(作为原生图片消息,而不是文本链接)。 + + 仅支持 png/jpeg/gif/webp/bmp,且不超过大小上限;超限或类型不符会被拒绝 + 并返回原因。同一轮回复里最多登记 8 个附件。 + + Args: + path: 本地图片文件路径(绝对路径或相对当前工作目录)。 + caption: 附在图片上的说明,可留空。 + """ + outbox = current_outbox() + if outbox is None: + return "[发送失败] 当前不在渠道会话中,无法发送图片" + try: + part = make_image_part( + path, + limits=outbox.limits, + allowed_roots=outbox.allowed_roots, + caption=caption, + ) + outbox.push(part) + except MediaRejected as exc: + return f"[发送失败] {exc.reason}" + (f":{exc.detail}" if exc.detail else "") + return f"[已登记图片] {part.local_path}({format_size(part.size or 0)},将在本轮回复后发送)" + + +@tool +async def send_file(path: str, filename: str = "") -> str: + """把本地文件发给用户(作为文件消息)。 + + 可执行/脚本类扩展名(exe/bat/ps1/dll 等)会被拒绝。 + + Args: + path: 本地文件路径。 + filename: 对方看到的文件名,留空则用原文件名。 + """ + outbox = current_outbox() + if outbox is None: + return "[发送失败] 当前不在渠道会话中,无法发送文件" + try: + part = make_file_part( + path, + limits=outbox.limits, + allowed_roots=outbox.allowed_roots, + filename=filename, + ) + outbox.push(part) + except MediaRejected as exc: + return f"[发送失败] {exc.reason}" + (f":{exc.detail}" if exc.detail else "") + return f"[已登记文件] {part.filename}({format_size(part.size or 0)},将在本轮回复后发送)" + + def get_tools() -> list[Any]: """返回机器人工具集(世界操作 + 联网 + 本地执行)。 shell 执行(``execute``)由 deepagents 的 FilesystemMiddleware 依据后端能力 自动挂载,不在这里重复注册。 """ - return [perceive, move, speak, run_python, *get_web_tools()] + return [perceive, move, speak, send_image, send_file, run_python, *get_web_tools()] def reset_robot() -> None: diff --git a/src/bot042/channels/base.py b/src/bot042/channels/base.py index 2a53511..8d87419 100644 --- a/src/bot042/channels/base.py +++ b/src/bot042/channels/base.py @@ -16,8 +16,6 @@ from __future__ import annotations import asyncio -import base64 -import binascii import logging import mimetypes import time @@ -29,6 +27,14 @@ from typing import Any import httpx +from bot042.channels.media import ( + MediaLimits, + MediaRejected, + decode_base64_limited, + download_limited, + format_size, + read_file_limited, +) from bot042.channels.models import ( ChannelConfig, ChannelMessage, @@ -141,6 +147,15 @@ class BaseChannel(ABC): """是否已配置消息处理器。""" return self._processor is not None + @property + def media_limits(self) -> MediaLimits: + """本渠道的媒体大小上限(子类可覆写以适配平台限制)。""" + limits = getattr(self, "_media_limits", None) + if limits is None: + limits = MediaLimits() + self._media_limits = limits + return limits + @property def is_connected(self) -> bool: """平台连接是否在线(供管理器刷新运行时状态)。""" @@ -599,6 +614,9 @@ class BaseChannel(ABC): # ========================================================================= # 媒体字节读取(data / local_path / url 三级优先) # ========================================================================= + def media_download_headers(self) -> dict[str, str]: + """下载入站媒体时附带的请求头(平台鉴权等);默认无。""" + return {} async def fetch_remote_media(self, url: str) -> tuple[bytes, str]: """下载远端媒体并返回 ``(bytes, content_type)``;子类可覆写加平台鉴权。""" @@ -610,30 +628,51 @@ class BaseChannel(ABC): ) return resp.content, content_type - async def load_media_bytes(self, part: ContentPart) -> tuple[bytes, str]: + async def load_media_bytes( + self, part: ContentPart, *, limits: MediaLimits | None = None + ) -> tuple[bytes, str]: """把媒体分片解析为 ``(bytes, content_type)``。 解析顺序:``data``(base64 内联字节)→ ``local_path``(本地文件)→ ``url``(远端下载)。三者皆空时报 ValueError。 + + **全程带大小闸**(:class:`~bot042.channels.media.MediaLimits`): + 入站 URL 由平台给出、出站 ``local_path`` 由智能体给出,长度都不可信, + 整份读进内存会把进程打爆。超限抛 + :class:`~bot042.channels.media.MediaRejected`(``ValueError`` 子类)。 """ + limits = limits or self.media_limits if isinstance(part, TextContent): raise TypeError("load_media_bytes 不能用于文本分片") + limit = limits.for_part(part) if part.data: mime = part.mime_type or "application/octet-stream" - try: - return base64.b64decode(part.data, validate=False), mime - except (binascii.Error, ValueError) as exc: - raise ValueError(f"ContentPart.data 不是合法 base64: {exc}") from exc + return decode_base64_limited(part.data, limit), mime if part.local_path: path = Path(part.local_path) mime = part.mime_type or mimetypes.guess_type(str(path))[0] or "application/octet-stream" - return path.read_bytes(), mime + return read_file_limited(path, limit), mime if part.url: - mime = part.mime_type - raw, guessed = await self.fetch_remote_media(part.url) - return raw, mime or guessed + mime = part.mime_type or mimetypes.guess_type(part.url)[0] + try: + raw, guessed = await download_limited( + part.url, + limit=limit, + chunk=limits.chunk, + timeout=limits.timeout, + headers=self.media_download_headers(), + ) + except httpx.HTTPError: + # 平台鉴权只能由子类覆写 fetch_remote_media 提供;这里退回它取字节 + raw, guessed = await self.fetch_remote_media(part.url) + if len(raw) > limit: + raise MediaRejected( + "媒体超过大小上限", + f"{format_size(len(raw))} > {format_size(limit)}", + ) from None + return raw, mime or guessed or "application/octet-stream" raise ValueError(f"分片缺少 data/local_path/url: {part}") diff --git a/src/bot042/channels/media.py b/src/bot042/channels/media.py new file mode 100644 index 0000000..21cbb54 --- /dev/null +++ b/src/bot042/channels/media.py @@ -0,0 +1,503 @@ +"""媒体安全策略:大小上限、MIME 校验、文件名净化与落盘隔离。 + +入站媒体在进入智能体上下文之前必须经过这一层,理由有三条: + +1. **内存**:平台给的 URL 可能是任意大的文件,``resp.content`` 会把整份 + 内容读进内存。这里一律按块读取,超限立即中断; +2. **路径**:文件名来自平台,属于不可信输入,``../../.ssh/authorized_keys`` + 这类名字必须净化后才能拼进落盘路径; +3. **类型**:声明类型与实际字节可能不一致,需要按魔数嗅探交叉校验。 + +设计取舍(明确写出来,避免被当成完备防护): + +- MIME 白名单是纵深防御,不是内容扫描:它只保证「不把明显不是图片的字节 + 当图片处理」,不做病毒扫描、不做转码、不做像素级校验; +- 可执行扩展名黑名单天然不完备(总会有新扩展名),只拦常见的那批; +- 落盘后不做权限收紧(沿用进程 umask),隔离靠目录边界而非 DACL。 +""" + +from __future__ import annotations + +import base64 +import binascii +import hashlib +import mimetypes +import re +import unicodedata +from dataclasses import dataclass +from pathlib import Path +from typing import Final + +import httpx + +from bot042.channels.models import ( + AudioContent, + ContentPart, + FileContent, + ImageContent, + TextContent, + VideoContent, +) + +__all__ = [ + "ALLOWED_AUDIO_MIME", + "ALLOWED_IMAGE_MIME", + "ALLOWED_VIDEO_MIME", + "BLOCKED_EXTENSIONS", + "MediaLimits", + "MediaRejected", + "StoredMedia", + "check_mime", + "decode_base64_limited", + "download_limited", + "format_size", + "guess_mime", + "read_file_limited", + "safe_join", + "sanitize_filename", + "store_media", +] + +MB: Final[int] = 1024 * 1024 + +# --------------------------------------------------------------------------- +# 类型白名单 +# --------------------------------------------------------------------------- + +ALLOWED_IMAGE_MIME: Final[frozenset[str]] = frozenset( + {"image/png", "image/jpeg", "image/gif", "image/webp", "image/bmp"} +) +ALLOWED_AUDIO_MIME: Final[frozenset[str]] = frozenset( + { + "audio/amr", + "audio/mpeg", + "audio/wav", + "audio/x-wav", + "audio/ogg", + "audio/mp4", + "audio/aac", + "audio/silk", + } +) +ALLOWED_VIDEO_MIME: Final[frozenset[str]] = frozenset( + {"video/mp4", "video/quicktime", "video/webm", "video/x-msvideo"} +) + +BLOCKED_EXTENSIONS: Final[frozenset[str]] = frozenset( + { + ".exe", ".bat", ".cmd", ".com", ".scr", ".pif", ".msi", ".dll", + ".ps1", ".vbs", ".vbe", ".js", ".jse", ".wsf", ".hta", ".lnk", + ".jar", ".sh", ".bash", + } +) +"""可执行/脚本类扩展名,入站与出站都拒绝。 + +这是**黑名单**,不完备;只拦常见的那批。真正的防线是「不自动执行内容」, +而不是这张表。 +""" + +_IMAGE_EXT: Final[dict[str, str]] = { + ".png": "image/png", + ".jpg": "image/jpeg", + ".jpeg": "image/jpeg", + ".gif": "image/gif", + ".webp": "image/webp", + ".bmp": "image/bmp", +} +_VIDEO_EXT: Final[dict[str, str]] = { + ".mp4": "video/mp4", + ".mov": "video/quicktime", + ".webm": "video/webm", + ".avi": "video/x-msvideo", +} +_AUDIO_EXT: Final[dict[str, str]] = { + ".amr": "audio/amr", + ".mp3": "audio/mpeg", + ".wav": "audio/wav", + ".ogg": "audio/ogg", + ".m4a": "audio/mp4", + ".aac": "audio/aac", + ".silk": "audio/silk", +} + + +def guess_mime(filename: str) -> str | None: + """按扩展名推断 MIME;未知返回 ``None``。""" + ext = Path(filename).suffix.lower() + for table in (_IMAGE_EXT, _VIDEO_EXT, _AUDIO_EXT): + if ext in table: + return table[ext] + guessed, _ = mimetypes.guess_type(filename) + return guessed + + +def sniff_mime(head: bytes) -> str | None: + """按魔数嗅探 MIME;无法判定返回 ``None``。 + + 只覆盖本项目实际会碰到的格式,不做通用实现。 + """ + if head.startswith(b"\x89PNG\r\n\x1a\n"): + return "image/png" + if head.startswith(b"\xff\xd8\xff"): + return "image/jpeg" + if head[:6] in (b"GIF87a", b"GIF89a"): + return "image/gif" + if head.startswith(b"BM"): + return "image/bmp" + if head.startswith(b"RIFF") and len(head) >= 12: + form = head[8:12] + if form == b"WEBP": + return "image/webp" + if form == b"WAVE": + return "audio/wav" + if form == b"AVI ": + return "video/x-msvideo" + if head.startswith(b"#!AMR"): + return "audio/amr" + if head.startswith(b"OggS"): + return "audio/ogg" + if head.startswith(b"ID3") or head[:2] in (b"\xff\xfb", b"\xff\xf3"): + return "audio/mpeg" + if head.startswith(b"\x1aE\xdf\xa3"): + return "video/webm" + if len(head) >= 12 and head[4:8] == b"ftyp": + brand = head[8:12] + if brand.startswith(b"qt"): + return "video/quicktime" + return "video/mp4" + if head.startswith(b"#!SILK"): + return "audio/silk" + return None + + +def check_mime(part: ContentPart, declared: str, head: bytes = b"") -> str: + """校验媒体类型是否可接受,返回最终采信的 MIME。 + + 采信顺序:魔数嗅探 > 声明类型 > 扩展名推断。三者都没有时按 + ``application/octet-stream`` 处理——此时只有 :class:`FileContent` + 放行,图片/音视频一律拒绝(无法确认它真的是媒体)。 + + Raises: + MediaRejected: 类型不在该类媒体允许的集合内,或扩展名被拉黑。 + """ + sniffed = sniff_mime(head) if head else None + candidate = (sniffed or declared or "").split(";")[0].strip().lower() + + if isinstance(part, FileContent): + name = part.filename or "" + ext = Path(name).suffix.lower() + if ext in BLOCKED_EXTENSIONS: + raise MediaRejected("文件类型被拒绝", f"可执行/脚本扩展名:{ext}") + return candidate or guess_mime(name) or "application/octet-stream" + + if isinstance(part, ImageContent): + allowed, label = ALLOWED_IMAGE_MIME, "图片" + elif isinstance(part, AudioContent): + allowed, label = ALLOWED_AUDIO_MIME, "音频" + elif isinstance(part, VideoContent): + allowed, label = ALLOWED_VIDEO_MIME, "视频" + else: # pragma: no cover - ContentPart 联合已由类型系统约束 + raise MediaRejected("不支持的分片类型", type(part).__name__) + + if candidate in allowed: + return candidate + fallback = guess_mime(getattr(part, "filename", "") or "") + if fallback in allowed: + return fallback + raise MediaRejected( + f"{label}类型不被接受", + f"收到 {candidate or '未知'},允许:{sorted(allowed)}", + ) + + +# --------------------------------------------------------------------------- +# 上限 +# --------------------------------------------------------------------------- + + +def format_size(num: int) -> str: + """人类可读的字节数(1 位小数)。""" + value = float(num) + for unit in ("B", "KB", "MB", "GB"): + if value < 1024 or unit == "GB": + return f"{value:.1f} {unit}" if unit != "B" else f"{int(value)} B" + value /= 1024 + return f"{int(num)} B" # pragma: no cover + + +@dataclass(frozen=True) +class MediaLimits: + """各类媒体的字节上限与下载参数。 + + 默认值是按「单进程内存占用 + 交互体验」权衡设定的**本项目策略值**, + 不是平台官方限制;部署时按实际内存调。 + """ + + image: int = 10 * MB + audio: int = 20 * MB + video: int = 50 * MB + file: int = 20 * MB + chunk: int = 64 * 1024 + """按块读取的块大小,决定下载时的内存粒度。""" + timeout: float = 30.0 + """单次远端下载的总超时(秒)。""" + + def for_part(self, part: ContentPart) -> int: + """返回该分片适用的字节上限。""" + if isinstance(part, ImageContent): + return self.image + if isinstance(part, AudioContent): + return self.audio + if isinstance(part, VideoContent): + return self.video + if isinstance(part, FileContent): + return self.file + raise TypeError(f"文本分片没有大小上限:{type(part).__name__}") + + +class MediaRejected(ValueError): + """媒体被安全策略拒绝。 + + ``reason`` 是给用户看的一句话,``detail`` 是给日志的技术细节。 + 调用方应把 ``player_reason`` 降级成文本提示,而不是向上抛异常打断整轮回复。 + """ + + def __init__(self, reason: str, detail: str = "") -> None: + self.reason = reason + self.detail = detail + super().__init__(f"{reason}({detail})" if detail else reason) + + @property + def player_reason(self) -> str: + """面向用户的简短说明。""" + return self.reason + + +# --------------------------------------------------------------------------- +# 受限读取 +# --------------------------------------------------------------------------- + + +def read_file_limited(path: Path, limit: int) -> bytes: + """读取本地文件,超过 ``limit`` 抛 :class:`MediaRejected`。 + + 只多读 1 字节用于判定越界,不会把超大文件整个读进内存。 + """ + if not path.exists(): + raise MediaRejected("文件不存在", str(path)) + if not path.is_file(): + raise MediaRejected("不是普通文件", str(path)) + with path.open("rb") as handle: + data = handle.read(limit + 1) + if len(data) > limit: + raise MediaRejected( + "媒体超过大小上限", f"大于 {format_size(limit)}(上限 {format_size(limit)})" + ) + return data + + +def decode_base64_limited(data: str, limit: int) -> bytes: + """解码 base64 内联字节,超过 ``limit`` 抛 :class:`MediaRejected`。 + + 先按 4/3 膨胀率粗判长度,避免为一个必然超限的字符串分配大缓冲。 + """ + if len(data) > (limit * 4) // 3 + 16: + raise MediaRejected("媒体超过大小上限", f"base64 长度 {len(data)}") + try: + raw = base64.b64decode(data, validate=False) + except (binascii.Error, ValueError) as exc: + raise MediaRejected("媒体 base64 解码失败", str(exc)) from exc + if len(raw) > limit: + raise MediaRejected( + "媒体超过大小上限", f"{format_size(len(raw))} > {format_size(limit)}" + ) + return raw + + +async def download_limited( + url: str, + *, + limit: int, + chunk: int = 64 * 1024, + timeout: float = 30.0, + headers: dict[str, str] | None = None, +) -> tuple[bytes, str]: + """流式下载远端媒体,``(bytes, content_type)``。 + + 两道闸:``Content-Length`` 提前拒绝(省一次完整下载),以及按块累计的 + 硬上限(服务端谎报长度或不分块时仍然生效)。 + + Raises: + MediaRejected: 超限。 + httpx.HTTPError: 网络/状态码错误,由调用方决定是否降级。 + """ + async with httpx.AsyncClient( + follow_redirects=True, timeout=timeout, headers=headers + ) as client, client.stream("GET", url) as resp: + resp.raise_for_status() + declared = resp.headers.get("content-length", "") + if declared.isdigit() and int(declared) > limit: + raise MediaRejected( + "媒体超过大小上限", + f"Content-Length {format_size(int(declared))} > {format_size(limit)}", + ) + buffer = bytearray() + async for piece in resp.aiter_bytes(chunk): + buffer.extend(piece) + if len(buffer) > limit: + raise MediaRejected( + "媒体超过大小上限", + f"下载超过 {format_size(limit)} 已中断", + ) + content_type = (resp.headers.get("content-type") or "").split(";")[0].strip() + return bytes(buffer), content_type or "" + + +# --------------------------------------------------------------------------- +# 文件名与落盘路径 +# --------------------------------------------------------------------------- + +_UNSAFE_CHARS = re.compile(r"[^\w.\- ]+", re.UNICODE) +_DOTS = re.compile(r"\.{2,}") + + +def sanitize_filename(name: str, *, default: str = "media.bin", max_len: int = 120) -> str: + """把平台给的文件名净化成可安全落盘的单段名字。 + + 处理顺序:NFKC 归一(同形字)→ 去掉路径成分 → 替换控制字符与分隔符 → + 合并连续点(``..`` 穿越)→ 去首尾空白与点 → 截断。 + + 返回的值**不含目录分隔符**,仍须经 :func:`safe_join` 拼接。 + """ + raw = unicodedata.normalize("NFKC", name or "") + # 只取最后一段:同时覆盖 "/" 与 "\\" + raw = raw.replace("\\", "/").split("/")[-1] + raw = "".join(ch for ch in raw if ch.isprintable() and ch not in "\x00") + raw = _UNSAFE_CHARS.sub("_", raw) + raw = _DOTS.sub(".", raw).strip(" .") + if not raw: + return default + if len(raw) > max_len: + stem, dot, suffix = raw.rpartition(".") + if dot and len(suffix) <= 10: + keep = max(1, max_len - len(suffix) - 1) + raw = f"{stem[:keep]}.{suffix}" + else: + raw = raw[:max_len] + return raw or default + + +def safe_join(root: Path, filename: str) -> Path: + """把单段文件名拼到 ``root`` 下,并确认解析结果仍在 ``root`` 内。 + + ``root`` 不存在时按父目录解析——落盘前由调用方 ``mkdir``。 + + Raises: + MediaRejected: 路径逃出 ``root``。 + """ + base = root.resolve() + name = sanitize_filename(filename) + candidate = (base / name).resolve() + if candidate != base and base not in candidate.parents: + raise MediaRejected("落盘路径非法", f"{name!r} 解析到 {candidate}") + if candidate == base: + raise MediaRejected("落盘路径非法", f"{name!r} 解析为目录本身") + return candidate + + +# --------------------------------------------------------------------------- +# 入站落盘 +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class StoredMedia: + """一次入站落盘的结果。""" + + part: ContentPart + """更新后的分片:``local_path`` 已填、``url``/``data`` 已清空。""" + path: Path + size: int + mime: str + sha256: str + + +def _default_name_for(part: ContentPart, mime: str) -> str: + """没有文件名时按类型与 MIME 造一个。""" + ext = mimetypes.guess_extension(mime) if mime else None + if isinstance(part, ImageContent): + return f"image{ext or '.bin'}" + if isinstance(part, AudioContent): + return f"audio{ext or '.bin'}" + if isinstance(part, VideoContent): + return f"video{ext or '.bin'}" + if isinstance(part, FileContent) and part.filename: + return part.filename + return f"file{ext or '.bin'}" + + +async def store_media( + part: ContentPart, + *, + root: Path, + limits: MediaLimits | None = None, + session_key: str = "", + headers: dict[str, str] | None = None, +) -> StoredMedia: + """把媒体分片落盘到 ``root//``,返回更新后的分片。 + + 字节来源优先级与 ``BaseChannel.load_media_bytes`` 一致 + (``data`` → ``local_path`` → ``url``),但每一步都带大小闸; + 落盘后分片只保留 ``local_path``,让下游(智能体、出站回显)共用一份字节。 + + Raises: + MediaRejected: 超限、类型不符、路径非法。 + httpx.HTTPError: 远端下载失败(调用方降级为文本提示)。 + """ + limits = limits or MediaLimits() + if isinstance(part, TextContent): + raise TypeError("store_media 不能用于文本分片") + + limit = limits.for_part(part) + mime_declared = (part.mime_type or "").split(";")[0].strip().lower() + name_hint = getattr(part, "filename", "") or "" + + if part.data: + raw = decode_base64_limited(part.data, limit) + mime = check_mime(part, mime_declared or guess_mime(name_hint) or "", raw[:32]) + elif part.local_path: + source = Path(part.local_path) + raw = read_file_limited(source, limit) + mime = check_mime(part, mime_declared or guess_mime(str(source)) or "", raw[:32]) + name_hint = name_hint or source.name + elif part.url: + raw, fetched = await download_limited( + part.url, + limit=limit, + chunk=limits.chunk, + timeout=limits.timeout, + headers=headers, + ) + mime = check_mime(part, mime_declared or fetched or guess_mime(name_hint) or "", raw[:32]) + else: + raise MediaRejected("媒体缺少字节来源", "data/local_path/url 三者皆空") + + folder = root + if session_key: + folder = root / sanitize_filename(session_key, default="session", max_len=60) + folder.mkdir(parents=True, exist_ok=True) + + target = safe_join(folder, sanitize_filename(name_hint) if name_hint else _default_name_for(part, mime)) + digest = hashlib.sha256(raw).hexdigest() + # 同名不同内容时加哈希前缀,避免后到的覆盖先到的(也避免穿越后仍撞名) + if target.exists(): + target = safe_join(folder, f"{digest[:12]}-{target.name}") + + # 写临时文件再原子改名:中途失败不会留下半份字节 + temp = target.with_name(target.name + ".part") + temp.write_bytes(raw) + temp.replace(target) + + updated = part.model_copy(update={"local_path": str(target), "url": "", "data": None, + "size": len(raw), "mime_type": mime}) + return StoredMedia(part=updated, path=target, size=len(raw), mime=mime, sha256=digest) diff --git a/src/bot042/channels/models.py b/src/bot042/channels/models.py index e3b4500..55e46a3 100644 --- a/src/bot042/channels/models.py +++ b/src/bot042/channels/models.py @@ -268,6 +268,32 @@ class MessageEvent(BaseModel): """ERROR 事件:携带错误消息。""" return cls(type=MessageEventType.ERROR, error=message) + @classmethod + def content_event(cls, parts: list[ContentPart], **kwargs: Any) -> MessageEvent: + """MESSAGE 事件:一次投递任意分片组合(文本 + 图片/文件/音视频)。 + + 出站管线(``BaseChannel._deliver_event``)已按「先文本、再逐个媒体」 + 下发媒体分片,这里只是让调用方能真正构造出带媒体的 MESSAGE 事件—— + 在此之前 :class:`MediaContent` 在 ``src/`` 内没有任何构造入口。 + + 示例:: + + yield MessageEvent.content_event([ + TextContent(text="这是你要的图"), + ImageContent(local_path="/tmp/a.png", mime_type="image/png"), + ]) + """ + return cls(type=MessageEventType.MESSAGE, content=list(parts), **kwargs) + + @classmethod + def media_event(cls, media: MediaContent, caption: str = "", **kwargs: Any) -> MessageEvent: + """MESSAGE 事件:单个媒体分片,可选配一句说明文本。""" + parts: list[ContentPart] = [] + if caption: + parts.append(TextContent(text=caption)) + parts.append(media) + return cls(type=MessageEventType.MESSAGE, content=parts, **kwargs) + # --------------------------------------------------------------------------- # 总线事件载荷 diff --git a/src/bot042/flows/agent_task.py b/src/bot042/flows/agent_task.py index 375086b..6b02c87 100644 --- a/src/bot042/flows/agent_task.py +++ b/src/bot042/flows/agent_task.py @@ -17,8 +17,14 @@ from bot042.agent.middlewares.budget import unbind as unbind_budget from bot042.agent.middlewares.steering import SteeringBuffer from bot042.agent.middlewares.steering import bind as bind_steering from bot042.agent.middlewares.steering import unbind as unbind_steering +from bot042.agent.outbox import MediaOutbox +from bot042.agent.outbox import bind as bind_outbox +from bot042.agent.outbox import unbind as unbind_outbox from bot042.config import Settings +TaskInput = str | list[dict[str, Any]] +"""任务输入:纯文本,或 langchain 多模态内容块列表(图片 base64 + 文本)。""" + if TYPE_CHECKING: from langgraph.graph.state import CompiledStateGraph @@ -43,6 +49,13 @@ def _content_text(content: object) -> str: return "" +def _preview(task: TaskInput) -> str: + """日志用的任务摘要:多模态时只取文本块,避免把 base64 打进日志。""" + if isinstance(task, str): + return task + return _content_text(task) + + def _run_config(settings: Settings) -> dict[str, Any]: """图调用配置:硬步数上限 = 软预算 + 余量(见 ``Settings.recursion_limit``)。""" return {"recursion_limit": settings.recursion_limit} @@ -80,12 +93,13 @@ class AgentCache: async def run_task( - task: str, + task: TaskInput, settings: Settings | None = None, history: list[dict[str, str]] | None = None, *, cache: AgentCache | None = None, steering: SteeringBuffer | None = None, + outbox: MediaOutbox | None = None, ) -> dict[str, Any]: """异步执行单个任务,返回智能体最终状态(含 messages)。 @@ -95,6 +109,8 @@ async def run_task( history: 历史消息(不含本轮)。 cache: 智能体缓存;给定则复用其中的实例,缺省每次新建(一次性调用用)。 steering: 插话缓冲;给定则该次运行期间的插话会在下一轮模型调用前注入。 + outbox: 出站媒体信箱;给定则本次运行中 ``send_image`` / ``send_file`` + 登记的附件留在其中,由调用方取走下发。 Raises: StepBudgetExceeded: 图步数硬上限被耗尽(软预算的收尾提示没起作用)。 @@ -103,9 +119,10 @@ async def run_task( agent = cache.get(settings) if cache is not None else create_agent(settings) messages = list(history or []) messages.append({"role": "user", "content": task}) - logger.debug("执行任务:%s", task) + logger.debug("执行任务:%s", _preview(task)) token = bind_steering(steering) if steering is not None else None + out_token = bind_outbox(outbox) if outbox is not None else None budget_token = bind_budget(StepBudget(settings.agent_rounds)) try: return await agent.ainvoke( @@ -117,6 +134,8 @@ async def run_task( raise StepBudgetExceeded(settings.max_steps) from exc finally: unbind_budget(budget_token) + if out_token is not None: + unbind_outbox(out_token) if token is not None: unbind_steering(token) @@ -130,12 +149,13 @@ class _Round: async def stream_task( - task: str, + task: TaskInput, settings: Settings | None = None, history: list[dict[str, str]] | None = None, *, cache: AgentCache | None = None, steering: SteeringBuffer | None = None, + outbox: MediaOutbox | None = None, ) -> AsyncIterator[str]: """流式执行任务,逐步产出**累积文本**(不是增量)。 @@ -152,6 +172,7 @@ async def stream_task( history: 历史消息(不含本轮)。 cache: 智能体缓存;给定则复用其中的实例。 steering: 插话缓冲;给定则该次运行期间的插话会在下一轮模型调用前注入。 + outbox: 出站媒体信箱;给定则登记其中(流式路径不重复发送)。 Raises: StepBudgetExceeded: 图步数硬上限被耗尽;调用方可用已产出的部分文本拼提示。 @@ -160,9 +181,10 @@ async def stream_task( agent = cache.get(settings) if cache is not None else create_agent(settings) messages = list(history or []) messages.append({"role": "user", "content": task}) - logger.debug("流式执行任务:%s", task) + logger.debug("流式执行任务:%s", _preview(task)) token = bind_steering(steering) if steering is not None else None + out_token = bind_outbox(outbox) if outbox is not None else None budget_token = bind_budget(StepBudget(settings.agent_rounds)) rounds: dict[str, _Round] = {} order: list[str] = [] @@ -194,5 +216,7 @@ async def stream_task( raise StepBudgetExceeded(settings.max_steps) from exc finally: unbind_budget(budget_token) + if out_token is not None: + unbind_outbox(out_token) if token is not None: unbind_steering(token) diff --git a/src/bot042/flows/builtin.py b/src/bot042/flows/builtin.py index 2bb6216..9da96c4 100644 --- a/src/bot042/flows/builtin.py +++ b/src/bot042/flows/builtin.py @@ -25,7 +25,9 @@ from bot042.agent.middlewares.steering import SteeringBuffer from bot042.channels.manager import ChannelManager from bot042.channels.models import ( ChannelMessage, + ContentPart, InboundMessage, + OutboundContent, OutboundStream, OutboundText, ) @@ -144,6 +146,33 @@ class ChannelServices: return await self.channels.send_text(channel_id, subject_id, text) + async def send_content( + self, + channel_id: str, + subject_id: str, + parts: list[ContentPart], + *, + metadata: dict[str, Any] | None = None, + ) -> None: + """发送富内容(文本 + 媒体);出站管线按分片顺序下发。 + + 媒体分片自带 ``local_path``(入站落盘或智能体工具产出), + 平台侧由 ``_send_media`` 上传后按原生消息投递。 + """ + if self.hub is not None: + _ = await self.hub.call( + RPC_SEND, + OutboundContent( + channel_id=channel_id, + subject_id=subject_id, + parts=parts, + metadata=dict(metadata or {}), + ), + timeout=self.send_timeout, + ) + return + await self.channels.send_content(channel_id, subject_id, parts) + async def stream_text( self, channel_id: str, diff --git a/src/bot042/flows/media_input.py b/src/bot042/flows/media_input.py new file mode 100644 index 0000000..cba7747 --- /dev/null +++ b/src/bot042/flows/media_input.py @@ -0,0 +1,251 @@ +"""入站媒体 → 智能体上下文:落盘、降级与多模态内容块。 + +这是 issue #1 断点 1 的实现层:媒体消息不再被"暂仅支持文本"挡在门外, +而是按类型分三条路进入上下文: + +==================== ========================================================== +类型 进入上下文的方式 +==================== ========================================================== +图片(小) ``image_url`` 块(data URI,base64 内联) +图片(大/超量) 文本说明 + 落盘路径,模型可用文件工具自行读取 +文本类文件 抽取的正文(有字符上限),进 ``text`` 块 +音视频 / 二进制文件 元信息(类型、大小、时长)+ 落盘路径 +==================== ========================================================== + +**为什么不一概内联**:base64 进上下文会按 ~1.33 倍膨胀,一张 10MB 的图足以 +吃光窗口;因此内联有独立的字节与数量上限(:class:`InlinePolicy`),超过就 +退化成"路径 + 元信息",把"读不读、怎么读"交给模型按需处理。 + +**失败一律降级,不上抛**:单个附件超限/类型拒绝/下载失败只记录一条 +``notes``,其余附件与该消息的文本照常进入上下文。用户看到的是部分可用, +而不是整轮报错。 +""" + +from __future__ import annotations + +import base64 +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +import httpx + +from bot042.channels.media import ( + MB, + MediaLimits, + MediaRejected, + format_size, + store_media, +) +from bot042.channels.models import ( + AudioContent, + ContentPart, + FileContent, + ImageContent, + InboundMessage, + TextContent, + VideoContent, +) + +__all__ = ["InlinePolicy", "PreparedInbound", "prepare_inbound"] + +_TEXT_MIME_PREFIXES = ("text/",) +_TEXT_EXTENSIONS = frozenset( + { + ".txt", ".md", ".csv", ".tsv", ".json", ".yaml", ".yml", ".toml", ".ini", + ".log", ".py", ".js", ".ts", ".html", ".htm", ".xml", ".sql", ".sh", + ".cfg", ".conf", ".rst", ".tex", + } +) + + +@dataclass(frozen=True) +class InlinePolicy: + """图片内联进上下文的策略。 + + ``max_bytes`` 与 ``max_count`` 是**本项目策略值**,用于换取上下文可用性, + 不是平台限制。超出的图片退化为路径说明,功能不丢失。 + """ + + max_bytes: int = 2 * MB + max_count: int = 4 + max_text_chars: int = 20000 + """文本类文件抽取的字符上限(超出截断并注明)。""" + + +@dataclass +class PreparedInbound: + """入站消息的智能体可用形态。""" + + text: str + """纯文本部分(所有 ``TextContent`` 拼接)。""" + blocks: list[dict[str, Any]] = field(default_factory=list) + """发给模型的内容块(langchain 多模态格式)。仅文本时为一个 text 块; + 文本与附件都没有时为空列表(不留占位块)。""" + summary: str = "" + """用于落库的文本(正文 + 附件清单),不含字节。""" + notes: list[str] = field(default_factory=list) + """降级说明(超限 / 类型拒绝 / 下载失败),会并入 summary。""" + stored: list[Path] = field(default_factory=list) + + @property + def has_content(self) -> bool: + """是否拿到了任何可进上下文的内容(文本或附件)。 + + **不要**为了"总是有个块"而塞占位文本:占位块会让本属性恒为真,空消息 + 就再也走不到拒绝分支,用户发个空白消息会白白烧掉一轮模型调用。 + """ + return bool(self.text.strip()) or bool(self.blocks) or bool(self.stored) + + @property + def is_multimodal(self) -> bool: + """除正文块之外还有别的内容块(即确实带了附件)。 + + 用来决定交给模型的是内容块列表还是纯文本:``len(blocks) > 1`` 这种判断 + 在"只有一张图、没有正文"时会退化成纯文本,把附件整个丢掉。 + """ + body_blocks = 1 if self.text else 0 + return len(self.blocks) > body_blocks + + +def _is_text_file(part: FileContent) -> bool: + mime = (part.mime_type or "").lower() + if any(mime.startswith(p) for p in _TEXT_MIME_PREFIXES): + return True + return Path(part.filename or "").suffix.lower() in _TEXT_EXTENSIONS + + +def _decode_text(raw: bytes, limit: int) -> str | None: + """尝试把字节当 UTF-8 文本解码;含 NUL 或解码失败时返回 ``None``。""" + head = raw[:limit] + if b"\x00" in head: + return None + try: + return head.decode("utf-8") + except UnicodeDecodeError: + try: + return head.decode("gb18030") + except UnicodeDecodeError: + return None + + +def _media_label(part: ContentPart) -> str: + if isinstance(part, ImageContent): + return "图片" + if isinstance(part, AudioContent): + return "音频" + if isinstance(part, VideoContent): + return "视频" + if isinstance(part, FileContent): + return f"文件 {part.filename or ''}".strip() + return "媒体" + + +def _describe(part: ContentPart, size: int, mime: str, path: Path) -> str: + """生成给模型看的附件说明行(不含字节)。""" + bits = [f"{_media_label(part)}", f"{format_size(size)}", mime or "未知类型"] + duration = getattr(part, "duration", None) + if isinstance(duration, int) and duration > 0: + bits.append(f"{duration / 1000:.1f}s") + return f"{' / '.join(bits)},已保存到 {path}" + + +async def prepare_inbound( + message: InboundMessage, + *, + root: Path, + limits: MediaLimits | None = None, + policy: InlinePolicy | None = None, + headers: dict[str, str] | None = None, +) -> PreparedInbound: + """把入站消息整理成 ``(text, blocks, summary, notes)``,媒体先落盘。 + + Args: + message: 入站消息。 + root: 媒体落盘根目录(按会话建子目录)。 + limits: 字节上限;缺省 :class:`MediaLimits`。 + policy: 图片内联策略;缺省 :class:`InlinePolicy`。 + headers: 下载远端媒体时附带的请求头(平台鉴权由渠道提供)。 + + Returns: + :class:`PreparedInbound`。附件层面的失败只进 ``notes``,不抛异常。 + """ + limits = limits or MediaLimits() + policy = policy or InlinePolicy() + + text = message.text.strip() + prepared = PreparedInbound(text=text) + blocks: list[dict[str, Any]] = [] + descriptions: list[str] = [] + inline_images = 0 + session_key = message.db_session_id + + for part in message.content: + if isinstance(part, TextContent): + continue + try: + stored = await store_media( + part, + root=root, + limits=limits, + session_key=session_key, + headers=headers, + ) + except MediaRejected as exc: + prepared.notes.append(f"{_media_label(part)}未接收:{exc.reason}") + continue + except (httpx.HTTPError, OSError) as exc: + prepared.notes.append( + f"{_media_label(part)}未接收:下载失败({type(exc).__name__})" + ) + continue + + prepared.stored.append(stored.path) + description = _describe(part, stored.size, stored.mime, stored.path) + descriptions.append(description) + + if isinstance(stored.part, ImageContent) and stored.mime.startswith("image/"): + if stored.size <= policy.max_bytes and inline_images < policy.max_count: + payload = base64.b64encode(stored.path.read_bytes()).decode("ascii") + blocks.append( + { + "type": "image_url", + "image_url": {"url": f"data:{stored.mime};base64,{payload}"}, + } + ) + inline_images += 1 + else: + blocks.append( + {"type": "text", "text": f"[图片未内联] {description}(可用文件工具读取)"} + ) + continue + + if isinstance(stored.part, FileContent) and _is_text_file(stored.part): + raw = stored.path.read_bytes()[: policy.max_text_chars * 4] + decoded = _decode_text(raw, policy.max_text_chars * 4) + if decoded: + clipped = decoded[: policy.max_text_chars] + suffix = "" if len(decoded) <= policy.max_text_chars else "\n…(内容已截断)" + blocks.append( + { + "type": "text", + "text": f"【附件 {stored.part.filename or stored.path.name}】\n{clipped}{suffix}", + } + ) + continue + + blocks.append({"type": "text", "text": f"【附件】{description}(可用文件工具读取)"}) + + # 正文块一定排在最前:多数模型对首块是文本的提示更稳 + if text: + blocks.insert(0, {"type": "text", "text": text}) + # 无任何内容时 blocks 保持为空:占位块会让 has_content 恒真,见该属性的说明 + prepared.blocks = blocks + + summary_parts = [text] if text else [] + if descriptions: + summary_parts.append("[附件] " + ";".join(descriptions)) + if prepared.notes: + summary_parts.append("[降级] " + ";".join(prepared.notes)) + prepared.summary = "\n".join(p for p in summary_parts if p).strip() + return prepared diff --git a/src/bot042/flows/processor.py b/src/bot042/flows/processor.py index 7b65503..f509c29 100644 --- a/src/bot042/flows/processor.py +++ b/src/bot042/flows/processor.py @@ -27,6 +27,7 @@ from bot042.config import Settings from bot042.db import repo from bot042.db.schema import init_db from bot042.flows.agent_task import AgentCache, last_message_text, run_task +from bot042.flows.media_input import prepare_inbound logger = logging.getLogger(__name__) @@ -89,6 +90,7 @@ def make_processor( """ settings = settings or Settings.from_env() db_file = Path(db) if db is not None else settings.database + media_root = settings.home / "data" / "inbound" db_ready = False # 智能体按处理器复用:图构建开销大,每条消息重建是纯浪费 agent_cache = AgentCache() @@ -97,10 +99,17 @@ def make_processor( nonlocal db_ready yield MessageEvent.typing() - text = message.text.strip() - if not text: - yield MessageEvent.error_event("(空消息,已忽略)" if not message.has_media else "暂仅支持文本消息") + # 媒体先落盘再进上下文:小图内联、大图与音视频退化为「路径 + 元信息」。 + # 附件级失败只降级为说明,不打断整轮(见 media_input.prepare_inbound)。 + prepared = await prepare_inbound(message, root=media_root) + if not prepared.has_content: + # 有附件但全部没接收成功:说清原因,别让用户以为是「发了条空消息」 + if prepared.notes: + yield MessageEvent.error_event("附件未能接收:" + ";".join(prepared.notes)) + else: + yield MessageEvent.error_event("(空消息,已忽略)") return + text = prepared.summary session_id, channel = _session_key(message) try: @@ -115,7 +124,12 @@ def make_processor( await repo.add_message( db_file, session_id=session_id, role="user", content=text, channel=channel ) - result = await run_task(text, settings, history=history, cache=agent_cache) + # 只有正文时发纯文本,带附件才发多模态块列表;用 blocks 数量猜会 + # 在「只有一张图、没有正文」时把附件丢掉(见 PreparedInbound.is_multimodal) + task_input = prepared.blocks if prepared.is_multimodal else text + result = await run_task( + task_input, settings, history=history, cache=agent_cache + ) answer = last_message_text(result) if answer: await repo.add_message( diff --git a/tests/test_processor.py b/tests/test_processor.py index cb2197e..0ab0e83 100644 --- a/tests/test_processor.py +++ b/tests/test_processor.py @@ -16,6 +16,7 @@ from bot042.channels.models import ( ) from bot042.db import repo from bot042.flows import processor as processor_mod +from bot042.flows.media_input import PreparedInbound from bot042.flows.processor import make_processor @@ -210,7 +211,7 @@ def test_build_history_rules() -> None: ] -def test_processor_rejects_empty_and_media( +def test_processor_rejects_empty_message( monkeypatch: pytest.MonkeyPatch, tmp_path: Path ) -> None: async def fake_run_task(task, settings=None, history=None, *, cache=None): # pragma: no cover @@ -223,6 +224,55 @@ def test_processor_rejects_empty_and_media( assert events[-1].type == MessageEventType.ERROR assert "空消息" in (events[-1].error or "") + +def test_processor_explains_unreadable_attachments( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """附件全部没接收成功:给附件级说明,不要含糊成「空消息」。""" + + async def fake_prepare(message, *, root, **kwargs): + _ = message, root, kwargs + return PreparedInbound(text="", notes=["图片未接收:超过大小上限"]) + + async def fake_run_task(task, settings=None, history=None, *, cache=None): # pragma: no cover + raise AssertionError("不应执行任务") + + monkeypatch.setattr(processor_mod, "prepare_inbound", fake_prepare) + monkeypatch.setattr(processor_mod, "run_task", fake_run_task) + processor = make_processor(db=tmp_path / "bot.db") + events = _events(processor, _message("", media=True)) assert events[-1].type == MessageEventType.ERROR - assert "仅支持文本" in (events[-1].error or "") + error = events[-1].error or "" + assert "附件未能接收" in error + assert "超过大小上限" in error + + +def test_processor_sends_blocks_for_attachment_only_message( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """只有一张图、没有正文时也必须发多模态块,否则附件被静默丢掉。""" + + async def fake_prepare(message, *, root, **kwargs): + _ = message, root, kwargs + return PreparedInbound( + text="", + blocks=[ + {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA=="}} + ], + ) + + seen: list[object] = [] + + async def fake_run_task(task, settings=None, history=None, *, cache=None): + seen.append(task) + return {"messages": [{"role": "assistant", "content": "看到了"}]} + + monkeypatch.setattr(processor_mod, "prepare_inbound", fake_prepare) + monkeypatch.setattr(processor_mod, "run_task", fake_run_task) + processor = make_processor(db=tmp_path / "bot.db") + + events = _events(processor, _message("", media=True)) + assert isinstance(seen[0], list) + assert seen[0][0]["type"] == "image_url" + assert events[-1].type == MessageEventType.COMPLETED