Communitygithub.com

leocosta/八爪鱼 (Motion Promo Protocol)

将运行中的真实应用转化为高质量动态推广视频——通过无头浏览器驱动真实产品(headless Chrome),捕捉纯净截图,并利用 HyperFrames + GSAP 合成带有动态排版、电影级推近、聚光灯高亮、手机边框等效果的运动设计剪辑。支持任意应用,自动读取项目级别的 promo.config 和 beats 列表,并提取目标应用的设计系统以确保覆盖层与品牌匹配。输出 16:9 主版本和 9:16 竖版。

八爪鱼 (Motion Promo Protocol) 是什么?

Motion Promo Protocol 是一项 AI 技能,旨在将真实运行的应用转化为专业级动态推广视频。它通过驱动 headless Chrome 中的实际应用(而非屏幕录制或模拟),捕获干净截图,然后使用 HyperFrames(HTML 转 MP4)和 GSAP 合成包含动态排版、电影推近、聚光灯高亮、手机边框和配乐的运动设计剪辑。该技能与平台无关,支持 Claude Code、Cursor 等主流 AI 代理平台,并需要 Node 20+、系统 Chrome、ffmpeg 以及目标应用的可运行沙箱环境。其核心优势在于确定性、可重复运行的渲染流程,避免了屏幕录制的不稳定性和品牌控制的缺失。技能自动提取目标应用的设计令牌(—bg、—accent 等 CSS 变量),使覆盖层与品牌自动匹配;支持通过可插拔的身份验证配方(authInject 或 authFlow)处理登录,并特别设计了应对演示数据过期、CORS 跨域、高亮跟踪等常见问题的规则,最终产出 16:9 和 9:16 两种规格的视频。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/leocosta/octopus/tree/HEAD/skills/motion-promo

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

动态推广视频协议 (Motion Promo Protocol)

概述

此技能呈现的是真实产品的动态、广告级推广视频——不是屏幕录制,也不是模拟图。它会在无头浏览器中驱动实际应用,针对演示环境运行,捕获每个屏幕的干净截图,然后在其上合成运动设计剪辑:动态排版、电影推近、追踪变焦的聚光灯高亮、移动端屏幕手机边框、富有节奏的场景切换以及背景音乐。输出为 16:9 主版本和 9:16 竖版。

它是 launch-feature 的渲染对应角色:launch-feature 编写 video-script.md(剧本/节拍散文);motion-promo 将节拍列表转化为最终带配乐的成品视频。当两者同时运行时,将它们串联起来——launch-feature 脚本 → motion-promo 节拍。

为什么选择 HyperFrames (HTML→MP4) 而非屏幕录制: 它确定、可重复运行、品牌可控,并且避免了捕获实时导航的失败模式(见规则)。应用仅用于生成截图 + 设计令牌;所有动画都是自主创作的。

何时使用

  • 着陆页/销售页需要产品演示或主导视频。
  • 宣布新功能,希望获得渲染好的视频而不仅仅是脚本。
  • 拥有包含真实数据的演示/沙箱租户。

不要用于:对保真度要求不高的内部操作指南(原始屏幕录制更便宜),或者没有可运行演示环境的应用。

前提条件与密钥

无需 API 密钥/密钥。 HyperFrames render 是无密钥的(本地 HTML→MP4),字体(Google Fonts)和默认音乐(incompetech)均为公开 URL。唯一的凭据是目标应用的演示登录信息,它存在于目标仓库的 promo.config.mjs 中——绝不在本技能中。身份验证是可插拔的配方:authInject() 返回要注入的值(localStorage 中的令牌、cookie、API 密钥、多步骤租户选择),或 authFlow(page) 驱动交互式登录界面(Azure AD / Entra、Okta、Google SSO),引擎会快照会话(localStorage + sessionStorage + cookies,包括 HttpOnly)。SSO 凭据来自环境变量而非文件。无头浏览器无法通过交互式 MFA——请使用免 MFA 的演示账户(条件访问例外)或应用密码。

系统依赖(由您安装——本技能无法安装): Node 20+、系统 Chrome (google-chrome/Chromium)、ffmpeg + ffprobe。需要网络出口以获取字体/音乐。

自动/按需依赖: hyperframes 通过 npx 按需获取(无需预安装)。puppeteer-core 是脚手架化的 npm 依赖项——它使用系统 Chrome,不会下载 Chromium。

设置: 将 templates/ 模板文件架到 video/<slug>/ 目录下(包含 hyperframes.json;meta.json 由 compose-gen 生成),将 gitignore 重命名为 .gitignore,然后运行 npm install 和 npm run preflight(验证 Chrome、ffmpeg/ffprobe 和 puppeteer-core;如果缺失任何一个会输出错误)。逐步运行管道或直接 npm run build。

  • 目标应用的一个可运行演示/沙箱。

输入

所有项目特定的内容都位于目标仓库中,绝不在此技能中:

  1. promo.config.mjs——约定文件(参见 templates/promo.config.example.mjs)。包含应用 URL/服务方式、身份验证配方、演示账户/租户、输出路径和音乐偏好。设计令牌会自动提取(步骤 2),但可在此处覆盖。
  2. beats.json——有序镜头列表(参见 templates/beats.schema.json)。每个节拍包含:一个屏幕(路由或捕获的静态截图)+ 可选的高亮目标 + 标注文案 + 视口(桌面/移动端)。

将这两个文件从 templates/ 模板架放到目标仓库的 video/<slug>/ 目录下。

协议

在目标仓库的 video/<slug>/ 目录下工作。每个步骤都有验证环节。

0. 修复演示数据(首先执行此步骤——它决定视频成败)

演示/沙箱数据通常已过时或归零(当前期间未付费的发票、空的漏斗),这在“自动运行”的文案旁边表现为 “R$0 收入”——完全偏离信息主题。在捕获之前,编写一个幂等的、相对当前日期的种子数据,让每个节拍都显示健康的数字(参见规则 → 演示数据为零)。通过查询每个节拍将显示的指标进行验证。

1. 在允许 CORS 的来源上为应用提供服务,指向演示 API

构建/启动应用,指向演示 API。服务来源必须在 API 的 CORS 白名单中,否则每个数据请求都会被阻止,屏幕渲染为空(参见规则 → CORS 来源)。探测 API 的白名单,并在允许的端口上提供服务。验证:深层路由返回 200,且从该来源发出的已验证 /api/... 请求返回 2xx。

2. 提取目标应用的设计系统

针对已启动、已验证的应用运行 templates/engine/extract-design.mjs。它会采样计算样式(页面背景、按钮/链接的主色/强调色、标题 + 等宽字体族、圆角)→ design.tokens.json。这些内容作为 CSS 变量供给合成,使动态覆盖层、强调色和字体自动匹配应用的品牌。如果采样的令牌有误,请在 promo.config 中审查并覆盖。

3. 按节拍捕获干净截图

运行 templates/engine/capture.mjs。它会进行身份验证(通过配置的 authInject 配方),以每个节拍的视口导航到其路由,等待真实数据加载完成(不仅仅是网络空闲——参见规则),并将截图保存到 assets/<beat>.png。验证每个截图显示已加载的内容(大小 > 约 10 KB,抽查目标元素是否存在)。

4. 定义节拍 + 生成合成

填写 beats.json(路由/截图、高亮 {x,y,w,h,label} 以截图像素坐标表示——或 {selector,label,padding?},由 capture.mjs 自动测量,优先于手动调整的坐标;标注 {kicker,headline,sub};视口;持续时间)。运行 templates/engine/compose-gen.mjs → 从 templates/composition.html 生成 index.html,注入令牌和节拍。保持简洁有力:每个节拍 3–5 秒,硬切,每个节拍一个想法。

5. 获取免费音乐曲目

运行 templates/engine/fetch-music.mjs → assets/music.mp3。默认来源为 CC-BY (incompetech);CC-BY 需要署名(请记录在 LP 描述中)。如果可能,优先使用项目提供/CC0 的曲目。

6. 渲染

npx hyperframes render → 静音 MP4。首先运行 hyperframes lint / inspect;将画布外装饰/退出动画溢出视为噪音,真正的文字裁剪则需要修复。

7. 检查帧 + 修复高亮对齐

提取每次推近的开始和结束时的帧并进行肉眼检查。头号缺陷:聚光灯高亮在变焦过程中偏离目标——因为高亮框必须是缩放容器的子元素(参见规则 → 高亮跟踪)。同时验证:没有空白/加载中画面,移动端屏幕整齐地放置在手机框内,文案清晰可辨。

8. 混入音乐

运行 templates/engine/mux.mjs → 最终带配乐的 MP4(loudnorm、淡入淡出、-shortest)。验证输出包含音频流且与视频时长匹配。

9. 生成 9:16 竖版

mux.mjs --reframe 生成 1080×1920 竖版。不要居中裁剪(否则会切掉底部固定的标注)——应使用模糊信箱格式保留整个画面;移动端节拍已居中放置。

规则(来之不易——请勿重蹈覆辙)

  • 高亮跟踪。 在推近过程中,屏幕上的聚光灯/高亮矩形必须是在截图像素坐标空间中应用 scale 变换的同一元素的子元素。作为兄弟元素,它会在图像缩放时保持固定,从而导致在整个镜头中偏离目标。
  • 演示数据为零。 当前期间通常未付费或为空。使用幂等的种子数据(确定性 ID,先删后插)并相对于 current_date 进行修复,使其每个期间都能自我修复。
  • CORS 来源。 本地服务的应用调用已部署的演示 API 属于跨域行为。请在 API 允许的来源上提供服务(探测它)——绝不要通过禁用浏览器 Web 安全来绕过此问题。
  • 等待真实数据。 networkidle2 可能在应用的数据请求到达之前就解析完成→ 你会捕获到加载画面。在屏幕截图之前,还要额外等待成功的 /api/... 响应(或目标内容选择器)。
  • HyperFrames 优于实时捕获。 CDP screencast 在视觉上静态的页面上会停止发送帧,且运行帧率低于标称值;在 HTML(GSAP)中创作可避免这两个问题。如果必须录制实时内容,请抖动光标并以有效帧率编码。
  • 音乐许可。 CC-BY (incompetech/Kevin MacLeod) 需要在 LP 描述中注明出处;CC0 (Pixabay 等) 则不需要。切勿将未授权的抓取片段发布到公开页面。
  • 如果片段具有不同的帧率,请使用滤镜进行拼接,而不是解复用器——解复用器会静默地丢弃帧。

设计系统提取(无关品牌的品牌化)

合成本身是品牌中性的;extract-design.mjs 从目标应用本身填充其 CSS 变量:--bg(页面背景)、--accent(主色/链接颜色)、--fg(标题颜色)、--font-hero / --font-mono(计算字体族)、--radius。这正是同一个技能能为任何应用生成品牌推广视频的原因——无需手动选择令牌。请始终审查采样的令牌——低对比度或临时颜色有时会采样错误;在 promo.config.design 中覆盖。

错误

  • 应用无法在无头模式下进行身份验证 → 配置的 authInject 配方有误;请在首次导航之前验证令牌是否正确存储在 localStorage/cookies 中。
  • 屏幕渲染为空 → 未处理 CORS 来源(步骤 1)或等待数据规则(规则)遗漏。
  • 渲染时出现画布外错误 → 真正的文字裁剪需要更小的字体/换行;装饰/退出动画溢出是噪声。
  • 高亮未对齐 → 它不是缩放容器的子元素(规则)。

与营销者角色的协作

使用营销者角色负责文案:每个节拍的引文、标题和价值定位应遵循项目语气(launch-feature 的 voice.md / marketer-hooks.md,如果存在)。屏幕上的文案保持为节拍加一个短标题再加一行副标题。

相关技能