qiaomu-cut-skill

qiaomu-cut

你只说一句“我要什么视频”，它把素材、分镜、字幕、转场、动效、渲染和质检组织成一个可复现的视频工程。 Say what video you want; qiaomu-cut turns it into a source-aware, renderer-ready, verifiable video project.

为什么值得用

普通 AI 会给你一段剪辑建议，真正开剪时还要你自己找素材、查版权、装 ffmpeg、写字幕、调转场、验编码。

qiaomu-cut 把这些拆成一个可复用的视频导演系统：它先生成 QiaoCut IR，再按环境路由到 33台词、ClipSeek/Pexels/Pixabay、本地素材、ListenHub/MarsWave 图片/视频/TTS/Voice/音乐、Coli 本地 ASR、agent 图片生成、HTML/Manim/PPT 等可用引擎，最终由 ffmpeg-full 合成。

v0.9 已真实实现的是：一句话科普 Autopilot、影视英语混剪快速通道、付费切片前完整句门、33台词下载有界重连与已有任务恢复、素材流/SHA 审计、批量 HTML/SVG 场景渲染、自动审片帧、轻量场景认知契约、真实旁白时长锁、动态字幕、独立 SFX、向阳乔木 v1.1 MP3 旁白、三档渲染和 final/full 验收。PPT 直出、复杂遮罩、速度渐变、强制逐词对齐和更完整的转场库仍是外部能力，不冒充已全部内置。

v0.13 新增 代码动态图形工作室：参考 54 个 Opus 5.5 代码生成视频案例，把“导演信”写法、先分镜后代码、节拍网格卡点、seek(t) 确定性、子帧动态模糊、音效峰值对齐和 −14 LUFS 母带都做成了可执行的 qcut motion / qcut audio 命令与硬门；并新增 qcut setup，缺什么依赖就自动装什么。

它不是承诺“魔法般永远一键完美”，而是把专业视频制作流程变成 agent 能执行、能验证、能继续扩展的工程。

一行安装

npx skills add joeseesun/qiaomu-cut-skill --skill qiaomu-cut

本地开发或手动安装：

mkdir -p ~/.agents/skills
cp -R qiaomu-cut ~/.agents/skills/qiaomu-cut

验证并自动补齐依赖（ffmpeg-full、中文字幕字体、playwright + Chromium、Manim、ListenHub CLI）：

node ~/.agents/skills/qiaomu-cut/scripts/qcut.js doctor --json
node ~/.agents/skills/qiaomu-cut/scripts/qcut.js setup

setup 是幂等的：已就绪的组件跳过，缺失的用 Homebrew（Linux 用 apt）/npm 安装，playwright 装在 skill 自己的 .deps/。Agent 使用本 skill 时遇到缺依赖会直接运行它并继续任务，不会让你手动补环境。

你可以这样说

不用记命令，你可以直接这样说：

• “搜索几句电影里的脏话台词，混剪成英语学习视频。”
• “用免费素材做一个 60 秒挖掘机英语启蒙视频。”
• “介绍乔布斯，做一个电影感人物短片，有时间线和档案照片。”
• “把这个口播视频剪成小红书风格，强字幕、B-roll、卡点转场。”
• “用 3Blue1Brown 风格解释 Transformer attention。”
• “制作一个科普视频：介绍 LLM 中的 RL。”
• “给我的网站做一个产品发布视频，网页动效融入剪辑。”
• “用 AI 生成三个电影感转场镜头、中文旁白和配乐，再合成 45 秒预告片。”
• “做一个 15 秒的动态图形 showreel，全力以赴。”
• “用代码做一个卡 120 BPM 的 UI 形态变换无缝循环。”
• “把这首歌做成竖屏手绘歌词 MV。”
• “把我的口播改成线稿动画讲解，人像缩成右下角画中画。”

它会做什么

1. 把一句话需求变成 QiaoCut IR：时长、比例、受众、风格、分镜、素材策略、渲染器。
2. 搜索、生成或整理素材：33台词、ClipSeek、Pexels/Pixabay 原站、本地文件、ListenHub 图片/视频/旁白/音乐、Coli ASR、网页/信息源。
3. 设计专业镜头：推拉摇移、匹配剪辑、J/L cut、遮罩、字幕跟随、标题卡、动态图形。
4. 选择渲染引擎：ffmpeg-full、HTML/HyperFrames-style、Motion/CSS/SVG、Manim、PPT/slide、composite。
5. 先用 preview 快速迭代，内容锁定后再用 standard 或 final 渲染。
6. 输出与档位匹配的成片、contact sheet、缓存命中、阶段耗时和质检信息。

前置条件

• Node.js 18+：node --version
• 使用 ListenHub provider 时 Node.js 20+，并运行 scripts/bootstrap_listenhub.sh --check。
• macOS 推荐 Homebrew：brew --version
• ffmpeg-full、字体、浏览器、Manim：node scripts/qcut.js setup --check（缺失时去掉 --check 即自动安装）
• 需要影视台词素材时，本机已安装并登录 33台词 App，并另行安装获得授权的 33tc CLI adapter；用 which 33tc 验证，或设置 QIAOMU_33TC_CLI。
• 需要发布到 GitHub 时，GitHub CLI 已登录：gh auth status
• 需要 AI 图片生成时，当前 agent 环境提供图片生成工具。
• OpenAPI 路由从环境变量 LISTENHUB_API_KEY 或 ListenHub 官方本机 credential store 读取凭据，命令使用 listenhub openapi ...；OAuth/internal 路由需用户明确执行 listenhub auth login，命令使用顶层 listenhub ...。两者不是同一认证命名空间，不要把 key 放进命令、项目或仓库；doctor 会检查两类凭据文件均为普通文件且权限不宽于 0600。

安装 ffmpeg-full：

~/.agents/skills/qiaomu-cut/scripts/bootstrap_macos.sh --install

这个脚本不会强制覆盖系统 ffmpeg。运行时优先使用：

QIAOMU_FFMPEG
/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg
/usr/local/opt/ffmpeg-full/bin/ffmpeg
ffmpeg

安装已审计版本的 ListenHub CLI 与 Coli 本地 ASR：

~/.agents/skills/qiaomu-cut/scripts/bootstrap_listenhub.sh --install
node ~/.agents/skills/qiaomu-cut/scripts/qcut.js listenhub doctor --json

安装脚本锁定 @marswave/listenhub-cli@0.0.15（listenhub --version 协议版本 0.1.0）和 @marswave/coli@0.0.20。--check 遇到缺失、包名无法验证或版本不匹配会失败；--install 会对缺失或错版的包执行精确版本安装。它不运行 npm view，不跟随 latest，也不显示凭据。

CLI 示例

代码动态图形工作流（motion-design）

node scripts/qcut.js motion styles                      # 7 种预设：product-promo / ui-morph-loop / showreel / line-art-explainer / lyric-mv / pixel-art / cinematic-3d
node scripts/qcut.js motion init ./promo --style product-promo --audio assets/song.mp3 --json
#   → motion-brief.json（inputs → direction → structure → build → gotchas → start）
#   → reports/beat-grid.json（BPM、强拍、每小节能量、drop）
#   → scenes/main.html（seek(t) 纯函数起步场景）+ lib/qiaocut-motion.js（闭式弹簧、叠加、拖拽、随机、节拍）
node scripts/qcut.js motion check ./promo --json        # 先分镜后代码：镜头写完、切点在拍上、Banned≥3、确定性 lint
node scripts/qcut.js motion probe ./promo --json        # 切点截图 + 正序/倒序/冷启动字节一致 + 循环接缝 + contact sheet
node scripts/qcut.js motion render ./promo --profile draft --json   # 半分辨率快速迭代
node scripts/qcut.js motion render ./promo --profile final --json   # 3 子帧动态模糊、峰值对齐音效、−14 LUFS

独立使用音乐分析：

node scripts/qcut.js audio beats assets/song.mp3 --output reports/beat-grid.json --json
node scripts/qcut.js audio peak assets/sfx/click.wav --json

方法论见 references/code-motion-direction.md，可复制的导演信模板见 references/motion-prompt-patterns.md，调研来源见 reports/prior-art-research.md。

竖屏概念解释工作流

node scripts/qcut.js explainer init ./llm-rl --topic "LLM 中的 RL" --json
node scripts/qcut.js explainer check ./llm-rl --stage spec --json
node scripts/qcut.js explainer materialize ./llm-rl --json
# TTS 返回后：使用命令返回的项目相对音频路径
node scripts/qcut.js explainer timing ./llm-rl --audio assets/generated/narration.mp3 --apply --json
node scripts/qcut.js explainer materialize ./llm-rl --json
node scripts/qcut.js explainer check ./llm-rl --stage author --json
node scripts/qcut.js explainer preview ./llm-rl --json
# 查看 reports/scene-review.json 的逐场景首尾帧，再完成 reports/autopilot-review.json
node scripts/qcut.js explainer final ./llm-rl --json

Autopilot 创建七段 scene plan、专业基础样式和 author/review/final 门。--duration 表示包含默认 1.5 秒封面的总成片时长，正文预算会自动扣除封面。每个 scene 还声明唯一认知任务、真实组件主焦点和可见变化；mechanism 没有变化会在 spec gate 失败。preview 自动生成每场景首尾两帧和 soft review。HTML/SVG 捕获默认断网，CSS/Web Animations 按帧设置确定时间，PNG buffer 直接通过 image2pipe 进入 ffmpeg，不创建逐帧 PNG 目录。

影视英语混剪快速通道

node scripts/qcut.js english-mix init ./daily-english \
  --phrases "That makes sense|I see what you mean|That works for me|Let me get back to you" \
  --clips-per-phrase 4 --json

# 先填写 source-selection.json 的 subtitleWindow，再创建可能消耗积分的任务
node scripts/qcut.js english-mix audit ./daily-english --strict-boundaries --json

# 下载后检查音视频流、重复素材与字幕证据
node scripts/qcut.js english-mix audit ./daily-english --require-media --strict-boundaries --json

# 先裁掉首尾残句，再生成舒适版派生：前 60ms、后 500ms 静音停留并带 40/160ms 音频淡入淡出
node scripts/qcut.js english-mix pace ./daily-english --crossfade-ms 200 --apply --json

# 预览后生成素材总览和最长英文字幕的手机审查帧
node scripts/qcut.js english-mix review ./daily-english --frames 8 --json

同构标题卡、短语卡和片尾卡使用 qcut scene batch，共用一次 Chrome 会话：

node scripts/qcut.js scene batch ./daily-english scenes-batch.json --json

完整字段、付费任务恢复策略和验收顺序见 references/english-mix-fast-path.md。

检查本机能力：

node scripts/qcut.js doctor --json

通过已登录的本机 33台词 App 搜索台词：

node scripts/qcut.js 33tc search "dig deeper" --limit 8 --json

qcut 33tc 原样透传内置的 search、pick、cut、tasks、download、me 子命令。pick 和 cut 会创建剪辑任务，可能消耗账号积分；先核对影片、时间范围和输出目录，只有明确确认后才加 --yes。skill 不会替你静默确认。远程媒体下载默认启用有界重连；如果创建后返回了 task ID 但下载失败，先运行 qcut 33tc download TASK_ID --no-status 恢复，禁止重复提交付费任务。

检查 ListenHub/MarsWave 能力（只读，不消耗积分）：

node scripts/qcut.js listenhub doctor --json
node scripts/qcut.js listenhub auth status --json # 仅查 OAuth/internal 登录状态
node scripts/qcut.js listenhub openapi video estimate --model doubao-seedance-2-pro --resolution 720p --duration 5 --ratio 16:9 --json

确认估算后创建远端任务：

node scripts/qcut.js listenhub openapi video create \
  --prompt "slow cinematic push-in on an excavator at dawn" \
  --model doubao-seedance-2-pro --resolution 720p --duration 5 --ratio 16:9 \
  --no-wait --json --qcut-project ./excavator-video --yes

上面是 API key 路由，因此必须使用 openapi video。只有完成 OAuth 登录后，才使用顶层 listenhub video ... internal 路由。配置 API key 不会让顶层路由自动获得 OAuth 状态。

远端创建、解析和可能收费的音乐操作都要求 --yes 与 --qcut-project；引用本地图片/视频/音频时还要求 --allow-upload。创建返回的 task ID 会记入一份私有 capture。所有 capture 只能位于项目内 .qiaocut/jobs/listenhub/，以 0600 保存；终端只显示去密钥、去签名 URL 的摘要。

用创建结果中的 task ID 轮询。只读 get 加上 --qcut-project 后也会自动保存一份私有结果 capture：

node scripts/qcut.js listenhub openapi video get TASK_ID_FROM_SUBMIT \
  --json --qcut-project ./excavator-video

状态完成后，从这份 poll capture 把临时 URL 本地化并写入素材清单：

node scripts/qcut.js fetch ./excavator-video \
  --result .qiaocut/jobs/listenhub/<poll-capture>.json \
  --field result.videoUrl --kind video --provider listenhub --json

这就是 submit → poll capture → fetch 闭环。下载器会从 capture 补全 provider、task ID、model、积分和 capture 摘要等 provenance（provider 未返回的字段明确记为未报告），且不把临时 URL 写入 manifest。它只允许 HTTPS，拦截私网/本机地址，限制重定向与体积，检查 Content-Type 和媒体魔数，使用临时文件 + 原子 no-clobber 落盘。已有本地生成物可用：

node scripts/qcut.js ingest ./excavator-video /path/to/generated.mp4 \
  --kind video --provider listenhub --task-id <id> --model <model> --json

讲解旁白默认策略

讲解/口播音频优先使用 ListenHub，默认期望的 speaker/voice 名称是“向阳乔木 v1.1”。默认使用专用闭环命令，不要手工拼 speaker ID：

node scripts/qcut.js listenhub narration \
  --text-file scripts/narration.txt \
  --qcut-project ./excavator-video --voice-name "向阳乔木 v1.1" --yes --json

该命令自动执行只读 speaker list，在本地对“向阳乔木 v1.1”做唯一完全匹配，再调用 TTS、验证音频签名与所选容器、导入 assets-manifest.json，并返回可直接写入时间线的 timelineNarration。默认输出 MP3，避免当前 provider 的 WAV 容器不一致导致失败和二次计费；明确需要时仍可传 --format wav。格式不匹配的已签名音频会保留在项目私有 staging 供检查，不会自动再提交一次付费任务。Manifest 会记录 speaker、文本、任务、模型和积分 provenance。

当前 OpenAPI TTS 没有已验证的 estimate 子命令，因此调用前必须明说“费用/积分未知”并取得本次 --yes；--yes=false 等伪确认会被拒绝。--text-file 必须是项目内普通文件，也可用 --text 传短文本。最终旁白统一以带 manifest 身份校验的 narration.engine=file 进入 timeline。原始 openapi speakers/tts 透传仅用于调试，不是默认工作流。

AI 生图默认策略

生图提示词的风格必须从本片的主题、受众、年代、情绪和媒介推导，不把“电影感”、“粘土”、“像素”或任何单一风格硬编码为全局默认。生成第一张图前先写 visual bible：色板、时代/材质、镜头与构图、光线、对比度、纹理、字体/图形语言、人物和负面约束；后续镜头继承这套一致性。个别提示词与内容语义或 visual bible 不匹配时，拒绝直接生成，先重写提示词或重新规划该镜头。

qcut plan 会产出具体的 visual bible ID、媒介、时代、情绪、色板、光线、构图、负面提示与 prompt prefix。生成结果入库时必须带回同一个 ID、实际 prompt、model 与 provider 返回的 seed（若有）；直接文件用 qcut ingest --visual-bible-id <id> --prompt <prompt> --seed <seed>，URL 结果在 qcut fetch 使用同名参数。

本地转录不消耗 ListenHub 积分：

node scripts/qcut.js listenhub asr assets/interview.wav \
  --model sensevoice --json --qcut-project ./excavator-video

首次使用 ASR 模型可能下载约 60 MB；当前只把它描述为全文转录，不冒充逐词字幕对齐。

搜索 ClipSeek 免费素材候选：

node scripts/qcut.js clipseek "挖掘机" --type video --limit 5 --json

生成剪辑计划：

node scripts/qcut.js plan "做一个 60 秒挖掘机英语启蒙视频" --workflow stock-story --json

创建一个可继续制作的视频工程：

node scripts/qcut.js scaffold ./excavator-video --brief "做一个 60 秒挖掘机英语启蒙视频" --json

填好项目内 timeline.json 后，先执行快速预览：

node scripts/qcut.js render ./excavator-video --profile preview --json

确认内容、字幕、节奏和构图后再生成正式成片：

node scripts/qcut.js render ./excavator-video --profile final --json

render 默认读取 <project-dir>/timeline.json；也可用 --timeline alternate-timeline.json。为兼容 v0.2，省略 --profile 仍等价于 --profile final，不会悄悄降低既有项目的输出质量。时间线里的素材、字幕、旁白和输出路径必须是项目相对路径，渲染器会同时检查词法路径与软链接物理路径。已有输出默认保留；确认目标均为可替换的生成物后，才加 --force。调试时可加 --keep-build 保留本次唯一构建目录。

三档性能工作流

档位	默认渲染策略	默认校验	适合场景
preview	长边不超过 960、最高 24 fps、ultrafast、单遍响度；不生成 contact sheet	basic：流、尺寸、帧率、时长、像素格式、空文件	反复调整素材、字幕、节奏和构图