@optima-chat/gen-cli 2.3.0 → 2.4.0

package/.claude/skills/digital-human/references/train.md

@@ -2,11 +2,14 @@
 
 按顺序执行,每步必走。把用户上传的真人视频训成数字分身(voice + avatar),写入 `~/digital-human/avatars.md`。
 
+> ⚠️ **沙箱 bash 须知**(同 [generate.md §0](generate.md) / [SKILL.md Global Rule #7](../SKILL.md)):agent-runtime 的 bash **软拒绝** `$( )` 命令替换、`for`/`while` 循环、命令内换行(含 `\` 续行)、`;`/`&&`/`||` 串多条、`> file`/`>>`/heredoc(`<<EOF`)重定向、`| jq`/`| sed`/`| grep` 管道、`nohup &`。所以本文档:**取值靠 LLM 自己读单条命令的 stdout JSON**(不 `$()`/`jq`)、**写文件用 Write/Edit tool**(不 heredoc / `echo >`)、**轮询用单条命令逐次跑**(不 `while`)、**所有 id / 路径内联进命令**(不存 `$VAR`)。
+
 ## 0. 工作空间初始化(首次训练)
 
 ```bash
-mkdir -p ~/digital-human/{training,videos}
+mkdir -p ~/digital-human/training ~/digital-human/videos
 ```
+(`mkdir -p` 接受多个路径参数,一条命令建两个目录,不用 `{a,b}` brace 展开。)
 
 如 `~/digital-human/avatars.md` 不存在,**创建**含 SKILL.md 模板的空表(见 SKILL.md "工作空间"段)。
 
@@ -26,20 +29,13 @@ LLM 主动问:
 
 **重名处理**:
 - 反问"你已经有'张医生'了,起个别的(例如'张医生2'/'张主任')"
-- **不**提供"覆盖"选项(v1 不支持,见 [workspace SPEC §6 #6](https://github.com/Optima-Chat/optima-agent/blob/main/docs/superpowers/specs/2026-05-14-digital-human-workspace-naming.md))
+- **不**提供"覆盖"选项(v1 不支持,见 [workspace SPEC §6 #6](../../../../docs/superpowers/specs/2026-05-14-digital-human-workspace-naming.md))
 
 ## 2. 内部生成 external_id
 
-**由 LLM 在本地生成**,不依赖后端兜底:
-
-```bash
-EXTERNAL_ID="dh-$(openssl rand -hex 5 | base32 | tr 'A-Z' 'a-z' | tr -d '=' | head -c 8)"
-# 例: "dh-a7f2k9m1"
-# 注: 全大写,跨段(§4.5 / §5 / §6 / §6.5)统一用 $EXTERNAL_ID 引用,
-#     bash 大小写敏感,混用会取到空值导致路径错误
-```
+**由 LLM 自己生成**(你直接想一个,**别用 `$(openssl ...)`/管道**——沙箱拦):格式 `dh-` + 8 位随机小写字母数字(例 `dh-a7f2k9m1`)。生成后**记住这个值**,跨段(§4.5 / §5 / §6 / §6.5 / §8 / §9)在每条命令里**直接写全**,不存 `$EXTERNAL_ID` 变量(沙箱里没法安全赋值,且大小写混用会取空值导致路径错误)。
 
-**碰撞处理**(8 字节 base32 ≈ 64 bit 熵,碰撞概率低但非零,后端 `external_id` 有 UNIQUE 约束 `migrate.ts:44`):
+**碰撞处理**(随机 8 位,碰撞概率低但非零,后端 `external_id` 有 UNIQUE 约束 `migrate.ts:44`):
 - onboard insert 失败且 error_code 表明唯一冲突 → 重新生成 + 重试
 - **最多重试 3 次**,3 次失败 → 报错给用户
 
@@ -88,11 +84,13 @@ spec §13.4 关键约束:训练系统会把整段视频画面(包含背景)整
 
 ## 4.5 归档源视频(必须在 §5 拆音频之前)
 
-把用户上传的视频复制到 workspace,后续步骤全部从复制好的副本走:
+把用户上传的视频复制到 workspace,后续步骤全部从复制好的副本走(把 `<external_id>` 换成 §2 你生成的那个 id,**写全**,别用 `$EXTERNAL_ID`)。两条单命令:
 
 ```bash
-mkdir -p ~/digital-human/training/$EXTERNAL_ID
-cp "<用户上传的视频路径>" ~/digital-human/training/$EXTERNAL_ID/source-video.mp4
+mkdir -p ~/digital-human/training/dh-a7f2k9m1
+```
+```bash
+cp "<用户上传的视频路径>" ~/digital-human/training/dh-a7f2k9m1/source-video.mp4
 ```
 
 **为什么必须先复制**:
@@ -109,25 +107,23 @@ cp "<用户上传的视频路径>" ~/digital-human/training/$EXTERNAL_ID/source-
 
 ## 5. 提音频(从复制好的 source-video.mp4)
 
-`gen avatar onboard` 接受 `<audio-file> <video-file>` 两个文件参数。从 §4.5 复制好的 `source-video.mp4` 提音频(**不再从用户原始路径提**,因为原始路径可能中途消失):
+`gen avatar onboard` 接受 `<audio-file> <video-file>` 两个文件参数。从 §4.5 复制好的 `source-video.mp4` 提音频(**不再从用户原始路径提**,因为原始路径可能中途消失)。**一条命令、路径写全、不换行**(`\` 续行沙箱拦):
 
 ```bash
-AUDIO_PATH=~/digital-human/training/$EXTERNAL_ID/source-audio.wav
-ffmpeg -i ~/digital-human/training/$EXTERNAL_ID/source-video.mp4 \
-  -vn -acodec pcm_s16le -ar 44100 -ac 1 -t 90 "$AUDIO_PATH"
+ffmpeg -i ~/digital-human/training/dh-a7f2k9m1/source-video.mp4 -vn -acodec pcm_s16le -ar 44100 -ac 1 -t 90 ~/digital-human/training/dh-a7f2k9m1/source-audio.wav
 ```
 
 取前 90 秒单声道 WAV,够 voice clone。路径固定 = `training/<external_id>/source-audio.wav`,不用 `mktemp`(单分身一个 audio,无并发覆盖问题)。
 
 ## 6. 触发训练(onboard)
 
+**一条命令、路径 + id 写全、不换行**(`\` 续行沙箱拦;`--clean-bg` / `--accept-baked-bg` 按 §4 决策二选一,不能省):
+
 ```bash
-gen avatar onboard "$AUDIO_PATH" ~/digital-human/training/$EXTERNAL_ID/source-video.mp4 \
-  --external-id "$EXTERNAL_ID" \
-  --clean-bg          # 或 --accept-baked-bg(二选一,不能省)
+gen avatar onboard ~/digital-human/training/dh-a7f2k9m1/source-audio.wav ~/digital-human/training/dh-a7f2k9m1/source-video.mp4 --external-id dh-a7f2k9m1 --clean-bg
 ```
 
-> **不要传 `--display-name`** — 后端 CLI [`doctor.ts:36`](file:///C:/Users/zy/optima-gen/packages/cli/src/commands/doctor.ts) 不支持这个 flag,commander 会拒绝未知选项报错。display_name 唯一存在于 `~/digital-human/avatars.md`,backend 完全不感知。
+> **不要传 `--display-name`** — 后端 CLI [`doctor.ts:36`](packages/cli/src/commands/doctor.ts) 不支持这个 flag,commander 会拒绝未知选项报错。display_name 唯一存在于 `~/digital-human/avatars.md`,backend 完全不感知。
 
 返回 JSON:
 ```json
@@ -138,55 +134,48 @@ gen avatar onboard "$AUDIO_PATH" ~/digital-human/training/$EXTERNAL_ID/source-vi
 
 ## 6.5 写 train-meta.md(归档训练元数据)
 
-onboard 提交成功后,写训练元数据到 workspace:
+onboard 提交成功后,从它 stdout 的 JSON 里读 `voice_task_id` / `avatar_task_id`(自己读,别 `$()`/`jq`)。用 **Write tool** 写训练元数据到 `~/digital-human/training/<external_id>/train-meta.md`(**别用 `cat <<EOF` heredoc**——沙箱拦)。所有值(名字 / external_id / 两个 task_id / 背景决策 / 今天日期 / §3 ffprobe 的时长分辨率)你手头都有,**内联**进模板:
 
-```bash
-cat > ~/digital-human/training/$EXTERNAL_ID/train-meta.md <<EOF
-# Training: $DISPLAY_NAME (external_id: $EXTERNAL_ID)
+```markdown
+# Training: 张医生 (external_id: dh-a7f2k9m1)
 
 | 字段 | 值 |
 |---|---|
-| display_name | $DISPLAY_NAME |
-| external_id | $EXTERNAL_ID |
-| 训练时间 | $(date +%Y-%m-%d) |
-| voice_task_id | $VOICE_TASK_ID |
-| avatar_task_id | $AVATAR_TASK_ID |
-| 背景决策 | $BG_DECISION (--clean-bg / --accept-baked-bg) |
+| display_name | 张医生 |
+| external_id | dh-a7f2k9m1 |
+| 训练时间 | 2026-06-01 |
+| voice_task_id | <onboard 输出的 voice_task_id> |
+| avatar_task_id | <onboard 输出的 avatar_task_id> |
+| 背景决策 | --clean-bg(或 --accept-baked-bg) |
 | 源视频时长 | (从 §3 ffprobe 输出取) |
 | 源视频分辨率 | (同上) |
 | preview_image_url | (训完 §8 拉到后回填这一行) |
-EOF
 ```
 
+(日期用你 LLM 知道的当天真实日期,别 `$(date)`。)
+
 **为什么单独写文件**:
 - avatars.md 是分身索引(用户看 + LLM 用),只放最关键字段(名字 / external_id / 训练时间 / preview)
 - train-meta.md 是分身**完整训练记录**,含 task_ids / 背景决策 / 源视频 specs 等用户不关心但**重训时关键**的信息
 
 ## 7. Poll 直到完成
 
+**沙箱里没有 `while` 循环**——靠 LLM **逐次发单条命令**轮询(把 task_id 内联进命令,从输出 JSON 自己读 `status`,别 `$()`/`jq`)。每轮两条:
+
+```bash
+gen task get <voice_task_id>
+```
 ```bash
-# 30 min 上限(avatar train 慢边界);5s 间隔
-TIMEOUT=1800
-INTERVAL=5
-ELAPSED=0
-while [ $ELAPSED -lt $TIMEOUT ]; do
-  V_STATUS=$(gen task get $VOICE_TASK | jq -r '.status')
-  A_STATUS=$(gen task get $AVATAR_TASK | jq -r '.status')
-  echo "[t+${ELAPSED}s] voice=$V_STATUS avatar=$A_STATUS"
-
-  V_DONE=false; A_DONE=false
-  [[ "$V_STATUS" =~ ^(completed|failed)$ ]] && V_DONE=true
-  [[ "$A_STATUS" =~ ^(completed|failed)$ ]] && A_DONE=true
-  $V_DONE && $A_DONE && break
-
-  sleep $INTERVAL
-  ELAPSED=$((ELAPSED + INTERVAL))
-done
+gen task get <avatar_task_id>
 ```
 
-> **Fallback**:如果 `gen task get` 不可用,直接打后端 endpoint:
+- 读两条输出里的 `status`。两个都 `completed` → 进 §8;任一 `failed` → 看 `error_message` 处理(见下)。
+- 都还在 `pending`/`processing` → 等一会再来一轮。可选单条 `sleep 15`(**别** `sleep && gen ...` 串、别写 `while`),然后重发上面两条;或直接隔一轮再查。
+- **上限 ~30 min**(avatar train 慢边界):LLM 自己记开始时间,超时仍未完成 → 告诉用户"训练超时,稍后用'X 训好了吗'再查"(state 不丢,§profile 可续查),不要无限轮询。
+
+> **Fallback**:`gen task get` 不可用时,单条 curl 查后端(token / 域名内联,**别管道接 `| jq`**,直接看返回 JSON):
 > ```bash
-> curl -s -H "Authorization: Bearer $OPTIMA_TOKEN" "$GENERATION_API/api/task/$TASK_ID" | jq
+> curl -s -H "Authorization: Bearer <token>" "<generation-api>/api/task/<task_id>"
 > ```
 
 期望耗时:
@@ -200,10 +189,10 @@ done
 
 ## 8. 拉 profile 拿 preview
 
-两个 task 都 completed 后:
+两个 task 都 completed 后(external_id 内联):
 
 ```bash
-gen avatar profile "$EXTERNAL_ID"
+gen avatar profile dh-a7f2k9m1
 ```
 
 返回(关键字段):
@@ -222,19 +211,15 @@ gen avatar profile "$EXTERNAL_ID"
 
 **回填 `train-meta.md`**:把 §6.5 写的 train-meta.md 里 `preview_image_url` 那行补上真值(profile 拿到的 URL)。
 
-(可选)下载 preview 缓存到本地:
+(可选)下载 preview 缓存到本地(url + 路径内联,单条命令):
 ```bash
-curl -s -o ~/digital-human/training/$EXTERNAL_ID/preview.jpg "$PREVIEW_URL"
+curl -s -o ~/digital-human/training/dh-a7f2k9m1/preview.jpg "<preview_image_url>"
 ```
 加快"列我的分身"渲染速度,避免每次都打外网。
 
 ## 9. 追加一行到 `avatars.md`
 
-```bash
-TODAY=$(date +%Y-%m-%d)   # 真实日期,不凭印象
-```
-
-往 `~/digital-human/avatars.md` 末尾追加一行(用 Edit/Read 工具操作 markdown 表):
+用 **Read + Edit tool** 往 `~/digital-human/avatars.md` 末尾追加一行(别用 `echo >>`)。日期用你 LLM 知道的**当天真实日期**(别 `$(date)`,别凭印象):
 
 ```
 | <用户给的名字> | <external_id> | <TODAY> | <preview_image_url> |
@@ -282,7 +267,7 @@ TODAY=$(date +%Y-%m-%d)   # 真实日期,不凭印象
 | silent 默认 `--clean-bg`(§4) | 用户三选一 → 显式 `--clean-bg` 或 `--accept-baked-bg` | 错判脏背景为干净 → baked 进 avatar look,后续 video 永远换不掉背景(spec §13.4) |
 | 抽帧用图像识别判断背景(§4) | 直接问用户三选一 | 视觉判断不稳定 + 浪费 token + 用户答更准 |
 | 让用户起 ASCII slug 当名字(§1) | 用户起的就是友好名字,external_id 由 LLM 内部生成 | 让用户记英文 slug 反人性;workspace 文件已经隔离了 ASCII 约束 |
-| 给 `gen avatar onboard` 传 `--display-name`(§6) | 不要传,commander 会拒未知选项报错 | 后端 CLI 没这个 flag([doctor.ts:36](file:///C:/Users/zy/optima-gen/packages/cli/src/commands/doctor.ts));display_name 只在 workspace markdown |
+| 给 `gen avatar onboard` 传 `--display-name`(§6) | 不要传,commander 会拒未知选项报错 | 后端 CLI 没这个 flag([doctor.ts:36](packages/cli/src/commands/doctor.ts));display_name 只在 workspace markdown |
 | 凭印象搜公开视频去训(§Edge 1) | 反问用户上传视频 | 法律 + 同意书风险,无授权训练他人形象 |
 | 假设最后一个上传的视频 = 训练用(§Edge 2) | 列出所有让用户选 | 错训不该训的人 |
 | 视频含糊意图直接触发 skill(§Edge 3) | 三岔反问 (a) 训分身 / (b) 复刻 / (c) 翻译 | 错走训练流程浪费训练配额(训练成本 > 复刻) |

package/.claude/skills/gen/SKILL.md

@@ -284,6 +284,18 @@ gen task retry <task_id>          # 重试失败的任务
 
 所有 `gen` 命令在失败时会返回结构化错误,顶层是 `success: false` + `error` 对象,**进程退出码为 1**。`error.message` 是后端已经处理过的中文人话(上游英文报错已脱敏/翻译),大多数情况下**可以原样透传给用户**,但要按下表选择对应处理方式(重试 / 透传 / 询问用户)。
 
+### 执行方式（前置条件，先看这条）
+
+`gen` 命令**必须前台同步执行**，等命令真正退出后再判断结果（读 stdout 的 JSON envelope + 进程退出码）。同步等待 30s ~ 5min 是**正常的**（图片生成 + 上游 polling），不是卡住。
+
+**禁止以下行为** —— 它们会让你**永远看不到 `success` / `failure` envelope**，从而陷入 `cat` / `sleep` / `Monitor` 死循环：
+
+- ❌ 后台跑 `gen`（`&` / `nohup` / Bash `run_in_background:true` / 用 Task / Monitor 工具包一层）
+- ❌ 给 Bash 设短 timeout（< 600000ms / < 10min）强行打断 `gen` —— 命令被 kill 后**没机会写出 envelope**，你看到的只是空输出
+- ❌ 一边跑 `gen` 一边 `cat` 它的 `.output` 文件 / `sleep N` 等待 / `Monitor until [ -s file ]` —— `gen-cli` 走 buffered JSON 输出，**中途文件就是空**，空文件**既不代表失败也不代表"还在跑"**，只代表你不该 polling
+
+正确做法：**前台 Bash 跑 `gen image ...`，Bash `timeout` ≥ 600000ms**，命令退出后 stdout 一定有 `success:true` 或 `success:false` JSON envelope，按下面的对照表处理即可。
+
 ### 失败响应示例
 
 ```json
@@ -343,6 +355,7 @@ gen task retry <task_id>          # 重试失败的任务
 ❌ 把 `"维护中"` 三个字直接砸给用户
 ❌ 任何失败都自动 retry 三五次造成账单浪费
 ❌ 看到 `success: false` 却跑去 `cat` 输出文件、`sleep` 等待、再调一次 `gen`——这就是把失败当"任务还在跑"。真实事故：上游返回 CONTENT_POLICY_VIOLATION 后 Agent 没识别失败,反复 polling+重试,用户被晾几分钟才看到错误（且每次都已计费）
+❌ 把 `gen` 跑后台（`run_in_background:true` / 包 Task / 短 Bash `timeout`）+ 用 `cat` / `sleep 30` / `Monitor until [ -s file ]` 轮询 `.output` 文件——`gen` 同步会跑几十秒到几分钟，期间 output 文件就是空，你 cat 出来"什么都没有"既不代表失败也不代表"还在跑"。等 Bash `timeout` 把 `gen` kill 掉，envelope 都没机会写出来，你**永远看不到 `success:false`**，陷入死循环。真实事故 2026-05-19：ai.optima.onl 复测 Disney prompt，Bash `timeout:120000` 把 gen 提前 kill，agent 看到空 `.output` 文件后开 `cat` / `sleep 30` / `Monitor until` polling，用户被晾几分钟才感知失败
 ❌ `CONTENT_POLICY_VIOLATION` 时擅自改 prompt 偷偷重试（用户失去控制，多等一次生成时间，且 Agent 无法确知触发哪条政策，改完大概率还是被拒；正确做法是把 `error.message` 透传给用户并询问怎么办）
 ❌ `PROVIDER_INSUFFICIENT_CREDITS` 时让用户去充值（这跟用户余额无关）
 ❌ **任何 `gen` 命令失败后，在 sandbox 里 `pip install` 重 ML 推理库（rembg / onnxruntime / torch / segmentation-models 等）做 fallback** —— 纯像素操作（PIL / cv2 的 crop / paste / resize / 简单 alpha 通道处理）不在此列。真实事故：grsai 超时后 LLM 自己装 rembg → 内存不足被 kill → 反复重试 → 用户等 20 分钟才出图。失败必须**诚实告知用户**，不要在 sandbox 里"自己想办法"。

package/.claude/skills/motion-control/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: motion-control
+description: "用一段参考视频的动作驱动一张人物图，输出该人物按相同动作运动的视频（kling motion-control）。触发场景：用户给一张人物图 + 一段动作参考视频，说'让这个人按这个动作动起来'/'用这个视频的动作做我这张图的视频'/'motion transfer'/'动作克隆'/'让 X 跳这段舞'。范围：画面里有真人/角色按参考动作做身体运动；不是讲话（讲话走 digital-human）、不是产品演示（走 video-gen）。"
+version: 1.0.0
+owner_repo: Optima-Chat/optima-gen
+---
+
+# Motion Control Skill
+
+把「一张人物图 + 一段动作参考视频」变成「人物图里的角色按参考动作动起来」的视频。kling-2.6/motion-control 驱动，720p，$0.10/秒。
+
+> **CLI 版本要求**：`@optima-chat/gen-cli ≥ 2.2.0`（含 `gen video motion-control` 子命令）。报 `unknown command` → 引导用户升级，**不**自己拼接 HTTP 调用。
+
+> **用户向输出原则**：status / 错误 / 总结里**不出现上游品牌名**，统一用「动作驱动视频生成中」「视频生成完成」等中性描述。
+
+## 不是这个 skill 的场景（先路由出去）
+
+| 用户意图 | 走哪里 |
+|---|---|
+| 真人/数字人**讲话** | `digital-human` |
+| **产品**视频（PDP / 社媒投放 / 复刻爆款） | `video-gen` |
+| 纯文生 / 图生**非人物**视频（风景、动物） | `gen video`（基础视频） |
+| 翻译已有口播视频 | `video-translate` |
+| 剪辑已有视频 | `video-edit` |
+
+motion-control **只管**：有具体人物图 + 想让 ta 按某段动作运动。
+
+## 输入要求（不满足先问）
+
+- **人物图**：jpeg/png，≥300px，长宽比 2:5 到 5:2（即不能比 5:2 更窄或更宽）。**单一清晰主角**——背景人物 / 多人会被服务端拒。
+- **参考视频**：mp4/mov/mkv，3-30 秒，≤100MB，**镜头里要有完整可识别的上半身**——服务端会做人体检测，没识别到上半身会以 `No complete upper body detected` 报错。
+- **缺其中之一** → 问用户补齐，不要硬上。
+
+## 工作流（极简）
+
+1. **确认两个输入都有**（本地路径或 http(s) URL 都行）
+2. **告知预估成本**：
+   - 本地视频：`ffprobe` 取时长 `D`
+   - URL：必须问用户视频多长（CLI 不能自动 probe URL）
+   - 成本 = `D × $0.10`，告诉用户 + 等"继续"
+3. **执行**：`gen video motion-control --image <img> --reference-video <vid> [--character-orientation image|video] [--prompt "..."]`
+   - duration 不传 → CLI 自动 ffprobe 本地视频；URL 必须显式 `--duration`
+   - `character-orientation`：默认 `video`（输出时长 = 参考视频）；用户说「保持角色形象优先」→ `image`（输出截到 ≤10s）
+4. **下载 + 展示**：CLI 自动 download 到 `./gen-output/motion_<id>.mp4`，告诉用户路径
+5. **失败处理**见下表
+
+## 错误处理
+
+| 服务端错误 | 含义 + 处理 |
+|---|---|
+| `No complete upper body detected in the video` | 参考视频里没识别到完整上半身。让用户换段更清晰的动作视频，或截出有上半身的片段 |
+| `file format not support` | 极少触发（已修，走 kie File Upload API）。再现 → 报 bug，不要自己重试 |
+| `duration out of range` | duration 不在 3-30s（或 image-orientation 时超 10s）。截短参考视频或换 orientation 重试 |
+| `INSUFFICIENT_CREDITS` | 用户积分不足，告知充值 |
+| 任务超时 / 网络故障 | 用 `gen task get <id>` 查最新状态；服务端真正完成但 CLI poll 超时是正常的，结果还在 |
+
+## 不要做的事
+
+- **不要自己跑 ffmpeg** 拼/剪/转码 motion-control 的输出——这个 skill 只管「生成那条 motion-control 视频」，后期编辑走 `video-edit`
+- **不要给"改第 N 段"做支持**——motion-control 是单次原子生成，没有 storyboard / 多段概念。用户要改 → 重新生成一发
+- **不要传 `--mode`**——服务端锁 720p，传了 CLI 会过但没意义
+- **不要给商家用作产品视频**——product 视频走 `video-gen`，motion-control 不适合「让产品旋转一圈」这种纯物体场景（参考视频必须有人）
+
+## 相关工具
+
+- `gen video motion-control` — 本 skill 唯一执行命令
+- `gen task get <id>` — 查任务状态（轮询超时后用）
+- `ffprobe` — 取本地视频时长，CLI 内部已用，skill 一般不直接调

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

@@ -0,0 +1,144 @@
+---
+name: video-compose
+description: "把【多个素材片段 + 一段口播文案】自动合成一条可发布短视频——自动配音、按文案语义选片拼接、烧字幕、加 BGM。用户只需拍素材/用 AI 生成片段 + 写文案，剪辑配音字幕全交给 AI。
+
+  必备前提：用户有 ≥1 个视频片段文件 + 一段口播文案（或愿意现写）。
+
+  触发：用户给出多个视频片段 + 文案，并说'拼个视频'/'把这堆素材剪一下'/'给这段文案配视频'/'做条口播带画面的视频'/'素材+文案做成片'。
+
+  不触发：只给 1 个口播 talking-head 视频要剪（用 video-edit）；只给产品图要生成画面（用 video-gen）；用户要【保留片段原声】拼接（用 video-edit，本 skill 会丢弃原声）。"
+version: 1.0.0
+owner_repo: Optima-Chat/optima-gen
+---
+
+# video-compose — 素材 + 文案 → 成片
+
+用户给一堆片段 + 一段口播稿，你交付配好音、配好画面、带字幕和 BGM 的竖版成片。
+
+> ⚠ **语义前提：片段被当作纯画面 b-roll，原声一律丢弃**，成片音频 = AI 配音 + BGM。若用户给的是带人声的口播片段、想**保留原声**拼接，那是 video-edit 的活——开工前跟用户确认一句"片段原声会去掉、全程用 AI 配音"，避免出片后才发现声音没了。
+
+**关键：选片这一步由你（Claude）亲自看帧判断**——脚本把每个 clip 抽 3 帧，你用 Read 看图，按文案语义写 `proposal.json`。不需要任何外部 vision API。
+
+## 工具
+
+`python3 $CLAUDE_SKILL_DIR/scripts/video_compose.py <frames|build> <proj-dir>`
+- 依赖（容器自带）：`python3`、`ffmpeg`、`gen` CLI。
+- 情感配音走 `gen tts --provider minimax`（key + 计费在后端 optima-generation，skill 不碰密钥）。
+
+## 工作目录
+
+```
+<proj>/inputs/clips/*.mp4    素材（任意命名，按文件名排序得 clip id）
+<proj>/inputs/script.txt     口播稿，每行一句 = 一个 segment
+<proj>/work/                 中间产物（frames/ proposal.json subs.ass 等）
+<proj>/final.mp4             成片
+```
+
+## Step 0：指令清单读回（≥ 2 个动作时必跑）
+
+用户一条消息里给多个要求（如"竖版 + 不要 BGM + 字幕大一点 + 压到 20 秒"）时，**先拆成原子清单读回、等确认再动手**，不要边读边做。单一动作（"拼个视频"）跳过。
+（理由同 video-edit：多指令直接执行易漏，漏了要等成片出来才发现，全流程重做。）
+
+## 主流程
+
+### 1. 建工程 + 落素材和文案
+- 建 `<proj>/inputs/clips/` 和 `<proj>/inputs/script.txt`
+- 把用户的片段拷进 clips/（命名随意，建议 `01.mp4 02.mp4 …` 便于引用）
+- 文案写进 script.txt，**每行一句**。用户没给文案就先帮他写（看素材定主题），写完**先给用户确认文案**再继续。
+
+### 2. 抽帧
+```
+python .../video_compose.py frames <proj>
+```
+产出 `work/frames/<clipid>_<tag>.jpg`（每片自适应抽 3~6 帧，约每 5s 一帧）+ `work/clips_manifest.json`。**manifest 里每帧带 `t`（秒）= 该子镜头在素材中的时间点**——写 proposal 时用它指定 `src_start`。
+
+### 3. 看帧 + 写 proposal.json（**你的核心判断**）
+- 用 **Read 逐张看** `work/frames/` 里的帧，在心里给每个 clip 一句话描述（人物/动作/场景/有无烧死字幕）。
+- 按 script 每句的语义，给它挑最贴合的 clip，写出 `work/proposal.json`：
+
+```json
+{
+  "voice": "Chinese (Mandarin)_Warm_Girl",
+  "bgm_mood": "warm",
+  "assignments": [
+    { "segment_idx": 0, "text": "第一句原文", "clip": "01", "src_start": 5.2, "emotion": "sad", "speed": 0.92, "rationale": "为什么选它 + 为什么这个子镜头 + 为什么这个情绪" }
+  ]
+}
+```
+
+- **voice**：voice_id。**只用 `voice-samples/CATALOG.md` 里 7 个实测可用的音色**（标签 ↔ voice_id），别填没验证过的（错的 voice_id 会 `UPSTREAM_UNKNOWN: voice id not exist` 失败）。默认 `Chinese (Mandarin)_Warm_Girl`（温暖少女）。**具体音色让用户试听后定，见 §4。**
+- **clip**：素材 id（manifest 里的 `id`）
+- **src_start**：从该素材的**哪一秒**开始切（= 你选中那个子镜头帧的 `t`，看 manifest）。**这是避免重复镜头的关键**：同一 clip 给多句复用时，每句填**不同的 `t`**（如倒水特写 t=11.5、碰杯 t=20.7），脚本以该时刻为中心切，画面就不会重复。不填则脚本按复用顺序自动均匀错开（也不会重复，但选的子镜头不一定贴文案，所以建议显式填）。
+- **emotion**：每句独立，九选一 `happy/sad/angry/fearful/disgusted/surprised/calm/fluent/whisper`，按文案情绪配
+- **speed**：0.5–2.0。**这是抖音/TikTok/小红书短视频工具，默认就要快**——不写 speed 脚本按 `DEFAULT_SPEED=1.35` 配音（≈TikTok 口播节奏）；想更冲可显式写 1.5；**只有明确要治愈/抒情慢节奏才写 ≤1.0**（如 0.9）。别让成片听起来拖沓。
+- **bgm_mood / bgm**：见 §BGM（用户没指定就按文案情绪填 `bgm_mood`）
+
+选片规则：
+- 首句优先用能建立场景/正面的镜头
+- 时序上有视觉故事线就尊重它
+- **clip 可复用，但复用时必须给不同的 `src_start`（选不同子镜头），否则画面重复**；也尽量别连续两句用同一 clip
+- **每个 clip 通常有多个子镜头（manifest 多帧）——优先把不同子镜头分给不同句子，让素材都出镜，而不是反复用片头**
+- 素材数 < 句子数时复用并提示用户素材偏少
+- **若某 clip 帧里有烧死的字幕/水印**（见 §坑），尽量不选它承载关键句；非用不可则提示用户
+
+情绪配法：按文案的情感弧线给每句配 emotion，不要全句一个调。例：怅然开场 `sad` → 转折欣喜 `happy` → 高潮 `surprised` → 舒缓 `calm` → 暖心收尾 `happy`。
+
+节奏（平台风格）：这是短视频，默认**快节奏**（像抖音/TikTok 口播）。文案**短句、强钩子、句子别太长**（一句太长配音就拖、画面也切得慢）；语速默认 1.35，想更冲可更快。除非用户明确要慢节奏治愈片，否则别配出"念课文"那种拖沓感。
+
+### 4. 试听音色 / BGM + 看选片方案 → 用户拍板
+**音色和 BGM 是创作决策，让用户自己听、自己定，不要替用户默认死。** 出片前：
+
+> **素材路径**：BGM 库和音色样音随 `gen-cli` 一起发布（不在 skill 目录）。先解析一次：
+> ```bash
+> ASSETS=$(python3 $CLAUDE_SKILL_DIR/scripts/video_compose.py assets-dir)
+> ```
+> 下面用 `$ASSETS/voice-samples`、`$ASSETS/bgm-library/<mood>`。
+
+1. **音色试听**：把 `$ASSETS/voice-samples/*.mp3`（7 个音色样音，标签↔voice_id 见同目录 `CATALOG.md`）拷到 `<proj>/previews/`，把可播放的文件链接列给用户，让用户**听完选一个**。
+2. **BGM 试听**：按文案情绪先推荐一类（治愈→`warm`、种草→`upbeat`…），把该类（用户想多听就多拷几类）`$ASSETS/bgm-library/<mood>/*.mp3` 拷到 `<proj>/previews/` 给用户试听；用户可换类、指定某首，或**自己上传一首**（放 `inputs/bgm/`，优先级最高）。
+3. **选片方案**：把 assignments 摘要（每句哪个 clip + 理由）一并给用户过目。
+4. **给推荐默认**（音色=贴文案的一个、BGM=按情绪一类），用户想省事一句「就用默认」即可直接出片；想换就听了再定。
+
+用户拍板后：选定的 voice_id 写进 `proposal.voice`、BGM 写进 `bgm`(自带路径) 或 `bgm_mood`(情绪库)，再：
+```
+python3 $CLAUDE_SKILL_DIR/scripts/video_compose.py build <proj>
+```
+脚本做：逐句情感配音（带缓存，未改的句子不重跑）→ 每句按 `src_start` 用 `-ss` **精切对应子镜头**到该句时长（竖版 crop，clip 比该句短则**慢放填满、不 loop**；**同素材复用强制时间窗不重叠，防重复镜头**）→ 拼接 → 烧字幕 → BGM sidechain ducking（有 BGM 才加）→ `final.mp4`。
+
+### 5. 交付汇报
+报成片路径 + 时长 + 用了几个 clip + 配音字数。**不要提任何模型/服务名**，配音统一说"AI 配音"。
+
+## BGM（不锁死；用户没指定就按文案情绪自动配）
+来源优先级：
+1. `proposal["bgm"]` 显式路径（用户明确指定某首）
+2. `inputs/bgm/` 用户上传的音频
+3. `proposal["bgm_mood"]` → 从情绪库 `bgm-library/<mood>/` **随机挑一首**（用户没指定 BGM 时，**你按文案整体情绪填这个字段**）
+4. 都没有 → 仅人声
+
+- 有 BGM 时自动 sidechain ducking（人声起时压低 BGM）
+- **优先让用户试听后选**（见 §4 步骤 2）；用户说「你定/随便」时才按文案情绪自动填 `bgm_mood`，**绝不留空**。情绪 → 目录：`warm`(治愈/温暖) `upbeat`(欢快) `sad`(伤感) `calm`(舒缓) `energetic`(高能/卖货) `dramatic`(戏剧/科技)
+- 用户明确要某首 / 要换 → 用优先级 1、2
+- ⚠ 库里只能放**可商用授权**的曲子（公开发布视频有版权要求）；某情绪目录为空时该句跳过 BGM 并提示
+
+## 用户改方案怎么办
+- 换某句的画面：改 `proposal.json` 那条的 `clip`（换素材）或 `src_start`（同素材换子镜头），重跑 `build`
+- 嫌某两句画面重复：给它们填不同的 `src_start`（看 manifest 的帧 `t`），重跑 `build`
+- 换情绪/音色：改 `emotion`/`voice`，重跑 `build`
+- 换/加 BGM：丢文件进 `inputs/bgm/` 或改 `bgm` 路径，重跑 `build`
+**配音有缓存**（engine/voice/emotion/speed/text 没变就复用），所以单纯换 BGM/字幕**不重新花钱跑配音**，秒出。`proposal.json` 就是反复调的抓手。
+
+## 坑（实跑踩过）
+
+| 坑 | 处理 |
+|---|---|
+| **用户素材自带烧死字幕/水印** | 你看帧时若发现某片已有硬字幕（如原片烧了英文 caption），新字幕叠上去会重影。承载关键句时避开该片，或提示用户该片有原生字幕 |
+| **clip 是横版** | 脚本默认 center-crop 到竖版会裁掉两侧；横版素材多时提示用户成片是竖版裁切 |
+| **素材总时长 < 文案配音时长** | 不再 loop（loop=重复）：单片比某句短→慢放填满；某片被多句复用但时长不够 distinct 画面→`[mix] ⚠` 告警。**要彻底不重复**：素材总时长应 ≥ 配音总时长，且每片别被复用超过它能切出的 distinct 段数；不够就提示用户补素材或精简文案 |
+| **字幕样式/字体** | 默认白字黑边底部。字体走 env `VIDEO_COMPOSE_FONT`（默认 `Noto Sans CJK SC`）。prod shell 镜像（optima-ai-shell 根 `Dockerfile`，Ubuntu 22.04）已装 `fonts-noto-cjk`（提供 `Noto Sans CJK SC`）+ Source Han Sans SC，CJK 字体确认可用。`build` 前 `_preflight_font()` 会 `fc-match` 兜底，缺字体 fail-loud 不静默渲染豆腐块。换镜像/换 env 字体时按此 fc-match 验证 |
+| **gen tts 报错** | 透传后端错误。`PROVIDER_INSUFFICIENT_CREDITS`=MiniMax 余额；`INVALID_INPUT`=emotion/voice 非法。配音失败不出片，不静默吞 |
+
+## 关键参数（scripts/video_compose.py 顶部）
+- `W,H=1080,1920`（竖版）、`FPS=30`、`CRF=20`
+- 配音：`gen tts --provider minimax`，密钥/计费在后端，skill 不碰密钥
+- `VIDEO_COMPOSE_FONT`：字幕字体（容器需有对应 CJK 字体）
+- BGM 不锁死：见 §BGM；情绪库随 `gen-cli` 打包，脚本自动解析（`$ASSETS/bgm-library/<mood>/`，见 §4 素材路径）