全自动剪映工作流-柳十一

> 出品：十一AGI认知圈（品牌：十一AGI）· 开源协议 MIT · 版本 v1.0.17 · 引导式小白向导

从一段口播文案到一条剪映可编辑草稿，全程分步引导、边做边讲：

> 关于「视频链接文案」：本 skill 1.0.14 起提供可选的深度抓取模式——直接丢抖音链接，由本 skill 下载视频 + 本地 ASR 自动转写出口播文案（无需登录态）。注意 ASR 是草稿级，同音字/专有名词会有误差（如「头条」→「投条」），拿到文案后需人工读一遍校对。轻量默认路径仍是你自备文案文本。详见下方「工作流1 · 节点 1.1」。

口播文案 ──┬─ (自备文本) ───────┐
          └─ (深度模式: 抖音链接→下载→ASR转写) ─┤
                                             ▼
                              工作流1 改写二创 ──> 改写版文案 ──桥接脚本──> script_data.py
                                                                                              │
                                                                  script_data.py + 素材图/
                                                                                              │
                                                                                      工作流2
                                                                                              │
                                                                                              ▼
                                                                          剪映草稿（默认）/ 竖屏 MP4（可选）

核心设计：时间轴由 TTS 真实时长驱动，配音/字幕/画面三轨严格对齐。

安装后第一次使用（三步，只做一次）

第 1 步：装依赖

pip install pyJianYingDraft edge-tts numpy

> 深度抓取模式（可选，丢抖音链接才需要）额外依赖：
> bash > pip install faster-whisper playwright requests # 本地 ASR + 下载视频（首次自动下模型 base~145MB/small~460MB） > playwright install chromium # 下载器需要的浏览器内核 > # 国内下载慢/失败可加镜像：HF_ENDPOINT=https://hf-mirror.com（link_to_script 已默认设）和 PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright >
> 不装这些也能用——退回到「自备文案文本」的轻量路径即可，两条路最终产出一致。
> 装完后跑 check_env.py，第 6 项会单独检查深度模式依赖（缺失仅 WARN，不阻断轻量路径）。
> ⚠️ 平台限制：剪映草稿仅 Windows / macOS 剪映专业版可用；Linux 无剪映，深度模式只能产出 script_data.py 脚本，无法生成 App 内草稿。下载器 download_douyin.py 已内联打包在本 skill 内，无需另装任何下载 skill。

再装 ffmpeg 并确保在 PATH 里：

第 2 步：跑环境自检（强烈建议）

# Windows PowerShell
python "$env:USERPROFILE\.workbuddy\skills\shiyi-agi-draft-kit\scripts\check_env.py"

# macOS / Linux
python "$HOME/.workbuddy/skills/shiyi-agi-draft-kit/scripts/check_env.py"

自检会逐项检查 Python 版本 / 三个依赖包 / ffmpeg / 剪映草稿目录 / 网络连通性，
每个不通过项都会给出可直接复制执行的修复命令。全绿才往下走。

> 另需：本机装过剪映专业版并至少完整打开过一次（否则草稿生成了但 App 里看不到）。

第 3 步：直接对 AI 说话，别自己敲命令

装完之后，普通用户不需要记任何命令。你只要把口播文案（或参考视频链接，
链接抓取需自备或外部工具）交给 AI 助手，它会按本文档的引导式流程带你走完，命令由它执行。

你全程只需亲自做 3 件事：

① 给口播文案（或参考链接）  →  ② 准备竖屏素材图  →  ③ 打开剪映草稿箱验收

其余（改写、切句、配音、字幕、转场、BGM、组装草稿）全自动。

脚本路径写法（给 AI 助手 / 命令行用户）

本 skill 的脚本安装在用户级 skill 目录，不要复制到工程目录。
下文命令统一写作 python "$SKILL/scripts/xxx.py"，其中 $SKILL 按你的 shell 先定义：

# Windows PowerShell
$SKILL = "$env:USERPROFILE\.workbuddy\skills\shiyi-agi-draft-kit"

# Windows cmd
set SKILL=%USERPROFILE%\.workbuddy\skills\shiyi-agi-draft-kit

# macOS / Linux
SKILL="$HOME/.workbuddy/skills/shiyi-agi-draft-kit"

⚠️ Windows Git Bash 专用坑（实测踩过）

Git Bash 下 $HOME 展开成 MSYS 风格路径 /c/Users/xxx，Windows 原生 Python 不认，
会把它当成 C:\c\Users\xxx 从而报 No such file or directory。必须转成原生路径：

# 方案 A：cygpath 转换（推荐）
SKILL="$(cygpath -w "$HOME")\\.workbuddy\\skills\\shiyi-agi-draft-kit"

# 方案 B：让 Python 自己解析（任何 shell 都成立）
SKILL=$(python -c "import os;print(os.path.expanduser(os.path.join('~','.workbuddy','skills','shiyi-agi-draft-kit')))")

> 补充说明：
> - $SKILL 是占位变量，执行时展开成当前用户的真实路径 —— 文档里不写死任何具体用户名。
> - 若 skill 装在项目级（<工程>/.workbuddy/skills/），把 $SKILL 指向那里即可。
> - pipeline.py 内部用 sys.executable + __file__ 自动定位同级脚本，代码本身跨平台，无需修改。

⚠️ 引导式使用原则（执行本 skill 必须遵循）

本 skill 是向导，不是黑盒。无论用户多急，都按下面几条走，别一口气把活干完甩个结果：

0. 调用即引导：用户一调用本 skill，先用白话把下方「用户引导清单」或 docs/用户引导图.svg 过一遍，让用户立刻知道整个过程里「他需要做什么、哪些自动」，再开始动手。
   0.5 首次运行先自检：若本机首次使用（或流水线报过依赖类错误），先跑 python "$SKILL/scripts/check_env.py"，把自检结果讲给用户听。有阻断项就先带用户修，不要带着坏环境往下跑。
1. 先讲后做：每进入一个阶段，先用 1-2 句白话讲清「这一步要产出什么、它是什么、为什么需要」，再动手。用户"不知道什么是什么"是本 skill 首要解决的问题。
2. 关键选择用提问确认：下列节点必须用 AskUserQuestion 让用户选，不要替用户默认硬定：
   - 工作流1 拿到文案后：用哪一版文案做素材？要不要做品牌改写？
   - 桥接脚本：每镜几句（--shots-per-line 1/2/3）？
   - 工作流2 生成前：配音音色（男声/女声/青年男声）？要不要 BGM·音效·运镜？
   - 是否要出 MP4？（默认否，只到剪映草稿箱）
3. 节点间留停顿：每个节点做完，告诉用户「你刚得到了什么、它在哪、下一步是什么」，再进下一节点。
4. 默认只到剪映草稿：--all 跑到草稿箱即停，不主动渲染 MP4。除非用户明确说"我要 MP4/成片"，否则不要跑 render/tou。

> 名词不懂？见下方「名词小课堂」，或同包 docs/名词手册.md 取完整版。

用户引导清单（一调用先看）

用户调用本 skill 后，需要你亲自做的事只有这几件，其余交给 AI / 脚本自动跑：

1. 给口播文案：直接粘贴参考视频的口播文案文本（最稳），或发一条抖音链接让 AI 用「深度抓取模式」自动下载+ASR 转写（1.0.14 新增，无需登录态，但转写是草稿级、需你校对）。其他平台链接仍建议自备文案。
2. 选素材版：有文案后，选用哪一版口播文案（原版 / 优化朗读版 / 精简版）。
3. 确认改写：是否做品牌二创改写（推荐做，脱胎不抄袭）。
4. 定每镜几句：每张图配几句口播（常用 2 句）。
5. 备素材图：准备竖屏图 01.png / 02.png …（9:16、无文字无水印），放进 素材图/。
6. 定偏好：选配音音色、要不要 BGM·音效、是否出 MP4（默认只到剪映草稿）。
7. 开剪映：在草稿箱找到生成的草稿，查看 / 精修 / 导出。

> 全程可视化引导见 docs/用户引导图.svg（灰=你做 · 绿=自动 · 橙=你要选 · 虚线=可选）。

名词小课堂（先搞懂"什么是什么"）

• 口播文案：视频里人说的那一段话，写成文字。这是整个视频的"稿子"。
• 脚本 / script_data.py（SCENES）：把口播文案拆成「第几张图 + 图上说哪几句」的结构化清单。它是给剪映"喂料"的格式，AI 和脚本都读它。
• 剪映草稿：剪映 App 里的工程文件（不是视频文件）。打开剪映「草稿箱」能看到，可以继续精修、换图、调字、导出。本 skill 的默认终点。
• 三轨对齐：一条视频有三条时间线——画面轨（图）、字幕轨（字）、配音轨（声音）。三者必须卡在同一时间点，否则"话对着图、字对不上嘴"。本 skill 用配音的真实时长统一驱动三条轨，天然对齐。
• TTS 真实时长：用微软 Edge 免费中文语音把每句念出来，实测这句念了多久（微秒级），再按这个时长排时间轴。所以图、字、声永远同步。
• 转场 / 运镜 / BGM / 音效：图与图之间的过渡（默认叠化淡入淡出）、图片缓慢推近的镜头感、背景垫乐、金句提示音。都是"锦上添花"，可开可关。

工作流1：口播文案 → 改写 → 脚本（可选「深度抓取模式」自动取链接文案）

> 目标：把一段已有的口播文案，做成后续能直接用的 script_data.py 脚本骨架。
> 文案来源两条路：① 自备文本（最稳，默认）；② 深度抓取模式：丢抖音链接，由本 skill 下载视频 + 本地 ASR 转写出口播文案（1.0.14 新增，无需登录态，但转写是草稿级、需人工校对）。

节点 1.1 输入 · 你给口播文案（两条路）

路 A — 自备文本（推荐、最稳）：直接粘贴参考视频的口播文案文本，交给 AI 即可。

路 B — 深度抓取模式（1.0.14 新增，可选）：直接发一条抖音分享链接（形如 https://v.douyin.com/xxxx/），AI 调用本 skill 的 link_to_script.py 自动完成：

抖音链接 ──[download_douyin.py 内联下载无水印视频]──> .mp4
                                                 │
                                          [faster-whisper 本地 ASR]
                                                 │
                                                 ▼
                                          口播文案.txt（草稿级，需校对）
                                                 │
                                    [复用 extract_to_script 聪明切分]
                                                 │
                                                 ▼
                                          script_data.py（镜头脚手架）

前置依赖（仅深度模式需要，首次用才装）：

pip install faster-whisper playwright requests   # 本地 ASR + 内联下载器（无需另装下载 skill）

调用示例（AI 代执行，用户无需记命令）：

python "$SKILL/scripts/link_to_script.py" "https://v.douyin.com/xxxx/" \
    --out ./outputs/ --shots-per-line 1 --target-chars 28
# 已下好 mp4 只想做 ASR+脚本： python link_to_script.py --mp4 已下载.mp4 --out ./outputs/
# 想要更准的转写（首跑自动下 ~460MB）： 加 --model small

> ⚠️ 诚实边界（务必讲给用户听）：
> - 抖音口播在语音里，视频元数据（标题/简介）只有默认的「在抖音记录美好生活」，所以点链接「读文案」这条路永远取不到——本模式是「下载视频 + 语音识别」才通，这是当前唯一可靠路径。
> - ASR 是草稿级：base 模型中文同音字/专有名词会有误差（如「头条」→「投条」、「巨量云图」→「剧量云涂」），拿到 口播文案.txt 后请人工读一遍校对，再继续改写/进脚本。想要更干净可用 --model small。
> - 依赖较重（faster-whisper + 首次模型下载 + 内联下载器的 playwright）；若不想装，退回路 A 自备文本即可，两条路产出完全一致。

节点 1.2 整理 · AI 基于你给的文案，出可选版本

这是什么：基于你提供的口播文案（路 A 自备文本，或路 B 深度模式 ASR 转写后校对过的文案），AI 顺手给出版本变体方便你挑。

固定产出格式：

【标题】
(视频标题)

【简介】
(视频简介)

【口播文案 · 原版】（即你提供的原文）

【口播文案 · 优化朗读版】
(语句通顺、断句清晰，适合口播)

【口播文案 · 精简浓缩版】
(核心内容精炼，适合短平快视频)

【文案时长参考】
总字数：XXX 字
建议口播时长：约 XX 秒

动手后、往下走之前，用 AskUserQuestion 确认：

• 问题：用哪一版口播文案作为后续素材？
• 选项：① 原版（即你提供的）② 优化朗读版（断句顺、好念）③ 精简浓缩版（更短）④ 我自己另外给

> 一般取 原版提取 或 优化朗读版。

节点 1.3 改写 · AI 品牌二创（推荐必做）

这是什么：提取到的是参考视频的原话，直接照搬易抄袭/撞车、也不像你自己的号。这一步让 AI 按「十一AGI认知圈」调性重写——换表述、换结构、换例子，做到"脱胎不抄袭"，但保留核心信息点。

• 调性：说人话、小白向、可加数据 / 故事钩子（参考卡兹克爆款风）。
• 产出「改写版口播文案」（纯文本）。

> 注意：节点 1.2 给的「优化朗读版 / 精简浓缩版」只是断句通顺，不算二创；真正要进脚本的，是这一步的改写版。

动手后：把改写版展示给用户看，并说明"这是为你账号重写的版本，和原视频不是同一篇"。

节点 1.4 桥接 · 改写成脚本 script_data.py

这是什么：剪映要的"料"是结构化清单——SCENES = [(第几张图, [图上说哪几句]), ...]。这一步把改写版文案自动按句切开、分镜，生成这个清单的脚手架。你之后只要把图片名对上即可。

用桥接脚本（脚本已在 skill 内，绝对路径调用）：

python "$SKILL/scripts/extract_to_script.py" \
    --input 改写版文案.txt --shots-per-line 2 --out script_data.py

动手前，用 AskUserQuestion 确认「每镜几句」：

• 问题：每张图配几句口播？
• 选项：① 1 句（金句卡点，节奏慢）② 2 句（成片常用，推荐）③ 3 句（信息密度高）

参数说明：

生成示例（请逐字段讲给用户听）：

SCENES = [
    ("01.png", ["你还在手剪短视频？", "其实丢个脚本，草稿自己长出来。"]),  # 第1张图，图上说这2句
    ("02.png", ["把素材丢进去，配音字幕转场一键到位！", "关注我，AI工作流持续拆解。"]),
]

> 01.png / 02.png 是占位序号，对应你后面要准备的图片。这一步结束，告诉用户：脚本骨架好了，下一步需要你备图。

工作流2：脚本 → 剪映草稿

> 目标：把 script_data.py + 竖屏图，生成剪映里能直接打开编辑的草稿。默认到此为止，不出 MP4。

节点 2.1 备图 · 你准备竖屏图

这是什么 & 要求：上面脚本里 01.png / 02.png 对应的图片。必须：
- 9:16 竖屏、无文字、无水印，建议 720×1280；
- 文件名与脚本顺序一一对应（01.png 是第一镜用的图）。

把图放进工程的 素材图/ 目录。这一步只能你来做（AI 不代生图）。

节点 2.2 确认偏好 · 用提问定音色与增强项

动手前，用 AskUserQuestion 确认（可合并一题多选）：

• 配音音色：① 男声（云扬，稳重）② 女声（晓晓，亲和）③ 青年男声（云希，年轻）
• 要不要背景音乐 BGM + 金句音效？① 要（推荐）② 不要
• 图片要不要轻微运镜推近？① 要（推荐）② 不要
• 是否要导出 MP4 成片？① 不用，只要剪映草稿（默认）② 要，顺带渲染 MP4

> 重申：默认只到剪映草稿。只有用户选"要 MP4"才进渲染。

节点 2.3 生成草稿 · 跑流水线（停在草稿箱）

在工程根执行（脚本已在 skill 内，用绝对路径调用）：

cd /你的工程根                      # 含 script_data.py 与 素材图/ 的目录
python "$SKILL/scripts/pipeline.py" --all

--all 会依次做：配音（TTS 真实时长）→ 合成 BGM/音效 → 组装剪映草稿，然后停在草稿箱，不出 MP4。

产出是什么：草稿自动写入剪映工程目录，打开剪映即可在「草稿箱」看到并继续编辑：

%LOCALAPPDATA%\JianyingPro\User Data\Projects\com.lveditor.draft\
  └── 短视频-配音+转场+BGM+音效+运镜-v1_YYYYMMDD/     ← 自动生成日期后缀
        ├── draft_content.json      # 草稿主体
        ├── draft_meta_info.json    # 元信息（时长/draft_id）
        ├── draft_info.json         # 剪映识别信息
        └── material/               # 引用的素材副本

草稿里包含（展开讲给用户听）：
- 视频轨：N 张竖屏图（封面推入 + 其余轻微推近 + 图间叠化转场）
- 字幕轨：逐句中文硬字幕（白字黑描边、居中靠下）
- 配音轨：N 条 Edge TTS 配音（与字幕/画面严格对齐）
- BGM 轨：整条垫乐 + 配音段自动音量避让（ducking）
- 音效轨：金句时刻提示音

> 怎么打开：启动剪映 → 首页「草稿箱」→ 找 短视频-配音+转场+BGM+音效+运镜-v1 开头的那条 → 点进去继续精修。

节点 2.4（可选）出 MP4 · 仅当用户明确要

只有用户在节点 2.2 选了"要 MP4"，才跑：

python "$SKILL/scripts/pipeline.py" --stages render   # 完整版
# 或 --stages tou                                      # 投流剪辑版（无字幕、更快）

渲染完成后在工程根生成 短视频_成品.mp4（720×1280）。这是"锦上添花"，不是默认动作。

边界与限制（讲给用户听，别藏）

• 抖音链接可深度抓取，但 ASR 是草稿级：1.0.14 起，抖音分享链接可用 link_to_script.py 自动下载视频 + 本地 faster-whisper 转写出口播文案（无需登录态）。但转写有同音字/专名误差，必须人工校对后才进脚本；想要更准用 --model small。快手/小红书/视频号暂无内置下载器，仍建议自备文案。从「链接」到「文案」本质是「下载视频 + ASR」工程，已在深度模式中落地，不再依赖读元数据（元数据读不到口播）。
• 不代生图：本 skill 只做「文案/脚本 → 剪映草稿」，竖屏素材图需你自备。
• 需本机环境：装过剪映并至少打开过一次（草稿才在 App 内显示）；系统有 ffmpeg；Python 3.10+。
• edge-tts 需联网：配音调用微软 TTS，离线无法生成（无需 GPU）。
• 默认产出是剪映草稿：--all 只到草稿箱；MP4 需显式 --stages render/tou。
• 图片需 9:16 竖屏、无文字无水印：文件名与 SCENES 顺序对应。

与 jianying-tts-draft 的关系（避免重复造轮子）

本 skill 的「工作流2（脚本 → 剪映草稿）」与库内 jianying-tts-draft 能力高度重叠。
差异点：本 skill 额外提供引导式向导 + 品牌二创改写 + 投流版 + 环境自检，且统一在「十一AGI」品牌下。
- 若你只要「文案 → 草稿」、不需要向导：直接用 jianying-tts-draft 更轻。
- 若要引导式全流程（含改写/投流/自检）：继续用本 skill。
- 本 skill（1.0.14）已通过 link_to_script.py 把「抖音链接 → 下载 + 本地 ASR → 口播文案」做成可选深度模式；jianying-tts-draft 暂无此能力，若你要"丢链接自动出文案"用本 skill。

环境准备

详见开头「安装后第一次使用（三步）」。一句话版：

pip install pyJianYingDraft edge-tts numpy    # 依赖
python "$SKILL/scripts/check_env.py"          # 自检，全绿才开跑

环境要求一览：

> 草稿写入位置：Windows %LOCALAPPDATA%\JianyingPro\User Data\Projects\com.lveditor.draft；
> macOS ~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft。
> 目录不存在时脚本会自动创建，但要在剪映内显示，仍需本机装过剪映并至少完整打开过一次。

项目结构约定

固化到用户级 skill 后，脚本已在 ~/.workbuddy/skills/shiyi-agi-draft-kit/scripts/，无需复制到工程目录。工程根只需：

your_project/
├── script_data.py          # SCENES 列表（工作流1 桥接生成 / 你手改）
├── 改写版文案.txt           # （工作流1 中间产物，可选保留）
└── 素材图/
    ├── 01.png
    └── ...

模板脚本清单（scripts/）

进阶与踩坑

转场/运镜参数、字幕竖屏样式、剪映 meta 修正、BGM 音量避让、草稿 JSON 字段陷阱、ffmpeg 渲染细节，见同包 使用说明.md 附录「实现细节与已知坑」。

完整可运行示例见 examples/script_data.example.py（复制到工程根改名 script_data.py 即可填自己的内容）。

> 工作流1 纯白话流程图（灰=你做 / 绿=自动，无命令术语，含改写步骤）见 docs/workflow1-flow-plain.svg。
> 名词完整解释（口播文案 / 脚本 / 草稿 / 三轨 / TTS 真实时长 / 转场运镜 BGM 音效）见 docs/名词手册.md（图文版 docs/名词手册.svg）。用户全程待办引导见 docs/用户引导图.svg。