# 使用说明与提示

> 从 README 提取的详细提示、约束与版本说明。

## 版本与安装

> [!NOTE]
> mooncakes 包版本 `0.6.0` 对应 **workspace 六模块重构**后的主模块（mooncakes 上 0.5.0 为重构前最后版本）；功能迭代版本（v0.1 → v237.0.0+）历史见 [docs/changelog.md](docs/changelog.md)。主模块安装：`moon add walkzzz/image`。

> [!TIP]
> **子模块可独立安装**（按需轻量依赖）：
> - `moon add walkzzz/core` — 基础类型（Image/Image16/ImageF/LoadError）
> - `moon add walkzzz/codec` — 18 种格式编解码 + 颜色 + 元数据 + 条码
> - `moon add walkzzz/process` — 90+ 图像算法子包
> - `moon add walkzzz/photography` / `walkzzz/vision` / `walkzzz/domain` — 上层能力

## 格式检测

> [!NOTE]
> `detect_format` 仅通过 magic bytes 识别 PNG/JPEG/BMP/GIF/QOI/PNM/PSD/HDR/WebP。TIFF/ICO/CUR/ICNS/APNG/TGA 需手动调用 `decode_tiff`/`decode_ico`/`decode_cur`/`decode_icns`/`decode_apng` 等函数。
> v244+ 已提供 `get_image_info_extended`（18 格式统一信息探测）与 `detect_image_format` 全格式检测，见 docs/roadmap.md。

## 多目标测试

> [!NOTE]
> 四目标（native / wasm-gc / js / wasm）均使用同一套纯 MoonBit 代码，各 **6574 测试**全部通过，覆盖率 90.4%，`moon check --deny-warn` 零警告。

> [!TIP]
> 四目标共用 workspace（core/codec/process/photography/vision/domain）同一套代码，无任何条件编译或目标分支。

## 安全约束

> [!WARNING]
> 所有解码器在分配内存前调用 `check_dims(width, height, channels)` 校验：
> - 宽/高必须为正数且不超过 `MAX_IMAGE_DIMENSION`（65535）
> - `width × height × channels` 不超过 `Int` 最大值（防整数溢出）
> - 校验失败时 `raise LoadError::DecodeFailed`
>
> `safe_mul` / `safe_mul3` 提供溢出安全乘法，返回 `Int?`（溢出时返回 `None`）。

## 形式化验证

> [!TIP]
> core/safe_math 通过 `moon prove` 验证 **8 个 goals**（溢出安全 / 维度有效 / clamp / 索引 / 旋转不变量等），另有 8 条谓词预留（SMT 超时与前端限制，清单见 safe_math.mbtp 注释）。

## 版本更新摘要

> [!TIP]
> **0.6.0（workspace 重构）** — src/ 单体 → 六模块 workspace · 根 CHANGELOG · CI `--deny-warn` 零警告门禁 · badge 数据实测对齐（6574 测试 / 8 goals）· 子模块独立安装 · 自演化叙事（中英）
>
> 完整功能迭代历史见 [docs/changelog.md](docs/changelog.md)。