koubou

Koubou：App Store 截图生成器

使用 HTML/CSS 模板生成专业的 App Store 截图，提供 100 多种真实设备边框、xcstrings 本地化支持，以及像素级精准的 Apple 尺寸。

截图是广告，不是文档。每张幻灯片都应推销一种感受、一种结果，或一种痛点解决方案。

用户指示始终优先于此技能中的默认设置。

默认情况下，创意方向不受限制。 运用此技能中的规则来确保冲击力、可读性和适配画布的缩放比例，而不是让每套截图看起来都一样。

规则层级

按以下顺序遵循此技能中的指导：

1. 硬性约束——可读性、缩放比例、缩略图清晰度、真实可信的产品营销，以及对画布的充分考量
2. 强烈建议——多样性、不对称、重叠、节奏感，以及避免使用千篇一律的布局
3. 审美偏好——避免粗制滥造的经验法则和风格默认设置；若有更出色的创意能明显提升作品效果，则可打破这些规则

如果打破某项默认设置能生成更好的截图集，请有意为之，并在生成前自行说明这种取舍。

参考文件（按需阅读，无需预先阅读）：

• setup.md — 安装和 HTML 运行时设置
• design-guide.md — 设计原则、文案撰写规则、CSS 规则、HTML 模板示例
• style-intake.md — 在提问前如何检查应用的真实视觉风格
• style-interview.md — 简短、重点突出的风格问题和对话模式
• yaml-reference.md — YAML 配置格式、本地化、素材、设备、尺寸
• capabilities-reference.md — koubou 的完整功能（内容模式、高亮、缩放、渐变）

阶段 1：设置（静默、自动）

先检查 kou 是否可用。如果 kou 已正常运行，则不要重新安装，也不要动 Python 打包环境。

首选顺序：

kou --version 2>/dev/null

如果 kou --version 执行成功：

• 视为已安装 koubou
• 不要运行 pip、pip3 或 playwright install
• 不要主动尝试“升级”或“修复”用户的环境
• 生成前始终运行 kou setup-html，因为此技能仅使用 HTML，且该命令可安全地重复运行

如果 kou --version 执行失败，请阅读 setup.md，并选择对环境影响最小的方式。

对于 HTML 渲染支持：

• 始终使用 kou setup-html
• 即使 HTML 在上次运行中正常工作，也不要跳过此步骤
• 不要直接运行 playwright install chromium

只有在设置失败时才告知用户。绝不要更改正常工作的安装环境。

阶段 2：了解应用，然后提问

不要一开始就使用泛泛的风格问卷。先检查应用的真实视觉风格，然后只询问仍缺失或不明确的信息。

提问前阅读 style-intake.md。按此顺序操作。

2.1 风格探索（提出风格问题前的必做步骤）

先检查本地项目源文件，再询问用户对视觉风格的想法。应先自动搜索。

优先检查以下来源：

1. Assets.xcassets、应用图标、插画、Logo、颜色资源
2. 现有截图和营销文件夹：
   • .maestro/
   • screenshots/
   • AppStore/
   • fastlane/screenshots/
   • marketing/
3. 产品文档和定位：
   • README*
   • CLAUDE.md
   • 发布计划、落地页文案、文档文件夹
4. 设计令牌和 UI 代码：
   • CSS 变量
   • SwiftUI 颜色、渐变、材质、排版选择
   • Web 主题文件和共享设计常量
5. 如果存在，查看以往的 App Store 资源：
   • 过往模板
   • 旧版截图宣传素材
   • 本地化营销资源

至少提取并总结以下信息：

• 主色和强调色
• 整体对比度：深色、浅色、混合、柔和、鲜艳
• UI 密度：疏朗、均衡、密集
• 形状语言：锐利、柔和、圆润、卡片较多、扁平
• 图标和插画风格
• 可见时的字体排版方向
• 文案语气：沉静、技术感、活泼、高端、温暖、紧迫
• 应用给人的整体感觉：沉静、技术感、温暖、有活力、精致、活泼等

如果应用风格清晰：

• 用通俗语言向用户总结检测到的风格信号
• 确认会基于这一方向创作，而不是从通用模板风格重新开始

如果风格信号较弱、缺失或相互矛盾：

• 说明找到了什么
• 针对尚不确定的部分提出聚焦的追问，不要泛泛地询问设计偏好

2.2 意图访谈（简短且直击重点）

阅读 style-interview.md，只询问必要的问题。保持对话自然，不要一次性抛出所有问题。

仍有必要时必须询问的风格问题：

1. 这组宣传图应营造什么感觉：高端、活泼、编辑风、实用、技术感、温暖等？
2. 是否有希望作为参考的 App Store 页面、品牌或截图组？
3. 有哪些视觉风格是明确禁止的：醒目渐变、玻璃拟态、仅深色、卡片网格、过于活泼的样式等？
4. 截图中必须保留应用本身的哪种视觉特征，才能让人认出它？

仅在仍未明确时询问的可选问题：

5. 偏好的排版方向或字体个性
6. 偏向浅色、深色还是混合
7. 密度偏好：留白更多，还是信息更多
8. 整组页面应保持高度统一，还是每张幻灯片都明显各异

2.3 产品信息（仍为必需）

开始风格探索后，自然地收集其余制作所需的信息：

1. 应用：名称、功能（一句话说明）、主要价值主张
2. 截图：应用截图在哪里？先自动搜索：
   • 如果找到了，展示搜索结果并请用户确认
   • 如果没有找到，询问用户如何生成截图
   • 优先使用能清晰展示应用 UI 的干净模拟器截图。如果用户可以选择，优先将近期的 6.1 英寸 iPhone 截图用作素材
3. 重点展示的功能：按优先级排列的功能或优势（建议 3–5 项）。每张幻灯片对应 1 项功能
4. 主视觉素材：应用图标或其他品牌素材。先自动搜索，再询问
5. 幻灯片数量：需要多少张截图（建议先做 3–5 张，Apple 最多允许 10 张）

仅在相关时询问的可选信息：

6. 设备：默认使用 iPhone 16 Pro - Black Titanium - Portrait。仅在 iPad、Mac 或其他设备更合适时询问
7. 本地化：仅当项目已有 xcstrings 或支持多种语言时询问
8. 其他素材：悬浮 UI 元素、徽章、辅助插画
9. 其他限制：必须包含的宣传内容、禁用风格或营销限制

2.4 风格决策（HTML 之前必须完成）

在编写模板之前，明确决定并在内部锁定以下六项：

• 检测到的品牌信号
• 选定的营销风格
• 文案语气
• 背景系统
• 设备构图节奏
• 幻灯片之间的变化计划

每项都必须有以下依据之一：

• 风格探索中发现的应用证据，或
• 访谈中用户提供的直接反馈

如果无法为某项提供依据，请继续提出有针对性的问题，再开始设计。

派生项（除非受阻，否则不要询问）

• 根据品牌颜色和 UI 氛围设计背景渐变或纹理
• 布局分布（主视觉 → 顶部特性 → 底部特性 → 交替布局）
• 根据功能和价值主张撰写标题文案
• 根据应用的实际配色确定辅助配色
• 通过 kou inspect-frame，根据 project.device + project.output_size 确定画布类别
• 是否应显示应用名称。默认：除非在可读尺寸下能带来真正的品牌价值，否则不显示
• 是否应显示应用图标。默认：仅在主视觉或收尾幻灯片中谨慎使用，不要将其作为微小的装饰标记

原则：如果本地已有相关上下文，应先使用，再提问。风格问题应在检查之后提出，而不是之前。

阶段 3：生成

生成模板前先阅读 design-guide.md。编写配置前先阅读 yaml-reference.md。

1. 创建工作目录（例如 AppStore/，或项目中合适的位置）

2. 运行 kou setup-html

3. 从 YAML 中读取 project.device 和 project.output_size；对于 iPhone Duo 这类双屏设备，则读取 project.displays 下的每个条目（见 yaml-reference.md）

4. 运行 kou inspect-frame "<device>" --output-size <size> --output json（每个显示屏运行一次），并在编写 CSS 前使用其几何信息

5. 在开始布局前，先拟定叙事脉络，并为每张幻灯片准备 2-3 个标题／副标题选项。先选出最有力的方案。文案质量优先于 CSS

6. 将风格决策转化为宣传方案：

   • 整组内容应营造什么感觉
   • 允许使用哪些视觉元素
   • 禁止使用哪些视觉元素
   • 前 5 张幻灯片应呈现多大程度的变化

7. 使用 HTML 模板创建 templates/，至少要有 3 种不同布局，并且前 3 张幻灯片不得重复使用同一种构图类型

8. 在每个 HTML 模板中，编写任何 CSS 之前，为以下元素添加 data-kou-id 和 data-kou-role：

   • 主标题：data-kou-id="headline" data-kou-role="headline"
   • 辅助文案：data-kou-id="subtitle" data-kou-role="supporting"
   • 主设备图片：data-kou-id="device" data-kou-role="device"
   • 功能标题／副标题（收尾／功能幻灯片）：data-kou-id="feature-N-title" data-kou-role="feature-title"、data-kou-id="feature-N-sub" data-kou-role="feature-sub"

   缺少这些属性时，布局 sidecar 的 elements 数组将为空，渲染后的 QA 就无法进行。正确的标注方式请参见 design-guide.md 中的模板示例。

9. 使用 koubou 配置创建 config.yaml（格式请阅读 yaml-reference.md）

10. 使用能适应画布和文案长度的 CSS：有意地使用 vw 或 clamp()，优先采用 CSS Grid、重叠布局和绝对定位图层，并在实际画布上验证最终计算出的文字缩放比例

11. 编写 HTML 之前：规划每张幻灯片的文字／设备区域（每个区域占画布的百分比）。明确区域划分后再开始编写 CSS

12. 运行：kou generate config.yaml --output json

13. 对于每张生成的 HTML 截图，从 JSON 结果中读取 layout_path，并在判断布局是否合格前检查 sidecar

14. 渲染后 QA（必须执行，不得跳过）：

    • 直观检查每张生成的幻灯片
    • 打开 layout_path 引用的每个 *.layout.json sidecar
    • 对照 design-guide.md 中的拒绝检查清单进行检查
    • 检查渲染后的整组内容是否仍体现你发现的应用风格，而非通用的 App Store 默认风格
    • 仅使用布局 JSON 检查客观几何信息：位置、占用空间、比例和数学意义上的重叠
    • 如果某张需要测量的 HTML 幻灯片的 elements 为空，应视为标注缺失或损坏，并修复模板
    • 确认：没有表情符号图标、没有完全相同的卡片网格、设备没有偏离中心、文字没有低于最小缩放比例、设备没有被意外裁切（主视觉幻灯片上必须显示设备顶部／刘海；屏幕内容必须清晰可读）
    • 应用 Logo 替换测试：这些幻灯片能否用于竞争对手的产品？
    • 如果有任何幻灯片不合格，应先修复并重新生成，再向用户展示

15. 打开输出文件夹：open <output_dir>

16. 询问用户是否需要调整——针对具体幻灯片迭代，无需全部重新生成

迭代规则

• 用户要求修改特定幻灯片时，只修改对应的模板和配置条目
• 用户要求全局风格调整（颜色、字体、氛围、密度、粗细）时，更新所有模板
• 修改后重新运行 kou generate config.yaml --output json，确保新的 layout_path 值与 sidecar 文件保持同步
• 用户需要编辑时实时预览，请使用 kou live config.yaml
• 如果幻灯片看起来太小，先增大缩放比例或切换布局。不要用额外的渐变或标签掩盖问题
• 如果文案导致文字过小，就改写文案或选择更合适的布局；绝不能因为“文字必须放得下”就接受效果平淡的幻灯片
• 保持足够的多样性：目标是让整组内容风格统一，而不是重复使用同一布局
• 如果输出仍违反设计规则或拒绝清单，不要在第一次成功渲染后就停止
• 用户要求改变氛围时，应在质量限制范围内重新诠释整组内容，而不是为之前的默认设置辩护
• 如果截图与布局 JSON 不一致，应以渲染后的截图为准来判断视觉效果，并检查标注或渲染时机，而不是依据过时的几何信息强行决定布局

硬性规则

硬性约束

• 绝不使用表情符号作为图标——使用 CSS 形状（强调色条、圆点）或纯文本
• 绝不使用禁用的文案表达——“revolutionary”、“seamless”、“unlock”、“game-changing”等
• 应用品牌替换测试——如果换成竞争对手的名字也适用，那么整组内容就太过泛化
• 每个 HTML 模板都必须带有 data-kou-id 标注——至少包括：headline、subtitle 和 device。如果生成后布局 sidecar 中的 elements 为空，就说明缺少标注——在 QA 通过前修复模板。不要向用户展示未标注的幻灯片。

比例

• 在竖屏 iPhone 画布（iPhone6_9、iPhone6_7）上，主视觉标题必须 >=10vw，侧边布局标题必须 >=10vw，副标题必须 >=4.5vw
• 只有在目标画布上计算出的字号仍达到最低要求时，才能使用 vw 或 clamp()
• 在对比页或结束页上，内容组合必须占据画布高度的 60% 以上

强默认规则

• 连续幻灯片不要使用相同的直立居中手机构图
• 标题与设备之间不要留出高度超过画布 15% 的大片空白
• 除非渲染后视觉中心仍然自然，否则不要在居中设备上同时使用 rotate() 和 translate()
• 如果幻灯片需要重叠、突破边缘的裁切或分层构图，不要使用简单的居中弹性布局列
• 编写 CSS 前先规划文字与设备区域（参见 design-guide.md 中的 Device-Text Zone Planning）
• 如果使用卡片网格，除非严格网格确实符合概念，否则应错开排列、突出重点或简化设计

内容

• 默认不要添加细小的顶部标签、类别标签或应用名称标题
• 除非清晰易读且具有明确的策略目的，否则不要将应用名称渲染为小号装饰文字
• 不要将应用图标用作角落的小装饰；如果使用，应将其作为真正的品牌元素
• 不要为了简短而采用生硬、直译或不自然的标题
• 在幻灯片叙事与文案尚未连贯之前，不要开始布局工作

流程

• 如果前 3 张幻灯片还没有达到 App Store 上架水准，就继续迭代后再展示
• 不要将第一次技术上成功渲染的结果作为最终版本——始终按照 design-guide.md 中的拒绝清单进行检查
• 不要让规则削弱创意方向。只要保持可读性并具有强烈的视觉冲击力，奇特但出色的构图也完全可行
• 如果最终效果更出色、更清晰，也更贴合应用，就可以打破默认规则
• 不要默认采用“深色渐变 + 居中手机 + 大号白色标题”的通用方案，除非应用确实适合这种风格，或用户明确提出要求
• 你应该能向自己解释，为什么这组宣传图体现的是这个应用的特色，而不是某个功能列表相同的竞争对手

关键技术细节

HTML 模板中的资源工作方式

在模板 HTML 中，使用 {{asset_name}} 引用资源。在 YAML 配置中，将 asset_name 映射到 assets: 下的文件路径。

Koubou 会自动预渲染每个图像资源，并套用配置的设备边框，然后再传递给 HTML 模板。模板接收的是合成图像（设备边框内的屏幕截图），只需使用 <img src="{{asset_name}}"> 放置即可。

若要为特定屏幕截图停用边框：在其 YAML 定义中设置 frame: false。

模板变量替换

• YAML 中的 variables: → HTML 中的 {{key}} → 可本地化文本（提取到 xcstrings）
• YAML 中的 assets: → HTML 中的 {{key}} → 图像文件路径（预渲染并套用设备边框）

HTML 屏幕截图的布局 JSON

对于 HTML 屏幕截图，Koubou 可以生成包含测量布局几何信息的精简旁文件 JSON。

• 对任何需要测量的元素使用 data-kou-id
• 仅在有助于模型理解元素时使用 data-kou-role
• 注释应尽量简洁并体现结构，不要面面俱到
• 合理的默认做法：标注主标题、辅助文案以及主要设备或主视觉图像

示例：

<h1 data-kou-id="headline" data-kou-role="headline">{{headline}}</h1>
<p data-kou-id="subtitle" data-kou-role="supporting">{{subtitle}}</p>
<img data-kou-id="device" data-kou-role="device" src="{{app_screenshot}}" alt="">

生成工作流：

• 运行 kou generate config.yaml --output json
• 从命令输出中读取 layout_path
• 打开所引用的 *.layout.json

解读规则：

• 几何字段是归一化比例，范围为 0..1
• elements 仅包含已标注的节点
• overlaps 仅包含数学意义上的边界框交集
• 使用此文件了解布局事实，而不是判断审美
• 不要仅凭 JSON 臆测“尺寸过小”等主观规则；应结合几何数据和实际屏幕截图进行审查

输出结构

{output_dir}/{language}/{device_name}/{screenshot_id}.png

非本地化项目会跳过语言目录。

设备边框名称

使用 kou list-frames 中的准确名称。常见名称：

• iPhone 16 Pro - Black Titanium - Portrait
• iPhone 16 Pro Max - Black Titanium - Portrait
• iPad Pro 13 - M4 - Space Gray - Portrait
• iPhone Duo - Night Sky - Outer Closed Portrait 和 iPhone Duo - Night Sky - Inner Open Portrait（也有 Star White、横屏姿势，以及 Outer Open）

使用以下命令搜索：kou list-frames "iPhone 16"

iPhone Duo

一台设备，两块显示屏：外屏为 1398x2034，内屏为 2007x2853（也有对应的横屏版本）。使用 project.displays，让一份配置渲染两块屏幕；每块屏幕会输出到各自的文件夹。App Store Connect 会将两者保留在同一个屏幕截图集内：使用 asc screenshots upload --device-type IPHONE_DUO 上传每个文件夹（需 asc 5.12.0+）。canvas_class 为 duo_outer_portrait 或 duo_inner_portrait：内屏画布接近正方形，因此应针对它设计布局，而不是重复使用高长比 iPhone 模板。Apple 的指南要求产品图像原样使用：文案应放在设备旁边，而非覆盖在设备上。

用于布局决策的边框检查

使用 kou inspect-frame "<device>" --output-size <size> --output json 获取：

• 实际边框尺寸
• 屏幕边界和屏幕边界框
• 安全边距
• 覆盖率
• 方向
• canvas_class

使用这些数据选择字体排版比例、裁切强度和布局密度。

输出尺寸（App Store 尺寸）

名称	尺寸	设备
iPhone6_9	1320x2868	iPhone 16 Pro Max、15 Pro Max
iPhone6_7	1290x2796	iPhone 15/14/13 Pro Max、Plus
iPhone6_5	1242x2688	iPhone 11 Pro Max、XS Max
iPhone6_1	1179x2556	iPhone 16/15/14/13 Pro
iPhoneDuo_Outer	1398x2034	iPhone Duo 外屏
iPhoneDuo_Inner	2007x2853	iPhone Duo 内屏
iPhone5_5	1242x2208	iPhone 8 Plus、7 Plus
iPadPro13	2064x2752	iPad Pro 13" M4
iPadPro12_9	2048x2732	iPad Pro 12.9"
iPadPro11	1668x2388	iPad Pro 11"

自定义：output_size: [1320, 2868]