# Mirage Tank Creator

> 用 Codex 内置 Image2 / image_gen 按用户指定的主体创作幻影坦克图片（Mirage Tank）：自动搭配前景，生成素材，计算真实 PNG Alpha，实现白底隐藏、黑底或深灰底显现，并验证和保存原文件。适用于观音、佛、神明或其他主体的点开显现、放大变图、双背景透明图，也能处理已有成对素材；普通透明抠图不需要此工作流。

- Skill: `gnipbao/mirage-tank-creator` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add gnipbao/mirage-tank-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gnipbao/mirage-tank-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gnipbao (https://skillmd.com/u/gnipbao)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gnipbao/mirage-tank-creator

---


# 幻影坦克创作

交付一张真正带 Alpha 的 PNG：浅色底可见前景，深色底显现隐藏主体。Image2 负责绘画，确定性的像素计算负责透明通道。效果来自查看器背景变化；图片本身无法感知点击或双指缩放。

## 先确定创作意图

- 用户指定什么隐藏主体，就保留什么主体；可以是观音、佛、其他神明，也可以是龙、巨鲸、宇宙、人像、建筑等。参考图只约束用户希望参考的形式、风格或构图，不固定成香案与神像。
- 用户只给主体时，主动选择与主体有关系的前景、地点、动作和点缀。用一两句话告知采用的构思，然后开始；无需让用户补完整套分镜或逐项确认。
- 用户指定了前景、背景、风格、比例或颜色时，按其要求执行。未指定时可采用竖幅、少量彩色前景、上方大面积留白、白色/灰度隐藏主体。前景要单独成立，显现后两层要产生清楚的关系。
- 前景不一定是人物：舟、灯、伞、门、花、祭器、桥、树枝或其他适配物件均可。不要把跪拜、香案、佛教元素机械地加到所有主题里。
- 仅在缺少必需素材、用户明确要求准确复刻却存在歧义，或有实质成本边界时追问。主题与美术选择可自行决定的，直接推进。

## 选择一条素材路线

**新创作优先用 `layers`：**

1. 生成前景 A：纯白底，仅绘制正常预览时可见的事物，留出隐藏主体的位置。前景优先有足够深的色彩或线条，避免整体近乎纯白。
2. 以 A 作为构图参考生成隐藏层 H：同尺寸、同视角，纯黑底上绘制白色/灰度隐藏主体与适量环境；不重复绘制 A 的前景。两张素材在构图上相互呼应。
3. `layers` 把 H 的亮度编码成白色像素的透明度，再与 A 的前景合成。白底外观保持 A；黑底显示白色隐藏画面。主体颜色默认转灰度是这一效果的设计条件，不要暗中承诺任意两幅全彩画面无损切换。
4. 前景有大面积白衣、白色物品、精确轮廓要求时，优先使用有真实 Alpha 的前景素材或提供准确的灰度前景遮罩 `--foreground-mask`。自动白底提取无法判断纯白像素是衣服还是纸面；也可改用下面的配对路线。

**已有完整的白底图 A 与深色显现图 B 时用 `pair`：**

- 先检查相同尺寸、视角以及前景位置。已有素材可以直接处理，不必再生图。
- `pair` 保持白底 A，并拟合黑底 B。两图的差值不满足中性亮度差时，黑底会有偏差；检查报告与对比图后再交付。
- 只有一张前景参考、但需要复杂完整场景时，可以先生成 A，再引用 A 编辑出 B。锁定前景坐标、比例、色彩与光影。前景漂移明显时针对性修正，别靠拉伸、盲目调 Alpha 或全图调亮来掩盖。

创意与提示词见 [references/creative-recipes.md](references/creative-recipes.md)，执行相应路线前阅读。算法、参数、故障处理见 [references/alpha-and-tools.md](references/alpha-and-tools.md)。

## Codex Image2 的使用方式

- 使用当前会话内置的 `image_gen` 图像生成/编辑工具；“Image2”是能力偏好，按可调用工具的实际参数使用，不杜撰 `model`、`background`、`size` 等工具未支持的字段。不因需要 Alpha 就静默切换到其他收费 API 或 ChatCut 项目。
- 有本地参考图时先查看；工具支持本地路径时使用 `referenced_image_paths`。前景与隐藏层分别调用，明确每张参考的用途。保存提示词及所选输出到本次工作目录。
- 素材默认要求实色白底或黑底，不让生成模型承担 Alpha 编码。即使工具返回 `.png` 或棋盘格图案，也先检查 `hasAlpha` 与 Alpha 分布；棋盘格画在 RGB 里不是透明。
- 如输入已经具有有效 Alpha，应保留它；纯 RGB 的假透明候选不能交付为成品。可以针对性改为纯色背景素材后再处理。
- 内置生图失败时说明具体问题；已有素材处理、脚本验证等不受影响的部分继续完成。额外 API、上传或项目写入不由本 skill 自动授权。

## 处理与验证

将 `MIRAGE_SKILL_DIR` 设为本 skill 实际目录；在独立的本次输出目录中工作。

```bash
# 新创作：前景白底图 + 隐藏主体黑底图
node "$MIRAGE_SKILL_DIR/scripts/mirage.mjs" layers \
  --foreground foreground.png --hidden hidden-on-black.png \
  --out-dir output/guanyin-mirage --name '观音-幻影坦克' --title '月下观音'

# 已有完整的两种外观
node "$MIRAGE_SKILL_DIR/scripts/mirage.mjs" pair \
  --surface surface.jpg --revealed revealed.jpg \
  --out-dir output/restored-mirage --name '幻影坦克'

# 检查任何候选文件是否有真实透明通道
node "$MIRAGE_SKILL_DIR/scripts/mirage.mjs" inspect --image candidate.png
```

脚本依赖 Node.js 22+ 与 Sharp。开源仓库通过 `npm ci` 安装锁定的依赖；在 Codex 中也可使用已安装/捆绑依赖。若未自动找到 Sharp，调用 `load_workspace_dependencies` 取得 Node 包路径，将 `MIRAGE_SHARP_PATH` 设为其中的 `sharp` 目录。不要引用其他无关项目的 `node_modules`。

每次合成都输出成品、白/灰/黑底预览、对比图、离线交互页与 `validation.json`。重新读取**导出的文件**做以下检查：

- 是 PNG，有 Alpha，存在实际透明或半透明像素以及可见像素；全不透明或全透明的 PNG 不通过。插画的细节应保留必要的半透明层次。
- 白底与目标 A 的误差至多 1 / 255；隐藏层在白底没有可见轮廓残留。
- 黑底主体完整、可识别、灰底仍有合理层次；前景不出现幽灵重影、白色矩形或明显色偏。实际查看预览图，数值通过不等于美术通过。
- `pair` 的黑底误差过大时读报告判断：优先修正素材色彩/对齐；白底优先模式本就无法实现所有任意配对。
- `layers` 的暗底前景过淡时，检查白色前景遮罩或素材本身；不要为保前景而把整个画布设为不透明。

先修正造成失败的具体步骤，避免重复生成整套素材。数值或视觉仍不通过时保留候选并说明未达标，不把预览 JPG、棋盘格示意或平铺拼图当成最终 PNG。

## 保存与交付

先在工作目录保留成品与处理记录，再按用户指定位置复制。未指定时，本地桌面会话默认另存到用户的「下载」文件夹；这解决了聊天中的文件链接无法直接另存的问题。

```bash
node "$MIRAGE_SKILL_DIR/scripts/mirage.mjs" deliver \
  --image 'output/guanyin-mirage/观音-幻影坦克.png'
```

`deliver` 默认使用当前用户的 Downloads，可用 `--dest-dir` 改位置；不覆盖不同的同名文件，复制后核对 SHA-256。跨沙箱目录写入使用环境提供的权限机制，不能绕过；受阻时给出已完成的工作目录文件和具体原因。

最终给出**已保存的透明原图**的绝对路径链接，并一起提供本次 `preview.html`，说明下载后用浏览器打开、点击图片或“黑底”查看显现。`deliver` 只复制 PNG，交互页需另行复制到交付目录；它内嵌了原图，无需相邻图片文件。可附效果对比或背景切换演示，但应标明它们不是透明原图。

简要注明：需保留 PNG 原文件；截图、JPG 或平台压平透明通道会让效果消失；固定背景的查看器不会因放大自动变化。不要保证所有平台都保留透明度，也不要未经请求发布图片。用户反馈“一直只有前景”时，先重读实际交付文件检查 Alpha，并查看同一 PNG 的白黑底合成结果，再判断查看背景或压平问题；不要直接重生成美术。

创作记录写入本次输出目录，记录主体、前景选择、实际提示词、素材来源、脚本参数、输出与验证结果。引用用户提供作品时保留来源关系，不把转换已有作品称为原创。