fix(image): 支持 HEIC/HEIF 上传，并堵住静态图被误当视频处理的静默路径

[ExWang]

要解决的问题

iPhone 相机自 iOS 11 起默认存 HEIC，而 cv2.imdecode 解不了它。已在部署机复现，两个端点都是硬失败：

通路	改前
pet observe --images x.HEIC（Agent 注册主流程）	400 无法解码上传的图片（仅支持常见 jpg/png/webp 格式）
pet avatar --image x.HEIC	400 无法识别的图片
Web 上传素材做分析	同上 400

命中面是「照片先落到电脑再上传」——AirDrop 到 Mac、数据线/iCloud 下载、以及 Agent 走 CLI 读本地文件，这三条都保留 HEIC。在 iPhone 上直接用 web 传通常不受影响（iOS 相册选择器一般会转 JPEG）。

另一件事：一条今天就在损坏的静默路径

这条与 HEIC 支持没有因果关系，是修上面那个问题时顺着查出来的，独立成立：

flowchart LR
  A["identity register preview<br/>--image x.HEIC"] --> B["cli/identity.py<br/>只看 4..8 == ftyp<br/>判成 mp4/mov"]
  B --> C["报错文案指示<br/>请改用 --video"]
  C --> D["SKILL.md 要求 agent<br/>按提示自我纠正"]
  D --> E["person/router.py<br/>信客户端自报 media_kind<br/>不嗅一个字节"]
  E --> F["ffmpeg 不拼 HEIC 的 tile grid<br/>只暴露 512x512 瓦片"]
  F --> G["200 no valid subject<br/>零提示"]

Loading

HEIF/AVIF 与 mp4/mov 共用同一套 ISO BMFF 容器，只靠「字节 4..8 == ftyp」判不出图与视频。而这个误判会被 CLI 的报错文案和 SKILL 的纠错表放大成一次「自我纠正」，把照片送进视频抽帧路径。ffmpeg 把一张 3024×4032 的 HEIC 暴露成 61 条独立 hevc 流（60 块 512×512 瓦片 + 1 张 320×240 缩略图），不做 grid 拼接，于是流水线在一块瓦片上跑完全程、不报任何错。

Agent 于是告诉住户「没识别到人，换张素材」——这是假话，真实原因是格式被误路由。

修法是按容器品牌区分，接在三处：CLI 判据、pet observe 读到字节后复核、person register/preview 复核客户端自报的 media_kind。两个 SKILL.md 的话术同步更新（Agent 照它告诉住户能传什么）。

改动

解码单一入口 — 新增 identity/_image_utils.decode_image()：cv2 快路径（jpg/png/webp/bmp/tiff/gif/avif）→ Pillow(pi-heif) 回退。接到全部 9 处「用户原始字节」入口（person/router.py 7 处 + pet/observe.py 1 处 + _avatar.normalize_for_storage 1 处，后者被三个存储端点共用）。

它对外的契约是「解不出返回 None、不抛」，两条支都守住：cv2.imdecode 对超出 OpenCV 自身尺寸上限的图是 CV_Assert 抛 cv2.error（一个 29 字节的 GIF 头就能声明 40000×40000 触发），不接住会让这 9 个入口把本该 400 的请求变成 500。

解码本身一律经 asyncio.to_thread：格式放开后 HEIC 走 libheif 是几百毫秒量级（改前只解 jpg/png 是几十毫秒），而后端是单进程 asyncio、同一个循环上还跑着直播转码 / 录制切片 / MQTT 感知推理。这条口径由一条扫源码的测试钉住，新增裸调直接红。

落盘归一化 — 新增 _avatar.normalize_for_storage()：jpg/png/webp 原字节直通（先完整解码验真——只查魔数不够，\xff\xd8\xff 后接垃圾同样命中前 3 字节，直通落盘后识别侧解不出、界面会显示「3 张参考图」而实际注入 0 张）。其余格式解码后重编，并按用途封顶长边：

• 头像 256 + 无损 WebP。256 不是拍脑袋的数——它就是 web 裁剪器 AvatarCropEditor.OUT，让 CLI/API 的重编支与 web 主路径产出同规格；有跨端对齐测试守着，改一侧不改另一侧就红。实测 12MP HEIC：不封顶 5.26MB、封到 1024 是 0.56MB、封到 256 是 50KB，与 web 裁剪器产物的 20–50KB 同量级。改前非白名单格式一律 400，落盘物件被 5MB 上传闸隐含夹住；本 PR 放开了格式，就得自己补回这个上界。
• 宠物参考图 640 + JPEG q90。它唯一的消费者是 omni，而 pet_refs 拼图时恒缩到高 320 并重编 JPEG q85——640 留了一倍余量，存 WebP 只是多一道转换；且 ref_crop_N.jpg 的硬编码后缀牵动 glob 与下标解析，不宜与内容脱钩。

封顶只作用于重编支，白名单直通仍逐字节不动。

行为扩面 — BMP/TIFF/GIF/AVIF 原先能过 observe 却被头像/参考图端点 400。这条「observe 宽、存储窄」的不对称正是本轮一半文案要改的根源，一并消掉（归一化成 webp）。相应改了 test_person_router_avatar 里那条用真 BMP 断言 400 的用例。

资源与安全 — 解码后像素量加上限：字节闸挡不住解码炸弹，HEIF 的网格容器能让小文件解出上亿像素。imencode 加 ok 判定：WebP 边长 >16383 时它返回 ok=False 且只往 stderr 打一行，不判就会把空字节当图落盘。

依赖选型

选 pi-heif 而非更常见的 pillow-heif：

	PyPI 分类器	捆绑的编解码器
pillow-heif 1.5.0	GPLv2	libheif + x265 编码器
pi-heif 1.4.0	LGPLv3	libheif + libde265，仅解码

我们只需要解码，拿不到编码器零损失。已核实：1.4.0 在 py3.11–3.14 × darwin/linux/windows 五个平台均有 wheel、不会退化成源码编译（部署机的 tool env 是 py3.14）；register_heif_opener() 不影响 Pillow 12 自带的 AVIF 插件。

绕不开这个依赖：ffmpeg 只暴露瓦片（见上一节），Pillow 12 的 features.check("heif") 是 False。

一个副作用值得记：pi-heif 不能编码 HEIF（正是它 LGPLv3 的原因），所以测试无法现造 HEIC fixture，用了 466 字节的 base64 常量内嵌，不引二进制资产。

验证

部署机端到端复测（改动已装到 tool env，pi_heif + decode_image 都在已装 wheel 里）：

通路	改前	改后
pet observe --images x.HEIC	400	code: 0，warnings: []（图确实被解开）
pet avatar --image x.HEIC	400	200，avatar_ext: "webp"
identity register preview --image x.HEIC	CLI exit 1「请改用 --video」	code: 0，走图片路径

同一只狗的照片，HEIC 与 JPEG 各跑一遍完整链路（解码 → YOLO → 门控 → omni）：

HEIC : detected=True 候选=1 warnings=[] species=狗
       summary=一只白色短毛狗，最显著特征是双耳外侧有明显的黑色斑块，鼻头粉色带黑色斑点。
JPEG : detected=True 候选=1 warnings=[] species=狗
       summary=一只白色短毛狗，最显著特征是双耳外侧有明显的黑色斑块，鼻头粉色带黑斑。

检测置信度两边都是 0.957，crop 尺寸一致；描述末尾用词差异来自模型生成的随机性。

朝向做了像素级比对：以 sips 导出的 JPEG 走 cv2 作参照，相关系数 0.9998，三个旋转对照都趋近 0。这里踩过一个坑并修掉——起初按 pi-heif 的 info["original_orientation"] 自己转向，结果把苹果 HEIC 转了两次变成横图（libheif 已按 irot 转好，而该键仍带原值）。已把「为什么不能信这个键」写进 docstring。

测试 新增 37 个测试函数（含 7 处 parametrize 展开）：HEIC 解码与 BGR 通道序、既有 7 种格式不回归、白名单逐字节直通、合法魔数 + 坏 body 必拒、超大图不抛、像素炸弹（快路径与回退各一组）、重编封顶分档、brand 判定表全覆盖 + CLI 与后端两份手工表的字面量快照与交叉一致性、两侧误路由回归、以及「解码不得留在事件循环上」的结构性护栏。均已负向验证——退回对应实现后各自会红。

后端 3284 passed（4 个失败已确认在未改动的 main 上同样红）、CLI 579 passed、ruff check 全绿。

已知限制

• AVIF 竖拍可能仍是歪的：cv2 能解 AVIF 但不应用它的 EXIF Orientation（实测 4.13），而 AVIF 走 cv2 快路径、回退不触发。属既有行为，本 PR 不改快路径判据以免动到所有既有格式的解码结果。

• 非苹果 HEIF 的 EXIF-only 方向不支持：若某个编码器只用 EXIF 记方向、不写 irot，pi-heif 的无条件重置会让它解出来是歪的，且无法与「已转好」区分。取舍上保住绝对多数的苹果 HEIC。

• Web 手动换头像仍不支持 HEIC：那条路是 AvatarCropEditor 用 <img> + canvas 渲染源文件，Chrome/Firefox 解不了 HEIC（Safari 17+ 可以），且它恒导出 256×256 JPEG 才发给后端——所以后端改动对它无效，需要前端配合，不在本 PR 范围。

• Web 上传 HEIC 做观测：能传通，但看不到本地缩略图。PetAutoGenFlow 对图片走 FileReader.readAsDataURL 后直接把 data:image/heic;base64,… 交给 <img>（不经 canvas），Chrome/Firefox 渲染成空白，且 onerror 已 resolve("")、不出提示。这条是本 PR 带来的观感变化：改前这条路后端 400、住户至少看得到一句错误；现在字节能完整送达、观测正常返回，唯一残留的可见异常就变成了那张空白图。后端分析不受影响（候选 crop 由后端回传并正常显示），修它需要前端补一层解码或兜底文案，不在本 PR 范围。

给维护者

dependency-guard 会因 pyproject.toml + uv.lock 变更而阻塞，需要评论放行：

（放行口令须由维护者以评论形式发出，写在本正文里 dependency-guard 读不到——它只扫 issue comments。当前 head 的口令见下方评论。）

另：仓库目前没有 NOTICE / 第三方许可清单，而 LICENSE.md 写的是「entire content ... exclusively owned by Xiaomi」。这句话相对已捆绑的第三方原生库本来就不够准确——av 的 wheel 里带着编入 libx264/libx265 的 FFmpeg，opencv-python-headless 也自带一份。pi-heif 的 LGPLv3 不构成新的合规类别（比现状更轻），且平台归档里只有 miloco 自己的 3 个 wheel、不分发第三方二进制。补 NOTICE 属既有事项，没塞进本 PR。

[github-actions]

👋 感谢提交 PR @ExWang！维护者会尽快 review。

提交前请确认：

• CI 全绿（test / lint / build）
• 改动聚焦单一主题，便于审阅
• 若改动了依赖（lockfile / pyproject.toml / package.json），需维护者评论 /allow-dependencies-change <当前 head SHA> 放行（之后再 push 需重新放行）

[github-actions]

[PR #505]: fix(image): 支持 HEIC/HEIF 上传，并堵住静态图被误当视频处理的静默路径

作者: ExWang
范围: fix/pet-image-format-heic → main（+1073/-91，19 文件）

修改方案

要解决的问题

iPhone 自 iOS 11 起相机默认存 HEIC，而后端所有图片入口都只走 OpenCV 解码，解不了这个格式——照片经 AirDrop / 数据线 / iCloud 落到电脑再上传（以及 Agent 走 CLI 读本地文件）时全线 400。修这个问题时顺带查出一条独立成立的静默损坏路径：HEIF 与 mp4/mov 共用同一套 ISO BMFF 容器，只看「第 4~8 字节是 ftyp」判不出图与视频，而客户端自报的媒体类型后端从不复核；照片于是被送进视频抽帧路径，ffmpeg 又不拼 HEIC 的瓦片网格，流水线在一块 512×512 瓦片上跑完全程，最后回一个 200 +「没识别到人」，零报错。

整体方案 — 6 条正交主线

主线 1：解码收成单一入口，四层防线兜住「只返 None、绝不抛」

用户原始字节
  │
  ├─ OpenCV 直接解 ──成功──→ 像素量闸(1.2 亿) ──通过──→ BGR 图
  │        │                       └── 超限 ──→ None
  │        └─ 抛 cv2.error（尺寸断言）→ 记 warning，当成「没解出来」↓
  │
  └─ 没解出来 → 是纯 HEIF 品牌且没装 pi-heif？── 是 ──→ None（日志点明缺依赖）
                       │ 否
                       ↓
             Pillow(libheif) 开图 → header 宽高闸(1.2 亿) → exif_transpose
                       │                    └── 超限 / 为 0 ──→ None
                       ├─ 解码炸弹异常 ──→ None
                       ├─ 其它解码异常 ──→ None
                       ↓
                  RGB→BGR ──→ BGR 图

• 所有「用户原始字节」现在都过同一个函数：先用 OpenCV 直接解（jpg/png/webp/bmp/tiff/gif/avif 都在这条快路径上），解不出来才退到 Pillow 经 libheif 读 HEIC/HEIF，最后统一转成全仓通用的 BGR 通道序（decode_image）。接入点共 9 处，已逐一核对：人像路由 7 处（L329 / L365 / L613 / L1258 / L1283 / L1686 / L2223）、宠物观测 1 处、落盘归一化 1 处（后者被三个存储端点共用）
• 这个函数对外承诺「解不出返回 None、不抛」，所以把 OpenCV 自己的断言异常也接住了：一个 29 字节的 GIF 头就能声明自己 40000×40000，OpenCV 在尺寸校验里直接抛异常而非返回空——不接住，这 9 个入口会把本该 400 的请求变成 500（except cv2.error）
• 接住之后有个容易写错的细节做对了：不是就地 return None，而是把结果落成「没解出来」继续往下走回退支——这样一个被 OpenCV 尺寸断言拒掉、但 libheif 读得动的文件仍有第二次机会
• 解码炸弹在两条支上各卡一次：快路径解完看真实 shape，回退支在 Pillow 惰性加载像素之前先读 header 里的宽高，超过 1.2 亿像素就拒（_MAX_DECODE_PIXELS）。字节闸挡不住这个——HEIF 的网格容器能用很小的文件解出上亿像素
• 依赖缺失不静默降级也不炸后端：注册 HEIF 插件的动作包在 try 里，装不上只置一个标志位并打一行日志，等真收到 HEIC 时才在解码点报「缺 pi-heif」（_HEIF_OK）。这条短路只对纯 HEIF 品牌生效，AVIF 有意排除在外——它走 OpenCV 快路径，没 pi-heif 也能解
• 朝向那个坑写进了 docstring 当反面教材：libheif 读取时已按容器里的 irot 转好，但 EXIF 里的方向标记仍留着原值、被 pi-heif 挪到了另一个键上；照那个键再转一次，苹果的竖拍 HEIC 会变成横图

主线 2：按容器品牌判形，三处复核客户端自报的类型

通路	客户端自报依据	本 PR 加的复核	复核命中后
CLI identity register / preview	本地文件头 4~8 字节是 ftyp 就当视频	见到 ftyp 后再看紧随的 4 字节品牌，命中 14 个静态图品牌则判为图片（_looks_like_video_bytes）	不再输出「请改用 --video」，走 --image
POST /pets/observe（multipart）	Content-Type / 文件名后缀	读到字节后嗅前 16 字节（pet/router.py#L150）	翻回图片处理，并补一道 15MB 单张闸——视频闸比图片闸松，翻回来必须重新过紧的那道
POST /persons/register/preview（base64）	body 里的 media_kind 字段	只 base64-decode 前 64 字符拿到文件头（person/router.py#L1209）	就地把 media_kind 改成 "image"

• 判形与解码共用一套品牌定义，放在同一个模块里：14 个静态图品牌（12 个 HEIF + 2 个 AVIF）拆成两个子集再取并集，纯 HEIF 那个子集单独留着给主线 1 的「缺解码器短路」用（_HEIF_BRANDS）
• 三处复核的共同口径是只改路由、不改数据：宠物侧翻 is_video 标志、人像侧改 media_kind 字段，字节本身一个都不动，都各打一行 info 日志留痕
• CLI 侧因为跨进程拿不到后端常量，只能手抄一份平行表；这份重复不是靠注释「记得同步」维持的，而是有一条测试把两侧表取集合直接比相等，另有两条各自钉住整表字面量快照——单靠「两侧相等」漏掉「两边同时删同一个品牌」这种协同漂移（test_cli_and_backend_brand_tables_agree）。已核对该测试用 sys.path 直接指到 cli/src 导入，不依赖 CLI 包被装进后端测试环境，也不会静默 skip
• CLI 那处品牌比较要求头部至少 12 字节，调用方读的正好是 16 字节（identity.py#L98），前置条件成立

主线 3：落盘前先验真，再按用途归一化

上传内容	落盘结果
jpg / png / webp，且确实能完整解开	原字节逐字节直通，不重编
其余任何能解开的格式（HEIC/HEIF/BMP/TIFF/GIF/AVIF…）	头像：长边封 256 + 无损 WebP；宠物参考图：长边封 640 + JPEG q90
解不开（含魔数合法但 body 损坏）	返回 None → 端点 400

• 新增的落盘归一化函数把「验真」放在最前面：先整张解一次，解不开直接拒，之后才嗅魔数决定直通还是重编（normalize_for_storage）。顺序不能反——只查魔数的话，\xff\xd8\xff 后面接一堆垃圾同样命中前 3 字节，直通落盘后识别侧解不出，界面会显示「3 张参考图」而实际注入 0 张
• 两个封顶值都锚到了下游的真实规格，不是拍脑袋：头像的 256 就是 web 裁剪器的输出边长，让 CLI/API 重编支与 web 主路径产出同规格；参考图的 640 是拼图环节固定缩到高 320 的两倍余量（_AVATAR_MAX_SIDE / _REF_CROP_MAX_SIDE）
• 参考图选 JPEG 而非 WebP 有两个理由：唯一消费者是 omni，而拼图时反正会重编 JPEG，存 WebP 只是多一道转换；且盘上 ref_crop_N.jpg 的硬编码后缀牵动 glob 与下标解析，不宜与内容脱钩
• 编码失败不落空字节：OpenCV 编码在 WebP 边长超 16383 时只返回一个失败标志、不抛异常，这里判了这个标志并降级到 JPEG，JPEG 也失败才返回 None（imencode 判 ok）
• 魔数嗅探函数的 docstring 同步改了语义说明——返回 None 现在表示「不是这三种白名单格式」，不再等于「不支持」，支不支持要看归一化函数的返回值

主线 4：解码一律离开事件循环，并用一条扫源码的测试钉住

• 格式放开后单张 12MP HEIC 走 libheif 是几百毫秒量级（改前只解 jpg/png 是几十毫秒），而后端是单进程 asyncio，同一个循环上还跑着直播转码 / 录制切片 / MQTT 感知推理——所以人像侧 7 处解码、三个存储端点的归一化，全部丢进工作线程执行；宠物观测那处是整段选帧/检测/门控本来就已包在工作线程里
• 这条口径不靠人读注释维持：新增一条测试逐行扫两个 router 源码，发现没走工作线程的裸调就红（test_no_sync_decode_image_in_routers）。它同时盯解码和归一化两个符号——只盯前者的话，「新加一个头像端点裸调归一化」照样能绿
• 为配合这条，人像侧那个 base64 解码小函数改成了协程；已核对它与另一个上传解码函数的全部调用点都 await 了（分别在 L423、L274、L280），没有漏 await 导致「拿到协程对象、后续取 .shape 崩」的漏网点
• 观测侧顺手删掉了一个会重复解码的辅助函数：兜底帧改成在既有循环里就地留一份首个解得开的图，不在返回语句里再解一次——那一次在绝大多数请求里（检测器框到了）根本用不上（pet/observe.py#L745）。语义等价性成立：批次是原列表的前缀，且「整批解不出」在下一行就抛异常了，走不到用它的地方

主线 5：抹平「观测宽、存储窄」的不对称，文案随之收口

• BMP/TIFF/GIF/AVIF 原先能过观测端点、却被头像与参考图端点 400；归一化上线后这三个存储端点统一收下并重编，不对称消失。相应地把那条用真 BMP 断言 400 的旧用例改成断言归一化成 webp
• 用户可见文案分三处同步：两个 Agent SKILL 的话术（照片一律走 --image，含 .HEIC/.HEIF/.AVIF；并新增一行明确告诉 Agent「照片被说成视频时不要改用 --video」）、前端中英文案里「仅支持 jpg/png/webp」的措辞、以及端点自己的 OpenAPI 描述

主线 6：依赖选 pi-heif 而非 pillow-heif

• 两者同作者、同样封装 libheif，但 pillow-heif 捆绑 x265 编码器因而是 GPLv2，pi-heif 只带解码器 libde265、分类器是 LGPLv3；本仓只需要解码，拿不到编码器零损失
• 绕不开这个依赖：ffmpeg 只暴露瓦片不拼网格，Pillow 12 自身的 HEIF 能力检测为假
• 副作用记在了 PR 描述里：pi-heif 不能编码 HEIF，所以测试无法现造 HEIC 素材，用了一个 466 字节的 base64 常量内嵌，不引二进制资产
• 版本约束是 pi-heif>=1.4.0，与本仓其余依赖的写法一致（>= 为主，仅 apscheduler 因已知大版本破坏加了上界），锁文件另有精确版本

主线之间的依赖

主线	依赖谁	依赖什么
2（判形复核）	主线 1	品牌表与 ftyp 解析跟解码同住一个模块，判形与「缺解码器短路」共用一套品牌定义
3（落盘归一化）	主线 1	直通前整解一次验真，全靠主线 1 的「解不出返 None 不抛」契约；否则坏 body 会在端点里炸成 500
4（工作线程 + 护栏）	主线 1、3	护栏测试盯的两个符号正是主线 1 与主线 3 的入口
5（文案扩面）	主线 3	存储端点不再拒非白名单格式，才敢删掉「仅支持 jpg/png/webp」的措辞
6（pi-heif）	主线 1	只有回退支用它；快路径与判形都不依赖，装不上也不影响既有格式

关键设计原则

1. 验真先于直通 —— 白名单格式仍逐字节直通（保住「零转码」承诺），但直通的前提是整张解得开。宁可多花一次解码，也不让「魔数对、内容坏」的字节计进参考图张数，因为那种不一致到识别侧才暴露，且表现为「界面显示 3 张、实际注入 0 张」，比 400 难查得多。
2. 封顶只作用于重编支 —— 改前非白名单格式一律 400，落盘物件被 5MB 上传闸隐含夹住；放开格式就得自己补回这个上界。但封顶不能顺手加到直通支上，否则「零转码」失效，所以两条支刻意不共享这一步。
3. 依赖缺失降级要精确到品牌 —— HEIF 插件注册失败只置标志位不抛，避免一个可选依赖拖垮整个后端；同时短路只对纯 HEIF 品牌生效，避免误伤本来就能靠 OpenCV 解的 AVIF。
4. 复核只改路由不改数据 —— 三处复核都只翻标志位 / 改字段，字节原样往下传，并各留一行日志。这样万一品牌表判错，坏的也只是路由，不会产生被改写过的落盘物件。
5. 跨端口径靠测试钉死，不靠注释 —— 三处「必须同步」的隐性约定各配一条测试：解码不许留在事件循环上（扫源码）、CLI 与后端两份品牌表相等（跨包导入比集合）、头像封顶值与 web 裁剪器输出相等。三者都属于「靠人读注释守不住」的类型。

测试覆盖

主线	测试文件::用例	覆盖的 case
1	test_image_decode.py::test_decode_*	HEIC 经回退支解开、既有 7 种格式不回归、垃圾字节返回 None、通道序是 BGR 不是 RGB、超大图不抛只返 None、像素炸弹在快路径与回退支各一组
1	test_image_decode.py::test_heic_without_decoder_logs_at_failure_site、test_avif_not_short_circuited_when_heif_decoder_missing、test_non_heif_unaffected_when_decoder_missing	缺 pi-heif 时：HEIC 在解码点报缺依赖、AVIF 不被短路、非 HEIF 格式完全不受影响
2	test_image_decode.py::test_brand_table_*、test_video_brands_never_treated_as_still_image、test_non_isobmff_and_short_headers、test_cli_and_backend_brand_tables_agree	14 个静态图品牌全覆盖（非抽查）、整表字面量快照、9 个真视频品牌不得误判、非 ISO BMFF 与短头部、CLI↔后端两表相等
2	cli/tests/test_identity_video_magic.py（5 例）	CLI 侧同一组：静态图品牌不判视频、真视频仍判出、非 ISO BMFF 不变、ftyp 后缺品牌字节时仍回落成视频、整表快照
2	test_person_preview_media_kind.py（2 例）、test_pet_router.py::test_observe_heic_declared_as_video_is_treated_as_image	两侧误路由回归：HEIC 自报 video 不得进抽帧器、真视频仍进抽帧器、观测端点同口径
3	test_image_decode.py::test_normalize_*、test_avatar_cap_matches_web_cropper_output	白名单逐字节直通、HEIC→无损 WebP / →JPEG 两个用途、原先被拒格式现在收下、合法魔数+坏 body 必拒、封顶分档、WebP 编码失败降级 JPEG、封顶值与 web 裁剪器对齐
3	test_pet_router.py::test_avatar_accepts_heic_and_stores_webp、test_reference_crops_accept_heic_and_store_jpeg、test_person_router_avatar.py::test_post_non_passthrough_format_normalized	三个存储端点端到端：HEIC 进、webp/jpg 出；旧的「真 BMP 断言 400」改为断言归一化
4	test_image_decode.py::test_no_sync_decode_image_in_routers	扫两个 router 源码，裸调解码/归一化直接红（观测文件的豁免与理由写在测试内）
4	test_pet_observe.py::test_prepare_crops_goes_through_decode_image、test_fallback_frame_is_first_decodable_not_index_zero	删掉旧辅助函数后的两条不变量：确实走统一解码入口、兜底帧取首个解得开的而非下标 0

净新增 37 个测试函数（38 增 1 删）、7 处参数化展开，与 PR 描述所声明的数字一致。

问题

本轮未发现新问题。上一轮 ci-bot review 的两条 🔵 对账如下：

上轮问题	现状
🔵 PR 描述把 dependency-guard 放行口令硬编码成某个 SHA，push 后失效	已修。正文改成「当前 head 的口令见下方评论」，不再内嵌 SHA
🔵 已知限制未提「Web 上传 HEIC 做观测能传通、但本地缩略图空白」这一由本 PR 引入的观感变化	已修。新增第四条已知限制，写明是本 PR 带来的变化、原因（FileReader 结果直接交给 <img>、错误回调静默返回空串）、以及后端分析不受影响

代码部分自上轮 review 后无改动（HEAD 仍是 08256fd，其后三个 commit 修的注释/常量论据问题均已包含在上轮范围内）。本轮独立复核的重点及结论：

1. 解码契约的四层防线：异常接住后落成「没解出来」继续回退、而非提前返回，两条支各有独立像素闸——均已在代码中走通
2. 三处字节复核的完备性：观测端点在任一 upload 被判视频时已强制单文件，所以只嗅第 0 个字节流不漏；人像预览改写的 media_kind 有两个下游读取点（L1281/L1295 的分派与 L1367 的判定），都在改写之后
3. 护栏测试无假阳性/假阴性：正则要求符号后紧跟左括号，因此 to_thread(decode_image, raw) 这种传函数引用的写法不会误报；而 img = decode_image(raw) 这种裸调会命中
4. 残留的直接解码调用：全仓只剩解码入口自身与拼图模块两处，后者安全——归一化保证盘上字节恒为 jpg/png/webp
5. 陈旧措辞清扫：除测试内的字面量断言外，全仓已无「仅支持 jpg/png/webp」类表述

结论

LGTM — HEIC 支持与误路由修复各自独立成立、边界（异常、炸弹、编码失败、缺依赖、体积闸重过）都有代码级交代，三处「必须同步」的隐性约定各配了钉死它的测试；上一轮两条 🔵 均已在 PR 描述中处理。

---

_{由 review-pr skill v1.6 生成}

[ExWang]

/allow-dependencies-change 08256fd

[ExWang]

/review