card

VoxFlow 技能 — 卡片

将一段文本转化为一组风格鲜明、视觉统一的卡片图片。每张卡片都是一个独立网页；所有卡片采用相同的尺寸和样式系统；使用 Playwright 渲染并导出为 PNG。

这是静态卡片图片技能。其他内容形式请切换到：

• 文章 → 竖版卡片视频（Slice） — 1080×1920 短视频，13 种主题 → voxflow:slice
• 短视频 / AI 剪辑 / 知识卡片视频 → voxflow:video
• 多人播客 → voxflow:podcast
• TTS / 语音 / 安装 / 身份验证 / 配额 → voxflow:hub

如果任何 `voxflow` 命令向 stderr 输出一行 ``，请立即运行 `voxflow upgrade -y` 后再继续——不要询问，也不要先总结。如果 `voxflow upgrade` 因 `Unknown command` 报错（CLI 版本早于 1.12.0），则改用 `npm i -g voxflow@latest`。

步骤 0 · 登录检查（必需，首先执行）

此技能属于 VoxFlow，需要登录账户。在进行任何其他操作之前——提问、调研、设计之前——请先验证是否已登录：

voxflow status

• 显示账户和剩余配额 → 已登录，继续工作流。
• 报错 / 显示“not logged in” → 停止。运行 voxflow login（会打开浏览器，可使用 Google 或电子邮件 OTP），等待用户完成登录，然后重新运行 voxflow status。登录成功之前，请勿收集参数或生成任何卡片。
• voxflow: command not found → 先运行 npm install -g voxflow，然后运行 voxflow login。

绝不可跳过此检查，绝不可为未通过身份验证的用户生成卡片，也绝不可捏造令牌。缓存的令牌位于 ~/.config/voxflow/token.json；CI 中也支持 VOXFLOW_TOKEN。

概览

根据源内容创建一组可分享的视觉卡片。将每张卡片视为一个独立网页，确保所有卡片尺寸和样式系统一致，使用 Playwright 渲染并导出图片，然后迭代优化效果较弱的卡片。

品味基准

references/taste.md 是一份约束检查清单，用于限定每种卡片模板、主题、布局和设计语言。应将其视为设计阶段的底线，而不是工作流开始时照本宣科的开场仪式。

• 仅在以下两个时机加载 references/taste.md，不要在工作流开始时加载：
  • 选择主题预设和设计语言时（工作流步骤 4），确保选择符合硬性约束。
  • QA 评分时（工作流步骤 7），将其作为一项明确的验证维度。
• 其他步骤（参数收集、调研、文案规划）无需重新加载 references/taste.md；已选的预设和设计语言会将这些约束传递到后续步骤。
• 核心目标是去除明显的 AI 生成设计痕迹。
• 硬性约束包括：不使用默认的 Inter 字体、不使用纯黑色、不采用默认居中式主视觉、不使用三个等大的卡片组合、不采用通用的 AI 文案风格，也不使用看起来虚假的数据。
• 有品味不等于内容空洞。遵循 references/taste.md 中的密度规则，确保真正的卡片组至少包含一张实用信息卡，除非用户明确要求只制作海报或电影感卡片组。
• 如果主题预设或设计语言与 references/taste.md 冲突，应以品味基准为准，除非用户明确要求采用被禁止的风格。

输入

收集或推断：

• content：源文本、大纲、笔记、URL、主题或简述。
• ratio：默认设为 1:1，除非用户要求 3:4、9:16 或其他比例。
• count：根据内容密度自动确定默认数量；接受明确指定的数量。
• style：接受明确的风格指导、品牌限制、受众、氛围和平台要求。
• content-language：zh / en / mixed。根据来源内容推断；仅在情况模糊且会影响字体选择时询问。决定 references/fonts.md 中的语言覆盖设置。
• output：选择清晰的本地文件夹，例如 cards/<slug>/，除非用户另有指定。

如果重要事实可能已经变化或存在争议，请先搜索或核实，再进行规划。如果研究影响了内容，请保留来源归属信息，供用户查看。有关何时需要进行完整的深入研究而非快速核查，请参阅“研究与事实确认”部分。

研究与事实确认

仅当输入本身不足以作为卡片内容时，才在参数收集与设计工作之间加入此步骤。

• 当 content 属于以下任一情况时，触发深入研究：主题短语、单句简述、尚未阅读正文的 URL、推文长度的想法、问题，或“解释 X / 介绍 X / 制作关于 X 的卡片”这类请求。
• 当 content 已经是内容完整的文章、访谈记录、结构化笔记、完整的大纲，或用户明确希望基于这些文本制作卡片，而不是围绕这些内容另行创作时，跳过深入研究。
• 触发后，先整理事实大纲，再进行任何视觉规划：
  • 核心论点或主旨。
  • 3–7 条支持要点，包含具体数字、名称、日期或机制。
  • 每项非平凡事实的来源，附上将记录到 sources.md 中的 URL 或文档引用。
  • 用户需要确认的未决问题或争议点。
• 将事实大纲提交给用户，并在进入主题／设计语言选择前，请用户确认、补充或更正。这与之后的概念／视觉确认是分开的。
• 此步骤的产出是“骨架”——论点与证据，而不是完成的卡片文案。卡片层面的吸引点、解说和要点将在内容结构化阶段（第 5 步）基于已确认的骨架撰写。
• 事实大纲确认后，立即将此处收集的来源记录到输出文件夹中的 sources.md。

触发示例

以下情况需要进行深入研究：

• “做一组讲 MCP 协议的卡片”——只有主题，没有正文。
• “把这篇文章做成卡片：https://example.com/post”——当前对话中尚未阅读内容的 URL。
• “想做一组讲 RAG 优化技巧的卡片，重点放在 chunking 上”——只有主题和角度，没有具体要点或数据。
• “Cloudflare Durable Objects 适合什么场景？做几张卡片”——问题或“解释 X / 介绍 X”的表述。
• 只提供一条推文、标题或单句简述，其中仅提及主题，没有提供证据。

以下情况跳过深入研究：

• 用户粘贴了完整文章、博客文章、访谈记录或访谈正文（大约 500 字以上且内容完整的来源文本）。
• 用户提供了结构化笔记、会议纪要、课程笔记，或已经完成的大纲，其中已列出每张卡片的标题和 2–4 个要点。
• 用户提供了自己写好的文案，只要求进行视觉处理（“把这段话排成卡片”“美化一下这段文案”）。
• 用户明确表示“不要查资料 / 直接基于这段写 / 不要扩展”，无论输入有多长。

临界输入

• 简短概要与目标不匹配——例如，200 字的摘要加上“展开成 7 张卡”。概要内容太少，无法填满目标数量，因此应触发调研，并在扩写前指出概要缺乏证据。
• 文章加上“再补点最新数据 / 加点案例”——仅针对用户要求补充的内容开展范围明确的调研；不要重新调研用户已经写好的部分。
• 有标题但没有证据的项目符号列表——例如，“1. 性能更好 2. 更便宜 3. 更安全”。触发调研，补充具体数字或案例；否则卡片读起来会像 AI 凑出来的内容。
• 文章加上用户自己的观点或看法——跳过对来源的调研，但要向用户确认是否应逐字保留该观点，还是重新组织表达。
• 正文已在本次对话前文中获取并讨论过的 URL——将其视为已粘贴的内容，跳过调研，但仍要将该 URL 写入 sources.md。

输入含糊时，先问一个澄清问题（“这段内容是要直接做成卡片，还是希望我先查资料再展开？”），不要自行猜测——错误的调研决策会浪费用户的时间或模型的调研额度。

向用户提问

在概念规划前，于开始阶段一次性询问缺失的生成参数。将“向用户提问”视为一项可移植的决策策略，而不是调用特定工具的要求。不同编码 Agent 提供的交互机制各不相同，因此，无论 Agent 是否支持结构化提问工具，或其运行模式是否不鼓励使用此类工具，该技能都必须适用。

• 首先提取已知的 content、ratio、count、theme/style、platform/audience 和 output/constraints 值。
• 只要仍缺少任何有实质影响的选择，就在规划前请用户确认生成参数。即使用户说“帮我做 / 生成 / 制作 / 直接出图 / quickly export”，也要这样做；这些表达要求执行，并不代表可以默默推断参数。
• 如果答案会实质影响输出，就要提问。优先顺序：content/source intent、ratio、count、theme/style、platform/audience、output/constraints。
• 默认情况下，最多提出 3 个简洁问题。只有用户明确希望选择配置，或输出影响重大时，才可提出最多 5 个问题。
• 用户原始请求中已明确的参数，不要再次询问。
• 只有当用户明确表示不要提问，或明确同意使用默认参数时，才跳过提问步骤。在这种情况下，使用默认值，并在执行前或执行过程中简要说明假设。

兼容策略

使用当前环境中可用的最佳提问机制：

• 如果环境支持 ask_user_question、ask question 或同等的原生澄清功能，就使用该原生交互来澄清阻碍任务的问题。
• 如果环境不支持原生提问功能，就在正常对话中直接提问。
• 每次最多提出 2-5 个问题。
• 如果缺失的信息不会阻碍任务，仍要询问一次，确认会影响最终输出的参数。如果用户已同意使用默认值或要求不要提问，就做出合理假设并继续。
• 在最终回复、sources.md 或 credits.md 中明确列出重要假设。

停止条件

仅在满足以下任一条件时，才应在生成前停止并提问：

• 没有可用的 content、主题、URL 或源材料。
• 来源意图含糊，选错会浪费工作量，例如“原样使用这段文字”与“调研并扩展这个主题”之间的区别。
• 所要求的比例与平台要求相互矛盾，或无法通过单次导出实现。
• 视觉方向受品牌、法律、无障碍或精确文案要求约束，但缺少相关信息。
• 调研发现存在争议的事实，而这些事实会改变核心主张。

否则，询问一次以确认有实质影响的生成参数，然后按已记录的假设继续，并将这些假设记录在 sources.md 或最终回复中。

比例问题

使用以下默认选项：

• 1:1 方形卡片，适合一般社交分享。
• 3:4 竖版图文卡片，适合内容更丰富的文字／图片帖子。
• 9:16 故事、短视频、短视频封面或移动端优先的卡片。

如果用户提供了 4:5、16:9 等自由比例或精确像素尺寸，也应接受。

数量问题

使用以下默认选项：

• 根据内容自动推荐。
• 3 张卡片，适合紧凑的叙述。
• 5 张卡片，适合标准的说明内容。
• 7 张卡片，适合更完整的轮播内容。

自动推荐时，应选择能够完整表达主题且不会显得拥挤的最少卡片数。说明内容优先使用 3–7 张卡片，公告优先使用 1–3 张卡片。

主题问题

不要直接向用户展示完整的预设目录。加载 references/themes/presets.md，并在视觉方向很重要时加载 references/design-languages.md；然后根据内容、平台、受众和分享目标，推荐 3–5 种基于使用场景的风格选项。在内部将用户选择的场景映射到最终主题预设和设计语言组合。

询问用户选择风格时，不要只给出一个推荐选项，再含糊地问“或者要更改吗？”。提供 3–5 个具体选项，每个选项包括：

• 面向用户的简短风格名称；
• 最适用的场景；
• 一句话描述视觉效果；
• 内部主题预设和设计语言映射。

使用双层选择逻辑，确保输出既恰当，又不会总是集中在少数几种风格上：

1. 默认推荐层：

   • 根据内容类型、平台、受众和分享目标，提供 3–5 种高度契合的风格。
   • 推荐选项应与用户的任务足够贴近，让任一选项都能胜任，而无需大幅返工。
   • 优先选择视觉效果明显不同的选项，而不只是令牌名称不同。例如：保守型报告、数据海报、社交笔记、杂志式说明、鲜明观点。

2. 变体扰动层：

   • 如果用户没有明确指定具体风格，应在兼容的风格系列中轮换，而不是总选默认首选项。
   • 对于相似任务，至少在以下维度中改变两项：主题预设、主要设计语言、修饰项、布局配方、视觉锚点、表面隐喻或标题构图。
   • 变体必须在语义上适合内容。不要采用与主题、平台、无障碍需求或事实清晰度相冲突的随机新颖设计。
   • 在概念计划或 sources.md / credits.md 中记录最终选定的组合，以便检查变体。

使用面向用户的场景标签，例如：

• 工程信息图：映射到 engineering-paper、product-manual 或 porcelain-research。
• 商务简报：映射到 quiet-report、product-manual 或 porcelain-research。
• 鲜明观点：映射到 bold-editorial、magazine-eink 或 newsroom-paper。
• 社交产品短评：映射到 social-notebook、magazine-eink 或 bold-editorial。
• 编辑／杂志风格：映射到 magazine-eink、dune-gallery、field-notes 或 kraft-editorial。

对于设计语言选项，使用面向用户的场景标签，例如：

• 兼具技术感与设计感：映射到 editorial-artifact + cutaway + annotation。
• 杂志式说明：映射到 image-led-magazine + edge-crop + asymmetric-space。
• 鲜明主张：映射到 swiss-poster + scale-contrast + split-field。
• 新闻事件：映射到 newsroom-poster + stamp-label + big-number。
• 档案卷宗：映射到 field-notes + layered-depth + receipt-form。
• 产品标本：映射到 product-catalog + edge-crop + annotation。
• 数据海报：映射到 data-poster + scale-contrast + big-number。

用户选择后，在进入概念计划之前，说明选定的主题方向、最终预设、设计语言组合，以及该组合为何适合。

设计背景

优先沿用现有设计背景，而不是另创一套视觉系统。

• 选择视觉方向前，务必先加载 references/taste.md。将其中关于避免 AI 痕迹的规则融入视觉基因摘要。
• 规划卡片前，先查找用户提供或本地已有的品牌素材、以往的卡片组、截图、Figma/UI 套件参考、项目设计系统、现有网页或代码风格，判断哪些应当影响最终效果。
• 用户要求采用编辑风、杂志风、电子墨水风、演示文稿风或图片密集型卡片样式时，加载 references/magazine-card-adaptations.md，并仅应用适合卡片的部分：编辑风外框、紧凑布局原型、克制的墨色／纸张配色，以及图片插槽工作流。
• 卡片组需要更强的设计感，或风格并非明确的极简风时，加载 references/layouts/card-layouts.md，并在编写 HTML 前将其用作布局规范。
• 卡片组需要更强的设计感、风格变化或可供用户选择的视觉方向时，加载 references/design-languages.md，并选择一种主要设计语言和 1-2 种修饰风格。
• 提炼简洁的视觉基因摘要：配色、字体观感、信息密度、边框圆角、阴影／层次、图片或插画处理方式、布局节奏，以及文案语气。
• 如果没有可靠的设计背景，则根据内容、受众、平台和要求的氛围推导视觉方向，并在计划中说明这一假设。

主题预设

将主题预设作为起点，而非照搬 CSS。为每组卡片定义一套全新的设计令牌，并根据内容调整配色。

• 选择主题前，先应用 references/taste.md。预设可以提供配色和氛围建议，但不得因此重新引入 Inter、纯黑、居中主视觉默认样式、三张等宽卡片、AI 紫蓝渐变、霓虹光效、虚构数据或 AI 式文案语气。
• 用户要求提供风格选项、风格不明确，或卡片组需要明确的视觉方向时，加载 references/themes/presets.md。
• 在适当情况下，编码前先提供 3-5 种基于场景的主题选项。不要向用户列出完整的预设目录。
• 将选定的场景方向转换为目录中的最终预设，再通过全新的本地设计令牌进行调整。
• 不要整套照搬外部主题 CSS。应在本地卡片样式中重新实现所需的配色和效果。

默认推荐规则：

• 技术、API、架构或基础设施内容：优先选择 engineering-paper；备选为 product-manual 和 porcelain-research。
• 新闻、发布、产品更新、变更日志或事故内容：优先选择 newsroom-paper；备选为 quiet-report 和 engineering-paper。
• 商业、融资、增长或产品叙事内容：优先选择 quiet-report；备选为 product-manual 和 porcelain-research。
• 观点、评论或适合传播的强钩子内容：优先选择 bold-editorial；备选为 magazine-eink 和 newsroom-paper。
• 小红书、生活方式或消费类产品内容：优先选择 social-notebook；备选为 magazine-eink 和 bold-editorial。
• 编辑内容、演讲摘要、长篇内容、文化、随笔或高端轮播内容：优先选择 magazine-eink；根据主题，备选为 dune-gallery、field-notes 和 kraft-editorial。
• CLI、安全或终端工具：优先选择 engineering-paper、product-manual 或 newsroom-paper；仅在用户明确要求终端风格时使用 terminal-green。
• 除非用户明确要求这类视觉语言，否则不要默认采用霓虹、赛博朋克、终端风格、发光的深色仪表板或蓝紫色 AI 渐变。

编辑杂志模式

当卡片组需要借鉴演示文稿或杂志设计时，使用 references/magazine-card-adaptations.md。此模式灵感来自 op7418/guizang-ppt-skill，但已针对静态卡片导出进行调整。

• 仅复用适合卡片的设计理念：编辑风格装饰、页脚元数据、可见页码、衬线／展示字体标题层级、等宽字体元数据、克制的墨色／纸张配色，以及紧凑的布局原型。
• 不要复用幻灯片专属行为：横向导航、WebGL 背景、Motion One 显示系统、由 vh 驱动的幻灯片尺寸，或仅适用于 PPT 的类名。
• 编写代码前，为每张卡片选择原型：编辑风格封面、章节分隔页、大数字、左侧叙述＋右侧视觉内容、图片佐证网格、流程／过程、以问题收尾、大段引文、前后对比，或主图＋侧边栏。
• 将 chrome 和 kicker 视为不同的内容角色。chrome 是稳定的元数据或系列导航；kicker 是该卡片独有的引子。两者不得重复表达同一概念。
• 如果涉及图片，请先定义图片槽位和宽高比，再寻找或生成素材。生成的图片仅作为卡片素材；其中不得包含标题、页码、水印、说明文字或卡片边框。

布局规范

只要输出需要具备可见的设计质感，而不仅仅是信息易读，就使用 references/layouts/card-layouts.md。

• 将 references/taste.md 作为首要布局筛选标准。除非用户明确要求且有充分理由，否则舍弃居中主视觉默认布局和三等分卡片布局。
• 编写 HTML 前，创建一份每张卡片占一行的布局计划，包含：卡片角色、布局方案、视觉锚点、文本密度、素材槽位和布局风险。
• 从整组卡片的层面规划信息密度。真正的讲解类卡片组不能让每张卡片都处于低密度；至少要包含一张机制说明、佐证、清单、对比或要点总结卡片，并列出 2-4 个具体要点。
• 每张卡片都必须有视觉锚点。锚点可以是字体排版、数字、图片、实物、图表、表单、印章、地图、截图或自定义 CSS 对象。如果锚点为“无”，就重新设计卡片概念。
• 对于 1-3 张卡片，至少使用 2 种布局方案。对于 4-7 张，至少使用 3 种。对于 8 张及以上，至少使用 4 种，并且每 3-4 张加入一张重置卡片。
• 避免整组反复使用 headline + equal grid + footer。风格统一很好，但构图不要重复。
• 避免将细线、坐标网格和方框面板作为默认设计语言。仅将它们用作更强视觉锚点的辅助元素。
• 优先采用剪裁、叠放、对角线布局、尺寸对比、剖切形状、印章、标签、胶带、大型图片／物件锚点和不对称留白等构图手法。
• 在概念规划阶段，如果布局／设计质量是重点，请展示布局计划。在最终质量检查时，注明每张渲染卡片实际使用的布局。

设计语言系统

使用 references/design-languages.md，在不受主题预设影响的情况下定义卡片组的视觉语法。

• 主题预设控制配色和字体氛围；设计语言控制构图、视觉焦点、视觉隐喻、肌理和节奏。
• 选择 1 种主要设计语言，并可选 1–2 种修饰语言。除非用户要求多元混搭，否则设计语言和修饰语言总数不要超过 3 种。
• 选择主要设计语言后，加载其专属规范文件 references/design-languages/<name>.md，并遵循其中的 Must Use、Must Not Use、排版、布局、密度、素材和 QA 规则。
• 支持的主要设计语言包括 editorial-artifact、swiss-poster、image-led-magazine、field-notes、newsroom-poster、product-catalog、cinematic-still 和 data-poster。
• 支持的修饰语言包括 scale-contrast、edge-crop、diagonal-tension、layered-depth、split-field、asymmetric-space、cutaway、stamp-label、receipt-form、annotation、big-number、paper-cut 和 map-route。
• 用户可以选择预设组合，例如 Technical but designed、Magazine explainer、Bold thesis、News incident、Archive dossier、Product specimen 或 Data poster。
• 在整组卡片中保持设计语言组合一致，但针对每张卡片调整布局方案和视觉锚点。
• 如果卡片组混用多种主要设计语言，应为整组指定一种主要设计语言，其他语言仅作为单张卡片的点缀。

工作流

1. 收集参数，并在需要时向用户提问。

   • 从原始请求中提取已知参数，不要重复询问。
   • 遵循 Ask User Questions 策略：推断低风险默认值，只询问真正的阻碍项，并适应当前 Agent 的交互模式。
   • 此步骤不要读取 references/taste.md；该文件将在第 4 步（主题／语言选择）和第 7 步（QA）中加载。
   • 只有用户明确要求不提问或明确同意使用默认值时，才跳过提问步骤。直接生成、快速导出或“帮我做”请求，如果缺少重要选择，仍需先进行一次参数确认。

2. 按需进行深入研究并确认事实提纲。

   • 遵循 Research & Fact Confirmation 中的触发规则：输入为主题、URL、简报、问题或“围绕 X 制作卡片”的请求时，进行研究；输入已是完整文章、文字记录、结构化笔记或完成的提纲时，则跳过。
   • 触发研究时，整理事实提纲（核心论点、3–7 条包含具体数据的支撑要点、来源、待解问题）。如果事实、框架或范围可能改变卡片叙事，应提交给用户并等待确认；否则，在初次参数确认后记录清晰且无争议的事实及其来源。
   • 在以确认流程为主的工作流中，将此确认与第 6 步后续的视觉／概念确认分开处理。在以执行为先的工作流中，除非符合 Stop Conditions，否则将其作为简短的进度更新，而不是阻塞关卡。
   • 将已确认的来源保存到输出文件夹中的 sources.md。
   • 未触发研究条件，或用户明确要求不做研究时，完全跳过。

3. 扩展内容并规划结构。

   • 从已确认的内容骨架中提炼核心信息、目标受众、情感切入点、主张和支撑要点（如果跳过了步骤 2，则直接从输入内容中提炼）。
   • 如果未提供 count，请选择能够涵盖主题且不会显得拥挤的最少卡片数；说明类内容优先使用 3-7 张卡片，公告类内容优先使用 1-3 张。
   • 为每张卡片确定标题、副标题和核心视觉构思。
   • 在撰写最终文案前，确定整组卡片的内容密度变化。对于 3 张卡片，默认采用 hook / explain / takeaway；对于 5 张卡片，默认采用 hook / context / mechanism / evidence / takeaway；对于 7 张卡片，默认采用 hook / context / mechanism / evidence / contrast / action / closer。
   • 除非用户只想要海报式卡片，否则至少要有一张卡片包含一项具体主张，以及 2-4 条支撑要点、标签、观察、步骤或标注。
   • 规划文案时，删除 AI 文案套话、泛泛的占位品牌名或占位人名，以及看起来像伪造的数据。

4. 选择主题预设和设计语言，然后制定布局方案。

   • 现在加载 references/taste.md，并将其作为必须遵循的检查清单；本步骤中所有后续设计决策都必须遵守其中的硬性约束。
   • 根据风格基准，确认或重新评估步骤 1 中选择的主题预设；如果某个预设会违反硬性约束，则先替换再继续。
   • 应用两层风格选择逻辑：先从高度匹配的推荐项中选择，再在用户未指定确切风格时，进行兼容的变体调整。
   • 变体调整必须影响实际视觉效果，而不能只体现在元数据中。除主题／设计语言标记外，还要轮换布局方案、视觉锚点、表面隐喻和构图手法。
   • 为每张卡片指定一个具体布局方案。若要提升设计质量，请使用 references/layouts/card-layouts.md；对于杂志／编辑风格卡片，还要使用 references/magazine-card-adaptations.md。
   • 如果风格开放，或用户希望有更多设计变化，则指定设计语言组合。加载所选主要设计语言对应的单独规范文件 references/design-languages/<name>.md。
   • 加载 references/fonts.md 并执行其中的字体选择算法：根据所选预设 × 设计语言 × 内容语言，获取各角色的候选字体池，应用硬性约束筛选，然后为整组卡片的每个角色进行加权随机抽选（使用输出 slug 作为随机种子，确保同一组内容可复现，同时让不同主题有所变化）。在 sources.md 中记录所选的 display/serif/sans/mono 字体系列。
   • 对于每张卡片，在撰写正文前先确定视觉锚点和构图手法。如果卡片只有文字块、等大的方框或背景网格，则应改用更有力的布局，或明确将其标记为低设计度实用卡片。
   • 遵守低内容密度主要设计语言的限制：应将细节移至同组的其他卡片，不要让 swiss-poster、cinematic-still、引言卡、封面卡或收尾卡承载过多内容。

5. 规划概念并请求确认。

   • 呈现最终确定的比例、卡片数量、选定的主题方向和预设、选定的设计语言／修饰元素、内容大纲，以及首张卡片的概念。
   • 当布局质量很重要时，附上布局方案：卡片用途、布局配方、视觉锚点、构图手法、文字密度和素材位置。
   • 如果封面或主要语言有意采用低密度设计，请说明哪张卡片承载了实用细节。
   • 将第 1 张卡片设计成精准且有冲击力的封面：必须让人立即了解主题，引发好奇，并让人觉得值得打开和分享。
   • 概念确认仅涵盖封面概念、内容大纲和视觉方向。不要重复询问已确定的比例、数量、主题、平台或输出限制。
   • 当任务影响重大，或经过提问步骤后风格仍不明确时，在编写代码前提供 3-5 种视觉方向。应涵盖不同选项，例如符合品牌风格／保守、结构化／信息图表、适合社交传播、杂志／编辑风格，以及更大胆／更易分享的风格。
   • 对每种方向，描述封面概念、整体视觉语言，以及最适合的使用场景。
   • 如果用户已指定视觉风格、明确要求不经确认直接继续，或需要快速直接导出，则跳过概念变体。
   • 适用停止条件时，或概念方向可能实质性改变输出时，请在编写代码前请求用户确认。如果用户已确认参数，且概念符合这些选择，则简要说明概念，作为进度更新，然后继续实施。

6. 构建卡片网页。

   • 为每张卡片创建一个 HTML 页面，并采用 card-01.html、card-02.html 这类易于预测的命名方式。
   • 使用一个共享 CSS 文件或共享设计令牌，确保尺寸、排版、间距、配色、圆角和组件样式保持一致。
   • 按照第 4 步确定的 references/fonts.md 选择算法选用字体；通过导入 assets/fonts/fonts.css 在本地嵌入字体（或将所用字体复制到 cards/<slug>/assets/fonts/，并使用本地 @font-face 引用）。切勿从 CDN 加载字体。选择符合 references/taste.md 要求的颜色：不要默认使用 Inter，不要使用纯黑色，并避免采用千篇一律的 AI 紫蓝渐变或霓虹光效。
   • 根据比例设置明确的固定画布尺寸。建议尺寸：
     • 1:1：1080x1080
     • 3:4：1080x1440
     • 9:16：1080x1920
     • 自定义比例 a:b：宽度设为 1080，高度设为 round(1080*b/a)，除非用户要求精确像素尺寸。
   • 将每张卡片都限制在单个固定尺寸的 .card 根元素内。禁止页面纵向滚动。
   • 使用真实的 HTML/CSS 文本，不要将文字烘焙进图片。
   • 所有卡片使用相同的风格语言；仅为适应内容而调整构图。
   • 在制作单张卡片前，先在 CSS 中为选定的布局配方定义共享布局基元。每张卡片都应有一个易识别的布局父类，例如 .layout-cover、.layout-split、.layout-artifact、.layout-rail、.layout-compare、.layout-quote 或 .layout-checklist。
   • 对于杂志编辑模式，使用本地 CSS 中的卡片原生类来构建外壳。不要粘贴 PPT 布局类，除非这些类已在该卡片组的 CSS 中定义并经过适配。

7. 为每张卡片评分并重新生成。

   • 重新加载 references/taste.md，并在评分前将其作为 QA 验收清单阅读；不要凭记忆评分。
   • 渲染每张卡片并截图，然后再进行评判。
   • 按以下类别为每张卡片评分：
     • 边界：没有明显裁切、意外滚动条、画布外的文字，或紧贴边缘的重要元素。
     • 色彩：调色板清晰易读、赏心悦目、设计有意图，并与要求的风格一致。
     • 布局：层级清晰、留白均衡，内容密度符合画面比例。
     • 信息价值：整组卡片至少有一张包含可操作或具体的细节，而不只是营造氛围的标题；任何低密度卡片都必须有充分的角色定位或主要语言上的理由。
     • 布局约定：计划中的视觉锚点确实存在且足够突出；从截图中能够辨认出设计方案；整组卡片不会张张重复同一种构图。
     • 设计表现：卡片不能主要依赖细线、网格和带边框的面板；这些元素必须从属于视觉锚点。
     • 设计语言：从截图中能够辨认出选定的主要设计语言及其修饰特征，并且符合相关规范文件的 Must Use / Must Not Use 规则。
     • 品味基线：符合 references/taste.md 中的每一条硬性约束——不得默认使用 Inter、纯黑、默认居中的主视觉、三个等宽卡片组成的主体布局、AI 文案腔、看起来虚假的数据或霓虹／发光的 AI 美学。
     • 编辑规范（适用时）：界面装饰与引导语不重复，图片框使用一致的裁切规则，生成的素材不包含自身的幻灯片／卡片界面装饰。
   • 如果任何类别不合格，就修改该卡片并重新渲染。每张卡片最多修复 3 轮。
   • 如果卡片经过 3 轮修复后仍不合格，报告剩余风险，并保留最佳版本。

8. 导出最终图片。

   • 使用 Playwright 截图，不要手动截取浏览器画面。
   • 每张卡片导出一张 PNG，并使用稳定的文件名，例如 card-01.png。
   • 默认以 2x 倍率导出截图，以确保清晰度。尺寸为 1080x1080 的卡片应导出为 2160x2160 的 PNG，除非用户明确要求较小的文件，或指定 --scale 1。
   • 向用户提供输出路径，并简要说明最终画面比例、卡片数量和风格。

9. 为视频导出编写 deck.json（用户要求视频／旁白时必须执行）。

   • 完成所有 HTML 卡片并导出 PNG 后，在输出目录中编写 deck.json。
   • 此文件用于下一步合成 TTS 旁白和渲染视频。
   • 格式：

   {
     "meta": {
       "title": "<Series title>",
       "ratio": "<ratio used: 9:16 | 1:1 | 3:4>",
       "language": "<zh | en | ja | ...>"
     },
     "cards": [
       { "file": "card-01.html", "title": "...", "narration": "1-3 sentence spoken caption." },
       { "file": "card-02.html", "title": "...", "narration": "..." }
     ]
   }
   

   • 字段含义：
     • meta.title — 用于引导卡片上的文字和默认输出文件名（slug 化：将 [^a-z0-9一-鿿] 替换为 -，并转为小写；保留 CJK 字符）。
     • meta.language — 只有 "zh" 会将引导字幕切换为「知识卡片」；任何其他值（包括 "ja"、"en"、"mixed"）都会回退为「Card Series」。
     • card.title — 当 card.narration 为空时，作为屏幕字幕栏的后备文本。
     • card.narration — 提供给 TTS 的口播字幕，默认也会渲染为字幕栏文本。
   • 旁白规则：
     • 旁白应使用与卡片文案相同的语言。
     • 每张卡片写 1-3 句话。节奏自然，适合口语表达——避免列表和项目符号式表达。
     • 不要复述画面；应补充背景、解读或核心结论。
     • 即使不看图片，每张卡片的旁白也应能让人理解。
   • 还要在每个 HTML 文件的 .card 元素中添加 data-narration="..."，以便查看。
   • 如果用户明确只要求图片（不需要视频），则跳过此步骤。

10. 渲染视频（可选——仅在用户要求输出视频／旁白时执行）。

    • exports/ 中已有 PNG 且已编写 deck.json 后：

    voxflow card render <output-dir>/
    

    • 渲染后的输出目录结构：

      cards/my-topic/
      ├── card-01.html … card-N.html   (源 HTML)
      ├── deck.json                     (旁白 + 元数据)
      ├── exports/card-01.png …         (PNG 导出文件)
      ├── sources.md                    (来源说明)
      └── my-topic.mp4                  (最终视频 — 文件名取自 deck.meta.title 的 slug)
      

    • 音频 / TTS：

      • --voice <id> — TTS 语音。建议使用 voxflow voices 浏览可选语音。
      • --speed <n> — 旁白语速，范围为 0.5-2.0（默认值：1.0）
      • --no-audio — 跳过 TTS，生成无声视频（不消耗配额）

    • 时长：

      • --pause <sec> — 每张卡片的旁白结束后静音的时长，用于阅读（默认值：2.5）。会写入 WAV，因此始终会显示在最终片段中。
      • --hold <sec> — --no-audio 模式下的卡片时长（默认值：5）

    • 结构：

      • --no-intro / --no-outro — 跳过标题 / 品牌卡片
      • --intro-dur <sec> — 片头卡片时长（默认值：2.5）
      • --outro-dur <sec> — 片尾卡片时长（默认值：2）

    • 叠加与混音：

      • --no-subtitle — 禁用底部字幕栏（字幕需要带有 libfreetype 的 FFmpeg；若未检测到，则会自动跳过）
      • --bgm <path> — 背景音乐，以低音量循环播放
      • --bgm-volume <n> — BGM 音量，范围为 0-1（默认值：0.08）

    • 输出：

      • -o <path> / --output <path> — 自定义输出路径（自动创建父目录）

    • CJK 内容（自 CLI 1.17.1 起）：字幕、片头和片尾叠加层会自动检测 meta.title / card.title / card.narration 中的 CJK 文本，并注入支持 CJK 的系统字体文件（macOS 上为 PingFang / Hiragino / Heiti；Linux 上为 Noto CJK / WQY；Windows 上为 msyh / SimSun）。如果你的平台未安装 CJK 字体，请设置 VOXFLOW_CJK_FONT=/path/to/font.ttc，显式指定字体文件。如果自动检测和覆盖设置都未找到字体，命令会记录警告；此时应改用 --no-subtitle --no-intro --no-outro，以避免出现 □ 豆腐块。

    • 默认输出：<dir>/<slugified deck.meta.title>.mp4（与卡片位于同一目录）。如果 meta.title 为空，则回退为 cards.mp4。

    • 除 FFmpeg 外没有其他外部依赖（会自动检测；如果系统中缺少 ffmpeg，则回退到 ffmpeg-static npm 包）。

    • 中间文件（WAV、片段）存储在 <dir>/.card-render-work/ 中——成功后自动清理，失败时保留以便调试。

    • 配额：每张带旁白的卡片约消耗 50 配额（tts-synthesize）；使用 --no-audio 时不消耗配额。5 张卡片的卡组总计约消耗 250 配额。

    • 对于使用 Slice 主题（paper-slide、editorial-mag 等）的文章转卡片视频，优先使用 voxflow:slice。

资源与来源规范

• 将生成的文件保存在指定的输出文件夹中。
• 除非用户指定其他输出路径，否则将卡片使用的所有本地图片、徽标、屏幕截图、纹理、图标或其他资源放入 cards/<slug>/assets/。
• 在输出文件夹内的 sources.md 或 credits.md 中记录研究来源、外部资源来源和重要事实依据。
• 最终导出文件不得依赖外部热链资源。外部 URL 仅可用于研究或临时预览。
• 只复制卡片组实际使用的最少资源；不要批量复制无关的资源文件夹。
• 对于生成或重新设计的卡片图片，请在 sources.md 或 credits.md 中记录提示意图、已知的模型 / 工具，以及该资源是否为合成内容。

渲染辅助脚本

当项目没有现成的等效 Playwright 导出脚本时，请使用 scripts/render-cards.mjs。

node /path/to/card/scripts/render-cards.mjs \
  --input ./cards/my-set \
  --output ./cards/my-set/exports \
  --ratio 9:16

辅助脚本默认使用 --scale 2，以输出更清晰的 PNG。仅当文件大小比边缘清晰度更重要时，才使用 --scale 1。

该脚本会：

• 扫描输入文件夹中的 .html 文件。
• 根据 --ratio 或 --size 设置视口。
• 如果存在 .card，则截取该元素；否则截取整个视口。
• 将 PNG 文件写入输出文件夹。
• 写入 audit.json，其中包含 DOM 溢出和越界信号。

如果目标项目中缺少 Playwright，请使用本地包管理器安装或运行它，然后按需安装 Chromium：

npm install -D playwright
npx playwright install chromium

实现规则

• 确保所有卡片在视觉上属于同一系列：共享设计令牌、基础布局、字体尺寸比例和图像处理方式。
• 在设计阶段（工作流第 4 步）和 QA 阶段（工作流第 7 步）将 references/taste.md 作为必须遵守的最低标准，包括测试和演示。即使走快速流程，也不得跳过这两次加载。
• 优先沿用现有设计背景，而不是另创一套视觉系统。
• 风格不明确或卡片集影响较大时，先探索概念变化，再开始编码。
• 先定义主题令牌：背景、表面层级、边框层级、文本层级、三种强调色、语义色、渐变、圆角、阴影和字体。
• 在组件 CSS 中使用令牌。除非一次性素材或数据可视化确有需要，否则不要在令牌块之外零散使用字面颜色值。
• 不要将 Inter 作为默认卡片字体。按照 references/fonts.md 中的加权随机算法选择具体字体（预设 × 设计语言 × 内容语言 → 按角色选择）。此处不要硬编码字体列表；references/fonts.md 是唯一可信来源。Avenir Next 和其他付费字体或系统字体均不允许使用，因为所有字体都必须能在本地嵌入。
• 不要使用纯黑色。请使用近黑色、炭灰色、类似锌的深色或墨色。
• 不要整套照搬外部主题 CSS。应在本地卡片样式中重现所需的配色和行为，并在相关情况下将灵感来源记录到 sources.md 或 credits.md。
• 除非用户明确要求单色风格，否则避免只使用一种色调的配色方案。
• 在缩小所有内容之前，先通过编辑文案、分组或调整布局来适应文本。
• 不要让每张卡片的信息密度都偏低。对于真正的说明型内容，至少有一张卡片应包含结构化信息：2–4 个要点、标签、观察结果、步骤、提示框或决策标准。
• 不要通过到处缩小文本来增加信息密度。应先增加结构：分组、层级、标签、侧注、清单、说明文字或附着于对象的提示。
• 用具体语言替换 AI 式文案。避免使用“赋能”“无缝”“释放”“下一代”“智能化”“重塑”等类似空话，除非这些词是从源材料中引用的。
• 不要编造虚假数据。请使用有来源的已核实事实、明确标注为合成的演示值，或不使用数字。
• 响应式 CSS 仅用于开发预览；导出画布必须保持固定。
• 除非视觉效果需要自定义绘制，否则卡片内容优先使用语义化 HTML 和 CSS，而不是 canvas。
• 将素材和来源归属信息保留在输出文件夹中。
• 除非文件现有的设计系统明确要求大写字母间距，否则字间距保持为 0；不要使用负字间距。
• 对于技术性强或信息密集的卡片，正文使用无衬线字体，衬线字体或展示字体仅用于标题、引文和数字。根据 references/fonts.md，编辑类／文学类预设（magazine-eink、field-notes、kraft-editorial）的正文可以使用衬线字体或楷体。对于编辑类布局，无论正文字体为何，都要手动控制较长中文标题的换行。
• 对于图像较多的卡片，统一每组中的图像比例或框架高度；使用 cover 时从底部裁切，图表或包含文字的截图则使用 contain。
• 不要跳过视觉验证。最终答复必须说明渲染和导出是否成功。