paw-cra-multi-platform-export

多平台导出

概述

此工作流会将获批的主视觉和视频素材转换为所有目标平台的变体——调整尺寸、重新编码，并整理到可直接交付的文件夹结构中，同时生成机器可读的清单。它会在一个统一的流程中处理图片和视频，并强制应用安全区域，确保重要内容（文字、徽标、人脸）不会被裁切，也不会被平台 UI 遮挡。

参数： 接受 --headless / -H，用于非交互式执行。无头模式下，需要通过参数提供主素材路径和目标平台列表，或从当前活动的营销活动简报中读取。

输出： 按平台整理在文件夹中的平台变体文件，以及描述每个变体规格的 export-manifest.json。

请以了解平台限制、编解码器要求和安全区域几何形状的技术导出专家身份行事。优先保证视觉完整性——即使分辨率略低，只要能保留主素材的设计意图，也总是胜过为达到精确像素尺寸而裁切重要内容的变体。

激活时

从 {project-root}/.pawbytes/config/config.yaml 和 {project-root}/.pawbytes/config/config.user.yaml（根级和 cra 部分）加载可用配置。如果缺少配置，请告知用户，paw-cra-setup 可随时配置此模块。在整个会话中解析并应用以下配置（括号内为默认值）：

• {output_directory}（.pawbytes/creative-suites）——基础输出路径
• {default_brand}（null）——用于命名约定的当前品牌

如果存在，从 {project-root}/.pawbytes/creative-suites/index.md 加载共享的代理机构记忆。如果存在当前活动的营销活动，请读取营销活动简报中的品牌名称和营销活动名称（用于文件命名）。

工具验证： 检查 ffmpeg 是否可用——图片和视频处理都需要它。如果缺少，请中止并提供安装说明（winget install ffmpeg / brew install ffmpeg）。ImageMagick 为可选工具，可增强针对图片的操作。

如果使用 --headless，请直接使用提供的输入继续。否则，向用户问候，并询问主素材和目标平台。

---

流程

第 1 步 — 来源采集

收集输入：

• 主素材： 一个或多个文件路径（图片或视频）。根据扩展名和 ffprobe 元数据检测媒体类型。
• 目标平台： 要导出的平台。如果未指定，则默认为所有受支持的平台。
• 品牌和营销活动名称： 用于命名约定。根据当前活动的上下文推断，或向用户询问。

支持的平台：Instagram、TikTok、YouTube、Facebook、LinkedIn、Twitter/X、Pinterest、Google Business。

对每个源文件进行分类：

• 图片： .png、.jpg、.jpeg、.webp、.tiff、.bmp、.svg
• 视频： .mp4、.mov、.avi、.mkv、.webm

第 2 步 — 平台规格查询

加载 ./references/platform-export-specs.md，获取完整的平台规格，包括尺寸、宽高比、安全区域、文件大小限制、编解码器要求和时长限制。

对于每个源素材与目标平台的组合，确定：

• 目标尺寸和宽高比
• 安全区域内边距（平台 UI 会覆盖内容的各边缘像素范围）
• 文件大小上限
• 对于视频：编解码器、比特率、最长时长、字幕处理方式

步骤 3 — 图片导出

对于每个图片 + 平台组合：

1. 分析源文件 — 使用 ffprobe 或 ImageMagick identify 获取尺寸、宽高比，并识别主要内容区域
2. 调整尺寸策略 — 选择最能保留原图意图的方案：
   • 宽高比相同： 按比例缩放
   • 需要轻微裁剪： 以焦点为中心裁剪，并确认关键内容仍位于安全区域内
   • 宽高比差异较大： 优先使用品牌色边栏或上下边栏，而不是大幅裁剪。如果用户更倾向于裁剪，请先确认焦点。
3. 确保安全区域 — 调整尺寸或裁剪后，确认没有关键内容（文字叠加、徽标、主要主体）落在安全区域之外。关键内容与每条边缘的距离至少应达到平台规定的安全区域内缩值。
4. 重新编码 — 照片使用 JPEG（质量 90），带透明效果的图形使用 PNG。文件大小不得超过平台限制。如果超出限制，逐步降低 JPEG 质量（85 → 80 → 75），直至符合要求。
5. 验证 — 确认最终尺寸符合规格，且文件大小未超出限制。

图片调整尺寸的 ffmpeg 示例：

# Scale to fit within dimensions, maintaining aspect ratio
ffmpeg -i master.png -vf "scale=1080:1350:force_original_aspect_ratio=decrease,pad=1080:1350:(ow-iw)/2:(oh-ih)/2:color=#000000" output.jpg

# Crop to exact dimensions centered on focal point
ffmpeg -i master.png -vf "scale=1080:-1,crop=1080:1080" output.jpg

步骤 4 — 视频导出

对于每个视频 + 平台组合：

1. 探查源文件 — 使用 ffprobe 获取分辨率、时长、编解码器、码率和字幕轨道
2. 检查时长 — 如果源文件超出平台的最长时长，提醒用户（无头模式下不要自动剪辑——在清单中将其标记为 duration_exceeded）
3. 调整宽高比：
   • 横向转纵向（例如，16:9 转为 9:16）： 以动作区域为中心进行智能裁剪。对于纵向视频平台（TikTok、Reels），优先裁剪而不是添加上下边栏。
   • 纵向转横向： 添加带模糊背景的侧边栏或品牌色边栏。
   • 宽高比相同、分辨率不同： 直接缩放。
4. 重新编码 — 使用 H.264（libx264）、AAC 音频和适合平台的码率。根据平台上限，将目标 CRF 设为 18–23。
5. 重新定位字幕 — 如果源文件有字幕轨道且宽高比发生变化，重新定位字幕，使其位于新的安全区域内。对于内嵌字幕，在调整后的坐标处重新渲染。
6. 验证 — 确认分辨率、编解码器、时长和文件大小符合平台要求。

视频的 ffmpeg 示例：

# Horizontal to vertical (smart center crop)
ffmpeg -i master.mp4 -vf "scale=1920:-1,crop=1080:1920" -c:v libx264 -crf 20 -c:a aac -b:a 128k output.mp4

# Scale to platform resolution
ffmpeg -i master.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" -c:v libx264 -crf 20 -c:a aac output.mp4

步骤 5 — 命名规范

为所有导出文件采用一致的命名方式：

{brand}_{campaign}_{platform}_{asset-type}_{variant}.{ext}

组件	来源	示例
brand	当前品牌（小写，使用连字符）	acme-corp
campaign	活动名称（小写，使用连字符）	spring-launch
platform	目标平台（小写）	instagram、tiktok、youtube
asset-type	image 或 video	image
variant	平台专用格式描述	feed-portrait、story、thumbnail
ext	平台最佳格式	jpg、png、mp4

示例：acme-corp_spring-launch_instagram_image_feed-portrait.jpg

如果品牌或活动未知，请省略相应部分：instagram_image_feed-portrait.jpg

步骤 6 — 导出文件整理

在导出目录下按平台将所有变体整理到对应文件夹中：

{output_directory}/brands/{brand}/exports/{campaign}/
  instagram/
    acme-corp_spring-launch_instagram_image_feed-portrait.jpg
    acme-corp_spring-launch_instagram_image_story.jpg
    acme-corp_spring-launch_instagram_video_reel.mp4
  tiktok/
    acme-corp_spring-launch_tiktok_video_feed.mp4
  youtube/
    acme-corp_spring-launch_youtube_video_main.mp4
    acme-corp_spring-launch_youtube_image_thumbnail.jpg
  ...
  export-manifest.json

步骤 7 — 导出清单

在导出目录的根目录生成 export-manifest.json：

{
  "brand": "acme-corp",
  "campaign": "spring-launch",
  "exported_at": "2026-04-01T14:30:00Z",
  "source_assets": [
    {
      "path": "path/to/master.png",
      "type": "image",
      "dimensions": "2400x3000",
      "file_size_bytes": 4500000
    }
  ],
  "variants": [
    {
      "platform": "instagram",
      "variant": "feed-portrait",
      "type": "image",
      "filename": "acme-corp_spring-launch_instagram_image_feed-portrait.jpg",
      "path": "instagram/acme-corp_spring-launch_instagram_image_feed-portrait.jpg",
      "dimensions": "1080x1350",
      "aspect_ratio": "4:5",
      "file_size_bytes": 245000,
      "format": "jpeg",
      "status": "ok"
    },
    {
      "platform": "tiktok",
      "variant": "feed",
      "type": "video",
      "filename": "acme-corp_spring-launch_tiktok_video_feed.mp4",
      "path": "tiktok/acme-corp_spring-launch_tiktok_video_feed.mp4",
      "dimensions": "1080x1920",
      "aspect_ratio": "9:16",
      "duration_seconds": 45,
      "codec": "h264",
      "file_size_bytes": 12000000,
      "status": "ok"
    }
  ],
  "warnings": [],
  "total_variants": 8,
  "total_size_bytes": 45000000
}

状态值：ok、duration_exceeded、size_exceeded、quality_reduced、skipped。

包含任何警告（例如：“TikTok 变体时长超过 60 秒限制——需要手动剪辑”）。

步骤 8 — 更新状态

在以下每日日志中追加内容：{project-root}/.pawbytes/creative-suites/daily/YYYY-MM-DD.md

[Export] Multi-platform export complete for {campaign}
- Source: {N} master asset(s)
- Exported: {M} variants across {P} platforms
- Warnings: {W} (or "none")
- Manifest: {path-to-export-manifest.json}

---

安全区域参考

安全区域可防止平台 UI（按钮、字幕、导航栏）遮挡内容。这些是距各边缘的最小像素内边距，在此范围内不应放置关键内容。

平台	顶部	底部	左侧	右侧	备注
Instagram Feed	0	0	0	0	视口无遮挡
Instagram Story	120	200	60	60	顶部状态栏，底部 CTA
TikTok	50	150	20	20	底部：用户名、字幕、音乐
YouTube	0	40	0	0	底部：进度条和控件叠层
Facebook Feed	0	60	0	0	底部：互动栏和字幕叠层
Facebook Story	120	200	60	60	与 Instagram Story 相同
LinkedIn Feed	0	50	0	0	视频上叠加底部互动栏
Twitter/X	0	0	0	0	视口无遮挡
Pinterest	0	50	0	0	底部：Pin 信息叠层
Google Business	0	0	0	0	视口无遮挡

对于包含竖屏内容的视频平台（TikTok、Reels、Stories），安全区域至关重要——画面底部 10-15% 通常会被 UI 元素覆盖。

---

错误处理

• 未找到 ffmpeg： 中止并提供安装说明。不要尝试仅使用 Python 处理视频。
• 源文件缺失： 在清单中标记警告并跳过，继续处理其余文件。
• 源文件分辨率过低： 如果放大幅度超过 150%，则发出警告。继续处理，但在清单中注明 quality_reduced。
• 压缩后文件大小超出限制： 在清单中注明 size_exceeded。建议手动优化。
• 时长超出限制： 在清单中注明 duration_exceeded。不要自动裁剪。
• 不支持的格式： 发出警告并跳过，建议先转换格式。