convez.ai
AgenteAutomaçãoAvançado
PomeloR611

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 GitHub
BomPluginScore · de 0 a 100

Agent 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-agent

1 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

Estrelas
70
Forks
11
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v2.0.0
Issues abertas
2
Contribuidores
2

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)。

  1. 定基调:选一套固定质感词(2D 绘本 或 写实,全片不混用,模板见 references/prompt-recipes.md §13)。
  2. 建定版资产:把角色/场景/道具的定版图 libtv upload 上去;涉及已定版元素必须挂对应锚点。受控多参考 image2video 的槽位语义遵循 AGENTS.md 契约。
  3. 画/洗九宫格:黑白素描九宫格(9 格 = 9 个运镜表演节拍,格内零文字)→ 做 clean 喂片版(nebula-ultra image2image 去格号/箭头/彩色)。
  4. 单镜生成(先报方案、得「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)。生成后抽帧拼图自查通过才交付。

  1. 终剪:全部镜头齐后,用本地 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。可自由使用、修改、分享。

Ver o original no GitHub

Bom para

Relacionados