Name: app-preview-craft
Author: Community

app-preview-craft — 商店截图、社交卡片和 3D 设备视频

该技能生成的所有内容都是一个页面 (stage/stage.html)，由主题布局后通过无头 Chrome 捕获：静态图像通过截图并用 sharp 处理完成，视频则逐帧渲染并导入 ffmpeg。同一个页面也驱动着预览 Studio，因此用户在 Studio 中看到的内容与 CLI 导出的内容完全一致。

0. 查找技能并进行一次性设置

以下路径相对于包含此 SKILL.md 的目录。 请解析一次，并将其作为命令的前缀——$SKILL 在整个文档中代表该目录：

SKILL=/absolute/path/to/app-preview-craft        # 包含 SKILL.md、scripts/、stage/ 的文件夹
# 不确定安装位置？(查找技能文件夹，然后是 Claude Code 插件缓存)
find ./.claude/skills ./.agents/skills ./.goose/skills ~/.claude/skills ~/.agents/skills \
     ~/.gemini/skills ~/.config/goose/skills ~/.claude/plugins \
     -path '*app-preview-craft*/scripts/cli.mjs' 2>/dev/null | head -1

然后检查机器。--fix 在缺少包时会在技能目录内运行 npm install：

node "$SKILL/scripts/doctor.mjs" --fix

Doctor 必须以 Ready. 结束。缺少 ffmpeg 只是一个警告（静态图像仍能工作）。如果报告没有 WebGL，则 3D 主题无法渲染——请明确告知用户，而不是静默切换到平面主题。

输出将写入用户当前工作目录（shell 的 cwd），除非他们使用 --out 指定了另一个文件夹。切勿将渲染结果写入 $SKILL。临时状态保存在 $TMPDIR/app-preview-craft/ 中，并在每次运行后清除。

1. 工作流程

选择类别（第一个 CLI 参数），根据用户的需求：

类别	生成内容	默认尺寸
`app-store`	一个集合：每张截图对应一个幻灯片，每种尺寸，加上 `overview.png`	`iphone-6.9` 1320×2868
`social-card`	一张卡片（或使用 `--all` 生成所有幻灯片的卡片）用于 og/X/LinkedIn/Instagram/故事	`og` 1200×630
`screen-video`	仅屏幕的 2D 动画；支持录屏	`reel` 1080×1920
`device-video`	three.js 设备展示视频	`reel` 1080×1920
`device-mockup`	3D 英雄静态图，可选透明背景	`mockup-landscape` 2400×1600

收集内容。 从用户项目中获取截图（PNG/JPG/WebP）和/或录屏（MP4/MOV/WebM），每个幻灯片一个，按顺序排列。除非用户提供文案，否则自行编写文案（参见第 4 节）。如果没有截图，则使用内置的示例应用“Tempo”——这适用于展示主题，但绝不能用于交付物。
选择主题。 用户命名的主题优先。对于 App Store 集合，将应用的商店类别与第 3 节的表格匹配，并说明您选择了哪个主题以及原因。当用户犹豫不决时，先向他们展示选项：
```
node "$SKILL/scripts/cli.mjs" gallery app-store        # → ./gallery-app-store.png
```
读回预览图片（以便为用户渲染），让他们选择。当用户想要浏览和微调时，Studio（第 8 节）是更好的选择。

渲染。

node "$SKILL/scripts/cli.mjs" app-store shots/01.png shots/02.png shots/03.png \
  --theme ledger \
  --title "每一欧元，*心中有数*" --title "预算会*自动调整*" --title "*设计上*保障隐私" \
  --subtitle "一行优势说明……" --subtitle "……" --subtitle "……" \
  --size iphone-6.9,ipad-13 --set palette.accent=auto

在报告之前检查。 查看 overview.png（集合）、静态图像，或从视频中抽取帧（--frames 1,4,mid,end 会渲染 PNG 帧而不是视频——检查运动效果更经济）。检查是否有裁剪的标题、覆盖在设备上的文本、遮挡装饰的设备、空白的屏幕。使用 --set/每个幻灯片的覆盖参数进行修复并重新渲染。
报告输出路径、主题和尺寸，并且——每当出现 3D 设备时——告知已写入 CREDITS.txt，并且 CC-BY 署名必须随图像一起传播（第 7 节）。

2. 尺寸

node "$SKILL/scripts/cli.mjs" list sizes --category app-store 会打印表格。任何 WxH 格式也有效。可以同时指定多个尺寸：--size iphone-6.9,iphone-6.5,ipad-13。

App Store Connect 要求 iPhone 应用使用 6.9 英寸屏幕尺寸集（iphone-6.9），iPad 应用使用 ipad-13；其他尺寸为可选。PNG 输出为扁平化（Apple 拒绝 Alpha 通道）。
平板电脑尺寸会自动将手机替换为平板电脑的扁平框架，除非主题是无框的。如果应用有 iPad 截图，请为这些幻灯片提供。
应用预览视频：--size app-preview（886×1920）或 app-preview-ipad，时长 15–30 秒，30 fps。会自动添加一段静音立体声 AAC 音轨（Connect 期望有音频）。
Google Play：play-phone、play-tablet 和 play-feature（1024×500，社交卡片）。

3. 主题

list themes --category <c> 会打印这些主题及其布局。每个类别至少有 5 个主题。

app-store——每个主题都模仿一个流行的应用类别

主题	应用类别	灵感来源	外观
`stride`	健康与健身	Strava, Nike Run Club	炽热橙色，浓缩全大写药丸，速度条纹，倾斜手机
`ledger`	金融	Revolut, Monzo, Robinhood	午夜网格，薄荷→青色渐变文字，铬色球体
`serene`	健康与正念	Calm, Headspace	柔和极光，斜体衬线强调，无框屏幕在柔软斑点之上
`canvas`	生产力	Notion, Things, Linear	温暖纸张，笔记本网格，大号衬线，扁平墨水手机
`sizzle`	美食与饮品	DoorDash, Uber Eats, Deliveroo	阳光黄色，波尔卡圆点，红色马克笔高亮，倾斜手机
`wander`	旅行	Airbnb, Hopper, Booking	黄昏渐变，带有复古太阳，贯穿整个集合（全景）
`mixtape`	音乐与音频	Spotify, Apple Music	屏幕模糊成发光背景，巨大的轮廓文字
`arcade`	游戏	Apple Arcade, 移动游戏发布宣传图	合成波网格，霓虹边框，光泽 3D 玩具
`snapshot`	照片与社交	Instagram, BeReal, VSCO	三张无框照片扇形排列，温暖胶片网格
`pulse`	健康数据与可穿戴设备	Oura, WHOOP, Apple Health	临床黑色，深红光芒，标题在正面的 Pro Max 下方

这些主题借鉴的是风格，而非品牌：这些应用中不会出现 Logo、名称或艺术作品。

social-card

launch（极光 + 倾斜手机）、spotlight（光束 + 镜面地板）、pastel-fan（三个扇形排列的屏幕）、bento（屏幕截图网格）、neon-grid（合成波）、editorial（纸张，衬线，双色调屏幕）、duo（MacBook + 手机——给笔记本电脑传递一个 desktop 屏幕）。

screen-video (2D)

carousel、stack（卡片飞走）、scroll（长截图在手机内滚动）、zoom-tour（全出血 Ken Burns 效果，移动到每个幻灯片的 focus）、wall（倾斜的屏幕墙）、store-preview（App Store 预览风格——使用 --size app-preview）、grid-reveal。

device-video (3D)

turntable、orbit（摄像机弧线运动）、float（可循环）、rise（摄像机推进）、flip（背面→正面展示）、trio（三个模型扇形展开）、desk（MacBook 盖子打开，手机滑入其旁边；两者都站在 scene.floor 上）、spotlight（在镜面上 360° 旋转）、synthwave、keyframes（您自己的设备和摄像机移动，来自 motion.keys——参见第 5 节）。

device-mockup (3D 静态图)

studio、noir、pedestal、levitate、lineup（每个手机型号）、flatlay、desk-duo。添加 --transparent 可生成剪影 PNG。

4. 文案

每个幻灯片的标题：≤ 6 个词，强调益处而非特性。将 1-2 个词用 *星号* 括起来，以在主题样式中突出显示；" | " 强制换行。
副标题：一个短句。标签（可选）：上方的一个单词标签。
前两个幻灯片承载宣传信息——大多数购物者不会继续滚动。
切勿虚构评分、下载量、奖项或媒体引用。装饰元素如 rating 和 laurels 仅用于用户提供的真实数据；如有疑问，请询问。
不要在文案中提及竞争对手或使用 Apple/Google 的商标，除非商店指南允许。

5. 配置所有内容

解析顺序，后者的优先级更高： 内置基础 → 布局默认值 → 主题（及其 extends 链）→ 自定义主题文件 → 项目配置 themeOverrides → CLI 快捷方式 → --set → 每个幻灯片的 theme。

快捷方式：--layout --device --finish --pose --font --body-font --bg --bg2 --bg3 --ink --sub --accent --accent2 --background --pattern --background-image --clean-status-bar --no-decor --duration --fps --speed --intro --outro。
--set path=value 可以访问任何主题键（可重复）。list options 会打印带有类型和范围的文档化路径。值会被强制转换；JSON 适用于列表/对象：--set device.pose=5,-15,4 --set 'decor=[{"kind":"sparkles","count":8}]'。
device.pose 是 x,y,z 度数。主题大致保持在 ±20° 偏航和 ±6° 滚动范围内，以便屏幕在商店缩略图尺寸下仍可阅读；更陡的角度可行，但会牺牲可读性。
颜色接受 auto = 第一张截图中最鲜艳的颜色：--accent auto。
--device iphone-17-pro | iphone-17-pro-max | iphone-12-pro | galaxy-s21-ultra | macbook-pro-16 | flat[:phone|phone-android|tablet|browser] | frameless | none，或用户自己的模型 ID（第 7 节）。
布局在同一类别的输出中可互换（list layouts）：静态图——hero-top、hero-bottom、tilt、duo、fan、split、big-type、callout、bento、laptop-phone、showcase、pedestal、lineup、flatlay；视频——carousel、stack、scroll、zoom-tour、wall、phone-swap、grid-reveal、turntable、orbit、float、rise、flip、trio、desk、spotlight、keyframes。
您自己的运动：keyframes 布局通过 motion.keys 控制一个 3D 设备和摄像机的移动，motion.keys 是一个列表，包含 { "at": 0..1, "x", "y", "size", "pose": [rx, ry, rz], "cam": { "yaw", "pitch", "dist" }, "ease" }。at 是整个视频的分数；某个键省略的值会保持前一个键的值；第一个键从主题自身的姿态开始。缓动函数：linear inOutCubic inOutSine outCubic outQuart outBack inOutQuart outExpo。 --theme keyframes --set 'motion.keys=[{"at":0,"y":1.4,"pose":[0,70,0]},{"at":0.3,"y":0.62,"pose":[4,-20,3],"ease":"outQuart"},{"at":1,"pose":[0,15,0],"cam":{"dist":0.9}}]'。不涉及动画库：每一帧都是其时间的纯函数，这使得帧可以乱序渲染。使用 --frames 0,2,mid,end 检查运动。

自定义主题是 JSON（或 .mjs）文件，包含主题键的任何子集，外加 extends：

{ "extends": "app-store/ledger", "name": "Acme", "palette": { "accent": "#ff5a1f" },
  "type": { "display": "bricolage", "weight": 800 }, "device": { "finish": "#1c1f24" } }

传递 --theme path/to/acme.json，或将其放在 ./.app-preview-craft/themes/（或 ~/.app-preview-craft/themes/）中，然后使用 --theme acme。list themes 会显示自定义主题。

项目配置。 node "$SKILL/scripts/cli.mjs" init app-store 会写入 app-preview-craft.json；之后运行 node "$SKILL/scripts/cli.mjs"（无参数）会渲染它，而标志会覆盖它。$SKILL/examples/app-preview-craft.json 是一个完整的工作示例：包含每个幻灯片的文案、装饰和主题覆盖、一个自定义主题文件、一个桌面屏幕，以及一个 jobs 列表，可以在一个命令中渲染 App Store 集、社交卡片、样机图和视频。配置文件中的路径相对于配置文件本身解析。

每个幻灯片的键：screen、desktop（笔记本电脑显示屏）、title、subtitle、kicker、theme（仅覆盖该幻灯片的设置）、decor（替换该幻灯片的主题装饰）、focus: [x, y, zoom]（缩放游览目标）、hold（视频中的秒数）、trim: [start, end] 和 at（录屏中用于静态图的秒数）、bigWord（大字体布局）。

装饰元素是 {kind, x, y, scale, rotate, style, layer, delay, …}，其中 x/y 是页面分数，style 是 glass | solid | light | dark | outline 之一：

kind	额外键
`badge`	`text`、`icon` (star bolt heart check sparkle trophy leaf lock music pin flame bell chart shield globe play)
`rating`	`score`、`label`、`starColor`
`laurels`	`top`、`text`、`bottom`
`chips`	`items[]`、`icons[]`、`width`、`lead`
`notification`	`app`、`title`、`body`、`time`、`icon` (图像路径) 或 `glyph`、`width`
`stat`	`label`、`value`、`trend`、`trendColor`
`callout`	`rect: [x, y, w, h]` 截图中要放大的区域，`w`、`border`、`radius`
`arrow`	`w`、`h`、`text` (手写笔记)、`flip`、`stroke`
`logo`	`name`、`src` (应用图标路径)
`store-badge`	`top`、`text`，或用于官方徽章素材的 `src`
`sparkles`、`confetti`	`count`、`colors[]`、`area: [x0, y0, x1, y1]`、`seed`
`blob`	`size`、`color`、`opacity` (位于设备后面)
`orbs`、`rings`、`shapes`	3D 图元：`count`、`shapes[]`、`finish` (glossy chrome matte glass iridescent)、`area`、`items[]`
`credit`	`text` (默认为模型署名行)

6. 屏幕和处理

sharp 在 Chrome 启动前预处理每张截图：screen.cleanStatusBar (重新绘制 9:41 / 满电 iOS 状态栏——仅限手机形状的截图)、tint + tintAmount、duotone: "#dark,#light"、saturate、brightness、sharpen，以及用于 blur-shot 背景的预模糊背景图。
在 iPhone 型号上，灵动岛被绘制为一个合并的黑色药丸形状，覆盖在模型的药丸和摄像头切口上，与 iOS 显示一致。请提供灵动岛区域清晰的截图（任何正常的 iOS 截图都是如此）；cleanStatusBar 会保留两侧的时间和图标。
比显示器更高的截图会在视频中滚动（scroll 主题），并在静态图中显示其顶部（screen.fit=top）。
录屏会被 ffmpeg 以输出帧率分割成帧；在视频中，每个录屏的幻灯片持续时间与剪辑长度相同（使用 hold 覆盖，使用 trim 剪切）。静态图使用一帧（at，默认为中间帧）。
笔记本电脑显示屏会在模糊副本上添加黑边显示手机截图，除非幻灯片有 desktop 屏幕。desktop 也接受录屏。在 desk 视频主题中，MacBook 展示 desktop 屏幕，而旁边的手机展示 screen。

7. 输出、署名和您自己的模型

所有图像和视频都写入 --out （默认为 cwd）。命名：{theme}-{slide}.png {theme}-video.mp4。集合获得 overview.png。社交卡片模板使用 {theme}-{slide}-{format}.png。

署名 — 每次使用 3D 设备模型时，无论是内置的还是自定义的，都会写入 CREDITS.txt ：

内置模型由 18 位艺术家根据 CC-BY 4.0 授权：下载链接和归属列表位于 $SKILL/CREDITS.md。用户必须在其渲染的图像中包含该列表或其简化版本。
用户的自定义 .glb 模型（在 --device my-device.glb 或 theme.device.glb 中）必须附带模型自身的 CREDITS.txt 文件，该文件会与输出合并。用户同意自行管理其模型的许可条款。

8. Studio（实时预览）

node "$SKILL/scripts/cli.mjs" studio [--theme ledger]

启动一个本地服务器，在浏览器中打开 stage/stage.html，并启用所有组件（装饰、帧率控制、实时编辑）。
用户拖入截图，或在页面内选择它们。
所有键盘快捷键和主题切换器都是原生的。预览始终处于活跃状态；不涉及热重载。
如果用户对某个变化不确定，Studio 中的默认视图与 CLI 导出的完全一致。告诉他们：“点击导出按钮可将当前帧保存到 --out。”
Studio 不会自动停止。在用户确认完成前不要继续操作。

9. 环境

工具	版本	用途
Node.js	≥ 18	脚本运行时
Chrome (无头)	最新稳定版	页面渲染和捕获
ffmpeg	≥ 5 (可选)	视频编码

默认字体：Inter 用于非衬线布局；Playfair Display 用于衬线布局。这可以通过 --font 或 --body-font 覆盖。语言设置：系统会根据屏幕截图元数据自动检测，但可以通过 --lang zh-CN 强制指定。

10. 故障排除

“无输出文件” → 检查 doctor 是否报告了 Ready.；运行 --verbose 查看更多细节。
“WebGL 不可用” → 3D 主题需要 GPU 加速。切换到平面主题（如 ledger、stride），或使用 --device flat。
“截图未对齐” → 检查 screen.cleanStatusBar 是否已启用；手动调整 screen.fit 为 cover 或 contain。
“视频无声” → ffmpeg 需要 AAC 编码器；运行 ffmpeg -encoders | grep aac。
“模型未显示” → 验证 .glb 文件的路径；使用 --verbose 查看模型加载错误。

有关装饰、布局和色彩理论的详细信息，请参阅 $SKILL/docs/ 中的文档。

11. 示例工作流

# 一次性设置
SKILL=/path/to/app-preview-craft
node "$SKILL/scripts/doctor.mjs" --fix

# 为您的健身应用生成 App Store 截图
node "$SKILL/scripts/cli.mjs" app-store shots/01.png shots/02.png shots/03.png \
  --theme stride \
  --title "追踪*每一步*" --title "挑战你的*极限*" --title "与朋友*一起*" \
  --subtitle "实时追踪你的跑步与锻炼" --subtitle "设置个人目标并打破记录" --subtitle "分享动态，互相激励" \
  --size iphone-6.9,ipad-13

# 生成社交分享卡片
node "$SKILL/scripts/cli.mjs" social-card shots/01.png --theme launch --size og

# 打开 Studio 进行微调
node "$SKILL/scripts/cli.mjs" studio --theme stride

app-preview-craft