feat: add GIF animation packer

AGENTS.md

@@ -0,0 +1,100 @@
+# AGENTS.md
+
+本文件给在本仓库中工作的编码代理使用。修改代码前先阅读 `README.md` 和当前脚本实现，保持改动小而直接。
+
+## 项目概览
+
+`EmbeddedAnimPacker` 是一个 Python 命令行工具，用于：
+
+1. 读取输入 GIF。
+2. 使用 Pillow 拆分为逐帧 PNG。
+3. 调用本地 LVGL 仓库中的 `scripts/LVGLImage.py`。
+4. 生成适合放入 LittleFS 的 LVGL BIN 图片文件。
+
+主入口是 `EmbeddedAnimPacker.py`。
+
+## 重要文件
+
+- `EmbeddedAnimPacker.py`: CLI 主程序。
+- `requirements.txt`: Python 运行依赖，目前只有 `Pillow`。
+- `README.md`: 面向用户的使用说明。
+- `default.gif`: 示例输入素材。
+- `frames/`: `--keep-frames` 生成的中间 PNG 帧，通常不要提交。
+- `littlefs/anim/`: 默认 BIN 输出目录，通常不要提交。
+- `lvgl/`: 本地 LVGL checkout，作为外部工具目录使用，通常不要提交。
+
+## 本地环境
+
+推荐使用虚拟环境：
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install -r requirements.txt
+```
+
+运行完整转换需要本地存在 LVGL 仓库，并确保 `lvgl/scripts/LVGLImage.py` 可用。
+
+## 常用命令
+
+安装依赖：
+
+```bash
+python3 -m pip install -r requirements.txt
+```
+
+运行转换：
+
+```bash
+python3 EmbeddedAnimPacker.py default.gif
+```
+
+指定 LVGL 和输出目录：
+
+```bash
+python3 EmbeddedAnimPacker.py default.gif \
+  --lvgl-dir ./lvgl \
+  --output-dir ./littlefs/anim \
+  --cf RGB565 \
+  --compress RLE
+```
+
+保留中间帧：
+
+```bash
+python3 EmbeddedAnimPacker.py default.gif --keep-frames ./frames
+```
+
+只检查 CLI 参数和基础语法时，可运行：
+
+```bash
+python3 -m py_compile EmbeddedAnimPacker.py
+python3 EmbeddedAnimPacker.py --help
+```
+
+## 代码约定
+
+- 使用 Python 标准库和 `pathlib.Path` 处理路径。
+- 保持 CLI 参数清晰，新增参数时同步更新 `README.md`。
+- 对用户输入、文件路径和外部工具缺失给出明确错误信息。
+- 调用外部命令时使用参数列表，不拼接 shell 字符串。
+- 默认行为应避免留下临时文件；只有用户传入 `--keep-frames` 时才保留中间 PNG。
+- 不要引入重量级依赖，除非能明显简化核心流程。
+
+## 版本控制注意事项
+
+- 不要提交 `.venv/`、`frames/`、`littlefs/anim/`、`lvgl/`、缓存目录或本地编辑器文件。
+- Commit messages must be written in English and follow Conventional Commits 1.0.0, for example `feat: add frame prefix option` or `fix: validate GIF input path`.
+- 如果需要新增示例输入素材，确认文件大小合理，并在 `README.md` 中说明用途。
+- 如果修改默认输出位置、颜色格式或压缩格式，请同步检查 `.gitignore` 和文档。
+
+## 验证建议
+
+没有完整 LVGL 环境时，至少运行：
+
+```bash
+python3 -m py_compile EmbeddedAnimPacker.py
+python3 EmbeddedAnimPacker.py --help
+```
+
+有完整 LVGL 环境时，使用小 GIF 做一次端到端转换，并检查输出目录中的 `.bin` 文件数量是否等于 GIF 帧数。