catalog/repos/abutun--claude-skill-aso-cosmicmeta-ss.md

# 应用商店截图生成器

`截图生成` `ASO优化` `多语言` `CLI工具` `Claude技能` `Gemini AI`

# ASO 截图生成器

生成高转化率的 App Store 和 Google Play 截图，支持设备外框、以利益为导向的标题、多语言支持和本地化视觉风格。可作为独立 CLI 工具使用，也可作为 Claude Code 技能通过引导式 6 阶段工作流使用。

<img width="1997" height="1920" alt="showcase" src="https://github.com/user-attachments/assets/8169944d-9f90-4b9c-bdbf-8ae313488399" />

[查看由本技能生成的完整截图集](https://apps.apple.com/us/app/swipe-slip-tunnel-dodge-game/id6752439274)

## 功能特性

- **4 个平台** — iOS 手机（1320×2868）、安卓手机（1080×1920）、iPad Pro 13"（2064×2752）、安卓平板（1600×2560）
- **每平台 6–8 张截图**，配有以利益为导向的行动标题
- **英语优先的多语言支持** — 先生成英语版本，然后通过 Gemini 一键翻译成任意语言
- **本地化视觉风格** — `--lang-code` 自动融入具有文化共鸣的视觉美学（土耳其语配奥斯曼瓷砖、德语配包豪斯几何、日语配樱花等）
- **标准化输出命名** — 文件遵循 `{lang_code}_{n:02d}.png` 格式（如 `en_01.png`、`tr_05.png`、`de_03.png`）
- **设备外框** — 逼真的 iPhone 16 Pro Max、Pixel 风格安卓、iPad Pro 13" 和安卓平板外框
- **高点击率设计** — 动作动词、视觉层次、醒目品牌色彩、微妙渐变
- **智能文字颜色** — 根据背景亮度自动选择白色或深色文字
- **Gemini AI 增强** — 所有截图均通过 `nano-banana-pro` 或 `nano-banana-2` 进行专业级优化
- **无付费墙规则** — 整个工作流强制执行（不包含订阅/内购截图）

## 环境要求

- Python 3.8+
- [Pillow](https://python-pillow.org/)（PIL 分支）
- 推荐 macOS（使用 SF Pro Display 字体；Linux 上回退到系统字体）
- [Gemini API 密钥](https://aistudio.google.com/apikey)（AI 增强功能必需）

## 安装

### 1. 克隆并安装依赖

```bash
git clone https://github.com/abutun/claude-skill-aso-cosmicmeta-ss.git
cd claude-skill-aso-cosmicmeta-ss
pip3 install Pillow
```

### 2. 安装字体

本技能使用 **SF Pro Display Black** 作为标题字体。在 macOS 上，从 [Apple 开发者字体页面](https://developer.apple.com/fonts/) 下载并安装。安装后预期路径：

```
/Library/Fonts/SF-Pro-Display-Black.otf
```

若 SF Pro 不可用，将回退到 Helvetica（macOS）或 DejaVu Sans（Linux）。

### 3. 生成设备外框

```bash
python3 generate_frame.py
```

在 `assets/` 目录下创建四个外框 PNG 文件：

| 文件 | 设备 | 尺寸 |
|------|--------|------|
| `iphone_frame.png` | iPhone 16 Pro Max（灵动岛） | 1054×2870 |
| `android_frame.png` | Pixel 风格手机（打孔屏） | 900×1980 |
| `ipad_frame.png` | iPad Pro 13"（前置摄像头） | 1600×2400 |
| `android_tablet_frame.png` | 安卓 10" 平板（打孔屏） | 1280×2200 |

### 4. 配置 Gemini API 密钥

```bash
# 方式 1：环境变量
export GEMINI_API_KEY="your-api-key-here"

# 方式 2：保存到配置文件（跨会话持久有效）
python3 gemini_enhance.py --save-key "your-api-key-here"

# 方式 3：每次直接传入
python3 gemini_enhance.py --api-key "your-api-key-here" ...
```

从 [Google AI Studio](https://aistudio.google.com/apikey) 获取密钥。

## 使用方式

### 方式 A — Claude Code 技能（推荐）

通过 Claude Code 安装并调用，享受完整的引导式工作流。

**通过 `npx add-skill` 安装：**

```bash
npx skills add abutun/claude-skill-aso-cosmicmeta-ss
```

**或手动安装：**

```bash
# 个人使用（所有项目）
cp -r claude-skill-aso-cosmicmeta-ss ~/.claude/skills/

# 项目专用
cp -r claude-skill-aso-cosmicmeta-ss .claude/skills/
```

重启 Claude Code 会话，然后让 Claude 生成应用商店截图。

**技能引导完成 6 个阶段：**

| 阶段 | 内容 |
|-------|-------------|
| **1. 配置** | 选择平台（手机/平板/全部）、截图数量、语言、来源、品牌色、Gemini 模型及 API 密钥 |
| **2. 利益挖掘** | 分析代码库（或向你询问）以生成行动动词标题 |
| **3. 截图配对** | 将应用截图与利益点匹配，进行质量检查，执行无付费墙规则 |
| **4. 生成** | 运行 `compose.py` + Gemini 增强；按平台输出 `en_01.png` … `en_0N.png` |
| **5. 展示** | 生成并排预览图；提供上传说明 |
| **6. 多语言** | 通过 Gemini 将英语截图翻译为任意语言，并为每个语言区域添加文化视觉风格 |

**交互示例：**

```
你：为我的应用生成商店截图
Claude：[第 1 阶段 — 询问平台、数量、语言...]
你：所有平台，6 张截图，先英语再土耳其语和德语
Claude：[分析代码库，提出标题，为全部 4 个平台生成 en_01–en_06，
         然后生成带奥斯曼瓷砖文化风格的 tr_01–tr_06，
         再生成带包豪斯几何风格的 de_01–de_06...]
```

### 方式 B — 独立 CLI

#### compose.py — 合成单张截图

```bash
# iOS 手机
python3 compose.py \
  --platform ios \
  --bg "#E31837" \
  --verb "TRACK" \
  --desc "YOUR DAILY MOOD" \
  --screenshot path/to/shot.png \
  --output output/en/ios/en_01.png

# iPad Pro 13"
python3 compose.py \
  --platform ipad \
  --bg "#E31837" \
  --verb "TRACK" \
  --desc "YOUR DAILY MOOD" \
  --screenshot path/to/shot_tablet.png \
  --output output/en/ipad/en_01.png

# 安卓手机
python3 compose.py \
  --platform android \
  --bg "#1A73E8" \
  --verb "DISCOVER" \
  --desc "NEW FEATURES" \
  --screenshot path/to/shot.png \
  --output output/en/android/en_01.png

# 安卓平板
python3 compose.py \
  --platform android_tablet \
  --bg "#1A73E8" \
  --verb "DISCOVER" \
  --desc "NEW FEATURES" \
  --screenshot path/to/shot_tablet.png \
  --output output/en/android_tablet/en_01.png
```

**参数说明：**

| 参数 | 必填 | 说明 |
|----------|----------|-------------|
| `--platform` | 是 | `ios`、`android`、`ipad`、`android_tablet` |
| `--bg` | 是 | 背景十六进制颜色（如 `#E31837`） |
| `--verb` | 是 | 行动动词标题（如 `TRACK`） |
| `--desc` | 是 | 利益描述语（如 `YOUR DAILY MOOD`） |
| `--screenshot` | 是 | 应用截图 PNG/JPG 路径 |
| `--output` | 是 | 输出文件路径 |
| `--no-gradient` | 否 | 禁用微妙的背景渐变叠加 |

#### gemini_enhance.py — AI 增强、翻译与文化风格

将普通样机转化为专业高转化率的视觉效果。一步完成增强、翻译、本地化和输出重命名。

```bash
# 增强英语截图（手机）
python3 gemini_enhance.py \
  --input-dir output/en/ios/ \
  --output-dir output/en/ios/ \
  --model nano-banana-pro \
  --app-desc "mood tracking app" \
  --bg-color "#E31837" \
  --lang-code "en"
# → 输出 en_01.png、en_02.png、...

# 翻译为土耳其语并添加奥斯曼文化风格
python3 gemini_enhance.py \
  --input-dir output/en/ios/ \
  --output-dir output/tr/ios/ \
  --model nano-banana-pro \
  --translate-to "Turkish" \
  --lang-code "tr"
# → 输出带有瓷砖/郁金香图案的 tr_01.png、tr_02.png、...

# 翻译为日语并添加侘寂美学
python3 gemini_enhance.py \
  --input-dir output/en/ios/ \
  --output-dir output/ja/ios/ \
  --model nano-banana-pro \
  --translate-to "Japanese" \
  --lang-code "ja"
# → 输出带有樱花/水墨风格的 ja_01.png、ja_02.png、...

# 平板平台 — 相同模式
python3 gemini_enhance.py \
  --input-dir output/en/ipad/ \
  --output-dir output/tr/ipad/ \
  --model nano-banana-pro \
  --translate-to "Turkish" \
  --lang-code "tr"

# 单个文件
python3 gemini_enhance.py \
  --input output/en/ios/en_01.png \
  --output output/tr/ios/tr_01.png \
  --model nano-banana-2 \
  --translate-to "Turkish" \
  --lang-code "tr"

# 自定义增强提示词
python3 gemini_enhance.py \
  --input shot.png \
  --output enhanced.png \
  --model nano-banana-2 \
  --prompt "Add warm lighting, floating music notes, and glass reflections"
```

**参数说明：**

| 参数 | 必填 | 说明 |
|----------|----------|-------------|
| `--input` | 是* | 输入截图路径（单文件模式） |
| `--output` | 是* | 输出路径（单文件模式） |
| `--input-dir` | 是* | 输入目录（批量模式） |
| `--output-dir` | 是* | 输出目录（批量模式） |
| `--model` | 是 | `nano-banana-pro`（质量更高）或 `nano-banana-2`（速度更快） |
| `--lang-code` | 否 | ISO 639-1 代码（如 `en`、`tr`、`de`、`ja`）。批量输出重命名为 `{code}_{n:02d}.png` 并添加文化视觉提示 |
| `--translate-to` | 否 | 将标题文字翻译为该语言（如 `"Turkish"`）。输入必须为英语 |
| `--app-desc` | 否 | 简短应用描述，用于生成相关装饰元素 |
| `--bg-color` | 否 | 背景十六进制颜色，用于渐变引导 |
| `--index` | 否 | 截图索引，用于提示词交替（偶数=风格A，奇数=风格B） |
| `--api-key` | 否 | Gemini API 密钥（或使用环境变量/配置文件） |
| `--save-key` | 否 | 将 API 密钥保存到 `.gemini_config.json` |
| `--prompt` | 否 | 自定义提示词（覆盖内置提示词） |
| `--platform` | 否 | 强制指定 `ios`、`android`、`ipad` 或 `android_tablet`（从尺寸自动检测） |

*使用 `--input`/`--output` 或 `--input-dir`/`--output-dir` 二选一。

**Gemini 模型对比：**

| 模型 | 质量 | 速度 | 最适合 |
|-------|---------|-------|----------|
| `nano-banana-pro` | 更高 | 较慢 | 最终生产截图 |
| `nano-banana-2` | 良好 | 较快 | 快速迭代和预览 |

**各语言代码对应文化风格：**

| 代码 | 应用的视觉风格 |
|------|-------------------|
| `tr` | 奥斯曼几何瓷砖、郁金香图案、赤陶与青绿色 |
| `de` | 包豪斯几何、冷钢蓝、结构化极简主义 |
| `fr` | 新艺术派曲线、金色点缀、巴黎优雅 |
| `ja` | 樱花、侘寂简约、水墨质感 |
| `ko` | 韩纸纹理、布角几何色彩 |
| `zh` | 如意云纹、竹子、红金点缀 |
| `ar` | 阿拉伯式几何、新月图案、青金石蓝与金色 |
| `ru` | 构成主义几何、深红与金色 |
| `es` | 摩尔式瓷砖暗示、赭石色调、地中海活力 |
| `it` | 文艺复兴构图、赤陶与钴蓝 |
| `pt` | 阿祖莱霍瓷砖图案、深靛蓝 |
| `hi` | 曼陀罗图案、藏红花与万寿菊色、莫卧儿几何 |
| `uk` | 彼得里基夫卡民间花卉、向日葵、蓝金配色 |
| `nl`、`pl`、`th`、`id` | 其他支持的语言区域 |

#### showcase.py — 生成预览画廊

```bash
python3 showcase.py \
  --ios output/ios/en_01.png output/ios/en_02.png output/ios/en_03.png \
  --android output/android/en_01.png output/android/en_02.png output/android/en_03.png \
  --output showcase.png
```

#### generate_frame.py — 重新生成设备外框

```bash
python3 generate_frame.py
```

重新生成 `assets/` 中的全部四个外框。仅在修改外框常量后需要执行。

## 输出结构

```
output/
  en/                         ← 英语（默认/源语言）
    ios/                        (1320×2868)
      en_01.png
      en_02.png
      ...
    android/                    (1080×1920)
      en_01.png
      ...
    ipad/                       (2064×2752)
      en_01.png
      ...
    android_tablet/             (1600×2560)
      en_01.png
      ...
  tr/                         ← 土耳其语（从 en/ 翻译）
    ios/
      tr_01.png
      ...
    android/
    ipad/
    android_tablet/
  de/                         ← 德语
    ios/
      de_01.png
      ...
    android/
    ...
  ja/                         ← 日语
    ...
showcase.png                  ← 并排预览图
```

## 截图尺寸

| 平台 | 宽度 | 高度 | 商店要求 |
|----------|-------|--------|-------------------|
| iOS 手机（App Store） | 1320 | 2868 | iPhone 6.9"（16 Pro Max） |
| 安卓手机（Google Play） | 1080 | 1920 | 标准手机 |
| iPad Pro 13"（App Store） | 2064 | 2752 | iPad Pro 13 英寸 |
| 安卓平板（Google Play） | 1600 | 2560 | 大屏手机/平板 |

## 更新

```bash
# 检查是否有新版本
python3 update.py --check

# 更新到最新版本
python3 update.py --update

# 显示当前版本
python3 update.py --version
```

## 上传到应用商店

### Apple App Store Connect
1. 进入 **我的 App** > 你的应用 > **App Store** 标签
2. 滚动到 **截图**
3. 在 **iPhone 6.9 英寸显示屏** 下上传 iOS 文件（`en_01.png` … `en_0N.png`）
4. 在 **iPad Pro 13 英寸显示屏** 下上传 iPad 文件

### Google Play 管理中心
1. 进入你的应用 > **商店发布** > **主要商店详情**
2. 在 **手机截图** 下上传安卓手机文件
3. 在 **平板电脑截图**（10 英寸）下上传安卓平板文件

## 设计原则

- **利益优先的信息传达** — 标题传递用户价值，而非功能名称
- **行动动词** — 醒目的动词（TRACK、DISCOVER、BUILD、CREATE）提升参与度
- **视觉层次** — 视线自然流动：标题 → 设备 → 应用内容
- **一致的品牌形象** — 整套截图保持相同的颜色、排版和布局
- **真实内容** — 截图展示应用实际使用状态，而非空白状态
- **文化真实性** — 每个语言版本在视觉上与目标市场产生共鸣

## 自定义

### 修改设备外框外观
编辑 `generate_frame.py` 中的常量（圆角半径、边框、颜色等）并重新生成：
```bash
python3 generate_frame.py
```

### 修改布局和排版
编辑 `compose.py` 中的 `PLATFORMS` 字典：
- `device_y` — 设备在画布上的垂直位置
- `text_top` — 标题文字起始位置
- `verb_size_max` / `verb_size_min` — 行动动词的字体大小范围
- `desc_size` — 描述语的字体大小

### 使用自定义字体
更新 `compose.py` 中的 `FONT_CANDIDATES_BOLD` 和 `FONT_CANDIDATES_REGULAR`。

## 许可证

MIT