gif-maker

# GIF 动画生成器 (GIF Maker)

本 Skill 旨在帮助用户快速将一组序列帧图片或单张精灵表（Sprite Sheet）转换为 GIF 动画。

## 核心功能

*   **序列帧转 GIF**：支持读取文件夹内的 `png`, `jpg` 序列，按文件名排序合成 GIF。
*   **精灵表转 GIF**：支持读取单张 Grid 图片（如 4x4 精灵表），自动切分并合成为 GIF。
*   **智能压缩**：支持通过 `--max-size` 参数指定目标文件大小（如 950KB），自动调整压缩参数以满足微信表情包等平台的体积限制。
*   **参数控制**：
    *   `--fps`：指定每秒帧数（默认为 12）。
    *   `--layout`：指定精灵表布局（如 `4x4`），仅在这个模式下需要。
    *   `--loop`：默认永久循环。
    *   `--max-size`: 指定最大体积 (KB)。

## 使用指南

### 1. 快速开始

无需手动安装依赖，直接运行脚本即可。工具会自动创建虚拟环境 (`.venv`) 并安装所需依赖。

```bash
# 基本用法 1：从文件夹读取序列帧
./skills/gif-maker/scripts/run.sh /path/to/frame_folder --output my_anim.gif

# 基本用法 2：从单张精灵表生成 (需要指定布局)
./skills/gif-maker/scripts/run.sh /path/to/sheet.png --layout 4x4 --output my_sheet_anim.gif

# 常用选项：
# - 指定 FPS (例如 24)
./skills/gif-maker/scripts/run.sh /path/to/folder --fps 24

# - 开启自动压缩 (限制文件大小在 950KB 以内)
./skills/gif-maker/scripts/run.sh /path/to/folder --max-size 950
```

### 2. (可选) 手动安装

如果您希望手动管理环境（注意：压缩功能依赖 `gifsicle` 工具，请确保系统已安装）：
- macOS: `brew install gifsicle`
- Ubuntu: `sudo apt-get install gifsicle`

```bash
python3 -m venv skills/gif-maker/.venv
source skills/gif-maker/.venv/bin/activate
pip install -r skills/gif-maker/requirements.txt
python3 skills/gif-maker/scripts/make_gif.py ...
```

## 参数说明

*   `source`: 输入路径。可以是包含图片的文件夹，也可以是单张图片文件。
*   `--output` (`-o`): 输出 GIF 文件名，默认为 `output.gif`。
*   `--fps`: 帧率，默认为 12。
*   `--layout`: 仅当 `source` 为单文件时使用，格式为 `行数x列数` (如 `4x4`)。
*   `--max-size`: (可选) 启用 GIF 压缩，指定目标文件最大大小 (KB)。仅当原始文件超过此大小时才会尝试压缩。

## 示例

假设你有一个文件夹 `frames/` 包含...

# GIF Maker (GIF 动画生成助手)

这是一个专为 Agent 流程设计的 Skill，旨在快速将序列帧图片或精灵表（Grid Sprite Sheet）转换为 GIF 动画，并支持针对微信表情包等场景的智能压缩。

## 🧩 核心原理

本 Skill 基于 Python 的 `Pillow` 和 `gifsicle` (可选) 构建，核心处理流程如下：

1.  **灵活的输入源处理 (Input Handling)**:
    *   **序列帧模式**: 自动扫描指定目录下的 `png`/`jpg` 图片，按文件名自然排序作为动画帧。
    *   **精灵表模式**: 支持读取单张大图（如 4x4 网格图），通过 `--layout` 参数将其切分为独立的帧序列。

2.  **动画合成 (Animation Composition)**:
    *   根据用户指定的帧率 (`--fps`)，精确计算每一帧的持续时间。
    *   使用 Pillow 库构建动画，设置循环模式（默认为永久循环）和处理方式（Disposal Method 为 Background，避免透明图层重叠残留）。

3.  **智能压缩 (Smart Compression)**:
    *   (集成 `gifsicle`) 针对微信表情包限制（通常需 <1MB 或 <500KB），提供 `--max-size` 参数。
    *   当输出文件超标时，系统通过二分逼近或预设梯度（Lossy 强度、尺寸缩放）自动尝试压缩，直到文件体积达标，无需人工反复试错。
    *   *注：此功能依赖系统安装 `gifsicle` 工具。*

## 📂 目录结构

Skill 的文件组织结构如下：

```text
skills/gif-maker/
├── README.md               # 本说明文档
├── SKILL.md                # Agent Skill 定义及规范引用
├── requirements.txt        # Python 依赖 (Pillow)
└── scripts/
    ├── make_gif.py         # 核心处理脚本 (包含压缩逻辑)
    └── run.sh              # 自动环境配置与执行入口
```

## 💡 最佳实践

### 配合 WeChat Sticker Maker 使用
通常我们使用 `wechat-sticker-maker` 切分好的静态图序列来生成 GIF：

1.  **切分**: 先用 `wechat-sticker-maker` 将九宫格切分为 `sticker_output/main/` 下的序列图。
2.  **合成**: 再用本 Skill 指向该目录生成 GIF。
    ```bash
    ./skills/gif-maker/scripts/run.sh sticker_output/main/ -o my_anim.gif --fps 10
    ```

### 精灵表直接生成
如果不需要中间的静态图，也可以直接从原图生成：
```bash
# 从 4x4 原图直接生成 25fps 的 GIF
./skills/gif-maker/scripts/run.sh origin_grid.png --layout 4x4 --fps 25 --output direct_anim.gif
```

### 控制体积
为...