app-preview-craft — 商店截图、社交卡片与 3D 设备视频
此技能生成的所有内容都是一个由主题装饰的页面（stage/stage.html），并通过无头 Chrome 捕获：静态图通过截图并由 sharp 处理完成，视频逐帧渲染并导入 ffmpeg。同一页面也驱动预览工作室，因此用户看到的预览与 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.pngiphone-6.91320×2868social-card一张卡片（或 --all所有幻灯片）用于 og/X/LinkedIn/Instagram/storyog1200×630screen-video纯屏幕的 2D 动画；可接受屏幕录制 reel1080×1920device-videothree.js 设备展示视频 reel1080×1920device-mockup3D 英雄静态图，可选透明背景 mockup-landscape2400×1600 -
收集素材。 从用户项目中获取截图（PNG/JPG/WebP）和/或录制（MP4/MOV/WebM），每张幻灯片一个，按顺序排列。除非用户提供文案（参见第 4 节），否则由你自己撰写文案。没有截图时，将使用捆绑的示例应用 "Tempo" — 仅用于展示主题，绝不用于交付物。
-
选择主题。 用户指定的主题优先。对于 App Store 集合，将应用的应用商店类别与第 3 节的表格匹配，并说明你选择了哪个主题及原因。当用户犹豫不决时，先向他们展示选项：
node "$SKILL/scripts/cli.mjs" gallery app-store # → ./gallery-app-store.png将表格读回（以便为用户渲染）并让用户选择。当用户希望浏览和可视化调整时，工作室（第 8 节）是更好的选择。
-
渲染。
node "$SKILL/scripts/cli.mjs" app-store shots/01.png shots/02.png shots/03.png \ --theme ledger \ --title "Every euro, *accounted for*" --title "Budgets that *adapt*" --title "Private *by design*" \ --subtitle "One-line benefit…" --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 截图时，为这些幻灯片提供 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 下方 |
主题借用情绪，而非品牌：不出现这些应用的徽标、名称或艺术作品。
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 个单词周围加上
*星号*以使用主题样式高亮它们；" | "强制换行。 - 副标题：一句简短句子。Kicker（可选）：上方的一个单词标签。
- 前两张幻灯片传达核心理念 — 大多数购物者不会继续往下滚动。
- 切勿虚构评分、下载量、奖项或媒体引述。装饰元素如
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视频布局中，两个屏幕并排渲染，每个屏幕都有其自己的内容（screen和desktop必须提供才能显示）。flat设备类型渲染一个扁平的二维码 - 风格的屏幕框架，无逼真手机模型；适用于简单的功能预告或公告。
7. 设备模型与归属
list devices打印内置设备模型（手机、平板、手表、笔记本），每个都包含其设计师和来源。每个 3D 设备模型 都必须附有CREDITS.txt文件，其中包含归属信息。该文件会在你首次导出包含该模型的任何内容时自动写入，但你有责任确保署名随最终图像一起传播。- 自定义设备：提供一个
.glb文件和一个等宽 PNG 贴图（物理尺寸与屏幕区域匹配）。将模型放入./.app-preview-craft/devices/中；下次运行list devices时会显示它。
8. 预览工作室
当用户想通过可视化操作和调整设置时，运行：
node "$SKILL/scripts/cli.mjs" studio
这会启动一个本地服务器（通常是 http://localhost:4444），允许用户在浏览器中实时调整。它使用与 CLI 导出完全相同的舞台和渲染引擎。应用到主题、布局或装饰的更改会立即反映。工作室是完全包含的：无需外部 CDN。
9. 约束
- 仅使用
$SKILL/stage/中的标记、CSS 和 JS — 不要注入外部库、文档或转译。headless Chrome 会渲染普通 HTML + 模块<script type="module">标签。 - 生成静态图时 — 不要启动浏览器；当需要精确控制文本或布局时，使用 HTML 渲染完全值得。无头 Chrome 启动延迟约为 2–3 秒。
- 当用户要求“商店截图”时，指的是 App Store 集合。询问基于 iOS 还是 Android。
- 请勿将应用标题或副标题替换为模板占位符。按照第 4 节的指导撰写文案。
- 请勿修改或替换
doctor.mjs、cli.mjs或stage/内部的任何内容。这些文件定义了技能的行为。 - 如果报告指出缺少 WebGL 或没有无头 Chrome，明确告知用户，不要尝试使用备用渲染器。
- 不要在同一个答案中同时运行多个渲染命令。
- 对于 App Store 集合，始终包含
overview.png。不要跳过它。 - 当生成社交卡片时，检查布局是否在广泛的文本变体中保持平衡。对较长标题进行微调，使它们不大于简报目录中的卡片。
- 对于 3D 模拟图，如果存在
--transparent，则输出必须是一个带有 alpha 通道的 PNG。默认是实色背景。 - 当视频输出过长（> 30s）时，提出建议以使其更紧凑。
- 除非用户明确要求，否则不要显示或复制原始 CLI 输出（例如，组合视频的 ffmpeg 日志）。如果遇到错误，请优雅地处理：描述问题，提供解决方案，并询问用户是否希望继续。