#片盒点检 · MediaPack Audit

#十月新生态项目建设与已有原型

#为什么做它

#三个可验证的预期使用场景

# 1. 独立包消费公开 API；报告位于 _build/library-consumer/
moon run --target native examples/library_consumer

# 2. 通过包与受控错误包；两次运行均应生成 report.html 和 report.json
moon run --target native cmd/main -- examples/clean/media-pack.json examples/clean/assets --output _build/scenarios/clean
moon run --target native cmd/main -- examples/demo/media-pack.json examples/demo/assets --output _build/scenarios/issues

# 3. 从非图像目录起草清单，再用草稿检查同一目录；预期均返回 0
moon run --target native cmd/main -- init examples/library_consumer/assets --output _build/scenarios/draft.json
moon run --target native cmd/main -- _build/scenarios/draft.json examples/library_consumer/assets --output _build/scenarios/draft-check

#能做什么

• 按清单递归检查素材目录中的相对路径是否存在、是否为普通文件；清单未登记的文件也会报告其相对路径。
• 对任意普通文件均可执行清单存在性、路径安全、容量上限/下限和可选 SHA-256 校验；非图像文件不要求提供图像尺寸字段。
• 读取 PNG IHDR、JPEG SOF、WebP VP8/VP8L/VP8X 头、GIF 逻辑屏幕、BMP DIB 头、TIFF 尺寸标签、SVG 宽高/viewBox、AVIF 主 item 关联的 ispe、JPEG 2000 的 ihdr 盒、ICO/CUR 首项与 PSD 头核对像素宽高；PNG 会校验 IHDR 字段、逐块 CRC 和基本容器结构，WebP 会检查 RIFF 长度、块边界和奇数字节填充；不解码图像。
• JPEG 尺寸按 EXIF Orientation 换算为方向校正后的显示宽高，支持小端和大端 TIFF 标记；无效或不完整的 EXIF 方向信息会忽略并保留 SOF 尺寸。
• 对受支持图像可校验文件大小，并报告格式、尺寸或宽高比；图像校验是通用文件包校验之上的可选能力。
• 每项可选填写 expected_sha256，核对交付文件是否与预期内容一致；不匹配会让素材项失败。
• 素材项可选填 aspect，按 W:H 核对宽高比（精确整数比例），用于封面、社媒图等有固定比例的交付要求。
• 可选设置 max_total_bytes，限制整个素材目录树的总容量；递归统计所有普通文件，包括非图片文件。
• 当尺寸或文件大小不符合清单时，报告会同时写出要求值和实际值，方便直接定位该改哪项素材。
• 素材项可选填 label，用“课程主视觉”“微信公众号封面”等用途标注交付内容；HTML 与 JSON 报告保留该标签，HTML 会转义标签文本。
• JSON、HTML 和 CLI 摘要会记录所用清单原始字节的 SHA-256，方便把归档报告对应回当时的规格文件；清单空格或换行变化也会改变指纹。清单与文件指纹都只是内容标识，不是来源认证或数字签名。
• 对清单内未超出 max_bytes 的文件生成 SHA-256 内容指纹，方便核对文件内容；它不证明来源或签名。相同指纹会提示潜在重复文件，仅供人工确认，不会判为失败。超限文件会跳过哈希与 expected_sha256 比较；PNG CRC/结构检查和 WebP RIFF 块边界检查仍会执行。
• 检查清单中的重复文件名、不安全路径和无效规格，并提示同一素材包中 SHA-256 相同的潜在重复文件；提示不改变通过/失败状态。
• 严格检查 JSON 清单字段：只接受顶层 assets、可选 max_total_bytes 及素材项中的 file、可选 label、width、height、max_bytes、可选 min_bytes、可选 expected_sha256、可选 aspect、可选 format；拼错或暂不支持的字段会在检查前指出路径并拒绝运行，并对拼写相近的字段给出“你是不是想写 X？”提示，重复字段（包括 JSON 转义后等价的字段名）也会被拒绝，避免规格被静默忽略。
• max_bytes、设置后的 min_bytes 和设置后的 max_total_bytes 必须为正整数；width 和 height 若填写必须成对且为正整数；expected_sha256 必须是 64 位十六进制字符串；format 必须是受支持的图像格式名；小数不会被截断成另一个看似有效的规格。
• 按文件头识别实际图片格式，与扩展名不一致时给出“扩展名与内容不符”的明确提示；素材项可选填 format 断言交付文件的内容格式（接受 png/jpeg/webp/gif/bmp/tiff/svg/avif/jp2/ico/psd 及常见别名）。
• 素材项可选填 min_bytes，用于限制交付文件不得小于某个体积（例如拒绝被过度压缩或损坏为空的文件）。
• 输出带中文界面的独立 HTML 报告和机器可读 JSON 报告；报告对文件名和文本做 HTML 转义。
• 只读检查输入文件，不会改写或删除素材。

#AVIF 有界结构一致性验证

// prefix 是完整文件的前缀，file_size 必须来自实际文件大小。
inspect_avif_structure(prefix, file_size) // Result[AvifStructure, AvifDiagnostic]
inspect_avif_file(path)                  // 异步，读取并调用同一核心

#生态调研与复用取舍

#快速开始

moon check --target native
moon test
moon run --target native cmd/main -- examples/clean/media-pack.json examples/clean/assets --output report

moon run --target native cmd/main -- init examples/formats/assets --output media-pack.json

{ "file": "说明\u001f.txt", "max_bytes": 1024 }

moon run --target native cmd/main -- examples/duplicates/media-pack.json examples/duplicates/assets --output report-duplicates

moon run --target native cmd/main -- examples/formats/media-pack.json examples/formats/assets --output report-formats

moon run --target native cmd/main -- examples/demo/media-pack.json examples/demo/assets --output report-issues

moon run --target native cmd/main -- examples/invalid/fractional-width.json examples/clean/assets --output report-invalid-manifest

moon run --target native scripts/cli_smoke.mbtx

Start-Process .\report\report.html

#作为库使用

moon add hxiuzheng/media-pack-audit
# 固定到已验证版本时：moon add hxiuzheng/media-pack-audit@0.1.0

moon run --target native examples/library_consumer

import {
  "hxiuzheng/media-pack-audit" @audit,
}

• 尺寸解析：png_dimensions / jpeg_dimensions / webp_dimensions / gif_dimensions / bmp_dimensions / tiff_dimensions / svg_dimensions / avif_dimensions / jp2_dimensions / ico_dimensions / psd_dimensions，均接收 Bytes 返回 (Int32, Int32)?；
• 内容格式识别：detect_content_format(bytes) 按文件头返回 ImageFormat?，format_name(format) 取规范小写名；
• 清单读取与校验：parse_manifest_json(text) 拒绝重复键、未知字段和无效规格，返回 Manifest 或抛出 ManifestParseError；scan_assets(asset_dir, manifest, manifest_sha256) 返回 AuditReport；
• 报告生成：render_html(report) 生成中文 HTML，AuditReport 实现 ToJson 生成机器可读 JSON；
• 起步清单：scaffold_manifest(asset_dir) 从目录生成 ScaffoldResult；
• 通用工具：sha256_bytes、parse_aspect / matches_aspect、closest_match、html_escape。

fn inspect(bytes : Bytes) -> Unit {
  match @audit.detect_content_format(bytes) {
    Some(format) => {
      let dims : (Int, Int)? = match format {
        @audit.ImageFormat::Png => @audit.png_dimensions(bytes)
        @audit.ImageFormat::Jpeg => @audit.jpeg_dimensions(bytes)
        _ => None
      }
      println("格式 \{@audit.format_name(format)}，尺寸 \{dims}")
    }
    None => println("未识别的文件头")
  }
}

#清单格式

{
  "max_total_bytes": 100000,
  "assets": [
    { "file": "poster.png", "label": "课程主视觉", "width": 1920, "height": 1080, "max_bytes": 5000000 },
    { "file": "social/cover.jpeg", "width": 1200, "height": 630, "max_bytes": 2000000, "expected_sha256": "FF1EE418EE804BB1BEB25D59D3E5059FDFB9B2F6B7E97B81943D3ADEDAFD7458" },
    { "file": "social/cover.webp", "width": 1200, "height": 630, "max_bytes": 2000000 },
    { "file": "motion/preview.gif", "width": 320, "height": 180, "max_bytes": 500000 },
    { "file": "social-card.png", "width": 1200, "height": 630, "max_bytes": 2000000 }
  ]
}

{ "assets": [{ "file": "release-notes.txt", "label": "发布说明", "max_bytes": 2048, "min_bytes": 20 }] }

#项目结构

• image.mbt、webp.mbt、svg.mbt、avif.mbt、jp2.mbt、ico.mbt、psd.mbt：清单类型、各格式尺寸解析与素材点检逻辑。
• isobmff.mbt：AVIF 与 JPEG 2000 共用的 ISO-BMFF 盒结构解析器。
• avif_structure.mbt、avif_structure_file.mbt：有界 AVIF 结构一致性核心和文件入口；与仅取尺寸的旧接口分开。
• manifest.mbt：init 子命令使用的起步清单生成器。
• report.mbt：HTML 报告及文本转义。
• cmd/main：命令行入口、check/init 子命令与报告落盘。
• examples/demo：可直接运行的多格式错误示例素材包（所有图片都是合成测试夹具）。
• examples/clean：所有规格都通过的素材包。
• examples/formats：SVG/AVIF/JP2/ICO/PSD 五种扩展格式全部通过的素材包。
• examples/duplicates：两份内容相同的 WebP 素材，演示潜在重复提示但仍通过。
• examples/case-mismatch：验证跨平台文件名大小写一致性的样例。
• examples/invalid：无效清单、路径越界、未知字段和小数规格样例。
• scripts/cli_smoke.mbtx：端到端验证 CLI 的退出码和报告生成。

#当前验证基线与复现说明

moon version --all
moon update
moon fmt --check
moon fmt --check scripts/cli_smoke.mbtx
moon check --target native --deny-warn
moon test --target native
moon run --target native examples/library_consumer
moon run --target native scripts/cli_smoke.mbtx

#人工主导、AI 辅助说明

#License