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
+738 -18

No files matched your search

+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