@optima-chat/gen-cli 2.0.0 → 2.1.0

package/.claude/skills/video-translate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: video-translate
 description: "把单段口播视频翻译成 English / Thai (Thailand) / Malay (Malaysia) / Vietnamese (Vietnam) 之一,出片自带译音(自动克隆原说话人)+ 烧录目标语花体字幕 + 默认 BGM ducking。触发场景:用户说翻译这个视频/做泰语版/英文版/越南语版/马来语版/视频本地化/换语言/dub。"
-version: 1.0.2
+version: 1.0.3
 owner_repo: Optima-Chat/optima-gen
 ---
 
@@ -21,7 +21,7 @@ owner_repo: Optima-Chat/optima-gen
 ## 前提
 
 - 源视频 URL 公网可访问(或先让用户上传到 Optima → 拿 URL)
-- 容器有:`gen` CLI(`@optima-chat/optima-gen` ≥ latest)、`video-translate` CLI(`@optima-chat/video-translate-tools` ≥ 1.0.2)、`ffmpeg`、`curl`、`jq`
+- 容器有:`gen` CLI(`@optima-chat/optima-gen` ≥ latest)、`video-translate` CLI(`@optima-chat/video-translate-tools` ≥ 1.0.5)、`ffmpeg`、`curl`、`jq`
 - gen video-translate 的 `--mode fast` / `--dynamic-duration` flag 在 latest 版本已存在;若 CLI 报 unknown flag → `npm i -g @optima-chat/optima-gen@latest` 升级
 
 ## 输入
@@ -33,13 +33,33 @@ owner_repo: Optima-Chat/optima-gen
 | `TAG` | ✅ | 对应的两字母 tag(`en` / `th` / `ms` / `vi`) |
 | `BGM` | ⬜ | 自定义 BGM 文件路径(覆盖默认)。不传则用 npm 包内置 `bgm/default.mp3`(22s clean instrumental,自动 loop)|
 | `NO_BGM` | ⬜ | 设非空值则跳过 BGM(出片只有人声 + 原视频 BGM 残留)|
+| `VOICE` | ⬜ | HeyGen stock voice_id(从下面 ## Voice Catalog 选)。**不传 = 克隆源说话人音色**(legacy 默认行为)|
 | `NAME` | ⬜ | 工作区名,默认从 URL 末段推 |
 
 ## 3 步主流程(+ Step 0 预检 + Step 4 可选清理)
 
-### Step 0:声明 + 工作区 + 源视频音量预检
+### Step 0:声明 + 工作区 + URL 预处理 + 源视频音量预检
 
 ```bash
+## ⚠ URL 必须是公网 https URL,不能是本地路径 /home/aiuser/...
+## gen video-translate 只接受 https URL(HeyGen 那边要拉的)
+## 如果是本地路径,先用 chat 系统的 file API 签 URL
+if [[ ! "$URL" =~ ^https?:// ]]; then
+  echo "INFO: 本地路径 '$URL',需要上传拿 https URL"
+  TOKEN=$(jq -r '.access_token' ~/.optima/token.json)
+  ## shell.optima.onl 的 file signing endpoint(具体路径以系统实际为准,
+  ## 这里给出常见模式;如果不行,根据 stderr 报错调整)
+  SIGNED=$(curl -sS -X POST "https://shell.optima.onl/api/files/sign" \
+    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    -d "{\"path\":\"$URL\"}" 2>&1 | jq -r '.data.url // .url // empty' 2>/dev/null)
+  if [ -z "$SIGNED" ]; then
+    echo "ERR: 拿不到 signed URL,把 '$URL' 上传到 chat 系统拿 https URL 再来"
+    exit 1
+  fi
+  URL="$SIGNED"
+  echo "URL → $URL"
+fi
+
 ## URL 末段可能含 query string(HeyGen / S3 预签名 url 含 token)— 先去掉再 basename
 NAME="${NAME:-$(echo "$URL" | cut -d'?' -f1 | xargs basename | sed 's/\.[^.]*$//' | sed 's/[^A-Za-z0-9_-]/_/g')}"
 WORK="./videos/${NAME}.work"
@@ -52,6 +72,42 @@ ffmpeg -i "$URL" -af volumedetect -f null - 2>&1 | grep mean_volume
 
 如果 `mean_volume < -25dB`,提示用户:"源视频音量太低(< −25dB),翻译服务大概率会报无人声。建议先用 `ffmpeg -i in.mp4 -af 'volume=20dB,acompressor=threshold=-20dB:ratio=4' -c:v copy out.mp4` 放大后再翻译。"
 
+### Step 0.5:让用户挑音色 — 纯文本对话(不要用 AskUserQuestion)
+
+**重要:不要用 AskUserQuestion 工具**(只支持 4 选项 + label-based 反查不可靠,试过失败)。**用纯文本输出 5 个选项,等用户文字回复**:
+
+agent 输出(逐字照搬,把 $LANG 换成实际目标语):
+
+```
+翻译到 $LANG,4 个语种共用一个音色。请回复编号(1-5)或名字:
+
+  1. Connie - 沉稳专业旁白(F) — preview: https://resource.heygen.ai/text_to_speech/locale=en-USmodel=eleven_multilingual_v2id=9FnNGNtwCeU9fyf6mFfDp8.mp3
+  2. Sophie - 温柔友好(F)     — preview: https://resource.heygen.ai/text_to_speech/locale=model=eleven_multilingual_v2id=kte4EzDuRTnsnHkATe6tDK.mp3
+  3. Bruce - 中年浑厚(M)      — preview: https://resource.heygen.ai/text_to_speech/locale=model=eleven_multilingual_v2id=2SdnapPUN7wvtCbkPSgdHV.mp3
+  4. Luca - 年轻活力(M)       — preview: https://resource.heygen.ai/text_to_speech/locale=model=eleven_multilingual_v2id=FVKYscu8J8EVReBuZdPXnJ.mp3
+  5. 保留原声(克隆源说话人音色)
+
+回复方式:数字 1-5,或者 "Connie"/"Sophie"/"Bruce"/"Luca"/"原声",或者 "随便"(我帮你随机挑)。
+```
+
+#### 用户回复 → VOICE 变量(严格按下表)
+
+| 用户回复 | VOICE 变量值 |
+|---|---|
+| `1` / `Connie` / `用 Connie` / 任何含 "Connie" | **`VOICE=d774d69075f24d1fb52a0dad145ba809`** |
+| `2` / `Sophie` / `用 Sophie` | **`VOICE=vakjM0uzzAxU4UiT0433`** |
+| `3` / `Bruce` / `用 Bruce` | **`VOICE=1LtsDD7yfTuX92TzjmJk`** |
+| `4` / `Luca` / `用 Luca` | **`VOICE=6HiVdeiuBdZbtcnukrQn`** |
+| `5` / `原声` / `克隆` / `用我自己的` / `keep original` | **`VOICE=`**(留空,不传 `--voice`) |
+| `随便` / `random` | 从 1-4 voice_id 里**随机挑一个**设 VOICE,**不要默认 5** |
+
+#### 严禁(踩过两次了)
+
+- ❌ **用 AskUserQuestion 工具**(4 选项限制 + label 反查不可靠,会让用户选了 voice 你跑 clone)
+- ❌ **用户选了 1-4,你设 VOICE=空走 clone** — 跟选择不一致就是 bug
+- ❌ **不列全 5 个选项**(比如只列"用 voice / 原声"二选一,等同不让选)
+- ❌ **不告诉用户怎么回复**(必须明确说"回复数字或名字")
+
 ### Step 1:HeyGen 翻译(用现成 CLI)
 
 ```bash
@@ -62,6 +118,7 @@ gen video-translate \
   --lang "$LANG" \
   --mode fast \
   --dynamic-duration \
+  ${VOICE:+--voice "$VOICE"} \
   -o "$RAW_DIR" \
   > "$WORK/gen.json"
 ```
@@ -70,14 +127,14 @@ gen video-translate \
 
 幂等:`$WORK/gen.json` 存在则跳。
 
-提取 v3 输出字段(jq null check —— gen 后端契约改名时早 fail):
+**⚠ 提取字段必须用 `.data.` 前缀**:gen-cli 的 `outputSuccess` 把所有字段包装在 `{success: true, data: {...}}` 结构里。**不带 `.data.` 永远读不到字段,SKILL 会卡死**:
 
 ```bash
-## v3 API 返回 audio_url + caption_url + video_url 分开;我们只要 audio + caption
-AUDIO_URL=$(jq -r '.audio_url // empty' "$WORK/gen.json")
-CAP_URL=$(jq -r '.caption_url // empty' "$WORK/gen.json")
+## gen-cli 输出格式: {"success": true, "data": {"task_id": "...", "audio_url": "...", "caption_url": "..."}}
+AUDIO_URL=$(jq -r '.data.audio_url // empty' "$WORK/gen.json")
+CAP_URL=$(jq -r '.data.caption_url // empty' "$WORK/gen.json")
 [ -n "$AUDIO_URL" ] && [ -n "$CAP_URL" ] || {
-  echo "ERR: gen.json 缺 .audio_url 或 .caption_url 字段(需 gen v3 adapter)。看原始 response:"
+  echo "ERR: gen.json 缺 .data.audio_url 或 .data.caption_url 字段。原始 response:"
   cat "$WORK/gen.json"
   exit 1
 }
@@ -132,6 +189,14 @@ video-translate mux \
 - `--raw` = HeyGen v3 译音(audio_url 下载的 wav)
 - 字幕烧 + BGM ducking 走 mux 内置
 
+**BGM + 花体字幕样式 = 默认产出的一部分,不是可选项。** 不要问用户"要不要加",不要在结尾说"如需 BGM/字幕样式可补充"。`video-translate mux` 默认就用 `bgm/default.mp3` + Path-B 描边样式;`render-ass --lang $TAG` 默认按语言选字体(Bangers / Sarabun / Noto Sans)。不要绕过 `mux` 自己手写 ffmpeg(会丢 BGM + 字幕样式 + 音轨规范化)。
+
+如果 `mux` 真的失败,先把完整 stderr 给用户看(不要默默用 `ffmpeg -i ... -c copy` 兜底出"裸版"),让用户决定下一步。
+
+## 出片汇报口径
+
+只描述事实("xxx_th.mp4 翻译完成,泰语花体字幕 + BGM ducking 已烧录")。**禁止**任何形式的"如需 X 可以告诉我"尾巴 — BGM 和字幕样式不是可选 add-on,这种话术暗示没做。
+
 ### Step 4(可选):清理
 
 ```bash
@@ -139,6 +204,170 @@ video-translate mux \
 rm -rf "$WORK"
 ```
 
+---
+
+## 批量模式(多语种,一段视频翻多语)
+
+**触发条件**:用户一次请求 ≥2 种目标语言("翻译成英/泰/越/马 4 国语")。
+
+**不要按单语流程循环跑 N 次**——会有两个致命问题:
+1. wall time = N × 单次 (~12min/lang × 4 = 48min)
+2. chat bash 队列被 N 条阻塞命令塞满,后续命令(mux/SFX)全卡"准备中"
+
+改用 **单条 bash 内 N 路 subshell 并发**:chat 队列只占 1 slot,HeyGen 服务端并行处理,wall time ≈ 单次最慢 (~12min)。
+
+### Step B0:URL 预处理 + workspace + 音量预检 + 源视频下载(只跑一次)
+
+```bash
+## ⚠ URL 预处理:同单语 Step 0,本地路径必须先上传拿 https URL
+if [[ ! "$URL" =~ ^https?:// ]]; then
+  TOKEN=$(jq -r '.access_token' ~/.optima/token.json)
+  SIGNED=$(curl -sS -X POST "https://shell.optima.onl/api/files/sign" \
+    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    -d "{\"path\":\"$URL\"}" 2>&1 | jq -r '.data.url // .url // empty' 2>/dev/null)
+  if [ -z "$SIGNED" ]; then
+    echo "ERR: 拿不到 signed URL for '$URL'"; exit 1
+  fi
+  URL="$SIGNED"
+fi
+
+NAME="${NAME:-$(echo "$URL" | cut -d'?' -f1 | xargs basename | sed 's/\.[^.]*$//' | sed 's/[^A-Za-z0-9_-]/_/g')}"
+mkdir -p "./videos/${NAME}.batch"
+
+## 音量预检(同单语 Step 0)
+ffmpeg -i "$URL" -af volumedetect -f null - 2>&1 | grep mean_volume
+
+## 源视频下载一次,所有 mux 共用(避免 N 次重复下载)
+ORIG_VIDEO="./videos/${NAME}.batch/orig.mp4"
+[ -f "$ORIG_VIDEO" ] || curl -sSL "$URL" -o "$ORIG_VIDEO"
+```
+
+### Step B0.5:voice 选一次,所有语种共用
+
+同单语 Step 0.5。`VOICE` 变量设一次后下方循环里所有 subshell 都继承,**所有语种用同一个 voice 出片**(用户只需挑一次)。
+
+### Step B1:并发派出所有 HeyGen 翻译(后台跑,~5 秒返回)
+
+```bash
+## 用户实际要的语种,从下面 4 个里选(不要的注释掉)
+LANG_LIST=(
+  "English:en"
+  "Thai (Thailand):th"
+  "Malay (Malaysia):ms"
+  "Vietnamese (Vietnam):vi"
+)
+
+for entry in "${LANG_LIST[@]}"; do
+  LANG="${entry%:*}"
+  TAG="${entry##*:}"
+  WORK="./videos/${NAME}_${TAG}.work"
+  mkdir -p "$WORK/raw"
+
+  ## 后台启动 gen video-translate,各自写 gen.json,bash 立即继续
+  nohup gen video-translate \
+    --video-url "$URL" --lang "$LANG" \
+    --mode fast --dynamic-duration \
+    ${VOICE:+--voice "$VOICE"} \
+    -o "$WORK/raw" > "$WORK/gen.json" 2>&1 &
+
+  echo "$TAG: launched (PID $!) -> $WORK/gen.json"
+done
+echo "=== all submitted, returning immediately ==="
+```
+
+这一步 5 秒返回。**关键**:用 `nohup ... &` 后台启动,bash exit 后进程继续(尽量 survive 短暂 idle / 容器升级)。每个进程会在 HeyGen 翻译完成后把 audio_url/caption_url 写入对应的 gen.json。
+
+### Step B2-B5:逐语种等结果 → 出片(每个一条独立 bash)
+
+**重点:每个语种用单独的 bash 命令处理,不要再用 `&` 并发**。这样:
+- chat 看到每个语种独立完成、独立报告
+- 第 1 个 bash 等 HeyGen(~12 min),后续每个 bash 几乎瞬间完成(因为 4 个翻译是并行跑的,后续几个早已 done)
+- 失败隔离:1 个失败不影响其他
+
+通用 per-lang 模板(把 `$TAG` 换成 en / th / ms / vi 各跑一遍):
+
+```bash
+TAG=en                                   ## ← 换语种就改这个
+WORK="./videos/${NAME}_${TAG}.work"
+FINAL="./videos/${NAME}_${TAG}.mp4"
+
+## 等 gen.json 写完(或失败)
+## ⚠ gen-cli 用 outputSuccess 包装在 {success, data: {...}} 里,字段在 .data.* 下
+DEADLINE=$(( $(date +%s) + 1800 ))     ## 30min 上限,跟 HeyGen poll timeout 对齐
+while true; do
+  ## Case 1: 成功 → .data.audio_url 非 null
+  if jq -e '.data.audio_url' "$WORK/gen.json" >/dev/null 2>&1; then
+    break
+  fi
+  ## Case 2: 业务失败 → .data.error_message(outputSuccess with status=failed)
+  if jq -e '.data.error_message' "$WORK/gen.json" >/dev/null 2>&1; then
+    echo "[$TAG] FAIL: $(jq -r '.data.error_message' "$WORK/gen.json")"
+    exit 1
+  fi
+  ## Case 3: CLI 异常 → .error.code/.error.message(outputError 抛出)
+  if jq -e '.error' "$WORK/gen.json" >/dev/null 2>&1; then
+    echo "[$TAG] FAIL: $(jq -r '.error.code + \": \" + .error.message' "$WORK/gen.json")"
+    exit 1
+  fi
+  ## Case 4: 30min 超时(HeyGen 一般 5-15min,30min 还没就是真挂了)
+  if [ "$(date +%s)" -gt "$DEADLINE" ]; then
+    echo "[$TAG] TIMEOUT 30min,gen.json 内容:"; cat "$WORK/gen.json"; exit 1
+  fi
+  sleep 15
+done
+
+## 拿到 audio_url + caption_url(必须带 .data. 前缀)
+AUDIO_URL=$(jq -r '.data.audio_url' "$WORK/gen.json")
+CAP_URL=$(jq -r '.data.caption_url' "$WORK/gen.json")
+
+## 下载 + render-ass
+curl -sSL --retry 1 "$AUDIO_URL" -o "$WORK/translated_audio.wav"
+curl -sSL --retry 1 "$CAP_URL"   -o "$WORK/caption.srt"
+video-translate render-ass \
+  --srt "$WORK/caption.srt" --lang "$TAG" \
+  --translations "$WORK/translations.json" \
+  --out "$WORK/subs.ass"
+
+## mux 出片
+video-translate mux \
+  --raw "$WORK/translated_audio.wav" \
+  --orig-video "$ORIG_VIDEO" \
+  --ass "$WORK/subs.ass" \
+  ${BGM:+--bgm "$BGM"} ${NO_BGM:+--no-bgm} \
+  --work "$WORK" \
+  --out "$FINAL"
+
+echo "[$TAG] DONE -> $FINAL"
+```
+
+**Agent 执行节奏**:
+1. 跑 Step B1(1 条 bash,5 秒返回,**立刻告知用户"4 个翻译派出去了"**)
+2. 跑 per-lang 模板 `TAG=en`(1 条 bash,~12 min,出片后**立刻告知用户"English 出片 ✓"**)
+3. 跑 per-lang 模板 `TAG=th`(1 条 bash,~30 秒,出片后**立刻告知用户"Thai 出片 ✓"**)
+4. 跑 per-lang 模板 `TAG=ms`(~30 秒)
+5. 跑 per-lang 模板 `TAG=vi`(~30 秒)
+
+**总 wall time 不变(~13 min)**,但用户每 30 秒看到一个出片,不是 12 min 黑盒后突然 4 个一起出。
+
+输出:`./videos/${NAME}_en.mp4` / `_th.mp4` / `_ms.mp4` / `_vi.mp4`
+
+### 单语 vs 渐进批量对比
+
+| | 单语循环(❌ 不要) | 渐进批量(✓) |
+|---|---|---|
+| 源视频下载 | N 次重下 | 1 次共用 |
+| HeyGen 调用 | 串行 N × 12min | 并发 max(12min) |
+| chat 队列占 | N 条阻塞 bash | 1 条 submit + N 条快速 poll |
+| 失败隔离 | 一个挂全停 | per-lang subshell + bash 独立 |
+| 用户感知 | 黑盒 48 min | 第 1 个 ~12 min 出,后续每 ~30 秒 1 个 |
+| **wall time(N=4)** | **~48 min** | **~13 min(73%↓)** |
+
+### 失败处理
+
+- 单 lang 失败:per-lang bash `exit 1`,agent 报告该语种失败但**继续跑下一个语种的 bash**
+- 用户对失败的单 lang re-run → 删 `$WORK/gen.json` 重跑 Step B1 单语 + per-lang 模板即可
+- HeyGen credit 不足报错 → 当 lang 个失败处理,不阻塞其他 lang
+
 ## 错误处理
 
 | 失败 | 处理 |
@@ -148,15 +377,14 @@ rm -rf "$WORK"
 | HeyGen `status: failed` "No speaker is detected" | 同源视频音量过低处理 |
 | HeyGen 其他失败 | 透出 task_id,提示用 `gen task get <id>` 查最新;干净退出 |
 | HeyGen >30min 超时 | 同上,可能任务还在 running |
-| `gen.json` 缺 `.output` / `.caption_url` | gen 后端契约可能改字段名。打 `cat $WORK/gen.json` 看实际字段 |
+| `gen.json` 缺 `.audio_url` / `.caption_url` | gen 后端契约可能改字段名。打 `cat $WORK/gen.json` 看实际字段 |
 | `curl <caption_url>` 失败 | URL 7 天 expire。retry 1 次后仍失败 → 重跑 step 1 |
 | `video-translate render-ass` SRT 解析失败 | 显示 SRT 头 20 行,不重试 |
 | `video-translate mux` 字体 ☐ | 检查 `fc-match Bangers / Sarabun / "Noto Sans"` 是否精确返回 |
 
 ## 不做
 
-- ❌ 音色覆盖(voice override)— v1 默认 HeyGen 自动克隆;v2 再考虑"用户问起时 LLM 给候选 + preview URL"流程
-- ❌ 性别自动检测 — 同上 defer v2
+- ❌ 性别自动检测(让用户自己选,见 Step 0.5)
 - ❌ 硬字幕(burnt-in)抹除 — 源视频有的话出片会双语
 - ❌ 自动加粗关键词 — SRT 直入无粉色,用户手编 translations.json
 - ❌ 双说话人差异化音色 — HeyGen 自动 diarize 但用同一克隆音色
@@ -166,3 +394,18 @@ rm -rf "$WORK"
 
 - 设计 SPEC:https://github.com/Optima-Chat/video-translate/blob/main/SPEC.md (v3.1)
 - 实测踩坑(gotchas):同上 §Gotchas
+
+---
+
+## Voice Catalog
+
+下面 4 个 voice 全部是 HeyGen catalog 里走 **ElevenLabs `eleven_multilingual_v2`** 模型的多语 voice,**任选一个,所有支持语言(en/th/ms/vi)都能说**。实测 Connie 跨 4 语全部 Whisper 95%+ 语种识别置信度,音色保留 + 自动适配目标语言性别敬语(如泰语 ค่ะ/ครับ)。
+
+| # | voice_id | 名字 | 性别 | 风格定位 | preview(英文样本) |
+|---|---|---|---|---|---|
+| 1 | `d774d69075f24d1fb52a0dad145ba809` | Connie - Professional | F | 沉稳专业旁白 | https://resource.heygen.ai/text_to_speech/locale=en-USmodel=eleven_multilingual_v2id=9FnNGNtwCeU9fyf6mFfDp8.mp3 |
+| 2 | `vakjM0uzzAxU4UiT0433`             | Sophie                | F | 温柔友好     | https://resource.heygen.ai/text_to_speech/locale=model=eleven_multilingual_v2id=kte4EzDuRTnsnHkATe6tDK.mp3 |
+| 3 | `1LtsDD7yfTuX92TzjmJk`             | Bruce                 | M | 中年浑厚     | https://resource.heygen.ai/text_to_speech/locale=model=eleven_multilingual_v2id=2SdnapPUN7wvtCbkPSgdHV.mp3 |
+| 4 | `6HiVdeiuBdZbtcnukrQn`             | Luca                  | M | 年轻活力     | https://resource.heygen.ai/text_to_speech/locale=model=eleven_multilingual_v2id=FVKYscu8J8EVReBuZdPXnJ.mp3 |
+
+> 维护说明:换 voice 时,从 `GET /v2/voices` 里筛 `preview_audio` 含 `multilingual` 的 EL 系列。其它非 EL 系列的"English"标签 voice **大概率**不能跨语言,要实测验证。

package/dist/commands/video.d.ts

@@ -1,3 +1,22 @@
 import { Command } from 'commander';
 export declare function registerVideoCommand(program: Command): void;
+export declare function hasFfmpegBinary(name: 'ffmpeg' | 'ffprobe'): boolean;
+export declare function runFfmpegCopy(concatListPath: string, outputPath: string): {
+    ok: boolean;
+    stderr: string;
+};
+export declare function runFfmpegReencode(concatListPath: string, outputPath: string): {
+    ok: boolean;
+    stderr: string;
+};
+export declare function ffprobeDuration(filePath: string): number;
+/**
+ * 3 层 failed_input 探测(SPEC 决策 #9):
+ * 1) ffmpeg stderr 含 input 路径字面 → 再 ffprobe verify 一次,验证 fail 才返回
+ *    (P2-2 修正:ffmpeg `Input #N` 默认会把所有 input 名字打 stderr,
+ *    Layer 1 命中不等于该 input 真坏;必须 ffprobe verify 避免 false positive)
+ * 2) 否则 ffprobe scan 全部 input,首个 exit≠0 = failed_input
+ * 3) 都 ffprobe OK 但 concat 仍失败 → null (codec mismatch,非单个 input 问题)
+ */
+export declare function detectFailedInput(stderr: string, inputs: string[]): string | null;
 //# sourceMappingURL=video.d.ts.map

package/dist/commands/video.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../../src/commands/video.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAkB5C,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAuQpD"}
+{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../../src/commands/video.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAmB5C,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA0QpD;AA6OD,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAGnE;AAED,wBAAgB,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAOzG;AAED,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAsB7G;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYxD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAsBjF"}

package/dist/commands/video.js

@@ -1,6 +1,7 @@
 import { Option } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
+import { execFileSync, spawnSync } from 'child_process';
 import ora from 'ora';
 import { success, info } from '../utils/logger.js';
 import { outputSuccess, outputError, isPrettyMode } from '../utils/output.js';
@@ -257,6 +258,7 @@ export function registerVideoCommand(program) {
         relatedCommands: [
             { command: 'task get <id>', description: '查看任务状态' },
             { command: 'image <prompt>', description: '生成图像' },
+            { command: 'video stitch', description: '拼接多段 mp4（ffmpeg concat）' },
         ],
         notes: [
             '默认 dashscope（仅图生视频，需要输入图像；自动配音默认开启）',
@@ -266,5 +268,277 @@ export function registerVideoCommand(program) {
             '视频生成需要 1-5 分钟',
         ],
     });
+    registerVideoStitch(cmd);
+}
+/**
+ * `gen video stitch` —— 多段 mp4 拼接 (ffmpeg concat) primitive.
+ *
+ * 实施 SPEC: docs/superpowers/specs/2026-05-16-gen-video-stitch-primitive.md (optima-agent)
+ *
+ * 关键设计:
+ * - Mode A (--workspace-dir): glob <dir>/segments/seg-*.mp4 按文件名 lexical sort
+ * - Mode B (--inputs): 显式 mp4 列表,用户给的顺序
+ * - --codec auto (默认): 试 -c copy → fail 回退 libx264+aac
+ * - 失败 failed_input 探测 3 层: stderr parse → ffprobe scan → null + codec mismatch
+ * - concat list 用固定路径 <workspace>/.stitch-concat.txt,不用 mktemp
+ *
+ * 返回 JSON (成功): { output_path, duration_sec, concat_mode, input_count }
+ * 返回 JSON (失败): { error: { code, message, failed_input } }
+ */
+function registerVideoStitch(parent) {
+    const cmd = parent
+        .command('stitch')
+        .description('拼接多段 mp4 为单个视频（ffmpeg concat）')
+        .option('--workspace-dir <dir>', 'Mode A: 扫描 <dir>/segments/seg-*.mp4 按文件名排序')
+        .option('--inputs <inputs...>', 'Mode B: 显式 mp4 列表 (顺序 = concat 顺序)')
+        // -o 短 flag 跟父命令 gen video -o <dir> 冲突 (commander 限制),subcommand 用长 flag --out
+        // SPEC §4.1 用 -o 是设计期写法,实施时改 --out 不影响契约 (wrapper 调时跟 SPEC 实施版本一致即可)
+        .requiredOption('--out <path>', '输出 mp4 路径')
+        .addOption(new Option('--codec <mode>', 'codec 模式: auto 试 copy 失败回退 reencode')
+        .choices(['auto', 'copy', 'reencode'])
+        .default('auto'))
+        .action(async (options) => {
+        const pretty = isPrettyMode(options);
+        try {
+            // P2-3: ffmpeg / ffprobe PATH 预检
+            if (!hasFfmpegBinary('ffmpeg')) {
+                outputError('STITCH_FFMPEG_NOT_FOUND', '未找到 ffmpeg 命令。请先安装 ffmpeg (https://ffmpeg.org/) 并加入 PATH', options);
+                return;
+            }
+            if (!hasFfmpegBinary('ffprobe')) {
+                outputError('STITCH_FFPROBE_NOT_FOUND', '未找到 ffprobe 命令 (ffmpeg 套件)。请确认 ffmpeg 完整安装并加入 PATH', options);
+                return;
+            }
+            // Mode A vs Mode B 互斥校验
+            const hasWorkspace = !!options.workspaceDir;
+            const hasInputs = Array.isArray(options.inputs) && options.inputs.length > 0;
+            if (hasWorkspace && hasInputs) {
+                outputError('STITCH_USAGE_ERROR', '--workspace-dir 和 --inputs 二选一,不能同时传', options);
+                return;
+            }
+            if (!hasWorkspace && !hasInputs) {
+                outputError('STITCH_USAGE_ERROR', '必须传 --workspace-dir <dir> 或 --inputs <p1> <p2> ...', options);
+                return;
+            }
+            // --codec 校验由 commander .choices() 处理,这里直接读 (无效值 commander 已 reject)
+            const codec = options.codec;
+            // 解析 inputs (Mode A glob 或 Mode B 直接用)
+            let inputs;
+            if (hasWorkspace) {
+                const segmentsDir = path.join(path.resolve(options.workspaceDir), 'segments');
+                if (!fs.existsSync(segmentsDir)) {
+                    outputError('STITCH_FAILED', `segments 目录不存在: ${segmentsDir}`, options);
+                    return;
+                }
+                inputs = fs
+                    .readdirSync(segmentsDir)
+                    .filter((f) => /^seg-\d+\.mp4$/.test(f))
+                    // natural sort: 不依赖填充宽度,seg-2 < seg-10 < seg-100 都对
+                    // (lexical sort 在混 1/2/3 位时会错乱:seg-1 < seg-10 < seg-100 < seg-2)
+                    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+                    .map((f) => path.join(segmentsDir, f));
+            }
+            else {
+                inputs = options.inputs.map((p) => path.resolve(p));
+            }
+            if (inputs.length === 0) {
+                outputError('STITCH_FAILED', 'inputs 为空,没有 mp4 可拼接', options);
+                return;
+            }
+            // 验证 inputs 存在
+            for (const input of inputs) {
+                if (!fs.existsSync(input)) {
+                    outputError('STITCH_FAILED', `input 文件不存在: ${input}`, options, { failed_input: input });
+                    return;
+                }
+            }
+            const outputPath = path.resolve(options.out);
+            // concat list 临时文件位置 (SPEC 决策 #11):
+            // - Mode A: <workspace>/.stitch-concat.txt
+            // - Mode B 无 workspace 概念,落 output dir 同卷,避免跨 fs 问题
+            // - 假设单作业,并发场景需各自 workspace 或换 mktemp (本 v1 不做)
+            const concatListPath = path.join(hasWorkspace ? path.resolve(options.workspaceDir) : path.dirname(outputPath), '.stitch-concat.txt');
+            const spinner = pretty ? ora(`拼接 ${inputs.length} 段 mp4...`).start() : null;
+            // 生成 concat list (ffmpeg concat demuxer 格式)
+            const concatContent = inputs.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join('\n') + '\n';
+            fs.writeFileSync(concatListPath, concatContent);
+            try {
+                // 执行 ffmpeg,根据 --codec 决定路径
+                let concatMode;
+                let ffmpegError = null;
+                if (codec === 'copy') {
+                    // 只试 copy,失败直接报错
+                    const r = runFfmpegCopy(concatListPath, outputPath);
+                    if (r.ok) {
+                        concatMode = 'copy';
+                    }
+                    else {
+                        ffmpegError = r.stderr;
+                        concatMode = 'copy'; // 标记,但下面会进 error path
+                    }
+                }
+                else if (codec === 'reencode') {
+                    // 直接 reencode,跳过 copy 试探
+                    const r = runFfmpegReencode(concatListPath, outputPath);
+                    if (r.ok) {
+                        concatMode = 'reencode';
+                    }
+                    else {
+                        ffmpegError = r.stderr;
+                        concatMode = 'reencode';
+                    }
+                }
+                else {
+                    // auto: 试 copy → fail 回退 reencode
+                    const r1 = runFfmpegCopy(concatListPath, outputPath);
+                    if (r1.ok) {
+                        concatMode = 'copy';
+                    }
+                    else {
+                        const r2 = runFfmpegReencode(concatListPath, outputPath);
+                        if (r2.ok) {
+                            concatMode = 'reencode';
+                        }
+                        else {
+                            ffmpegError = r2.stderr;
+                            concatMode = 'reencode';
+                        }
+                    }
+                }
+                if (ffmpegError) {
+                    // 3 层 failed_input 探测
+                    const failedInput = detectFailedInput(ffmpegError, inputs);
+                    if (pretty)
+                        spinner.fail('ffmpeg concat 失败');
+                    outputError('STITCH_FAILED', failedInput
+                        ? `ffmpeg concat 失败 (failing input: ${failedInput})`
+                        : 'ffmpeg concat 失败:所有 input 单独 ffprobe OK,但 concat 失败 (likely codec mismatch)', options, { failed_input: failedInput });
+                    return;
+                }
+                // 成功:ffprobe 取 duration
+                const duration = ffprobeDuration(outputPath);
+                if (pretty) {
+                    spinner.succeed(`拼接完成 (${concatMode}): ${outputPath} [${duration.toFixed(2)}s, ${inputs.length} 段]`);
+                }
+                else {
+                    outputSuccess({
+                        output_path: outputPath,
+                        duration_sec: duration,
+                        concat_mode: concatMode,
+                        input_count: inputs.length,
+                    });
+                }
+            }
+            finally {
+                // 清理临时 concat list
+                if (fs.existsSync(concatListPath)) {
+                    try {
+                        fs.unlinkSync(concatListPath);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+        }
+        catch (err) {
+            outputError('STITCH_FAILED', `拼接过程异常: ${err}`, options);
+        }
+    });
+    addEnhancedHelp(cmd, {
+        examples: [
+            '# Mode A: 自动扫描 workspace segments/',
+            '$ gen video stitch --workspace-dir ~/digital-human/videos/20260516-1430 --out final.mp4',
+            '# Mode B: 显式列 mp4 (任意顺序)',
+            '$ gen video stitch --inputs intro.mp4 seg-1.mp4 seg-2.mp4 outro.mp4 --out final.mp4',
+            '# 强制重编码 (保证 codec 兼容)',
+            '$ gen video stitch --workspace-dir . --out final.mp4 --codec reencode',
+        ],
+        outputJson: `{
+  "success": true,
+  "data": {
+    "output_path": "/abs/path/final.mp4",
+    "duration_sec": 87.3,
+    "concat_mode": "copy",
+    "input_count": 4
+  }
+}`,
+        relatedCommands: [
+            { command: 'video', description: '生成单段视频' },
+        ],
+        notes: [
+            'Mode A / Mode B 二选一,不能同时传',
+            '--codec auto (默认): 试 -c copy → fail 回退 libx264+aac,JSON 返回实际 concat_mode',
+            '失败时 failed_input 字段指出 broken mp4 (若可定位)',
+            'concat list 临时文件用完即删,无残留',
+        ],
+    });
+}
+// ===== Helpers (exported for unit tests) =====
+export function hasFfmpegBinary(name) {
+    const r = spawnSync(name, ['-version'], { encoding: 'utf-8' });
+    return r.status === 0;
+}
+export function runFfmpegCopy(concatListPath, outputPath) {
+    const r = spawnSync('ffmpeg', ['-y', '-f', 'concat', '-safe', '0', '-i', concatListPath, '-c', 'copy', outputPath], { encoding: 'utf-8' });
+    return { ok: r.status === 0, stderr: r.stderr || '' };
+}
+export function runFfmpegReencode(concatListPath, outputPath) {
+    const r = spawnSync('ffmpeg', [
+        '-y',
+        '-f',
+        'concat',
+        '-safe',
+        '0',
+        '-i',
+        concatListPath,
+        '-c:v',
+        'libx264',
+        '-preset',
+        'fast',
+        '-c:a',
+        'aac',
+        outputPath,
+    ], { encoding: 'utf-8' });
+    return { ok: r.status === 0, stderr: r.stderr || '' };
+}
+export function ffprobeDuration(filePath) {
+    try {
+        const out = execFileSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', filePath], { encoding: 'utf-8' });
+        const d = parseFloat(out.trim());
+        return Number.isFinite(d) ? d : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * 3 层 failed_input 探测(SPEC 决策 #9):
+ * 1) ffmpeg stderr 含 input 路径字面 → 再 ffprobe verify 一次,验证 fail 才返回
+ *    (P2-2 修正:ffmpeg `Input #N` 默认会把所有 input 名字打 stderr,
+ *    Layer 1 命中不等于该 input 真坏;必须 ffprobe verify 避免 false positive)
+ * 2) 否则 ffprobe scan 全部 input,首个 exit≠0 = failed_input
+ * 3) 都 ffprobe OK 但 concat 仍失败 → null (codec mismatch,非单个 input 问题)
+ */
+export function detectFailedInput(stderr, inputs) {
+    // Layer 1: stderr 含具体 input 路径 + ffprobe 验证
+    for (const input of inputs) {
+        if (stderr.includes(input) || stderr.includes(path.basename(input))) {
+            const r = spawnSync('ffprobe', ['-v', 'error', input], { encoding: 'utf-8' });
+            if (r.status !== 0 || (r.stderr && r.stderr.trim() !== '')) {
+                return input; // 验证确认坏
+            }
+            // stderr 提了 input 但 ffprobe OK → 可能只是 Input #N 标识,降级 Layer 2
+        }
+    }
+    // Layer 2: ffprobe scan 每个 input
+    for (const input of inputs) {
+        const r = spawnSync('ffprobe', ['-v', 'error', input], { encoding: 'utf-8' });
+        if (r.status !== 0 || (r.stderr && r.stderr.trim() !== '')) {
+            return input;
+        }
+    }
+    // Layer 3: 都 OK 但 concat fail → 不是单个 input 问题
+    return null;
 }
 //# sourceMappingURL=video.js.map