LibTV Vídeo Agent: Produção de Curtas com IA
PomeloR611/libtv-video-agent
Converta storyboards em vídeos prontos com pipeline automatizado end-to-end.
Ver no GitHubAgent especializado em converter storyboards em vídeos curtos usando LibTV CLI (Seedance 2.0), com fluxo completo: 9 quadros → limpeza → image2video → ffmpeg final. Inclui biblioteca de prompts "ferro" testados em produção real (30 planos, 32 segmentos, ~5 minutos) e troubleshooting detalhado. Funciona em Claude Code, Codex e CodeBuddy.
Instalação
npx convez-ai PomeloR611/libtv-video-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Produção de vídeos curtos 2D e realistas a partir de scripts
- Automação de pipelines de edição de vídeo com ffmpeg
- Implementação de workflows cross-tool com prompts parametrizados
Veredito

Agent robusto para criação de vídeos procedurais, bem documentado com referências e troubleshooting profundo. Exige investimento em aprendizado da LibTV CLI e conhecimento técnico sólido, mas entrega workflow repetível e escalável.
README
A tradução para o português deste README ainda está na fila.
LibTV 视频制作 Agent
一套跨项目、跨工具通用的「用 LibTV CLI 把分镜做成短片」的 Agent 知识包。 给一句话需求或一份脚本,按这套方法论能从 0 做成一支成片(2D 绘本 / 写实皆可)。 它由一支真实短片实战(30 镜、32 段、约 5 分钟)沉淀而成——文中标「案例」的内容均仅作举例,方法论本身不绑定任何项目。
案例视频
下面是使用本 Agent 工作流生成的 15 秒案例片段(含声音):
https://github.com/user-attachments/assets/1adc12ca-1d2a-4205-ad58-588db807e83a
工作语言:简体中文。当前审计的 schema 查询键为 star-video2,创建视频节点的模型名为 StarVideo 2.0(仓库首版曾沿用 Seedance 2.0 称呼)。当前实测范围、可变 schema 与参考图槽位结论见能力快照(2026-08-05);多参考顺序以 AGENTS.md 的唯一槽位契约为准。
核心管线(贯穿整个知识包):
定调(锁质感词) → 建定版资产(角色/场景/道具) → 黑白九宫格故事板
→ clean 喂片版(去格号/箭头/彩色) → StarVideo 2.0 单镜 image2video(720p 试错)
→ 抽帧自查 → 每批拼带转场预览 → ffmpeg 统一终剪 → 1080p 定稿
目录结构
.
├── README.md ← 本文件:总览 + 多工具接入 + 快速上手
├── AGENTS.md ← 【通用入口】完整系统提示词/操作手册(Codex/CodeBuddy/Cursor 等跨工具标准入口)
├── SKILL.md ← 【Claude Code 入口】带 frontmatter 的 skill,自动发现/触发
└── references/ ← 六篇专题深档(所有工具共用,按需翻)
├── cli-reference.md CLI 命令矩阵 / 三层结构 / -s vs -u / modeType / 模型 schema / 能力边界
├── production-workflow.md 端到端五阶段方法论 / 后台轮询完整模板 / 抽帧自查 / 批次节奏
├── prompt-recipes.md 19 条可复制「铁律」prompt 模板(角色/比例/零文字/场景锁定/正面穷举/装备/服装渗透/in-scene…)
├── editing-pipeline.md ffmpeg 本地终剪完整可跑模板(xfade 转场链 / acrossfade / 封面 / 字幕卡 / 缩略图嵌入 / 续拍拼接)
├── content-safety-and-env.md 内容审核 5s 探针二分排查 / 真人合规墙 / Windows·PowerShell·中文环境怪癖
└── pitfalls.md 全量踩坑速查表(七类归档,现象→根因→解法)
各司其职:AGENTS.md 是给所有 AI 编程工具读的完整人格与纪律;SKILL.md 是 Claude Code 的 skill 包装(最短上手 + 自动触发);references/ 是细节全文,遇到对应场景再翻。
一、前置:配置 LibTV(任何工具都要做一次)
🔒 本仓库不含任何密钥、凭据或个人路径。 你必须用自己的账号完成下面三步;登录凭据只存在你本机
~/.libtv/credentials.json,永远不进仓库。
1. 安装 CLI
# Windows PowerShell
Invoke-WebRequest -Uri "https://liblibai-web-static.liblib.cloud/cli/latest/install-libtv-cli.ps1" -UseBasicParsing | Invoke-Expression
# macOS / Linux
curl -fL "https://liblibai-web-static.liblib.cloud/cli/latest/install-libtv-cli.sh" | sh
装完可执行文件在用户主目录下的 .libtv/:
| 平台 | 二进制路径(用环境变量引用,勿硬编码) |
|---|---|
| Windows | $env:USERPROFILE\.libtv\libtv.exe |
| macOS / Linux | ~/.libtv/libtv |
本知识包里所有脚本都用
$env:USERPROFILE/~这类家目录相对路径引用 CLI,不含任何人的真实绝对路径——直接复制即可跨机器用。
2. 登录(浏览器同源,必须)
libtv login web # 默认浏览器打开 → 登录完自动回调,凭据落 ~/.libtv/credentials.json
libtv account info # 成功退出才是登录证明;project list 仅用于可见性/列举
⚠️ 旧的 sk-libtv-* OpenAPI / access key 已废弃,且旧 API 建的项目不会出现在 web dashboard——只用 CLI。
3. 在你的项目目录里绑定一个画布项目
cd /path/to/your/project # 你自己的工作目录
libtv project create "你的项目名" # 记录 CLI 返回的项目 ID(格式不作 UUID 假设)
libtv project use <YOUR_PROJECT_ID> # 写 .libtv/project.json,绑定当前目录
绑定前从 project list 只选择唯一且项目名完全匹配的项目;零个或多个匹配都停止并人工确认。绑定后,在该目录下跑 libtv node / libtv upload 都不用再带 -p。
二、接入各 AI 编程工具
共同原理:
AGENTS.md是跨工具通用入口,references/是共用深档。 大多数工具只要把本仓库 clone 进工作区、或把它们的「规则/自定义指令」指向AGENTS.md,即可让 Agent 带着这套方法论上场。先 clone 本仓库到任意本地路径(下文<REPO_DIR>即指它):
git clone <本仓库地址> libtv-video-agent
# <REPO_DIR> = 你 clone 下来的绝对路径
Claude Code
通过 skill 机制接入——把本仓库复制或软链到技能目录,Claude Code 靠 SKILL.md 的 frontmatter 自动发现并按关键词触发:
# Windows(软链推荐:仓库更新即同步)
New-Item -ItemType SymbolicLink `
-Path "$env:USERPROFILE\.claude\skills\libtv-video-production" `
-Target "<REPO_DIR>"
# macOS / Linux
ln -s "<REPO_DIR>" ~/.claude/skills/libtv-video-production
须保持 SKILL.md 在技能根、AGENTS.md 与 references/ 为同级——否则文档里的相对路径索引会失效。安装后,提到 liblib.tv / libtv / Seedance / 把参考图或脚本做成视频短片 时自动触发。
Codex(OpenAI Codex CLI)
Codex 遵循 AGENTS.md 约定:
- 按项目:把本仓库 clone 进你的工作区(或直接在
<REPO_DIR>里开 Codex),Codex 会自动读取仓库根的AGENTS.md。 - 全局生效:把
AGENTS.md的内容并入你的全局~/.codex/AGENTS.md(Codex 会合并全局 + 项目级 AGENTS.md);references/保留在<REPO_DIR>,AGENTS.md 里对它们的相对引用,Codex 需要时按路径去读。
CodeBuddy(腾讯 CodeBuddy)
CodeBuddy 支持项目规则 / 自定义指令,并兼容 AGENTS.md 约定:
- 把本仓库 clone 进工作区,让 CodeBuddy 读取仓库根
AGENTS.md;或 - 在 CodeBuddy 的「规则 / 自定义指令」里,加一条指向
<REPO_DIR>/AGENTS.md与<REPO_DIR>/references/(让它需要细节时去查),或直接把AGENTS.md内容粘贴为一条常驻规则。
其他工具(Cursor / Cline / Windsurf / Zed / Aider 等)
这些工具大多直接读取工作区根目录的 AGENTS.md(跨工具事实标准):
- 最简单:把本仓库 clone 进工作区,根
AGENTS.md自动生效; - 或把
AGENTS.md复制/软链成该工具的规则文件(如 Cursor 的.cursor/rules、Cline 的.clinerules),并保留references/同级目录供查阅。
三、5 分钟跑通一条镜头
前提:已完成「一、前置配置」;本机有 Python(终剪用 ffmpeg,推荐
pip install imageio-ffmpeg)。
- 定基调:选一套固定质感词(2D 绘本 或 写实,全片不混用,模板见
references/prompt-recipes.md §13)。 - 建定版资产:把角色/场景/道具的定版图
libtv upload上去;涉及已定版元素必须挂对应锚点。受控多参考image2video的槽位语义遵循 AGENTS.md 契约。 - 画/洗九宫格:黑白素描九宫格(9 格 = 9 个运镜表演节拍,格内零文字)→ 做
clean喂片版(nebula-ultraimage2image 去格号/箭头/彩色)。 - 单镜生成(先报方案、得「OK」再
--run):
$libtv = "$env:USERPROFILE\.libtv\libtv.exe"
& $libtv model star-video2 # 先查当前 schema;查询键不等于创建参数的模型名
& $libtv node create "shot07_video" -t video `
--prompt "{{Image 1}} 是 clean 九宫格,唯一拍摄脚本;{{Image 2}} 是角色定版,唯一外观依据;{{Image 3}} 是场景定版,只确定布局。<本镜画面> + <质感词> + <按需铁律>" `
--left "sb_07_clean" --left "char_fixed" --left "scene_classroom" `
-s model="StarVideo 2.0" -s modeType=image2video `
-s ratio=16:9 -s resolution=720p -s duration=8 -s enableSound=off --run
720p 与 8 秒是生产试错选择,不是 schema 默认或唯一值;当前 schema 的允许值以刚查询的输出为准。两次审计 --run 前台调用超时而后端继续,因此超时后必须先查询同名既有节点,再决定是否重试;只消费经验证的 MP4 结果(详见 references/production-workflow.md)。生成后抽帧拼图自查通过才交付。
- 终剪:全部镜头齐后,用本地 ffmpeg 缝合(
xfade转场链 +acrossfade音频 + BGM/字幕卡/封面/缩略图),完整可跑模板见references/editing-pipeline.md。
纪律红线:生成视频前必报方案、得用户「可以/OK」才
--run(图片可直接做);每批 3–5 镜逐镜确认 + 整批拼带转场预览;每条视频抽帧自查后才交付。
四、能力边界(一句话)
LibTV CLI 只负责「单镜出片」(图片/视频/音频/脚本节点生成);不能创建 custom/group 节点、不能改节点 type、不能离线拿 token、含真人形象的参考图会被合规墙硬拦——真正的转场/配乐/字幕剪辑一律下沉到本地 ffmpeg。 详见 references/cli-reference.md 与 references/content-safety-and-env.md。
五、脱敏与隐私说明
- 本仓库不含任何 API key、登录 token、账号信息或个人绝对路径;所有命令用环境变量 / 家目录相对路径。
- 你的 LibTV 凭据由
libtv login web生成,只存你本机~/.libtv/credentials.json,不要提交进任何仓库。 - 项目 ID 等均用
<YOUR_PROJECT_ID>占位,请换成你自己project create拿到的;不要假定它符合 UUID 格式。 - 文中「案例」仅为说明方法论来源,不含可识别的个人/隐私信息。
版本
- 2026-06 · 首版:从一支 30 镜短片实战沉淀,覆盖 CLI 操作 / 端到端方法论 / prompt 铁律库 / ffmpeg 终剪 / 审核合规 / 环境怪癖。已弃旧 OpenAPI,全程基于 LibTV CLI。
- 2026-08 · v2:依据 CLI 1.0.2 的实测审计同步认证、模型标识符、schema 与受控多参考槽位契约;详情见能力快照。
License
MIT,见 LICENSE。可自由使用、修改、分享。