hypershots

HyperShots — 规格可靠的 App Store 截图

该确定的地方就确定（HTML/CSS：设备边框、字体、文案、画布尺寸、语言区域）；只有在有帮助时才使用生成式功能（抠图贴纸、可选的风格调色）。你为每个 App 编写定制的面板 HTML；脚本负责确保符合规格。

适用场景 / 不适用场景

适用于：App Store 截图集、本地化现有截图集、修改面板、“让我的截图更酷”、Apple 截图规格相关问题、向 ASC 提交完成的截图集。不适用于：通用图像生成、社交媒体 / OG 图片、捕获模拟器截图（→ fastlane snapshot）。

意图路由

用户需求	首先阅读	然后
新建截图集	references/create.md	搭建脚手架 → 编写简介 → 选择主题 → 编写内容 → 渲染 → 自行检查 → 验证
为 App 选择字体	references/typography.md	沿用品牌字体，或从菜单中选择 → scripts/fetch-fonts.sh 会将字体引入项目
调整标题 / 贴纸 / 主题	references/revise.md	编辑 → 重新渲染 → 重新验证
本地化现有截图集	references/translate.md + references/i18n.md	提取键 → strings..json → 注入 → 渲染 → 验证
风格化 / 调色外观	references/edit-filter.md	对每个面板运行 edit-pass.sh，对整组运行 grade-set.sh，以保持风格一致（需要 genmedia + ImageMagick）
生成贴纸 / 背景	references/asset-recipes.md	使用固定的 genmedia 配方 + 降级模式
需要截屏 / 手势进行中的画面	references/capture-recipes.md	simctl 状态栏 / 外观 / 连拍配方
将截图集提交到 App Store Connect	references/fastlane-deliver.md	验证 → 复制 out/ → fastlane/screenshots/<asc-locale>/ → 执行 deliver lane
Apple 尺寸 / 规格问题	references/store-specs.md	画布表格、素材规则
在 hypershots.dev 上展示截图集	references/gallery-submission.md	经同意后创建 GitHub issue
遇到问题	references/gotchas.md	症状 → 原因 → 修复

前置条件（每次会话）

bash <skill>/scripts/preflight.sh

始终以 0 退出码结束——这是报告，而非门禁。chrome 和 node 为必需项：若缺少其中任意一项，请停止并帮助用户安装（或运行 export CHROME=/path/to/chrome）。imagemagick 为可选项（用于 Alpha 扁平化、风格编辑合成）。genmedia 为可选项——仅在需要生成素材或风格调色时才需要；若缺少且任务需要这些功能，请先征求用户同意再安装：npm i -g genmedia && genmedia setup（需要用户的 FAL_KEY），然后运行 genmedia skills install genmedia && genmedia skills install fal-models-catalog。如果用户拒绝，请使用降级模式（references/asset-recipes.md）。

画板契约

即使不阅读 create.md，每个 Agent 也必须遵守的部分：

• 几何类不可变（.panel .stage .device .screen .di .statusbar）——由配置文件 CSS 变量（--panel-w/--panel-h）设定尺寸。绝不硬编码画板像素值，也绝不重设 .device 样式。屏幕宽高比约为 0.460。类型类（.headline .sub .eyebrow）可以在 theme.css 中重设样式——这是品牌层的职责（fit.js 会测量实际框，因此更改字号/字重是安全的）。
• .stage 是必需的绝对定位层（inset:0），用于容纳作为同级元素的设备和贴纸——省略它会导致设备失去定位上下文（这是错误做法，但验证仍会通过）。
• 真实模拟器截图上绝不可叠加 .di/.statusbar（<img class="shot"> 已包含自己的状态栏和灵动岛）——否则会出现双 DI 问题。
• 每个画板都必须包含以下标记：每个可翻译节点上都有 data-i18n="pN.key"（双引号、单行，且只能包含文本和 <br>——不能嵌套其他标记）；标题/副标题块上有 data-fit；.wrap 和 .device 上有 data-protect="name"。
• fit.js 必须是 <body> 中的最后一个元素——它会等待 document.fonts.ready，并输出 render.sh 所需的适配/保护框数据。
• 画板不能依赖时间、随机性或动画——render.sh 会运行两轮 Chrome（截图 + DOM 转储），两轮结果必须一致。
• 完整的创作骨架、贴纸原语和叙事弧指导：references/create.md。

工作区

bash <skill>/scripts/scaffold.sh [dir=.shots]

在用户的仓库中运行——已安装的技能目录是只读参考，绝不可在其中创作。如果 <ws>/brief.md 已存在，则拒绝运行（说明你正在进行修订）。画板会通过工作区同级路径链接套件副本（../frame.css、../theme.css 等）。如果你的技能副本中存在 examples/spotless/panels/panel-1.html，请在创作第一个画板前将其作为带注释的示例阅读。

让输出变好的循环——必做

render.sh → Read every rendered PNG yourself → fix → re-render → validate.sh → review page (make-review.mjs) + contact sheet → show the user

阅读每张 PNG 并检查：文案溢出或换行不自然、贴纸被裁切/重叠、.di/.statusbar 双灵动岛、可读性（墨色与纸张的对比度、强调色不会产生视觉抖动）、截图拉伸/裁切不当。绝不要跳过阅读——验证器检查规格，不检查审美；只有你的眼睛能发现被裁切的贴纸。

render.sh <ws> [profile=iphone-6.9] [locale=en] 退出代码：1 通用错误（没有 Chrome、没有画板、Chrome 崩溃、未知配置文件——检查 profiles.json）；2 适配失败（文案触底后仍与设备重叠——应改写文案，而不是降低底线）；3 画板尺寸 ≠ 配置文件（几乎总是因为画板 <head> 中缺少 ../profile.css）。

常见错误

在真实截图上叠加 .di/.statusbar；硬编码画板像素值或重设 .device 样式（会破坏配置文件 → 边距 → alpha → 拒绝）；在 theme.css 中使用远程字体 @import（字体必须随项目提供，且使用 font-display:block）；手动编辑 out/ 或 panels-<locale>/（两者都是生成内容——渲染会清空 out/，成功注入会清除过时的 panels-<locale>/*.html）；因为“看起来没问题”就跳过 validate.sh；将 iPhone 画板重新渲染为 ipad-13（iPad 是单独的创作流程，宽高比为 0.75）；对 data-i18n 使用单引号（注入器无法识别——最终会发布英文，并在之后因出现未使用键而报致命错误）。

审核清单（展示给用户之前）

• 每个要发布的配置文件 + 语言环境，validate.sh 都会输出 VALIDATED
• 最后一次编辑后，你已阅读每张 PNG
• 画板不超过 10 张；前 3 张传达安装决策（“显示全部”之前大约只会显示 3 张）
• 每张画板都包含所需标记：data-i18n、data-fit、data-protect
• 主题源自应用的实际品牌，而不是脚手架的占位符令牌

验证

• 在依赖上述内容之前，请根据实际脚本检查其中关于命令、标志和退出代码的所有说明——本文仅作摘要，脚本才是事实依据。
• 在认为技能更改已完成之前，npm run validate（仓库根目录——检查 SKILL.md frontmatter）和 bash tests/run-tests.sh（夹具渲染/验证/翻译测试套件）都应通过。