feature-image

生成一张品牌风格的社交媒体图片，用于宣布某项功能或更新。图片以符合项目品牌风格的 HTML 页面制作，然后使用 Playwright 截图。

阶段 1：确保 Playwright 可用

npx playwright --version 2>/dev/null || (echo "Installing Playwright..." && npx playwright install chromium)

如果安装失败，请告知用户，并建议运行 npm install -D playwright && npx playwright install chromium。

阶段 2：了解变更内容（结合 Git 信息）

分析近期的 Git 历史记录，了解要宣布的功能或更新：

1. 查看近期提交：

   git log --oneline -20
   

2. 查看当前差异（已暂存和未暂存）：

   git diff HEAD --stat
   git diff HEAD -- '*.tsx' '*.jsx' '*.vue' '*.svelte' '*.html' '*.css' '*.scss' '*.rb' '*.erb'
   

3. 查看近期分支名称（通常会描述该功能）：

   git branch --show-current
   

4. 综合判断此处的功能或更新。

5. 使用 AskUserQuestion 向用户展示分析结果：

   • 标题："功能"
   • 问题："根据近期变更，你似乎正在开发 [X]。这次公告应该介绍什么内容？"
   • 选项：
     • "[自动检测到的功能描述]" - 使用检测到的内容
     • "其他内容" - 让用户自行描述
   • 如果提供了 $1 作为参数，则使用该参数，而不提问。

阶段 3：自动生成公告文案

为图片生成文案元素：

• 标题：简短有力地介绍该功能（3-8 个词）
• 标语：一句用于补充说明的描述
• 徽章/标签：可选的类别标签（例如“新功能”“更新”“改进”）

使用 AskUserQuestion 向用户展示这些内容：

• 标题："文案"
• 问题："这是我建议放在图片上的文案。你想调整吗？"
• 选项：
  • "看起来不错" - 按原样使用
  • "编辑标题" - 用户提供自定义标题
  • "全部编辑" - 用户提供所有文案
  • "不叠加文字" - 生成不带文字的图片

阶段 4：选择平台和尺寸

使用 AskUserQuestion：

• 标题："平台"
• 问题："这张图片用于哪个平台？"
• 选项：
  • "Twitter/X (1200x675)" - 标准 Twitter 卡片尺寸
  • "LinkedIn (1200x627)" - LinkedIn 分享图片
  • "Instagram (1080x1080)" - 方形格式
  • "Open Graph (1200x630)" - 通用社交媒体预览

记录所选宽度和高度，以设置 Playwright 视口。

阶段 5：选择视觉风格

使用 AskUserQuestion：

• 标题："风格"
• 问题："这张图片应采用哪种视觉风格？"
• 选项：
  • "风格化模型图（推荐）" - 使用应用的实际组件和 CSS，以简化、精致的方式重新呈现 UI 元素。风格易于辨认，但不追求像素级还原。
  • "截图 + 叠加层" - 对运行中的应用进行实际截图，再添加品牌文字叠加层、渐变和注释。
  • "抽象/插画风格" - 运用品牌色彩和字体，创作能够体现该功能但不直接复刻特定 UI 的几何图形或渐变设计。

风格：风格化模型图

这是工作量最大的风格。目标是呈现一种能让人联想到应用、但并非实际截图的 UI。

1. 查找与该功能相关的 UI 组件：

   • 搜索与该功能匹配的组件文件（例如，如果功能是“深色模式”，则查找主题切换组件）
   • 阅读组件标记，了解 UI 结构
   • 记录关键视觉元素：按钮、卡片、输入框、表格、导航项

2. 从组件中提取视觉模式：

   • 圆角值
   • 阴影样式
   • 特定布局模式（侧边栏 + 主区域、卡片网格等）
   • 图标用法
   • 交互元素样式（按钮、切换开关、输入框）

3. 构建简化的 HTML 模型图，要求：

   • 以风格化、编辑设计的布局展示该功能的关键 UI 元素
   • 使用代码库中的实际品牌色彩、字体和圆角
   • 添加细腻的视觉润色（柔和阴影、轻微渐变、宽松留白）
   • 如适用，将 UI 置于“浏览器窗口”或“设备边框”中
   • 不要制作完整的可用页面，而应创作经过精心编排和艺术指导的视觉构图

样式：截图 + 覆盖层

1. 请用户提供正在运行的应用 URL（建议常见的 localhost URL）
2. 使用 Playwright 导航到相关页面
3. 截取基础截图
4. 创建一个 HTML 覆盖层页面，其中：
   • 将截图嵌入为背景图片
   • 添加渐变覆盖层（使用品牌色），提升文字可读性
   • 在顶部放置标题和标语
   • 视情况添加徽章或标签
5. 截取覆盖层页面

样式：抽象／插画风格

构建一个 HTML 页面，包含：

• 使用品牌色的渐变或几何背景
• 项目 Logo（如果在 /public、/assets 或 /src/assets 中找到）
• 使用项目字体的大号粗体标题
• 配套标语
• 能体现功能类别的抽象形状、线条或图案
• 简洁、现代的美感，并留有充足的留白

第 6 阶段：深入分析品牌

这是最重要的阶段。请在此投入充分时间。生成的图片必须让人感觉出自打造该产品的同一团队，而非仅仅替换了品牌色的通用模板。目标是深入理解品牌的视觉形象，使图片看起来与设计团队制作的作品别无二致。

6.1：先研究现有营销材料

在查看配置文件之前，先研究品牌实际呈现自身的方式。这些是首要参考资料：

1. 落地页和营销页面——搜索：

   • pages/index、app/page、pages/home、components/landing/、components/marketing/、components/hero
   • 文件名中包含 landing、marketing、home、hero、cta 的任何文件
   • 仔细阅读这些文件。留意准确的语气、布局模式、文本与视觉元素的组合方式、渐变方向、装饰元素和背景处理

2. 现有社交媒体／OG 图片——搜索：

   • /public 或 /assets 中的 og-image、social、share、twitter、preview
   • 仓库中已有的任何公告或营销图片
   • 这些是了解品牌认为适合社交媒体的风格的最佳参考

3. 博客或更新日志页面——搜索：

   • 页面／路由文件中的 blog、changelog、updates、announcements
   • 这些能体现品牌如何传达更新——请仿照其语气和风格

4. 电子邮件模板——搜索：

   • email、mailer、newsletter 模板
   • 这些能展现品牌视觉语言的另一面

5. README 和文档——检查是否有能体现品牌个性的徽章、横幅图片或样式化标题

6.2：调色板

提取完整的色彩系统，而不只是主色和辅助色：

1. Tailwind 配置（tailwind.config.js、tailwind.config.ts）：

   • 阅读完整的 theme.extend.colors 块
   • 记录完整的调色板：主色、辅助色、强调色、中性色、成功色、警告色、错误色
   • 留意颜色之间的搭配关系——品牌会如何组合颜色？

2. CSS 自定义属性（在全局 CSS 文件中搜索 :root）：

   • 查找 --primary、--brand、--accent、--background、--foreground、--muted、--card 或类似属性
   • 提取 HSL／RGB／十六进制值
   • 留意是否有分别适用于浅色／深色模式的调色板

3. 设计令牌文件（在文件名中搜索 tokens、theme、design-system）：

   • 提取颜色定义和语义映射

4. 营销组件中的实际用法：

   • 阅读主视觉区、CTA 按钮、功能卡片、定价表
   • 留意哪些颜色用于背景、文字、强调元素和边框
   • 查找渐变定义——准确的色标、方向和使用位置
   • 找出品牌的“标志性”配色组合（例如：深色背景 + 明亮强调色、柔和的粉彩色、大胆的原色）

6.3：字体排版

1. 字体导入（搜索包含字体 URL 的 @import、@font-face 或 Google Fonts 链接）
2. Tailwind fontFamily 配置
3. body/headings 上的 CSS font-family 声明
4. Package.json 中的字体包（例如 @fontsource/*、next/font）
5. 实际标题样式——阅读营销页面的标题，查看：
   • 字重（粗体？黑体？中等？）
   • 字间距（紧凑？正常？宽松？）
   • 文本转换（大写？正常？）
   • 行高
   • 标题相对于正文的字号

为图片使用检测到的字体。如果是 Google Font，请在 HTML 中添加 <link> 标签。如果是本地/自定义字体，请使用相似的系统字体或 Google Font 替代字体。

6.4：Logo 和资源

搜索 Logo 文件：

public/logo*, public/images/logo*, src/assets/logo*, assets/logo*
public/*.svg (check for logo-like SVGs)
public/brand*, src/assets/brand*

如果找到 Logo，请将其嵌入图片中（内联 SVG 或 Base64 编码）。

还要查找：

• 应用中使用的图标库或自定义图标集
• 插画风格（线描？实心填充？双色调？）
• 背景图案或纹理
• 装饰元素（圆点、网格、色块、圆环）

6.5：视觉语言与模式

不要只看基础配置——还要研究品牌的视觉 个性：

• 边框圆角：应用是圆润风格（rounded-xl、rounded-2xl）还是棱角分明（rounded-none、rounded-sm）？使用完全相同的圆角。
• 阴影：柔和/有层次，还是扁平？使用了哪些阴影值？（例如 shadow-lg、shadow-sm 或无阴影）
• 深色模式：深色模式是默认主题还是主要主题？背景色是什么？
• 渐变：是否大量使用渐变？渐变方向、颜色和位置是什么？
• 玻璃/模糊效果：是否使用了 backdrop-blur？是否有半透明卡片？
• 边框：边框用于分隔，还是界面元素没有边框？边框的颜色/透明度是什么？
• 间距节奏：设计是密集紧凑，还是留白充足、疏朗大方？
• 装饰元素：品牌是否使用背景网格、圆点图案、发光效果、噪点纹理、渐变光球？
• 动画风格：虽然图片中不会显示动画，但使用平滑弹簧动画的品牌与完全不使用动画的品牌，给人的感受不同，也能体现品牌个性

6.6：综合品牌概要

开始制作图片前，先简短地在内部总结品牌的视觉形象：

• “这个品牌使用[深色/浅色]背景和[颜色]点缀。字体为[字体]，字重为[字重]，字间距[紧凑/正常]。整体风格[极简/醒目/活泼/商务]。主要视觉元素包括[渐变/玻璃效果/直角等]。营销页面采用[布局模式]，并搭配[装饰元素]。”

每次做设计决策时，都以此概要为指导。每个元素都应通过这样的检验：“放在他们的落地页上，会不会显得格格不入？”

第 7 阶段：构建 HTML 图片页面

唯一临时文件： 为避免多个 Agent 并行运行时发生竞争条件，请为本次运行生成一个基于 slug 的 ID。格式：{project-slug}-{feature-slug}-{short-id}，其中 project slug 来自目录名称或 package.json 名称，feature slug 是对功能的 2–3 个词的 kebab-case 概括，short ID 为 4–6 个随机字母数字字符。例如：baremetrics-dark-mode-a3f2。在下方所有临时文件路径中使用此 slug（显示为 [UNIQUE_ID]）。HTML 文件和截图脚本必须使用相同的 slug。

创建一个独立的 HTML 文件，路径为 /tmp/feature-image-[UNIQUE_ID]-page.html，并满足以下要求：

1. 尺寸必须与选定尺寸完全一致（视口大小，不可滚动）
2. 所有样式均内联（无外部 CSS 依赖）
3. 通过 Google Fonts 链接引入字体（或类似 CDN）
4. 使用检测到的品牌颜色、字体和视觉模式
5. 包含选定的文字叠加层（标题、标语、徽章）
6. 符合选定的视觉风格（模型图、截图叠加文字或抽象风格）

HTML 结构模板

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <link href="https://fonts.googleapis.com/css2?family=[DETECTED_FONT]&display=swap" rel="stylesheet">
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    html, body {
      width: [WIDTH]px;
      height: [HEIGHT]px;
      overflow: hidden;
      font-family: '[DETECTED_FONT]', system-ui, sans-serif;
    }
    body {
      background: [BRAND_GRADIENT_OR_COLOR];
      color: [TEXT_COLOR];
      display: flex;
      /* Layout depends on style choice */
    }
    /* ... style-specific CSS ... */
  </style>
</head>
<body>
  
</body>
</html>

设计质量指南

图片应呈现出专业设计的效果。请遵循以下原则：

• 层次：标题是最大的元素。标语起辅助作用。徽章应较小。
• 对比度：文字在背景上必须清晰易读。
• 对齐：使用清晰的网格。统一采用左对齐或居中对齐。
• 精致度：使用柔和的阴影、平滑的渐变和精细的排版（字间距、行高）。
• 克制：颜色不要超过 2-3 种。字体粗细不要超过 2 种。

空间利用（至关重要）

这些图片会以较小尺寸显示在社交动态、时间线卡片和链接预览中。每个像素都很重要。空白区域就是空间浪费。

强制规则：

1. 填满画布。 内容应占据可用区域的 85-95%。留白要紧凑——宽度为 1200px 的图片，边距最多 40-60px，而不是 100px 以上。
2. 文字要大。 标题至少应为 48-72px（按 1x 比例）。如果标题较短（3-4 个词），字号还应更大——80-100px。文字需要在缩略图尺寸（约 400px 宽）下仍清晰可读。眯眼看图片时，如果读不清标题，说明字号太小。
3. 中心不要留空。 如果布局上方是标题、下方是 UI 模拟图，不要在中间留出大块空白。应紧凑地堆叠元素，或用辅助内容填充空间。
4. UI 模拟图应足够大。 如果要展示风格化的 UI 元素，其面积至少应占图片的 50-60%。不要让一张小卡片漂浮在大片渐变背景中。
5. 适当延伸到画布边缘。 UI 模拟图可以延伸出画布边缘——这样比所有内容都带着边距居中更有动感，也能更好地利用空间。
6. 徽章/标签文字应为 14-18px，不要更小。文字必须清晰可见。
7. 以缩略图尺寸测试。 定稿前，在脑海中将图片缩小到 400px 宽。还能读清标题吗？还能看出 UI 展示的内容吗？如果不能，就把元素做大。

应避免的常见错误：

• 在大块背景中央放置小标题——放大标题，并将其推向角落或边缘
• UI 模拟图只占画布的 30%，周围全是渐变背景——让它成为视觉主体
• 留白过多，导致内容看起来像是漂浮在空间中
• 标语文字只有 14-16px——至少增大到 20-24px
• 所有元素之间都使用相同间距，而不是将相关内容紧凑分组

第 8 阶段：使用 Playwright 截图

创建并运行 Node.js 脚本：

import { chromium } from 'playwright';
import { readFileSync } from 'fs';

async function capture() {
  const browser = await chromium.launch();
  const context = await browser.newContext({
    viewport: { width: [WIDTH], height: [HEIGHT] },
    deviceScaleFactor: 2, // Retina quality
  });
  const page = await context.newPage();

  // Load the HTML file
  const html = readFileSync('/tmp/feature-image-[UNIQUE_ID]-page.html', 'utf-8');
  await page.setContent(html, { waitUntil: 'networkidle' });

  // Wait for fonts to load
  await page.waitForTimeout(1000);

  await page.screenshot({
    path: './feature-image.png',
    type: 'png',
  });

  await browser.close();
  console.log('Saved: ./feature-image.png');
}

capture().catch(console.error);

将脚本保存到 /tmp/feature-image-[UNIQUE_ID]-capture.mjs，运行后再清理：

node /tmp/feature-image-[UNIQUE_ID]-capture.mjs && rm /tmp/feature-image-[UNIQUE_ID]-capture.mjs /tmp/feature-image-[UNIQUE_ID]-page.html

第 9 阶段：验证并展示

1. 检查文件是否存在且大小合理：

   ls -la ./feature-image.png
   sips -g pixelWidth -g pixelHeight ./feature-image.png 2>/dev/null || file ./feature-image.png
   

2. 使用 Read 工具读取图片并向用户展示。

3. 使用 AskUserQuestion 询问是否需要调整：

   • 标题："Result"
   • 问题："Here's your feature image. What do you think?"
   • 选项：
     • "Looks great" - 完成
     • "Adjust colors" - 微调配色方案
     • "Adjust text" - 修改标题/标语
     • "Try different style" - 切换到另一种视觉风格
   • 如果需要调整，则返回相应阶段并重新生成。

4. 输出摘要：

   Generated: ./feature-image.png
   Size: [W]x[H] @ 2x ([actual_W]x[actual_H] pixels)
   Platform: [chosen platform]
   Style: [chosen style]
   

错误处理

• 尝试安装后仍未找到 Playwright：建议手动运行 npm install -D playwright && npx playwright install chromium 安装
• 没有 Git 历史记录：跳过 Git 分析，直接询问用户这项功能是什么
• 未找到品牌颜色：改用简洁、中性的配色方案（深色背景、白色文字、蓝色点缀）
• 未检测到字体：使用 Inter（Google Font）作为安全、现代的默认字体
• 截图失败：检查 HTML 文件是否创建正确，并尝试使用更简单的布局
• 截图时字体未加载：延长等待超时时间，或改用系统字体

获得最佳效果的技巧

1. 在项目目录中运行此技能，以确保品牌检测正常工作
2. 如果应用正在运行开发服务器，“截图 + 覆盖层”风格将呈现最真实的效果
3. 对于抽象风格，即使没有可供参考的 UI 组件，此技能也能很好地发挥作用
4. 生成的图像分辨率为 2 倍（视网膜级）——在所有屏幕上都会显得清晰