# MoonSquash：MoonBit SquashFS 4 文件系统镜像工具库

版本 0.3.1；2026-11-05；十一月参赛本地草稿。GitHub：Magic486/MoonSquash；模块 Magic486/moonsquash@0.3.1，发布状态见 docs/release.md；尚未报名或取得官方审核结论。

面向固件分析、只读 Linux 系统和离线制品检查，提供镜像读取、构建、目录打包、安全提取、结构校验和语义差异分析。Mooncakes 与 GitHub 公开检索未发现直接同类 MoonBit 实现；不宣称全球首创。

核心格式逻辑独立用 MoonBit 实现：十四类 inode、目录与元数据流、稀疏文件和 fragment、硬链接和符号链接、UID/GID、扩展属性及导出索引。支持有界随机读取、确定性布局、流式构建、数据及元数据压缩、属性保留及按路径解释镜像变化。Node/Python 只承担明确披露的宿主操作和标准压缩库适配，不调用官方镜像工具代替核心实现。

交付包括可复用 API、九个 CLI 命令、示例、测试与说明。gzip、xz、zstd、lz4、lzo、旧式 LZMA 完成官方生成与官方解包双向验证；构建侧逐字节比较 164 个独立文件，并核对链接、权限、时间与二进制属性。21 项库测试通过 JS/Wasm-GC；服务器从源码编译验证。合成规模测试覆盖约 201 MiB 独立内容、2403 个文件路径，官方解包后逐文件比较通过；同一约 97 MiB 数据集构建峰值内存由约 428 MiB 降至约 147 MiB。另有 1101 个 inode 目录、20 个损坏镜像用例、8 个无效构建配置、提取安全回归和实际 ZIP 独立消费证据。未将合成数据宣称为真实固件。

另以公开 OpenWrt 24.10.0 根文件系统验证真实发行布局：1564 个条目、1225 个普通文件和 224 个符号链接，与官方工具逐项对照通过；设备记录识别后报告省略，没有创建设备、安装或运行镜像内容。

边界明确：镜像偏移与单文件小于 2 GiB；流式构建默认累计数据预算为 4 GiB，内存便利 API 保留 128 MiB 上限；字符串路径为 UTF-8。安全提取不创建特殊节点或应用特权属性，并报告省略项。不是内核挂载认证或完整 squashfs-tools 参数复刻。严格审查与可复现证据见 docs/strict-review.md 和 docs/test-evidence/review-0.3.md。

Apache-2.0；格式参考和系统库许可在 THIRD_PARTY 中披露。AI 辅助编写，保留真实本地开发记录；参赛者须理解并能演示架构与验证方法。维护以独立兼容性用例和公开 API 回归为准。材料与证据已本地准备；发布结果见 docs/release.md，十一月报名规则仍待核实。