LibTV Skill Pro

agent-im 会话技能 Pro 版（在 @haofanwang/libtv-skill 基础上扩展高级工作流脚本）- 通过 liblib.tv 的 AI 能力生成和编辑图片/视频。覆盖场景包括：生成（文生图、文生视频、图生视频、做动画、画一个xxx、来段xxx）、编辑修改（把xxx换成yyy、去掉xxx、加上xxx、改成xxx、调整xxx、局部修改、改镜头）、风格转换（风格迁移、转绘、换风格）、视频续写延长、复刻视频/TVC/宣传片、短剧/短漫剧生成、音乐MV生成、产品广告/展示片制作、分镜/故事板设计、教育视频/短视频制作。当用户提到 liblib、libtv、上传参考图/视频、查看生成进度时也应触发。关键判断：只要用户的请求涉及 AI 图片或视频的创作、生成、编辑、修改，无论措辞如何（如"画只猫"、"做个海报"、"把纸船换成爱心"、"这个视频帮我改一下"、"帮我复刻这段视频"、"用这首歌做个MV"、"一句话生成短剧"），都必须触发此技能。Pro 版相比原版增加了批量任务、实时监控、工作流模板、结果导出、会话历史、项目管理等高级能力。

fork of @haofanwang/libtv-skill (1.0.3)

Audits

Pending

ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPending

Multi-engine malware detections and file reputation.

Install

openclaw skills install libtv-skill-pro

agent-im 会话（生图 / 生视频）

Fork of @haofanwang/libtv-skill

基础层（来自原版）：create_session / query_session / change_project / upload_file / download_results

高级工作流层：manage_project / batch_create / monitor_session / quick_poll / workflow_template / export_results / session_history

LibTV 功能矩阵层（v0.3.0+）：flow（预设流程）/ node（节点能力）/ edit（修饰器）/ model（模型路由），覆盖 LibTV 画布上看到的功能与模型

通过 agent-im 的 OpenAPI 创建会话、发送消息（生图、生视频、编辑视频等）、上传图片/视频文件，并查询会话消息进展。

LibTV 是 LiblibAI 推出的 AI 视频创作平台，同时为人类创作者和 Agent 设计。Agent 通过 Skill 入口理解任务、调用模型并自动编排工作流。

平台核心能力：

生成：文生图、文生视频、图生视频、视频续写
编辑：局部修改、元素替换、镜头调整、风格迁移
复杂创作：一句话生成完整短剧（剧本→分镜→成片）、复刻已有视频风格做 TVC/宣传片、用音乐生成 MV、产品展示片制作
模型：Seedance 2.0、Kling 3.0/O3、Wan 2.6、NanoBanana、Midjourney、Seedream 5.0 等顶级模型

用户的所有创作和编辑需求都通过发送自然语言消息来完成，Agent 会自主编排工作流。复杂任务（短剧、MV）耗时较长，需耐心轮询。

功能

创建会话 / 发消息 - 创建新会话或向已有会话发送一条消息（如「生一个动漫视频」「把纸船换成爱心」）
查询会话进展 - 根据 sessionId 拉取该会话的消息列表，用于轮询生图/生视频结果
切换项目 - 将当前 accessKey 绑定的项目切换到新项目，后续 create_session 将使用新 projectUuid
上传文件 - 上传图片或视频文件到 OSS，返回可访问的 OSS 地址（编辑已有视频/图片时需要先上传）
下载结果 - 将会话中生成的图片/视频批量下载到本地，自动提取 URL 并命名

高级功能

批量创建任务 - 同时发起多个生图/生视频任务，支持并发控制和任务队列
实时监控 - 持续监控会话消息进展，支持多种输出格式和 URL 提取
快速轮询 - 简化版轮询工具，自动等待直到任务完成
工作流模板 - 预设常用工作流（分镜生成、角色设计、短剧制作等）
结果导出 - 导出会话结果为 JSON/Markdown/HTML 格式
会话历史 - 管理常用会话，快速查看历史记录
项目管理 - 多项目管理，快速切换和查看项目列表

LibTV 平台功能直达（v0.3.0+）

按 LibTV 画布上的功能矩阵直接调用，每个脚本内置精准 prompt 模板：

预设流程 (flow.py) - 故事脚本生成 / 角色三视图 / 首帧图生视频 / 音频生视频（首页 4 入口）
节点能力 (node.py) - 文本节点（文生视频提示词 / 图片反推 / 文字生音乐）、图片节点（图生图 / 图片高清）、视频节点（首尾帧 / 图片参考）
修饰器 (edit.py) - 风格 / 标记 / 聚焦 / 运镜 / 角色库（应用在已生成内容上的精细修饰）
模型路由 (model.py) - 列出已知模型（GVLM 3.1 / Lib Nano Pro / Seedance 2.0 VIP / Kling 3.0/O3 / Wan 2.6 / NanoBanana / Midjourney / Seedream 5.0），或显式指定模型 + 参数（比例/分辨率/时长/数量）生成

13-16 是 v0.3.0 新增的"功能矩阵层"，与 1-12 的"基础工具 + 高级工作流层"互补。如果你已经知道想要哪个 LibTV 入口/模型，优先用 13-16；如果只有自然语言意图，走 1-9 的通用路径。

前置要求

export LIBTV_ACCESS_KEY="your-access-key"

可选：OPENAPI_IM_BASE 或 IM_BASE_URL，默认 https://im.liblib.tv。

无需安装额外依赖，仅使用 Python 标准库。

使用方法

1. 创建会话 / 发送消息

# 创建新会话并发送「生一个动漫视频」
python3 {baseDir}/scripts/create_session.py "生一个动漫视频"

# 向已有会话发送消息
python3 {baseDir}/scripts/create_session.py "再生成一张风景图" --session-id SESSION_ID

# 只创建/绑定会话，不发消息
python3 {baseDir}/scripts/create_session.py

2. 查询会话进展

# 查询会话消息列表
python3 {baseDir}/scripts/query_session.py SESSION_ID

# 增量拉取（只返回 seq 大于 N 的消息）
python3 {baseDir}/scripts/query_session.py SESSION_ID --after-seq 5

# 附带项目地址（传入 create_session 返回的 projectUuid，结果中带 projectUrl）
python3 {baseDir}/scripts/query_session.py SESSION_ID --project-id PROJECT_UUID

3. 切换项目

# 切换当前 accessKey 绑定的项目（后续创建会话将使用新项目）
python3 {baseDir}/scripts/change_project.py

4. 上传文件

当用户提供了参考的文件地址时，进行上传，仅支持图片、视频，文件大小必须在200M以下。

# 上传图片
python3 {baseDir}/scripts/upload_file.py /path/to/image.png

# 上传视频
python3 {baseDir}/scripts/upload_file.py /path/to/video.mp4

5. 下载结果

生成完成后，可以将会话中的所有图片/视频批量下载到本地。

# 从会话自动提取并下载所有结果
python3 {baseDir}/scripts/download_results.py SESSION_ID

# 指定输出目录
python3 {baseDir}/scripts/download_results.py SESSION_ID --output-dir ~/Desktop/my_project

# 指定文件名前缀（如 storyboard_01.png, storyboard_02.png ...）
python3 {baseDir}/scripts/download_results.py SESSION_ID --prefix "storyboard"

# 直接下载指定 URL 列表（不需要 session_id）
python3 {baseDir}/scripts/download_results.py --urls URL1 URL2 URL3 --output-dir ./output

6. 批量创建任务

同时发起多个生图/生视频任务，支持并发控制。

# 从文件批量创建（每行一个任务描述）
python3 {baseDir}/scripts/batch_create.py --file tasks.txt

# 直接指定多个任务
python3 {baseDir}/scripts/batch_create.py -m "生成猫的图片" -m "生成狗的图片" -m "生成鸟的图片"

# 限制并发数
python3 {baseDir}/scripts/batch_create.py --file tasks.txt --workers 3 --output results.json

7. 实时监控

持续监控会话消息进展，支持多种输出格式。

# 基本监控
python3 {baseDir}/scripts/monitor_session.py SESSION_ID

# 轮询模式（每 10 秒查询一次）
python3 {baseDir}/scripts/monitor_session.py SESSION_ID --poll --interval 10

# 只显示助手消息并提取 URL
python3 {baseDir}/scripts/monitor_session.py SESSION_ID --poll --role assistant --extract-urls

# JSON 格式输出并保存
python3 {baseDir}/scripts/monitor_session.py SESSION_ID --poll --format json --output log.json

8. 快速轮询

简化版轮询工具，自动等待直到任务完成。

# 基本轮询（默认间隔 8 秒，超时 10 分钟）
python3 {baseDir}/scripts/quick_poll.py SESSION_ID

# 自定义间隔和超时
python3 {baseDir}/scripts/quick_poll.py SESSION_ID --interval 5 --timeout 300

# 安静模式（只输出最终结果）
python3 {baseDir}/scripts/quick_poll.py SESSION_ID --quiet

9. 工作流模板

预设常用工作流，快速创建标准任务。

# 列出所有模板
python3 {baseDir}/scripts/workflow_template.py --list

# 使用分镜模板
python3 {baseDir}/scripts/workflow_template.py storyboard "科幻城市的故事"

# 使用角色设计模板
python3 {baseDir}/scripts/workflow_template.py character_design "勇敢的骑士"

# 使用短剧模板（自动生成完整短剧）
python3 {baseDir}/scripts/workflow_template.py short_drama "友情故事"

# 使用已有会话
python3 {baseDir}/scripts/workflow_template.py video_generation "夕阳下的海滩" --session-id SESSION_ID

可用模板： storyboard, character_design, video_generation, image_generation, style_transfer, short_drama, music_video, product_showcase

10. 结果导出

导出会话结果为多种格式。

# JSON 格式导出（默认）
python3 {baseDir}/scripts/export_results.py SESSION_ID

# Markdown 格式
python3 {baseDir}/scripts/export_results.py SESSION_ID --format markdown --output report.md

# HTML 格式（包含图片/视频预览）
python3 {baseDir}/scripts/export_results.py SESSION_ID --format html --output report.html

# 只导出 URL 列表
python3 {baseDir}/scripts/export_results.py SESSION_ID --urls-only

11. 会话历史

管理常用会话，快速查看历史记录。

# 列出所有会话
python3 {baseDir}/scripts/session_history.py list

# 添加会话记录
python3 {baseDir}/scripts/session_history.py add SESSION_ID --project-id PROJECT_UUID --desc "项目描述"

# 查看会话详情
python3 {baseDir}/scripts/session_history.py show 1

# 获取会话 ID（用于脚本）
python3 {baseDir}/scripts/session_history.py get 1

# 删除会话记录
python3 {baseDir}/scripts/session_history.py remove 1

12. 项目管理

多项目管理：列出/切换/记录项目。本地记录文件位于 ~/.libtv_projects.json，create_session.py 和 change_project.py 也会自动写入。

# 列出本地记录的所有项目（带 * 标记当前项目）
python3 {baseDir}/scripts/manage_project.py list

# 显示当前项目
python3 {baseDir}/scripts/manage_project.py current

# 调用 API 创建新项目并切换
python3 {baseDir}/scripts/manage_project.py switch --desc "短剧 A"

# 切换到指定项目（依赖服务端实现，失败时仅标记为本地当前项目）
python3 {baseDir}/scripts/manage_project.py use PROJECT_UUID

# 给项目添加/更新备注
python3 {baseDir}/scripts/manage_project.py describe PROJECT_UUID "MV 项目"

# 删除本地记录
python3 {baseDir}/scripts/manage_project.py remove PROJECT_UUID

旧的 change_project.py 仍然保留（等价于 manage_project.py switch），并会自动写入本地项目记录。

13. 预设流程（LibTV 首页 4 入口）

flow.py 把 LibTV 画布首页的 4 个预设流程做成一键入口，内置 prompt 模板。

# 故事脚本生成
python3 {baseDir}/scripts/flow.py story_script "机器人来到唐朝"

# 角色三视图（人物 IP 资产）
python3 {baseDir}/scripts/flow.py character_views "穿汉服的赛博朋克少女，银发"

# 首帧图生视频（需先用 upload_file.py 拿到首帧 OSS URL）
python3 {baseDir}/scripts/flow.py keyframe_to_video "角色拔剑出鞘" --ref https://libtv-res.../start.png

# 音频生视频（需先上传音频）
python3 {baseDir}/scripts/flow.py audio_to_video "暗黑风 MV" --ref https://libtv-res.../song.mp3

14. 节点能力

node.py 对应 LibTV 的文本节点 / 图片节点 / 视频节点的细分动作。

# 文本节点
python3 {baseDir}/scripts/node.py text_to_video_prompt "一只猫在屋顶看月亮"
python3 {baseDir}/scripts/node.py image_caption --ref https://example.com/a.png
python3 {baseDir}/scripts/node.py text_to_music "悲伤、钢琴独奏、60秒"

# 图片节点
python3 {baseDir}/scripts/node.py image_to_image "换成赛博朋克风" --ref https://example.com/a.png
python3 {baseDir}/scripts/node.py image_upscale --ref https://example.com/a.png

# 视频节点
python3 {baseDir}/scripts/node.py first_last_frame "角色拔剑过程" --ref start.png --ref2 end.png
python3 {baseDir}/scripts/node.py reference_video "保留主体演绎新场景" --ref ref.png

15. 修饰器（风格 / 运镜 / 角色库等）

edit.py 把 LibTV 节点上的修饰器按钮做成显式调用。建议传 --session-id 在同一会话里叠加。

# 风格迁移
python3 {baseDir}/scripts/edit.py style "宫崎骏吉卜力" --target https://example.com/v.mp4 --session-id SID

# 运镜调整
python3 {baseDir}/scripts/edit.py camera "无人机环绕镜头" --target "待生成的场景" --session-id SID

# 角色库调用
python3 {baseDir}/scripts/edit.py character_lib "孙悟空" --target "在花果山做早操" --session-id SID

# 局部标记 / 聚焦
python3 {baseDir}/scripts/edit.py mark "把画面中纸船的区域换成爱心" --target URL --session-id SID
python3 {baseDir}/scripts/edit.py focus "强调画面右上角的月亮" --target URL --session-id SID

16. 模型路由

model.py 列出已知模型，并支持显式指定模型 + 参数生成。

# 列出所有已知模型
python3 {baseDir}/scripts/model.py list

# 只看视频模型
python3 {baseDir}/scripts/model.py list --kind video

# 指定 Seedance 2.0 VIP 生成 5 秒 720P 16:9 视频
python3 {baseDir}/scripts/model.py with seedance-2.0-vip "黄昏草原一只白马奔跑" \
  --ratio 16:9 --duration 5s --resolution 720P

# 指定 Lib Nano Pro 生成 16:9 2K 图片
python3 {baseDir}/scripts/model.py with lib-nano-pro "赛博朋克少女肖像" \
  --ratio 16:9 --resolution 2K --count "4张"

# 指定 Kling O3 长视频
python3 {baseDir}/scripts/model.py with kling-o3 "古风武侠对决长镜头" --ratio 16:9 --duration 10s

关于模型/参数指令的执行程度：脚本会把 指定模型/比例/分辨率/时长/数量 以自然语言放在 prompt 顶端发给 LibTV IM 后端。服务端 Agent 接收后理论上会按指令路由，但严格执行程度依赖 LibTV 实现。即使后端只把指令当 prompt hint 处理，明确的指令也比模糊描述更有助于路由。

典型工作流

理解这些工作流，才能正确组合上面的脚本完成用户需求。

场景 1：用户要求生成图片/视频（最常见）

1. create_session.py "用户的描述"  →  拿到 sessionId + projectUuid
2. 每隔 8 秒调用 query_session.py SESSION_ID --after-seq 0 轮询
3. 检查 messages：当出现 assistant 角色的消息且包含图片/视频 URL → 任务完成
4. 自动下载：download_results.py SESSION_ID --output-dir ~/Downloads/项目名 --prefix 有意义的前缀
5. 向用户展示：本地文件列表 + projectUrl（画布链接）

生成完成后自动执行下载，不需要用户额外请求。下载目录和前缀根据任务语义自动命名（如分镜用 storyboard，角色设定用 character 等）。

场景 2：用户提供图片/视频要求编辑修改（如"把纸船换成爱心"）

1. upload_file.py /path/to/video.mp4  →  拿到 OSS URL
2. create_session.py "把四周的纸船都换成白色的纸爱心 参考视频：{oss_url}"
3. 后续同场景 1 的步骤 2-5

用户给了文件路径 + 编辑指令 = 先上传文件，再把编辑指令和 OSS URL 一起发送。

场景 3：用户提供参考图/视频要求生成新内容

1. upload_file.py /path/to/ref.png  →  拿到 OSS URL
2. create_session.py "根据参考图生成xxx，参考图：{oss_url}"
3. 后续同场景 1 的步骤 2-5

场景 4：在已有会话中追加新需求

1. create_session.py "新的描述" --session-id SESSION_ID
2. 后续同场景 1 的步骤 2-5

场景 5：批量生成多个图片/视频（使用批量功能）

1. 创建任务列表文件 tasks.txt（每行一个任务描述）
2. batch_create.py --file tasks.txt --workers 5 --output batch_result.json
3. 从结果中获取所有 session_id
4. 对每个 session_id 调用 quick_poll.py SESSION_ID 等待完成
5. 使用 export_results.py SESSION_ID --format html 导出结果

场景 6：制作完整短剧（使用工作流模板）

1. workflow_template.py short_drama "科幻爱情故事"
2. 记录返回的 session_id
3. monitor_session.py SESSION_ID --poll --interval 15 --extract-urls
4. 等待任务完成，导出结果
5. session_history.py add SESSION_ID --desc "科幻短剧项目"

场景 7：多项目管理和切换

1. manage_project.py switch  →  创建新项目
2. workflow_template.py storyboard "新项目分镜"  →  在新项目中创建任务
3. manage_project.py list  →  查看所有项目
4. manage_project.py use PROJECT_UUID  →  切换到指定项目
5. session_history.py list  →  查看该项目下的所有会话

场景 8：按 LibTV 网页功能直接调用（v0.3.0+ 推荐路径）

当用户已经知道想要 LibTV 哪个功能/模型时，跳过模糊的"传话"路径，直接走功能矩阵层：

1. flow.py story_script "科幻爱情故事"  →  对应 LibTV 首页「故事脚本生成」入口
2. flow.py character_views "男女主角设定" --session-id SID  →  对应「角色三视图」
3. node.py first_last_frame "拥抱过程" --ref start.png --ref2 end.png --session-id SID  →  视频节点 首尾帧
4. edit.py style "宫崎骏吉卜力" --target VIDEO_URL --session-id SID  →  应用风格修饰器
5. model.py with kling-o3 "古风长镜头" --ratio 16:9 --duration 10s --session-id SID  →  指定模型生成
6. quick_poll.py SID  →  等待完成
7. download_results.py SID --output-dir ~/Downloads/sci-fi-story

何时用 13-16 vs 1-9

用户已明确想要 LibTV 某个功能/模型 → 走 13-16（精确、可复现）
用户只给了模糊意图，要 Agent 自己路由 → 走 1-9（让 LibTV 后端 Agent 编排）
混合用法：先用 flow.py 起步建会话，再用 edit.py / model.py 在同一会话上叠加（--session-id）

轮询策略

间隔：每 8 秒查询一次
增量拉取：首次用 --after-seq 0，后续用上次拿到的最大 seq 值
完成判断：messages 中出现 assistant 消息且 content 包含结果 URL（图片/视频地址）
超时：连续轮询 3 分钟仍无结果，告知用户"生成时间较长，可稍后通过项目画布链接查看"，不再继续轮询
错误重试：单次查询失败可重试 1 次，连续 3 次失败则停止并告知用户

输出格式

create_session 返回：

{
  "projectUuid": "aa3ba04c5044477cb7a00a9e5bf3b4d0",
  "sessionId": "90f05e0c-...",
  "projectUrl": "https://www.liblib.tv/canvas?projectId=aa3ba04c5044477cb7a00a9e5bf3b4d0"
}

query_session 返回：

{
  "messages": [
    {"id": "msg-xxx", "role": "user", "content": "生一个动漫视频"},
    {"id": "msg-yyy", "role": "assistant", "content": "..."}
  ],
  "projectUrl": "https://www.liblib.tv/canvas?projectId=..."
}

（projectUrl 仅在传入 --project-id 时存在）

change_project 返回：

{
  "projectUuid": "新项目UUID",
  "projectUrl": "https://www.liblib.tv/canvas?projectId=新项目UUID"
}

upload_file 返回：

{
  "url": "https://libtv-res.liblib.art/claw/{projectUuid}/{uuid}.png"
}

download_results 返回：

{
  "output_dir": "/Users/xxx/Downloads/libtv_results",
  "downloaded": ["/Users/xxx/Downloads/libtv_results/01.png", "..."],
  "total": 9
}

最终向用户展示时（OpenClaw）

视频地址：来自 query_session 返回的 messages 中 assistant 消息的 content 或结果里的视频/图片 URL，即「返回的结果」。
项目地址：使用 create_session 返回的 projectUrl，或自行拼接 https://www.liblib.tv/canvas?projectId= + projectUuid。查询进展时若传入 --project-id PROJECT_UUID，query_session 会直接返回 projectUrl，便于一并展示。

在任务完成时，同时给出：视频/图片结果链接 + 项目画布链接（projectUrl）。过程中，不要给出 项目画布链接（projectUrl）。

核心原则：用户侧不做创作，只做传话

你（用户侧 Agent）的职责是搬运工，不是创作者。后端有专门的 Agent 负责理解需求、拆解分镜、编排工作流、选模型、写 prompt。你要做的只有三件事：

上传：用户给了本地文件 → upload_file.py 拿到 OSS URL
传话：把用户的原始描述 + OSS URL 原封不动发给 create_session.py
取件：轮询结果 → 下载到本地 → 展示给用户

绝对不要做的事：

不要替用户扩写、润色、翻译 prompt（用户说"帮我推演分镜"，就直接传"帮我推演分镜"，不要自己先写个分镜表再逐条发）
不要自行拆解任务步骤（如把"生成9张分镜图"拆成9次独立请求）
不要自行编排镜头描述、剧情推演、风格分析
不要在消息中添加自己编的 prompt（如"超写实风格，电影级光影，8K分辨率"之类的描述词）

后端 Agent 对模型能力、参数配置、prompt 工程远比用户侧更专业。用户侧越俎代庖只会降低生成质量，换个弱模型更是灾难。

正确示例：

用户说：「帮我推演后续的故事，来个分镜大爆炸，帮我出一个16:9的九宫格的图。新建一个任务。」
用户给了参考图：/path/to/ref.png

→ upload_file.py /path/to/ref.png  →  拿到 oss_url
→ create_session.py "帮我推演后续的故事，来个分镜大爆炸，帮我出一个16:9的九宫格的图。参考图：{oss_url}"
→ 轮询 → 下载 → 展示

错误示例：

❌ 用户侧自己先写了个九宫格分镜表（对峙、交锋、危机...）
❌ 然后把自己编的描述发给后端
❌ 或者拆成9次 create_session 分别发送

注意事项

鉴权方式为请求头 Authorization: Bearer <LIBTV_ACCESS_KEY>
创建会话时若不传 message，仅创建/绑定会话，不会调用 SendMessage
查询会话时可用 --after-seq 做增量拉取，便于轮询新消息（含 assistant 回复与生图/生视频结果）
项目画布地址固定为：https://www.liblib.tv/canvas?projectId= + projectUuid
切换项目后，Redis 缓存会更新，下次 create_session 将使用新的 projectUuid
上传文件仅支持图片（image/）和视频（video/）类型，其他类型会被拒绝，文件大小须在 200MB 以下
上传返回的 OSS 地址格式为 https://libtv-res.liblib.art/claw/{projectUuid}/{uuid}{ext}
生成过程中只告知用户"正在生成中"，不要提前给出 projectUrl；任务完成后再同时给出：结果链接（图片/视频 URL） + 项目画布链接（projectUrl）