🎬 视频字幕合成技能 V3.7

> 固定程序模式 — AI 对话式引导，自动配置，一键执行。无需用户手动操作。

🔔 首次加载指引

加载本技能后，必须立即向用户推送以下信息：

🎬 视频字幕合成 V3.7 已就绪！

只需告诉我：
  • 源视频文件路径
  • 字幕模板文件路径（.md 格式）

其他一切交给我——环境检测、引擎配置、TTS配音、字幕注入，全自动完成。

💡 制作字幕模板？推荐使用「字幕模板编辑器」：
  用浏览器打开 tools/subtitle-editor.html → 拖入视频 → 粘贴字幕文案 → 按 F 键拍板标记 → 导出 .md

📂 技能文件

<本技能目录>/
├── SKILL.md
├── scripts/                  ← AI 从这里复制程序到用户项目
│   ├── env_check.py
│   ├── step01_check.py
│   ├── step02_cut.py
│   ├── step03_tts.py
│   ├── step04_align.py
│   ├── step05_merge.py
│   ├── step06_finalize.py
│   ├── pipeline.py
│   ├── copy_template.py
│   └── script_template.md
├── tools/                    ← 辅助工具
│   └── subtitle-editor.html  ← 字幕模板编辑器（按键拍板式）
└── references/
    └── DESIGN.md

🤖 AI 对话交互流程（核心）

阶段 1：接收用户请求

用户说"帮我合成视频"或类似请求。AI 必须确认两个路径：

请提供：
1. 源视频路径（如 D:/视频/demo.mp4 或 /home/user/video/demo.mp4）
2. 配音模板路径（如 D:/视频/script.md 或 /home/user/video/script.md）

> 如果用户没有模板：AI 必须执行以下操作：
> bash > python <本技能目录>/scripts/copy_template.py --to-dir <用户项目目录> >
> 执行后告知用户："📝 模板已复制到 <用户项目目录>/script_template.md，请打开填写时间点和文案，完成后告诉我路径即可合成。"

阶段 1.5：AI 展示模板格式（用户有模板时也执行）

当用户提供了模板路径，但 AI 需要在对话中展示格式参考时：

python <本技能目录>/scripts/copy_template.py --chat

读取 stdout 输出，向用户展示模板格式说明。

阶段 2：环境检测（AI 自动执行）

AI 自行执行，无需用户干预：

1. 复制程序：在用户项目目录下创建 _scripts/ 子目录，将本技能 scripts/ 目录下的所有 .py 文件复制进去。
   - AI 已知本技能的安装路径（加载时系统会告知）
   - 用文件操作工具复制，不要写死绝对路径
   - 重要：程序文件放入 _scripts/ 子目录，不要和视频/模板文件混在同一目录。目录结构：
   用户项目目录/ ├── 视频文件.mp4 ← 用户的素材 ├── 模板文件.md ← 用户的模板 ├── _scripts/ ← 程序文件（AI 创建） │ ├── env_check.py │ ├── step01_check.py │ └── ...（共 9 个 .py 文件） ├── env.json ← 环境检测输出 ├── tts_config.json ← 讯飞凭证（如适用） └── output/ ← pipeline 自动创建
   - Windows/Linux 均使用各自系统的文件 API

2. 运行环境检测：

python _scripts/env_check.py --output env.json

读 env.json，按情况处理：

阶段 3：TTS 引擎选择（AI 提问 + 用户选择）

AI 必须主动提问，原文如下：

🔊 请选择 TTS 配音引擎：

1. 讯飞超拟人（推荐）— 音质最佳，需讯飞账号凭证
2. edge-tts（免费备用）— 微软服务，无需配置

请输入 1 或 2：

用户选 1（讯飞）：

AI 追问凭证：

请提供讯飞凭证（在 https://console.xfyun.cn 获取）：
  • APPID：
  • APIKey：
  • APISecret：
  • WS URL（在 https://console.xfyun.cn 获取超拟人端点）

（凭证仅保存在本地的 tts_config.json，不会上传）

> 安全提醒：凭证写入 tts_config.json 后，提醒用户将此文件加入 .gitignore。

用户提供凭证后，AI 问音色：

🎤 请选择讯飞音色：

1. 聆小糖（女，活泼流畅）— 默认，适合通用教学
2. 聆小璇（女，柔美自然）
3. 聆飞逸（男，稳重有力）
4. 聆小玥（女，清晰明亮）
5. 聆玉昭（女，自然亲切）

请输入 1-5（默认 1）：

根据用户选择，映射为 vcn：
- 1 → x5_lingxiaotang_flow
- 2 → x5_lingxiaoxuan_flow
- 3 → x5_lingfeiyi_flow
- 4 → x5_lingxiaoyue_flow
- 5 → x5_lingyuzhao_flow

AI 创建 tts_config.json：

{
  "spark": {
    "app_id": "<用户提供>",
    "api_key": "<用户提供>",
    "api_secret": "<用户提供>",
    "ws_url": "<用户提供>",
    "default_voice": "<用户选择的vcn>"
  }
}

用户选 2（edge-tts）：

AI 问音色：

🎤 请选择 edge-tts 音色：

1. 晓晓（女，温柔）— 默认
2. 云希（男，正式）
3. 晓伊（女，活泼）

请输入 1-3（默认 1）：

根据选择映射：
- 1 → zh-CN-XiaoxiaoNeural
- 2 → zh-CN-YunxiNeural
- 3 → zh-CN-XiaoyiNeural

不需要 tts_config.json，跳过创建。

用户说"没有讯飞 key"：

AI 直接走 edge-tts 流程，不追问。

阶段 4：AI 自动生成 job.yaml

AI 根据已收集的信息，自动创建 job.yaml：

video: "<用户在阶段1给出的视频路径>"
template: "<用户在阶段1给出的模板路径>"
voice: "<阶段3选择的音色>"
engine: "<spark 或 edge>"
output_root: "output"
env_file: "env.json"
tts_config: "tts_config.json"
# template_fps: 30  # 高级：手动指定模板帧率（程序默认自动检测，通常无需设置）

> 如果 engine=edge，不写 tts_config 这一行，或写 tts_config: ""。

阶段 5：AI 一键执行（不是让用户执行）

AI 自行执行以下命令，并在对话中报告进度：

python _scripts/pipeline.py --job job.yaml

将 pipeline.py 的标准输出实时展示给用户。每完成一步报告一次：

✅ 01_check  → 10段解析完成
✅ 02_cut    → 10段切分完成
✅ 03_tts    → 10段配音完成（讯飞spark）
✅ 04_align  → 对齐完成（含 filler/加速/冻结/静音决策）
✅ 05_merge  → 声画合成完成
✅ 06_finalize → 逐句字幕注入完成

🎉 成品：output/{task_id}/06_final/final_with_subs_xxx.mp4

阶段 6：容错处理

如果某步骤失败，pipeline.py 会输出 resume 命令。AI 必须：

1. 读错误信息，判断原因
2. 常见情况：

3. 执行 resume：

python _scripts/pipeline.py --job job.yaml --resume-from <失败的步骤>

📋 配置清单（AI 记住）

用户不需要手动创建或编辑任何文件。一切由 AI 对话引导完成。

🎤 音色速查（供 AI 参考）

讯飞 spark

edge-tts

⚠️ 环境缺失处理指南

> 重要：edge-tts==7.2.8 是 Python 包（pip install edge-tts==7.2.8），利用微软 Edge 浏览器的免费 TTS 服务。不是微软商店的 EdgeTTS 应用。不需要用户去微软商店下载。国内网络如 pip 直连失败，AI 自动追加 -i https://pypi.tuna.tsinghua.edu.cn/simple 重试。

🖱️ 字幕模板编辑器（"按键拍板" — 推荐制模方式）V3.5.6

目的：解决老师对照视频手动写时间码的痛点。

工具路径：<本技能目录>/tools/subtitle-editor.html

工作流

准备字幕文案 → 设工作目录 → 拖入视频 → 粘贴文案 → 播放视频 → 按F键拍板 → ⚡一键生成提示词

核心机制

• F 键 = 拍板标记：每次按下，当前视频时间自动对应到当前字幕的结束时间
• 自动衔接：上一段结束时间 = 下一段开始时间（无缝连续）
• 精确逐帧：单击 ← → 精确走 1 帧；长按 → 8x 高速播放（playbackRate，丝滑不卡）
• Ctrl+Z 撤销：按错了随时撤销上一个标记
• 自动缓存：所有标记 + 工作目录自动保存到 localStorage，关闭浏览器也不丢
• 一键生成提示词：⚡ 自动下载 .md + 构建完整提示词 + 复制到剪贴板，直接粘贴给 AI
• 路径校验：工作目录 3 层校验（无效字符/非绝对路径/像文件名），防止误存

AI 引导话术

当用户不知道如何制作模板时，AI 应主动推荐：

建议使用「字幕模板编辑器」制作模板，比手动写快很多：

1. 先用记事本写好每段字幕文案（按顺序编号）
2. 用浏览器打开 tools/subtitle-editor.html
3. 设置工作目录 → 拖入视频 → 粘贴字幕 → 播放视频
4. 每到画面切换点，按 F 键标记；← → 精调位置
5. 全部标记完成 → 点击 ⚡ 一键生成提示词
6. 把生成的提示词粘贴给我即可

📝 模板格式（供用户参考）

| 开始时间 | 结束时间 | 文案内容 |
|----------|----------|----------|
| 00:00 | 00:02 | 本视频将讲解如何制作进阶笔筒。 |
| 00:02 | 00:03,17 | 首先制作底座，选取圆柱体。 |

• 时间 MM:SS，帧数后缀 MM:SS,FF
• SMPTE 时间码：逗号后为帧编号（如 00:12,19 = 12 + 19/fps 秒），非小数点
• 自动适配：程序检测到 MM:SS,FF 逗号格式时，自动按 30fps（剪映默认帧率）解析，用户无需任何配置
• 也支持小数点格式 MM:SS.mmm
• 数学符号自动口语化：-5 → 朗读"负5"、5+3 → "5加3"、× → "乘"、÷ → "除以"（无需手动改写）
• 文件编码 UTF-8 / GBK 均支持

📋 变更日志

🔒 分享前检查清单

> 当用户要求「创建分享副本」「发布技能」「脱敏分享」时，AI 必须逐项执行以下检查，不得跳过。

必须清除的敏感信息

执行步骤

1. 复制整个技能目录到分享位置（如 D:\minimax\zmrobo\video-tutorial-v2-share/）
2. 逐文件搜索真实凭证片段（app_id 数字值、api_key 值、api_secret 值、私有端点路径），用 grep 确认全部命中位置
3. 替换所有命中为占位符
4. 删除 __pycache__/ 目录
5. 再次 grep 验证零残留
6. 告知用户：「分享副本已就绪，无凭证泄露」

不做的事

• 不修改原始工作区技能文件（C盘 ~/.workbuddy/skills/ 的版本保留凭证，仅用户本人使用）
• 只操作分享副本