# Gemini CLI Plan 模式教程：先规划再实现不覆盖原图的 WebP 批处理

## 身份和范围

本站原创 fixture 与人工参考；实际运行：六张实际编码 WebP 与源 SHA。目标代理模型、账号会话、付费 API、第三方 PR、推送和发布均未执行。公开包不含 .env；需要时仅在自己的临时练习目录从文本模板创建。

## 本地命令

```sh
python3 -m pip install -r requirements.txt
python3 verify.py
python3 convert.py --dry-run
python3 convert.py
```

## 七步原生操作

### 1. 看清六张输入的边界条件

input 中同时有透明 PNG、长图、小图和同名不同扩展名的 pair。目标最长边 1600、不放大、透明保留、输出独立目录；不是调用图片生成 API，也不改变图中内容。

### 2. 进入只读 Plan 模式

Gemini CLI 用 /plan 或 --approval-mode=plan，提交 plan-request.md，先要文件扫描、命名冲突、dry-run 与验证矩阵。批准计划之前不要要求创建转换脚本；模式切换和批准应以实际界面提示为准。

### 3. 审查计划里的写入与冲突策略

确认输出目录不能等于输入、不能嵌在输入目录中，pair.jpg/pair.png 必须输出不同名字。检查未放大、RGBA 和错误处理规则；没有这些边界就退回计划补充。

### 4. 批准后实现确定性本地编码

通过计划后再让 Gemini 实现代码。人工参考 convert.py 使用 Pillow thumbnail 和 WEBP 编码，以 -1/-2 后缀处理冲突；质量参数为 85，不承诺每张输出一定比原图小。

### 5. 先 dry-run 再写入独立目录

安装 requirements.txt 后先运行 python3 verify.py，检查器在自己的临时输出目录编码，首次解压或已运行转换后都可使用。再用 python3 convert.py --dry-run 预览，python3 convert.py 写入独立 output；包内 reference-output 是冻结参考，不能当成新执行结果。

### 6. 核对格式、透明度和源文件 SHA

verify.py 用独立 TemporaryDirectory 验证真实 WEBP、1600最长边、不放大、RGBA与源 SHA，并确认已有 output 文件完全不变。验证完成会清理临时编码；如需保留自己的新图，单独运行 convert.py。

### 7. 把原生计划与实跑产物一并交付

保存实际 Gemini 计划及批准记录、输出 WebP 和验收 JSON。本站已实际编码的图片是人工脚本结果；原生代理未执行，不能把参考输出当成 Gemini 成功记录。

## 验收产物

Plan 模式生成并人工确认的实施计划与边界测试表；本地转换 CLI、dry-run 清单、独立输出目录与尺寸/透明度/原图 SHA 验证记录

## 门槛

- Plan 阶段只读，批准实施后才写代码；本页未执行原生 Gemini CLI 会话。
- Gemini CLI Node >=20；转换脚本需固定 Pillow 版本并确认 WebP 支持。
- 不承诺每张 WebP 都更小；透明度和质量需实图验证，输出冲突不可静默覆盖。

## 官方来源

- https://geminicli.com/docs/cli/plan-mode/
- https://geminicli.com/docs/get-started/installation/
- https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html

静态配图冻结于本次输入。修改输入需重新运行并自行重渲染；不把旧截图当新结果。