LOCAL SVG VIDEO PRODUCTION

让 Agent 导演一支可编辑的机器人插画视频

这个生产包把中文讲解稿变成带旁白、动态字幕和手绘 SVG 画面的本地 MP4。它不调用图像模型，画面由可编辑的机器人、纸片、物件和路径组成。

开始前

安装包会将 Skill 安装到当前项目的 .agents/skills/。最终视频在本地的 outputs/<project-slug>/ 目录中生成，不会自动上传或发布。

Node.js 22 或更高版本
Python 3、FFmpeg 与 ffprobe
HyperFrames Agent 支持：npx hyperframes skills
在每个生成的 HyperFrames 项目内安装 gsap@3.14.2，不要全局安装

已有旁白、SRT 与字幕分段的任务不需要 SciTiger API key。只有缺少旁白或字幕时，Agent 才会使用对应服务。

安装

npx skills add Scitiger-AI/illustrated-video-skill

一次安装包含五项协作能力：机器人插画导演、旁白生成、字幕生成、视频编排与 HyperFrames 本地渲染。完整源码、问题反馈和更新记录见 github.com/Scitiger-AI/illustrated-video-skill。

已有旁白 + SRT

直接复用时间轴，进入插画导演和本地渲染。

只有旁白

仅生成带时间戳的字幕，再进入画面制作。

只有文稿

先生成旁白和字幕，再完成插画、渲染与质检。

发起创作

在 Codex 中提供文稿，或同时提供可复用的本地旁白和字幕。一个常用请求如下：

使用 robot-illustrated-video，将以下中文讲解稿制作成带旁白、
动态字幕和机器人插画的本地视频。

文稿：……

可以额外指定竖版、参考音色、语速、平台安全区或本地 BGM。默认交付为中文、1920 × 1080、30 FPS、16:9、无 BGM 的 MP4。

锁定媒体与时间轴复用或生成旁白、SRT 和字幕分段；音频与字幕时间戳始终是唯一时钟。

生成分镜并由 Agent 审阅每个 beat 对应一个认知动作，画面 cue 必须跟随其说明的字幕短语出现。

导演、绘制、渲染写入任务专属 SVG 场景与有限动画，随后通过预检、关键帧检查和 MP4 质检。

Agent 导演板

模板不负责把文稿套进固定画面。模板只提供机器人、手绘图元、安全区、字幕规则和动画边界；每次任务必须先由 Agent 生成 director-board.json，再编写 scene-overrides.js。

每个镜头都要有理由。 导演板为每个 beat 记录叙事世界、构图、焦点物件、可见动作、与前镜的连续性、转场理由和有限动作意图。它让“同一种插画语言”可以长出不同专题画面，而不是只换文字。

{
  "id": "beat-008",
  "world": "PNG 印刷厂",
  "composition": "中央自动售图机",
  "focal_object": "图像模型机器",
  "action": "机器吞入提示词，吐出单张静态图",
  "continuity_from": "beat-007",
  "transition": "成品飞出机器",
  "motion_intent": "machine-stamp"
}

预检会运行 check-scene-variety.mjs。它检查导演板覆盖、未规划的通用回退、相邻重复构图、场景多样性和连续性理由。缺少导演板时，生产构建会被阻止。

交付与质检

正式渲染前，任务会完成下列检查。任何一项失败都应先修复，再生成成片。

检查	目的
`preflight-video-task.mjs`	检查任务布局、媒体时间覆盖、标签长度、局部依赖、输出覆盖风险与导演板审计。
`hyperframes check --snapshots`	检查浏览器运行错误、子场景挂载、布局、对比度、关键帧与字幕安全区。
`qc_video.py`	检查 MP4 视频流、音频流、时长、字幕覆盖和结尾声音。
`check-mobile-illustration-labels.mjs`	生成 390px 联系表，确认机器人、标签与字幕互不遮挡。

渲染完成后，主要交付文件为 renders/final.mp4、renders/qc-report.json 和移动端审阅联系表。

任务文件结构

outputs/<project-slug>/
  script.md
  storyboard.json
  director-board.json
  scene-overrides.js
  audio/
  subtitles/
  video-manifest.json
  caption-layout.json
  hyperframes-project/
  renders/
    final.mp4
    qc-report.json
    director-board-audit.json

将 script.md、storyboard.json、源音频、源 SRT 和 video-manifest.json 视为可追溯的源文件。不要用渲染工程中的暂存媒体替换它们，也不要把 API key、签名 URL、素材或渲染产物提交到 Git。

常见问题

只有文稿，能生成视频吗？

可以。Agent 会按需调用旁白和字幕能力；前提是已配置相应运行环境与 API key。

已有配音和 SRT，会重复生成吗？

不会。已有旁白、SRT 和字幕分段时，Skill 直接复用它们，只制作画面与成片。

为什么需要导演板？

它确保每个镜头由叙事决定：不同的世界、物件、动作和转场，而不是固定模板中的文字替换。

画面会调用图像模型吗？

不会。所有机器人、路径、纸片和专题物件都是本地可编辑 SVG，使用 HyperFrames 本地渲染。