视频 AI 字幕翻译助手（编排 Skill）

这个 Skill 做什么 / 不做什么

做什么：把用户给的音视频/字幕文件，通过 HTTP 调用一个已经运行的「视频 AI 字幕翻译助手」实例，
跑完 上传 → 处理（抽音轨→语音识别→翻译）→ 轮询 → 下载 .srt 全流程，并把字幕文件交付给用户。

不做什么：
- ❌ 本 Skill 不自己跑 Whisper / 不自己装模型——那是助手实例的事。
- ❌ 本 Skill 不负责启动服务端。受平台安全策略限制，Agent 无法常驻拉起本地服务
（cmd /c start、Start-Process、wscript.exe 均被拦截，且子进程会在工具调用结束时被回收）。
- ✅ 因此：本 Skill 只驱动一个已在运行的实例；连不上时，指导用户先把服务起起来。

> 服务端的完整代码、便携包、部署说明在该项目里（E:\本地AI翻译助手，或用户自行分发的
> 本地AI翻译助手_便携版_*.zip）。本 Skill 只是它的「遥控器」。

适用场景（触发词）

• "提取这个视频的字幕" / "翻译字幕" / "视频转字幕" / "扒字幕"
• "把这部剧/这个视频的字幕做出来" / "语音转字幕" / "音频出字幕"
• 中日韩英等语种的字幕识别或互转
• 用户给了 .srt/.ass 文件要求翻译
• 只想要原文时间轴字幕（不翻译）→ 用 extract 后端

前置条件（一次性，用户侧）

需要一个运行中的助手实例，二选一：

1. 本地实例（最通用）：用户在本机双击 启动助手.vbs（或 start.bat），
   浏览器能打开 http://127.0.0.1:5180 即代表已就绪。便携包解压后同样操作。
2. 云端实例（已部署）：https://local-ai-translator.app.workbuddy.host/
   - 直接在浏览器打开上述链接即可使用
   - Agent 调用时设置环境变量 SUBTITLE_API_BASE=https://local-ai-translator.app.workbuddy.host

首次使用本地实例需确保依赖已装（start.bat 会自动建 venv + 装依赖；便携包用 一键部署.bat）。
语音识别依赖 ffmpeg，已随便携包或 E:\AI-Tools\ffmpeg 提供。

⚠️ 必须踩过的坑（Agent 必读）

1. 连不上服务时，不要尝试自己启动它。 直接指导用户启动（见上），然后等用户确认「已打开」
   再用 scripts/client.py health 复测。强行用 Bash 拉起 Flask 会被安全策略拦，且子进程随即被回收。
2. API 基础地址解析顺序（高优先级在前，已写进 scripts/client.py）：
   环境变量 SUBTITLE_API_BASE → 命令行 --base → 默认 http://127.0.0.1:5180。
   不确定时先 python scripts/client.py health 看是否在线。
3. extract 后端只产出 orig.srt（原文时间轴，不翻译）；translate 类后端产出
   orig / zh / bilingual 三份。下载时按服务端返回的 files 字段拿，缺哪份就别下哪份。
4. 默认档位是 small（2026-09-21 起）。tiny/base 中文易错字，medium/large-v3
   更准但更慢更大。small 是精度与体积的平衡点。
5. 长视频耗时久：几小时 1080p 的识别可能跑几十分钟。轮询超时默认 1800s，必要时调大
   --max-wait。不要中途判定失败。
6. 在线翻译后端要密钥：baidu/youdao/xfyun/tencent/deepseek/qwen/zhipu/kimi/siliconflow/ deepl/openai/gemini 需要在服务端 config.json 配好对应 Key；没配会返回错误。
   免费/离线后端：extract（不翻译）、argos（离线翻译，推荐）、mymemory（免费在线无需 Key）、
   libretranslate（本地 API）、ollama（本地模型）。

工作流（Agent 执行步骤）

步骤 0：确认输入文件

拿到用户给的音视频/字幕的绝对路径。若用户只给了相对路径或描述，先让其提供具体文件。

步骤 1：确认/探测服务端

"$PYTHON" "skills/video-subtitle-translator/scripts/client.py" health

• 返回 status: ok → 进入步骤 2。
• 连不上（exit 2）→ 在回复里明确告诉用户：
  > 助手服务未运行。请先在本机双击 启动助手.vbs（或运行项目里的 start.bat）启动，
  > 启动后浏览器能打开 http://127.0.0.1:5180 即可；云端用户可直接访问
  > https://local-ai-translator.app.workbuddy.host/ 使用，或把 SUBTITLE_API_BASE
  > 设为你的应用地址。启动好后告诉我，我继续处理。
  然后停下等用户确认，不要自行尝试拉起服务。

> 若需指定非默认地址：--base https://你的云端地址，或先
> export SUBTITLE_API_BASE=https://...。

推荐使用云端实例：https://local-ai-translator.app.workbuddy.host/
- 无需本地启动服务，直接浏览器访问即可使用
- Agent 调用时设置 SUBTITLE_API_BASE=https://local-ai-translator.app.workbuddy.host

步骤 2：弄清用户要「提取」还是「翻译」

• 只要原文时间轴字幕（不翻译）→ --backend extract
• 要翻译成中文 → 默认 --backend argos（离线，推荐）；若用户指定了某个在线服务则按其要求。
• 用户没说语种 → --source auto（自动检测）。明确知道语种就给准（如日剧 --source ja、
  美剧 --source en-US），能提升识别率。

步骤 3：跑全流程

用本 Skill 自带的客户端（仅标准库，无需额外安装）：

"$PYTHON" "skills/video-subtitle-translator/scripts/client.py" translate \
  --file "用户的文件绝对路径" \
  --source auto \
  --backend argos \
  --model small \
  --out "输出目录绝对路径"

• 多音轨视频选音轨：--audio-index 1（默认 0）
• 长视频加 --max-wait 3600
• 该命令会依次打印 上传/处理/轮询/下载 进度，结束打印下载路径。

步骤 4：交付

把下载到的 .srt 通过 present_files 交付（按 orig / zh / bilingual 顺序，主交付物通常是 zh 或 bilingual）。
简要回应用户：任务 ID、模式（extract/translate）、检测出的语种、产出了哪几份字幕、文件位置。

常用示例

参数速查

完整后端/档位列表随时用 client.py options 拉取（来自服务端 /api/options）。

参考文档

已知限制

• 本 Skill 不能启动服务端，必须用户侧先起（见步骤 1）。
• 语音识别质量受音频清晰度影响；强噪声/音乐/远场会下降。
• 在线翻译后端依赖对应服务可用性与密钥；离线/免费后端（extract/argos/mymemory）无需外网密钥。
• 长视频处理时间长，属正常，调大 --max-wait 即可。
• 服务端单进程、内存常驻任务上限 20 个、TTL 6 小时（详见 API.md），超期结果会被回收需重跑。