Communitygithub.com

simple tibir/simplicio-loop-marketing

运行 HyperFrames CLI 开发循环——在 `hyperframes` 技能创作的合成作品磁盘就绪后,执行 init、lint、inspect、preview 和 render 等步骤。在作品被标记为完成之前调用。

simplicio-loop-marketing 是什么?

此技能封装了 HyperFrames CLI(`npx hyperframes`),为营销引擎流水线提供自动化的开发循环。它要求 Node.js >= 22 和 FFmpeg 在 PATH 中(可通过 `npx hyperframes doctor` 验证)。所有命令默认在 DRY_RUN 安全模式下运行——lint 和 inspect 阶段不涉及外部调用,只有 `render` 会输出 MP4 文件。技能明确定义了调用时机:在 `hyperframes-prompt-builder` 生成项目后立即执行;在发布前进行组合验证;在迭代过程中提供本地预览;最终生成可被发布步骤拾取的成品。对于渲染,支持多种选项,如帧率、质量(draft/standard/high)、格式(mp4/webm)和变量覆盖,并通过 `--strict` 和 `--strict-variables` 参数确保严格验证。它还包含严格的不可违反规则:未通过 lint 和 inspect 不得渲染;不得全局静默发现;对于声明了变量的作品必须传递 `--strict-variables`。相关技能包括 `hyperframes`(创作规则)、`hyperframes-prompt-builder`(需求到规格)和 `qa-tech-specs`(渲染后验证)。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

HyperFrames CLI

封装 npx hyperframes 用于营销引擎流水线。需要 Node.js >= 22 和 FFmpeg 在 PATH 中(npx hyperframes doctor 可验证)。所有命令默认在 DRY_RUN 安全模式下运行——lint 和 inspect 阶段不涉及外部调用,只有 render 会输出 MP4 文件。

何时调用

  • 在 hyperframes-prompt-builder 于 outputs/<客户>/<日期>/<作品ID>/ 下生成项目后立即调用。
  • 每当组合需要在发布前进行验证时(lint + inspect)。
  • 在作品迭代过程中进行本地预览时(preview)。
  • 进行最终渲染以生成可被发布步骤拾取的制品时(render)。
  • 当渲染失败时进行环境故障排查(doctor、browser、info)。

输入

  • project_path:字符串。HyperFrames 项目的路径(必须包含 index.html 和 composition.json)。
  • mode:"lint" | "inspect" | "preview" | "render" | "doctor"。
  • render_opts:对象,可选,仅用于 mode = "render"。识别的键:
    • fps:24 | 30 | 60(默认 30)。
    • quality:"draft" | "standard" | "high"(默认 "standard";迭代时使用 "draft")。
    • format:"mp4" | "webm"(默认 "mp4")。
    • variables:对象。键为变量 ID 的 JSON 对象,覆盖 data-composition-variables 的默认值。
    • strict:布尔值。映射为 --strict。流水线中默认为 true——遇到 lint 错误时渲染失败。
    • strict_variables:布尔值。映射为 --strict-variables。作品运行时默认为 true。
    • workers:整数 1-8 或 "auto"。默认 "auto"。
    • output:字符串。outputs/<客户>/<日期>/<作品ID>/ 内部的输出文件路径。

流程

  1. 验证环境:在会话首次运行时执行 npx hyperframes doctor。将缺少 FFmpeg 或 Chrome 视为硬性障碍——不要尝试渲染。
  2. Lint:npx hyperframes lint <项目路径> --json。将所有 error 级别的发现问题视为阻塞项。警告项会呈现给编排器,由操作员决定处理方式。
  3. Inspect:npx hyperframes inspect <项目路径> --json。在渲染前解决所有报告的文本溢出或画布逃逸问题。如果溢出是入场/出场动画有意为之,请给元素添加 data-layout-allow-overflow(如果是装饰性元素,给祖先元素添加 data-layout-ignore)——不要全局静默该规则。
  4. 预览(仅操作员):npx hyperframes preview <项目路径> --port <端口>。返回 Studio 项目 URL(http://localhost:<端口>/#project/<项目名称>),而不是源 index.html 路径。
  5. 渲染:npx hyperframes render <项目路径>,并附上从 render_opts 解析出的标志。使用单行 JSON 字符串构建 --variables 参数。对于作品运行,始终传递 --strict 和 --strict-variables。
  6. 验证输出:渲染后,检查 MP4 文件是否存在且非零。将日志写入 data/video-usage.jsonl,包含 { ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }。

输出

  • lint:{ pass: boolean, errors: [...], warnings: [...] }。
  • inspect:{ pass: boolean, findings: [...] }。
  • render:{ artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }。
  • preview:{ url: string }。

命令速查表

npx hyperframes init <名称>                            # 脚手架(提示构建器为每个作品使用一次)
npx hyperframes lint <路径>                            # 验证标记
npx hyperframes inspect <路径>                         # 布局/溢出审计
npx hyperframes preview <路径> --port 3017             # 本地开发
npx hyperframes render <路径> \
  --fps 30 --quality standard --strict --strict-variables \
  --variables '{"leads":42,"delta_pct":12}' \
  --output outputs/<客户>/<日期>/<作品ID>/final.mp4
npx hyperframes doctor                                 # 环境检查
npx hyperframes info                                   # 版本/环境详情

不可违反的规则

  • 未通过 lint 和 inspect 时绝不渲染。流水线没有针对格式错误的组合的恢复路径。
  • 绝不全局静默 lint 或 inspect 的发现——修复标记,或使用 data-layout-allow-overflow / data-layout-ignore 白名单特定元素。
  • 对于声明了变量的作品,始终传递 --strict-variables。变量 ID 的拼写错误必须大声失败,而不是静默回退到默认值。
  • 对于最终交付渲染,使用 --quality high。对于迭代循环,使用 --quality draft 以节省计算资源。
  • 资产预处理(tts、transcribe、remove-background)不在此技能范围内——请通过未来的 hyperframes-media 技能调用,而不是在此处内联。

失败模式

  • doctor 报告缺少 FFmpeg 或 Chrome:按照项目的设置说明进行安装;不要尝试绕开。
  • render 失败并显示 unknown variable:通过 --variables 传递的键未在 data-composition-variables 中声明。修复标记或移除覆盖值。
  • render 超过时间预算:将 --quality 降低至 standard,或将组合拆分为子组合并通过 --workers 并行化。
  • 输出 MP4 字节数为零:重新运行 doctor;通常是由于 Chrome 在捕获过程中崩溃。

相关技能

  • hyperframes:组合创作规则;生成此技能验证和渲染的项目。
  • hyperframes-prompt-builder:需求到组合规格;在此技能之前运行。
  • qa-tech-specs:在此技能之后运行,针对渲染的 MP4 验证平台规格。

上游参考

完整的上游技能(所有标志、故障排查矩阵、参数化渲染):https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

相关技能