customer_fs.bin 双系统生成工具
本目录提供 EG800AKCN_11LG 项目的 customer_fs.bin 自动生成和校验工具，支持
Windows 与 macOS。
当前 customer_fs 分区大小为 576 KiB，设备 kernel 只支持 LittleFS 磁盘格式
0x00020000（disk 2.0）。所有生成入口都会在输出前执行兼容性检查，避免再次生成
kernel 无法挂载的 disk 2.1 镜像。
1. 源文件目录
文件系统的源文件统一存放在：
audio_prompts/customer_fs/
当前目录中的 14 个音频文件，全部从已经过实机验证、能够正常挂载的 Windows
customer_fs.bin 中提取，并经过重新打包和逐文件回读验证。
设备代码从 U:/ 根目录访问文件，因此所有文件必须直接放在上述目录中。例如：
正确：audio_prompts/customer_fs/network_connect_zh.mp3
错误：audio_prompts/customer_fs/subdir/network_connect_zh.mp3
生成工具会拒绝隐藏文件和子目录，避免把 .DS_Store 等无关文件打进正式镜像。
2. 如何增删改文件
生成工具采用“根据源目录全量重建”的方式，不是在旧 bin 上追加内容。
- 添加：把新文件直接放进
audio_prompts/customer_fs/； - 替换：用新文件覆盖同名文件；
- 编辑：使用音频工具修改原文件并保存到原位置；
- 删除：从源目录删除文件，下一次生成的 bin 中将不再包含该文件；
- 改名：直接修改源文件名，但必须同步确认业务代码使用的新文件名。
部分音频文件名已经写入业务代码。删除或改名后，如果代码仍然播放原文件，串口会打印：
tips file missing
因此，生成工具允许删减文件，但删减前仍需确认业务代码不再使用它。
3. Windows 一键生成
在项目根目录执行：
tools\customer_fs\build_windows.bat
Windows 版本使用项目自带并已通过实机验证的工具：
ql-cross-tool\win32\mklfs-v2.exe
同时使用 SDK 自带的 Python 执行兼容性校验，不需要另外安装 Python 依赖。
也可以指定自定义源目录和输出文件：
tools\customer_fs\build_windows.bat 源目录 输出文件
例如：
tools\customer_fs\build_windows.bat ^
audio_prompts\customer_fs ^
output\customer_fs\customer_fs.bin
4. macOS 一键生成
在项目根目录执行：
./tools/customer_fs/build_macos.sh
首次运行时，脚本会自动创建：
.venv-customer-fs
并安装项目固定的依赖版本：
littlefs-python==0.19.0
新版 littlefs-python 默认会生成 disk 2.1 镜像，不能直接使用它自带的命令行生成。
本项目的 generate_macos.py 会显式设置：
disk_version = 0x00020000
从而生成当前设备 kernel 可以识别的 disk 2.0 镜像。
也可以指定自定义源目录和输出文件：
./tools/customer_fs/build_macos.sh 源目录 输出文件
例如：
./tools/customer_fs/build_macos.sh \
audio_prompts/customer_fs \
output/customer_fs/customer_fs.bin
5. 默认输出位置
Windows 和 macOS 默认都输出到：
output/customer_fs/customer_fs.bin
生成时会先写入临时文件：
customer_fs.bin.tmp
只有生成和全部校验成功后，临时文件才会替换正式输出。生成或校验失败时，已有正式输出 不会被覆盖。
6. 自动门禁检查
每次生成都会检查：
| 检查项 | 要求 |
|---|---|
| 镜像大小 | 589824 字节 |
| LittleFS 磁盘格式 | 0x00020000 |
| Block Size | 4096 字节 |
| Block Count | 144 |
| 第一个 superblock | 必须存在且参数正确 |
| 第二个 superblock | 必须存在且参数正确 |
| 源目录 | 不能为空 |
| 源文件层级 | 只能是根目录文件 |
| 隐藏文件 | 不允许 |
| 文件名 | 必须能在生成镜像中找到 |
也可以单独校验一个镜像：
python3 tools/customer_fs/verify_customer_fs.py \
--image output/customer_fs/customer_fs.bin \
--source audio_prompts/customer_fs
校验成功会输出镜像大小、LittleFS 版本、块参数、源文件数量和 SHA-256。
7. 放入正式固件工程
生成并校验成功后，需要显式复制到 SDK 打包位置。
macOS：
cp output/customer_fs/customer_fs.bin \
ql-config/config/EG800AKCN_11LG/customer_fs.bin
Windows：
copy /Y output\customer_fs\customer_fs.bin ^
ql-config\config\EG800AKCN_11LG\customer_fs.bin
替换前建议备份原文件并记录新镜像的 SHA-256。
customer_fs.bin 不是当前 APP-only OTA 的升级内容。修改该镜像后，需要重新生成并烧录
包含分区表、kernel、customer_app 和 customer_fs 的完整工厂包，不能只下发 APP OTA。
8. 实机验收
Windows 生成工具已经过实机验证。macOS 工具已经通过结构校验、重新挂载和逐文件回读， 首次用于正式版本前仍应至少烧录一台设备验收。
启动日志应直接出现：
[U] mount successfully
不能出现：
[U] mount failed (-22), will format fs partition
还需要逐一验证镜像中的音频能够通过 U:/文件名 正常读取和播放，并记录本次发布使用的
customer_fs.bin SHA-256。
9. 注意事项
- 不要用十六进制工具把 disk 2.1 镜像的版本字段直接改成 disk 2.0；
- 不要直接使用
python -m littlefs create，它当前默认生成 disk 2.1； - 不要把
.venv-customer-fs、output或.DS_Store提交到仓库； - Windows 和 macOS 生成镜像的整体 SHA-256 可能不同，这是块分配顺序不同造成的；
- 两个平台产物必须满足相同的 disk 2.0、4096 字节块和 144 块约束；
- 修改、删除或重命名业务音频前，必须同步检查代码中的文件名引用。