AI剪口播

剪口播

ASR Router 转录 + AI 口误识别 + 网页审核 / 字幕格式化

模式

• 模式 A: 剪口播 — 转录 → 口误识别 → 网页审核 → 剪辑
• 模式 B: 转字幕 — 转录 → 格式化字幕文本（markdown，无时间戳）

输出目录结构

模式 A（剪口播）：

output/YYYY-MM-DD_HH-MM_视频名/剪口播/
├── 1_转录/   audio.mp3 · asr-result.json · subtitles_words.json
├── 2_分析/   analysis.txt · sentence_map.json · speech_errors.json · auto_selected.json
└── 3_审核/   review.html · audio.mp3 · data.json · silence_periods.json
                <视频名>_cut.fcpxml   ← 网页点击「导出 FCPXML」后生成在此目录
                                       拖入剪映 / Final Cut Pro 完成最终剪辑

模式 B（转字幕）：

output/YYYY-MM-DD_HH-MM_视频名/剪口播/
├── 1_转录/   audio.mp3 · asr-result.json · subtitles_words.json · raw_text.txt
└── 2_纠错/   corrected.txt · uncertain.md（可选）
视频所在目录/
└── subtitles_formatted.md   ← 最终输出

流程总览

-1. 首次引导（仅第一次：环境自检 + 配置 ASR Router）
0. 确认视频路径 + 选择模式
1-4. run_transcribe.sh（自动，两模式共用）

模式 A（剪口播）:
  5.1 gen_analysis.js
  5.2 读规则.md + analysis.txt
  5.3 AI 判断整句口误 → speech_errors.json（只填 delete_sentences）
  5.4 auto_filler.js → 自动补充词级口癖 idx（快速预筛）
  5.5 AI 逐句扫剩余词级口癖（B2/B3/B4，脚本覆盖不到的部分）
  5.6 merge_selections.js
  6-7. 生成审核网页 + 启动服务器
  【等待用户确认】→ 网页点击「导出 FCPXML」→ 拖入剪映 / Final Cut Pro 完成剪辑
       （导出同时写 3_审核/review_log.json，供步骤 8 学习）
  8. 自进化学习（用户显式触发「已导出，学一下」）→ diff 抽规则 → 确认 → 写 经验规则.md

模式 B（转字幕）:
  B-1 提取纯文本
  B-2 第一步：纠错（只改词，不断行）→ corrected.txt
  B-3 第二步：断行（只格式化，不改字）→ subtitles_formatted.md

执行步骤

路径约定（重要）：本 skill 不绑定特定 agent，不要假设它装在 ~/.claude/skills/。 下面命令里的 SKILL_DIR 一律指本 skill 的安装目录（即你加载本 SKILL.md 的那个目录， 含 scripts/、用户习惯/）。执行前把它设成你实际加载 skill 的绝对路径即可：

SKILL_DIR="<本 skill 的安装目录>"   # 例：Claude Code 默认 ~/.claude/skills/AI剪口播

ASR 方法、凭证和资源选择统一由 Agent 调用 asr-router 管理。

步骤 -1: 首次引导（只在第一次跑）

目的：第一次使用时检查业务依赖与 ASR Router；通过后写标记文件。

闸门：先看标记文件是否存在（SKILL_DIR = 本 skill 安装目录，见上方「路径约定」）。

SKILL_DIR="<本 skill 的安装目录>"
[ -f "$SKILL_DIR/.setup_done" ] && echo "已配置，跳过引导" || echo "需要引导"

• 存在 .setup_done → 直接进入步骤 0，不要跑自检、不要提引导。
• 不存在 → 跑自检脚本（跨平台，Win/macOS/Linux 通用）：

node "$SKILL_DIR/scripts/doctor.js"

doctor.js 只检查本 skill 的 ffmpeg 与 Node 业务依赖。ASR 可用性由 Agent 在调用 asr-router 时检查。全绿时写 .setup_done 并退出 0。

AI 按报告分情况引导用户（不要让用户自己看懂报告）：

1. 缺系统依赖 → 把报告里对应平台的安装命令复制给用户（脚本已按 Win/Mac 给好），让其装完。
2. Router 报告供应商不可用 → 按 Router 选中的子方法文档配置。
3. 用户修完 → 重跑对应检查，直到业务依赖与 Router 都可用。

全程不要替用户去控制台点按钮或粘贴他的私有 key 到别处；只给清晰可复制的命令和链接。

步骤 0: 确认视频路径 + 选择模式

收到视频路径后，先展示确认，格式：

? 视频：/path/to/视频.mp4
? 输出：~/Desktop/output/YYYY-MM-DD_HH-MM_视频名/剪口播/

请选择模式：
  [A] 剪口播 — 识别口误 → 网页审核 → 导出 FCPXML 给剪映 / FCP
  [B] 转字幕 — 转录 → 格式化字幕文本（markdown，无时间戳）

用户确认后再继续，不自动开始。

步骤 1-4: Router 转录 + 业务格式化

SKILL_DIR="<本 skill 的安装目录>"   # 见上方「路径约定」
VIDEO_PATH="/path/to/视频.mp4"
BASE_DIR="$HOME/Desktop/output/$(date +%Y-%m-%d_%H-%M)_$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')/剪口播"

# 1. Agent 调用 asr-router：
#    source=$VIDEO_PATH, profile=word_timestamps,
#    privacy=local_only 或 allow_api, output_dir=<临时 Router 输出目录>
# 2. 将 Router normalized result 交给本 skill：
bash "$SKILL_DIR/scripts/run_transcribe.sh" "$VIDEO_PATH" "$BASE_DIR" \
  --asr-result <临时 Router 输出目录>/asr-result.json
# 输出: BASE_DIR/1_转录/{audio.mp3, asr-result.json, subtitles_words.json}

步骤 5: 生成分析文件 + 口误识别

5.1 生成分析文件

node "$SKILL_DIR/scripts/gen_analysis.js" \
  "$BASE_DIR/1_转录/subtitles_words.json" \
  "$BASE_DIR/2_分析"
# 输出: analysis.txt + sentence_map.json + auto_selected.json

5.2 读取规则 + 分析文件

读 用户习惯/规则.md、用户习惯/经验规则.md（自进化沉淀的个人偏好，见步骤 8）和 analysis.txt。 两份规则都要遵守；冲突时以更具体、更新的为准。

analysis.txt 格式（每行一句，序号: 文本）：

0: 直接开始了啊
1: 这是深圳腾讯总部楼下
2: 就为了安装一只

5.3 AI 判断整句口误（只填 delete_sentences）

⚠️ 由你直接阅读 analysis.txt 并判断哪些整句是口误。 本步只填 delete_sentences，delete_idx 留空数组。词级口癖留到 5.4（脚本）+ 5.5（AI 补漏）。

按 规则.md 的 A 节（整句删除） 判断：重复重说、残句、句内卡顿、只含语气词的整句等。

输出格式（写入 $BASE_DIR/2_分析/speech_errors.json）：

{
  "delete_sentences": [2, 3, 8, 10],
  "delete_idx": []
}

5.4 脚本自动识别词级口癖（无需 AI）

node "$SKILL_DIR/scripts/auto_filler.js" \
  "$BASE_DIR/2_分析/sentence_map.json" \
  "$BASE_DIR/1_转录/subtitles_words.json" \
  "$BASE_DIR/2_分析/speech_errors.json"

脚本会就地修改 speech_errors.json，把识别到的口癖 idx 合并进 delete_idx：

• 任意位置：呃 / 嗯 / 额 / 诶 / 欸 / 唉 / 噢（已排除"额外/金额"等真词）
• 任意位置的：然后（用户偏好：宁可手动加回）
• 句首过渡词：然后 / 那么 / 好的 / 啊 / 哦 / 哎 / 呀 / 对 / 呢 / 那（"那"会避开"那个/那么/那里"等）
• 句尾废词：对 / 呢 / 啊 / 哦
• 跳过已整句删除的句子；保护剩余字数 ≤3-4 的短句不被掏空

跑完后，用户已手工填的 idx 也会被保留（合并去重）。

5.5 AI 逐句扫剩余词级口癖（脚本覆盖不到的部分）

脚本只处理"无需上下文判断"的安全口癖。AI 在此扫 analysis.txt，找出脚本覆盖不到的：

• B4 句中重说（优先级最高）：前半段说错、后半段纠正 → 删前半段，保留后半段
• B3 冗余引导短语：大家可以看到、你看、给大家看一下、比如说你看一下、我可以告诉你、你明白吗
• B2 句中填充词（慎用，需明确判断为口癖才删）：其实、就、也、大概、这个、那个、就是
• B5 脚本未覆盖的句尾拖音

工作方式（避免 token 爆炸 + 过删）：

1. 顺序扫 analysis.txt，只标"明显有问题"的句子。没明显问题的句子直接跳过，不要为了"也许能再删一点"硬挑刺。
2. 把候选句号攒成一批（建议 20-30 句一组），一次 gen_word_detail.js 调用拿到词级 idx。
3. 把新增 idx 合并写回 speech_errors.json 的 delete_idx（与 5.4 结果取并集，不要覆盖）。

# 一次传多个句号，减少往返
node "$SKILL_DIR/scripts/gen_word_detail.js" \
  "$BASE_DIR/2_分析/sentence_map.json" \
  "$BASE_DIR/1_转录/subtitles_words.json" \
  5 8 12 24 25 44 ...

判断尺度：句子已经能读通就不要再动。剪口播的容错来自审核网页（用户能取消勾选），但误删比漏删难恢复——用户得手动取消勾选才能找回。所以漏删优于过删。

5.6 合并到 auto_selected（代码自动映射句号→idx）

node "$SKILL_DIR/scripts/merge_selections.js" \
  "$BASE_DIR/2_分析/sentence_map.json" \
  "$BASE_DIR/2_分析/speech_errors.json" \
  "$BASE_DIR/2_分析/auto_selected.json"

步骤 6-7: 生成审核数据并启动服务器

# 6. 生成 data.json + review.html（从 templates/review.html 复制）
#    前端模板在 scripts/templates/review.html，改样式直接改那里
node "$SKILL_DIR/scripts/generate_review.js" \
  "$BASE_DIR/1_转录/subtitles_words.json" \
  "$BASE_DIR/2_分析/auto_selected.json" \
  "$BASE_DIR/1_转录/audio.mp3" \
  "$BASE_DIR/3_审核"

# 7. 启动审核服务器
#    serve_review.sh 会自动选端口、在【一个独立的 OS 终端窗口】里前台运行服务器、
#    健康检查、打开浏览器；若环境禁止开新窗口，会打印一条手动命令兜底。
#    （不要再用 `&` / nohup 在 agent 后台挂服务——见下方「为什么」。）
bash "$SKILL_DIR/scripts/serve_review.sh" \
  "$BASE_DIR/3_审核" "$VIDEO_PATH" "$SKILL_DIR/scripts/review_server.js"

⚠️ 为什么必须用 serve_review.sh，不能直接后台 &/nohup 挂服务（重要，否则用户会「拒绝连接」）： 审核网页要这个本地服务一直监听端口。但各 agent 对后台进程的处理不同：

• Claude Code 有常驻进程管理器，会在整个会话期间替你保活后台进程 → 直接 & 也没事；
• 某些 agent（如 Codex） 把每条命令放在临时子进程/沙箱里，命令一返回就回收整棵进程树 （连 nohup/disown 的子进程也杀）→ 端口失联，浏览器报「localhost 拒绝了连接请求」。

所以不要依赖 agent 替你保活。serve_review.sh 改在 OS 层另起一个真正的终端窗口前台运行 （macOS 写可双击的 .command 并 open；Linux/Windows 起对应终端），它由系统拥有、不随 agent 命令回收。脚本最后还会打印一条 bash "<3_审核>/启动审核服务.command" 的手动命令—— 万一连开窗口都被禁，让用户在自己的终端里跑这一条、保持窗口开着即可。

服务器启动时会把地址写进 3_审核/server_url.txt、进程号写进 .review_server.pid，方便排障。

用户在网页中：播放片段确认 → 勾选/取消 → 点击「导出 FCPXML」→ 生成的 *_cut.fcpxml 拖入剪映或 Final Cut Pro 完成最终剪辑。

导出时服务器同时写一份 3_审核/review_log.json（与 FCPXML 同一次点击产出）：记录 AI 初选 idx、用户最终 idx、切割参数，以及二者词级 diff（带文字+句子上下文）。 这是步骤 8「自进化学习」的唯一原料，不读 .fcpxml（那是算完的时间线，丢失了词级选择）。

步骤 8: 自进化学习（用户显式触发）

不自动跑。 用户导出后，在任意会话说「<项目> 已导出，学一下」之类，才执行本步。 本步只读文件、不依赖对话上下文还在，所以冷会话也能跑。

1. 定位日志：单个项目读 <project>/剪口播/3_审核/review_log.json； 批量重学则 glob ~/Desktop/output/*/剪口播/3_审核/review_log.json，逐个汇总。 （日志只存在项目里，清理 output 会丢语料。）
2. 读现有规则：先读 用户习惯/经验规则.md 全文 + 用户习惯/规则.md，避免重复提已有规则。
3. 看 diff 抽规则：对每条 diff.aiOnly（AI 想删你留回，可能过删）和 diff.userOnly （你删了 AI 没想到，可能漏删），对比「AI 为何这么剪 vs 你为何这么剪」， 抽象出能泛化到下一条视频的通用偏好。严禁把单条口误/语境例外固化成规则。
4. 违例提醒：若 diff 显示用户违反了某条已有规则，逐条提醒用户，让其判断 是「正当例外（规则不动）」还是「该改松/加例外条件」。
5. 列给用户确认：把候选的【新增 / 细化已有 / 合并重复 / 改某条】列出来，等用户确认。
6. 写入：确认后才改 用户习惯/经验规则.md，每条带出处标签 （学于 <视频名> YYYY-MM-DD；已确认）。 下次步骤 5.2 即生效。

模式 B: 转字幕

步骤 1-4 完成后，如果用户选了模式 B，执行以下步骤。 两步拆分：先纠错，再断行。两步必须分开进行，不要混为一步。

B-1 提取纯文本（脚本执行）

node "$SKILL_DIR/scripts/extract_text.js" \
  "$BASE_DIR/1_转录/subtitles_words.json" \
  "$BASE_DIR/1_转录"
# 输出: $BASE_DIR/1_转录/raw_text.txt

B-2 第一步：纠错（AI 处理）

1. 读取 $BASE_DIR/1_转录/raw_text.txt
2. 读取 $SKILL_DIR/用户习惯/纠错prompt.md 规则
3. 只做纠错，不断行、不去标点、不改格式
4. 输出到 $BASE_DIR/2_纠错/corrected.txt（每行一句，与输入 1:1 对应）
5. 如有「不确定清单」，输出到 $BASE_DIR/2_纠错/uncertain.md 并在对话中列出给用户

B-3 第二步：断行（AI 处理）

1. 读取 $BASE_DIR/2_纠错/corrected.txt
2. 读取 $SKILL_DIR/用户习惯/断行prompt.md 规则
3. 只做格式化，不改字、不删字、不加字
4. 输出到视频所在目录：$(dirname "$VIDEO_PATH")/subtitles_formatted.md
5. 告知用户文件路径，流程结束

---

ASR 委派

所有模型顺序、API 标注、凭证、资源 ID、请求方法和 fallback 规则都以 asr-router 为唯一来源。本 skill 不锁定 provider，也不执行任何 ASR adapter；只消费 Router 的 asr-result.json 与字级时间戳。