@optima-chat/gen-cli 1.2.1 → 2.1.0

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

@@ -0,0 +1,246 @@
+# Generate Talking-Head Video
+
+用已有分身(用户自训的 或 公共池的)合成口播视频。
+
+**关键设计**:每条视频独立 workspace 目录(`~/digital-human/videos/<video-id>/`),segments 分段保存,改一段不用全重生。详见 [edit.md](edit.md)。
+
+## 主流程: 用 X 做视频说 Y
+
+### 1. 确定 X 是什么
+
+按 [SKILL.md "LLM 如何区分用户输入是名字还是 external_id"](../SKILL.md) 表格判断:
+- 名字 → 在 `~/digital-human/avatars.md` "名字"列模糊匹配
+- 新格式 external_id (`dh-[a-z0-9]{8}`) → 直接走 §2
+- 存量 ASCII slug (例 `dr-wang`) → 走 [manage.md "存量分身"](manage.md) 流程
+- 歧义 → 反问消歧
+
+匹配结果:
+- 1 个匹配 → 取该行 external_id,走 §2
+- 多个匹配 → 反问消歧("你说的是'张医生'还是'张主任'?")
+- 0 个匹配 → 反问"没找到'X',要训新的吗?"(走 [train.md](train.md))
+
+### 2. 反查 voice_id + avatar_id
+
+后端 CLI [`doctor.ts:151-152`](file:///C:/Users/zy/optima-gen/packages/cli/src/commands/doctor.ts) 要求 `gen avatar video` 传 `--avatar` + `--voice` 两个 UUID,不支持 `--external-id` 自动反查,所以**必须先查**:
+
+```bash
+PROFILE=$(gen avatar profile "$external_id")
+VOICE_ID=$(echo "$PROFILE" | jq -r '.heygen_voice_id')
+AVATAR_ID=$(echo "$PROFILE" | jq -r '.heygen_avatar_look_ids[0]')
+```
+
+### 3. 创建 video 工作目录
+
+```bash
+# 纯时间戳 (决策表 #11,无 slug v1)
+VIDEO_ID="$(date +%Y%m%d-%H%M)"
+
+# 同一分钟内多次生成 → 自动追加 -2/-3 后缀避免覆盖
+# (不能直接 mkdir -p,因 mkdir -p 静默复用已存在目录会覆盖 segments)
+n=2
+while [ -d ~/digital-human/videos/$VIDEO_ID ]; do
+  VIDEO_ID="$(date +%Y%m%d-%H%M)-$n"
+  n=$((n+1))
+done
+
+VIDEO_DIR=~/digital-human/videos/$VIDEO_ID
+mkdir -p "$VIDEO_DIR/segments"
+cd "$VIDEO_DIR"
+```
+
+参考 `video-gen` skill 同款 disambiguation pattern。
+
+### 4. 拆段(text > 50 字时)
+
+text ≤ 50 字 → 跳过拆段,直接当 1 段处理(单段也走 segments 流程,保持一致性)。
+
+text > 50 字 → 按分隔符自然分割,每段 ≤ 50 字 / ≤ 10 秒(spec §13.3 硬约束)。
+
+**拆段分隔符优先级**(从强到弱依次尝试):
+
+1. **句末标点**:`。`(中文句号)/ `.`(英文句号)/ `?` / `?` / `!` / `!`
+2. **句中标点**(若 1 拆出的段仍 > 50 字):`,` / `,` / `;` / `;` / `:` / `:`
+3. **空格**(若 2 仍不行):按空格切,适用英文 / 长句拼接
+4. **硬切兜底**(若上述全无):按字符数 45-50 切,**避免在词中间切**(中文按字符 OK;英文遇到字母连续 → 退回到上一个空格)
+
+例:
+- "今天给大家推荐一款超级好用又便宜还能解决各种皮肤问题的护肤霜" (29 字,无标点)
+  → ≤ 50 字,不用拆,作为 seg-01 整段
+- "今天给大家推荐一款超级好用又便宜还能解决各种皮肤问题的护肤霜它真的太棒了你们一定要试试" (45 字,无标点)
+  → ≤ 50 字,整段
+- "今天给大家推荐一款超级好用又便宜还能解决各种皮肤问题的护肤霜它真的太棒了你们一定要试试我自己用了两个月效果惊人" (54 字,无标点)
+  → 超 50 字,无标点 → fallback 硬切到 45 字附近:`"...护肤霜它真的太棒了你们一定要试试" (35 字) + "我自己用了两个月效果惊人" (12 字)`
+
+**写每段 text 文件**:
+```bash
+# 2 位零填充,支持到 99 段
+echo "大家好,我是张医生。" > segments/seg-01.txt
+echo "今天给大家推荐一款..." > segments/seg-02.txt
+# ...
+```
+
+### 5. 写 meta.md(初版)
+
+```markdown
+# Video: <slug from text or topic>
+
+| 字段 | 值 |
+|---|---|
+| video-id | <VIDEO_ID> |
+| avatar | <display_name> (external_id: <external_id>) |
+| 创建时间 | <YYYY-MM-DD HH:MM> |
+| 当前版本 | final-v1.mp4 |
+
+## 总文本
+
+> <用户给的完整 text>
+
+## Segments
+
+| seg | text | 时长 | 文件 | 最后更新 |
+|---|---|---|---|---|
+| 01 | "大家好,我是张医生。" | ~3s | segments/seg-01.mp4 | <时间> |
+| 02 | "今天给大家推荐..." | ~4s | segments/seg-02.mp4 | <时间> |
+| ... |
+```
+
+> **不写 voice_id / avatar_id UUID** 到 meta.md —— 用户能看到这个文件,UUID 不冒泡;需要时 LLM 重新 `gen avatar profile` 反查。
+
+### 6. 逐段生成 mp4
+
+```bash
+for SEG_TXT in segments/seg-*.txt; do
+  N=$(basename "$SEG_TXT" .txt | sed 's/seg-//')
+  gen avatar video --avatar "$AVATAR_ID" --voice "$VOICE_ID" \
+    --text "$(cat "$SEG_TXT")" \
+    -o "segments/seg-$N.mp4"
+done
+```
+
+每段独立 mp4,文件名跟 text 文件零填充对齐(seg-01.txt ↔ seg-01.mp4)。
+
+### 7. ffmpeg concat → final-v1.mp4(两步走 + 透明告知)
+
+```bash
+printf "file '%s'\n" segments/seg-*.mp4 > concat.txt
+
+# Step 1: 试 -c copy(快,无画质损失)
+if ffmpeg -f concat -safe 0 -i concat.txt -c copy final-v1.mp4 2>/dev/null; then
+  CONCAT_MODE="stream-copy"
+else
+  # Step 2: fallback 重编码
+  ffmpeg -f concat -safe 0 -i concat.txt -c:v libx264 -preset fast -c:a aac final-v1.mp4
+  CONCAT_MODE="re-encode"
+fi
+```
+
+**禁止**:静默切换不告知用户(决策表 #15)。走 fallback 时**必须**在 §9 报告里加一句"段间 codec 兼容问题,自动重编码合成"。
+
+### 8. 写 history.md
+
+```bash
+cat > history.md <<EOF
+# History
+
+- **$(date +'%Y-%m-%d %H:%M')** [v1] 初版生成 (N 段)
+EOF
+```
+
+### 9. 报告 final-v1.mp4 给用户
+
+> "✅ 视频生成完成: $VIDEO_DIR/final-v1.mp4
+> 共 N 段,每段独立保存在 segments/。
+> 想改哪一段说一声,只重生那一段就行(不用全重做)。"
+
+如果走了 ffmpeg fallback(`CONCAT_MODE=re-encode`),多一句:
+> "⚠️ 段间 codec 兼容问题,自动重编码合成(多花了 ~ X 秒,画质轻微损失)。"
+
+---
+
+## 没指定分身但要"做个口播视频"
+
+走"公共 avatar"分支:
+
+1. 展示 [avatar-catalog.md](avatar-catalog.md) 公共 avatar / voice 清单(用 preview 图或名称,不冒泡 UUID)
+2. 让用户选一个 avatar + 一个 voice
+3. **是否走 workspace 持久化**:
+   - 用户给的 text > 50 字 → 拆段,走 workspace(VIDEO_ID 同 §3)
+   - text ≤ 50 字 → 同样走 workspace(单段也存),不冒泡 UUID
+4. 调用(注意:公共 avatar 用 `gen video --provider heygen`,**不是** `gen avatar video`):
+   ```bash
+   gen video --provider heygen \
+     --avatar <公共 avatar id> \
+     --voice <公共 voice id> \
+     --text "$(cat segments/seg-NN.txt)" \
+     -o segments/seg-NN.mp4
+   ```
+5. 后续 §7 ffmpeg concat + §8 history + §9 报告同主流程
+
+公共 avatar 视频的 `meta.md` "avatar" 字段写 `公共: Abigail (id 不冒泡)` 即可。
+
+---
+
+## 可选参数(`gen video --provider heygen` 路径专用)
+
+| 参数 | 说明 | 默认值 |
+|---|---|---|
+| `--avatar-style <style>` | normal \| circle \| closeUp | normal |
+| `--voice-speed <n>` | 语速 0.5-1.5 | 1.0 |
+| `--voice-emotion <emotion>` | Excited \| Friendly \| Serious \| Soothing \| Broadcaster | — |
+| `--bg-color <hex>` | 背景色 | — |
+| `--bg-image <url>` | 背景图 URL | — |
+| `--caption` | 启用字幕 | — |
+| `--title <title>` | 视频标题 | — |
+
+`gen avatar video` 不支持以上 flag(只接受 `--avatar` / `--voice` / `--text` / `--title` / `-o`)。
+
+---
+
+## 训完立即 demo(可选)
+
+如果用户在原始训练请求里说了想"看效果 / 做一段试试 / 给我个 demo":
+
+训完直接走 §主流程,text 用用户给的或默认 `"大家好,我是 X"`(X = 名字)。
+
+**降级**:如果 trained avatar 还在 still-processing(`gen avatar video` 返回错误)→ 用公共 avatar + trained voice 合成,告诉用户:
+> "分身的视觉部分还在最后定型(几十分钟内会好),先用通用形象 + 你的声音演示。**这条 demo 仅证明 voice 训成,不展示真分身效果** — 几小时后用 'X 做个视频说 Y' 重试就能用真分身了。"
+
+降级时 voice 用 trained 的,avatar 选 [avatar-catalog.md](avatar-catalog.md) 里任一公共 avatar。
+
+> **注意区分**:这是 trained avatar still-processing 期间的**临时降级**(待定型后自动恢复用真 avatar),**不算** §"Advanced: mix-and-match"。Mix-and-match 是用户主动要求"用 X 的声音 + 公共 Y 形象"的长期混搭意图;本段是 voice 已训好但 avatar 还没定型的应急方案,语义不同。
+
+---
+
+## Advanced: mix-and-match(参考实现,**不**进 SKILL.md 主流程)
+
+> [workspace SPEC §2](https://github.com/Optima-Chat/optima-agent/blob/main/docs/superpowers/specs/2026-05-14-digital-human-workspace-naming.md) 已声明 mix-and-match 是非目标。下面是参考实现,**不**写进 LLM 的引导路径,用户主动要求时再让 advanced agent 临时执行。
+
+例:"用张医生的声音 + 公共 Aditya 形象":
+
+1. Read `~/digital-human/avatars.md` 找张医生的 external_id
+2. `gen avatar profile <id>` 反查 voice_id
+3. 调:
+   ```bash
+   gen video --provider heygen \
+     --voice <张医生.voice_id> \
+     --avatar Aditya_public_4 \
+     --text "..." \
+     -o segments/seg-NN.mp4
+   ```
+
+LLM 主动告诉用户:"这是参考实现,未来若呼声高再进主流程。"
+
+---
+
+## Common Mistakes
+
+| ❌ Mistake | ✅ 正确做法 | 为什么 |
+|---|---|---|
+| 直接 `gen avatar video --external-id dh-...` | 必须先 `gen avatar profile` 拿 voice_id+avatar_id 再调 | doctor.ts:151-152 显示 `--avatar` + `--voice` 是 required;`--external-id` flag 不存在 |
+| 把 voice_id / avatar_id UUID 报给用户 | 只回 mp4 路径 + "用 X 做了" | UUID 不冒泡是核心 UX 原则 |
+| text > 50 字直接 send | 客户端拆段,每段 ≤ 50 字 / ≤ 10 秒 | 长 prompt 会让 trained avatar 挂死(spec §13.3) |
+| 公共"做个口播"用 `gen avatar video` | 用 `gen video --provider heygen` | `gen avatar video` 仅用于已 onboard 训练分身 |
+| 默认走 mix-and-match | 默认是"X 做视频" 整套用,mix 是 advanced 用户主动要 | mix 主流程会让 UX 复杂化 |
+| segments 写 ephemeral 目录(`/tmp`)而非 workspace | 写到 `~/digital-human/videos/<id>/segments/` | 用户后续想改一段,workspace 是单一真值;`/tmp` session 后丢失 |
+| ffmpeg fallback 静默切换不告知 | 走 re-encode 必须在报告里明示"自动重编码,画质轻微损失" | 用户看到画质变了 / 这次慢了会卡 debug,透明告知避免认知负担 |
+| 单段视频(text ≤ 50 字)跳过 workspace | 也写 `videos/<id>/segments/seg-01.{txt,mp4}` + `final-v1.mp4` | 一致性让用户后续"改这段"路径统一,不需要"短文本是另一种流程"的特殊知识 |

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

@@ -0,0 +1,126 @@
+# Manage Avatars & Videos
+
+管理 `~/digital-human/` 工作空间下的分身(`avatars.md`)+ 生成过的视频(`videos/<id>/`)+ 训练素材(`training/<id>/`)。
+
+## "我的分身有哪些"
+
+直接 Read `~/digital-human/avatars.md` 渲染给用户。
+
+文件不存在 → "你还没训过分身,要训一个吗?"(走 [train.md](train.md))
+
+文件存在但只有表头(无数据行)→ 同上。
+
+## "我的视频有哪些" / "列我的视频" / "做过哪些视频"
+
+按 mtime 降序列 `~/digital-human/videos/`:
+
+```bash
+for d in $(ls -t ~/digital-human/videos/); do
+  cd ~/digital-human/videos/$d
+  # 读 meta.md 提取关键字段
+  AVATAR=$(grep -E '^\| avatar \|' meta.md | sed 's/.*| //' | sed 's/ |$//')
+  VERSION=$(grep -E '^\| 当前版本 \|' meta.md | sed 's/.*| //' | sed 's/ |$//')
+  TEXT_PREVIEW=$(awk '/^## 总文本/{getline; getline; print}' meta.md | head -c 30)
+  N_SEGS=$(ls segments/seg-*.txt 2>/dev/null | wc -l)
+  # 渲染
+  echo "- $d ($AVATAR): \"$TEXT_PREVIEW...\" [$N_SEGS 段, $VERSION]"
+done
+```
+
+渲染给用户(markdown 表格更友好):
+
+| video-id | 分身 | 总文本(前 30 字) | 段数 | 当前版本 |
+|---|---|---|---|---|
+| 20260515-1430 | 张医生 | "大家好,我是张医生。今天介..." | 4 | final-v2.mp4 |
+| 20260514-0945 | 李老师 | "..." | 6 | final-v1.mp4 |
+
+文件夹不存在 / 空 → "你还没生成过视频,要做一条吗?"(走 [generate.md](generate.md))
+
+## "把张医生改成张主任"
+
+## "把张医生改成张主任"
+
+1. Read `~/digital-human/avatars.md`
+2. 在"名字"列找 `张医生`
+3. Edit 该行"名字"列的 cell:`张医生` → `张主任`
+4. 反馈"已改名,external_id 不变,以后可以用'张主任'引用了"
+
+如果用户给的旧名字找不到 → 反问"没找到叫'张医生'的分身,你现在的分身有:[列出]"
+
+## "删了张医生"
+
+1. Read `~/digital-human/avatars.md`
+2. 找到"张医生"行,记下该行所有字段(名字 / external_id / 训练时间 / preview URL)
+3. **二次确认 + 显式列出恢复锚点**:
+   > "确认删除'张医生'? **注意**:这是对你视角的硬删除 —
+   > - 你失去所有引用路径(external_id 从你视野消失 + 没有 list 端点)
+   > - 后端 DB 行成为 orphan 数据,**找回需要联系运维直接查 DB**
+   > - 运维查 DB 需要锚点,以下信息删除后你将看不到,**建议先记下来或截图**:
+   >   - 名字:`张医生`
+   >   - external_id:`dh-a7f2k9m1`
+   >   - 训练时间:`2026-05-14`
+   >   - preview:`https://...preview.jpg`
+   > 真要删吗?"
+4. 用户确认 → 删该行
+5. 反馈"已从你的列表删除'张医生'。如需找回请向运维提供上述 4 个锚点(名字 / external_id / 训练时间 / preview URL)。"
+
+如果用户给的名字找不到 → 同上反问。
+
+## 存量分身(用户在前 SPEC 落地之前训过 `dr-wang` 等)
+
+用户说"用 dr-wang 做视频"但 `~/digital-human/avatars.md` "名字"列没有 `dr-wang`:
+
+1. LLM 判断 `dr-wang` 是纯 ASCII + 含 `-` + 不在名字列 → 怀疑是存量 slug
+2. LLM 试着 `gen avatar profile dr-wang`(后端单查仍支持任意 external_id)
+3. **找到**(返回非 null) → 询问:
+   > "我发现你有个分身叫 'dr-wang',要起个友好名字加到你的列表吗?(以后可以用'张医生'这种说法引用,而不是记英文 slug)"
+   - 用户给名字 → 追加一行到 `avatars.md`:`| <用户给的名字> | dr-wang | <profile.created_at 或当天> | <preview_image_url> |`
+   - 用户说"不用" → 直接走生成流程,但下次还会反问
+4. **找不到** → 反问"没训过 dr-wang,要训吗?"
+
+这是**自动迁移路径**,不强制,用户继续用 dr-wang 也行。
+
+## "删了视频 20260515-1430"
+
+视频删除跟分身删除不同 —— 视频 workspace 是用户私有目录,直接删干净,**没有**后端 DB 行残留:
+
+1. 确认 video-id 存在(`ls ~/digital-human/videos/<id>`)
+2. 二次确认:
+   > "确认删除视频 `<id>`($N_SEGS 段, 当前 final-vX.mp4)?
+   > 这会删除整个目录(segments / final-v* / meta.md / history.md),**不可恢复**。"
+3. 用户确认 → `rm -rf ~/digital-human/videos/<id>`
+4. 反馈"已删除视频 `<id>`。"
+
+跟分身删除的对比:分身有后端 DB 行,删 markdown 行 = orphan;视频纯客户端,删目录 = 真删干净。
+
+## "改某段视频"
+
+走 [edit.md](edit.md)。
+
+## 磁盘占用查看
+
+用户问"我用了多少磁盘"/"workspace 多大" → 让 ta 自己跑:
+
+```bash
+du -sh ~/digital-human/
+du -sh ~/digital-human/training/*/
+du -sh ~/digital-human/videos/*/
+```
+
+每个 training/<id>/ ~ 50-200 MB(主要是 source-video);每个 videos/<id>/ ~ 8-20 MB。
+
+v1 不做自动清理。用户嫌占空间:
+- 删旧视频:`rm -rf ~/digital-human/videos/<old-id>`
+- 删某分身训练素材:`rm -rf ~/digital-human/training/<external_id>/`(但保留 `avatars.md` 那一行,以后还能用 ID 生成视频,只是不能重训了)
+
+## "我有哪些分身做过 X"(进阶筛选)
+
+v1 不支持。用户问就告诉:"workspace 不索引'分身 → 视频'反向关系。但可以 `grep` workspace:
+```bash
+grep -l 'external_id: dh-a7f2k9m1' ~/digital-human/videos/*/meta.md
+```
+找出该分身做过的所有视频。如需要常态化筛选请告诉我们。"
+
+## LLM 读 avatars.md 时的健全性校验
+
+每次 Read 后必须做一遍。**规则详见 [SKILL.md "工作空间" 段](../SKILL.md#工作空间)**,单源真值,本段不复述以免 drift。

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

@@ -0,0 +1,291 @@
+# Training Workflow
+
+按顺序执行,每步必走。把用户上传的真人视频训成数字分身(voice + avatar),写入 `~/digital-human/avatars.md`。
+
+## 0. 工作空间初始化(首次训练)
+
+```bash
+mkdir -p ~/digital-human/{training,videos}
+```
+
+如 `~/digital-human/avatars.md` 不存在,**创建**含 SKILL.md 模板的空表(见 SKILL.md "工作空间"段)。
+
+`training/` 用于归档每个分身的训练源素材(原视频 / 提取音频 / 训练元数据);`videos/` 用于每条生成视频的 segments + final。这两个目录的存在让用户后续可以**改某段视频不用全重生**(见 [edit.md](edit.md))、**重训不用重传视频**(下文 §4.5)。
+
+## 1. 询问名字
+
+LLM 主动问:
+
+> "训完叫什么名字?(中英文皆可,1-40 字,以后用这个名字找它)"
+
+用户答 → 直接作为"名字"列的值,**不做任何 normalize / 转换 / 拒绝**。
+
+约束(由 LLM 兜底):
+- 长度 1-40 字符(Unicode 可见字符,禁控制字符 `\x00-\x1f`)
+- 不能跟 `~/digital-human/avatars.md` 现有"名字"列重复
+
+**重名处理**:
+- 反问"你已经有'张医生'了,起个别的(例如'张医生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))
+
+## 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 大小写敏感,混用会取到空值导致路径错误
+```
+
+**碰撞处理**(8 字节 base32 ≈ 64 bit 熵,碰撞概率低但非零,后端 `external_id` 有 UNIQUE 约束 `migrate.ts:44`):
+- onboard insert 失败且 error_code 表明唯一冲突 → 重新生成 + 重试
+- **最多重试 3 次**,3 次失败 → 报错给用户
+
+## 3. 视频规格检查
+
+```bash
+ffprobe -v quiet -print_format json -show_format -show_streams <video-path>
+```
+
+记录:
+- `duration` 总时长
+- `width` × `height` 分辨率
+- `audio` 流是否存在 + sample_rate / channels
+
+判定:
+
+| 项 | 阈值 | 不达标动作 |
+|---|---|---|
+| 视频时长 | < 30s | 中止;要求重传 ≥ 30s 视频 |
+| 视频时长 | 30-119s | 警告"voice OK,但 avatar 质量可能受影响,推荐 ≥ 2min" |
+| 分辨率 | < 720p | 警告但继续 |
+| 音频流 | 缺失 | 中止;视频里没声音怎么训 voice |
+
+**不前置检测多人 vs 单人** — ffprobe 拿不到 speaker count。多人混杂等 voice clone fail 时按 `error_message` 反馈。
+
+## 4. 背景判断 + 决策
+
+spec §13.4 关键约束:训练系统会把整段视频画面(包含背景)整体作为 avatar look 内容,video gen 时**无法用 `background` 参数替换**。
+
+**直接问用户三选一**(不要抽帧 + Read 图判断 — 视觉判断不稳定且贵):
+
+> "训练前确认:这段视频的背景是?
+> A. **白墙 / 棚拍 / 绿幕 / 单色背景**(干净)
+> B. **标准固定场景**(诊室 / 办公桌 / 医院前台 — 这个背景将永远 baked 进分身,后续无法换)
+> C. **户外 / 商场 / 多人 / 杂乱**(脏)"
+
+| 用户选 | 决策 |
+|---|---|
+| A | `--clean-bg` |
+| B | 二次确认:"分身的所有未来视频背景都会是这个场景,可接受吗?" → 接受用 `--accept-baked-bg`;不接受 → 让用户重拍 A 类背景 |
+| C | 强烈劝退,推荐重拍干净背景。如用户坚持产出 → `--accept-baked-bg` + 明确告诉产出视频背景永远是录制时场景 |
+
+**禁止**:
+- ❌ silent 默认 `--clean-bg`(错判脏背景为干净 → 产出脏数据)
+- ❌ 自己抽帧用图像识别判断(视觉判断不稳定 + 浪费 token + 用户答更准)
+
+## 4.5 归档源视频(必须在 §5 拆音频之前)
+
+把用户上传的视频复制到 workspace,后续步骤全部从复制好的副本走:
+
+```bash
+mkdir -p ~/digital-human/training/$EXTERNAL_ID
+cp "<用户上传的视频路径>" ~/digital-human/training/$EXTERNAL_ID/source-video.mp4
+```
+
+**为什么必须先复制**:
+- Claude Code session 里 attach 的视频通常在临时目录(`/tmp/...` 或类似),**session 结束就消失**
+- 后续步骤(拆音频、ffprobe、onboard 上传)都依赖这个文件存在,临时附件中途消失会全部失败
+- 先 cp 到 workspace,等于把素材"焊死"在本地,后续就算 session 关了重启也能续做
+
+**为什么用 `cp` 而不是 `ln`(hardlink)或 `mv`(移动)**:
+- `mv` 删原文件 → 用户原始路径丢失,违和
+- `ln` 跨 filesystem 会失败,而且加 LLM 出错面(决策详见 SPEC `2026-05-15-digital-human-segment-persistence.md` 决策 #13)
+- `cp` 简单可靠,磁盘代价可接受(2-5 min 1080p 视频 ~ 50-200 MB,个人开发机能扛)
+
+**用户原始路径不动**,只是我们这边存一份副本。
+
+## 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"
+```
+
+取前 90 秒单声道 WAV,够 voice clone。路径固定 = `training/<external_id>/source-audio.wav`,不用 `mktemp`(单分身一个 audio,无并发覆盖问题)。
+
+## 6. 触发训练(onboard)
+
+```bash
+gen avatar onboard "$AUDIO_PATH" ~/digital-human/training/$EXTERNAL_ID/source-video.mp4 \
+  --external-id "$EXTERNAL_ID" \
+  --clean-bg          # 或 --accept-baked-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 完全不感知。
+
+返回 JSON:
+```json
+{ "external_id": "dh-a7f2k9m1", "voice_task_id": "<uuid>", "avatar_task_id": "<uuid>", "status": "pending" }
+```
+
+如返回唯一冲突错误 → 回到 §2 重新生成 external_id,重试(最多 3 次)。
+
+## 6.5 写 train-meta.md(归档训练元数据)
+
+onboard 提交成功后,写训练元数据到 workspace:
+
+```bash
+cat > ~/digital-human/training/$EXTERNAL_ID/train-meta.md <<EOF
+# Training: $DISPLAY_NAME (external_id: $EXTERNAL_ID)
+
+| 字段 | 值 |
+|---|---|
+| 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) |
+| 源视频时长 | (从 §3 ffprobe 输出取) |
+| 源视频分辨率 | (同上) |
+| preview_image_url | (训完 §8 拉到后回填这一行) |
+EOF
+```
+
+**为什么单独写文件**:
+- avatars.md 是分身索引(用户看 + LLM 用),只放最关键字段(名字 / external_id / 训练时间 / preview)
+- train-meta.md 是分身**完整训练记录**,含 task_ids / 背景决策 / 源视频 specs 等用户不关心但**重训时关键**的信息
+
+## 7. Poll 直到完成
+
+```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
+```
+
+> **Fallback**:如果 `gen task get` 不可用,直接打后端 endpoint:
+> ```bash
+> curl -s -H "Authorization: Bearer $OPTIMA_TOKEN" "$GENERATION_API/api/task/$TASK_ID" | jq
+> ```
+
+期望耗时:
+- voice clone:30s - 2 min
+- avatar train:5 - 30 min
+- spec §13.2:trained look 在训练完成后还有短期 race(几分钟到 1 小时);**onboard 阶段不阻塞**
+
+任一 fail → 看 `error_message`:
+- voice clone fail → 大概率音频质量(噪声 / 多人混杂)→ 提醒用户重传清晰音频
+- avatar train fail → 视频问题(时长 / 分辨率 / 内容)→ 给具体 error 让用户判断
+
+## 8. 拉 profile 拿 preview
+
+两个 task 都 completed 后:
+
+```bash
+gen avatar profile "$EXTERNAL_ID"
+```
+
+返回(关键字段):
+```json
+{
+  "external_id": "dh-a7f2k9m1",
+  "heygen_voice_id": "f7a8ea9f...",
+  "heygen_avatar_look_ids": ["04182555..."],
+  "voice_status": "complete",
+  "avatar_status": "completed",
+  "preview_image_url": "https://...preview.jpg"
+}
+```
+
+> DB 字段名 `heygen_*` 是历史命名,代码层不动。**LLM 给用户报告时不冒泡 UUID**(只展示名字 + preview)。
+
+**回填 `train-meta.md`**:把 §6.5 写的 train-meta.md 里 `preview_image_url` 那行补上真值(profile 拿到的 URL)。
+
+(可选)下载 preview 缓存到本地:
+```bash
+curl -s -o ~/digital-human/training/$EXTERNAL_ID/preview.jpg "$PREVIEW_URL"
+```
+加快"列我的分身"渲染速度,避免每次都打外网。
+
+## 9. 追加一行到 `avatars.md`
+
+```bash
+TODAY=$(date +%Y-%m-%d)   # 真实日期,不凭印象
+```
+
+往 `~/digital-human/avatars.md` 末尾追加一行(用 Edit/Read 工具操作 markdown 表):
+
+```
+| <用户给的名字> | <external_id> | <TODAY> | <preview_image_url> |
+```
+
+## 10. 给用户报告
+
+> "✅ 张医生 训练完成 [preview 图]
+> 训练素材已存档到 `~/digital-human/training/张医生/`,以后想重训不用再上传视频。
+> 以后说'用张医生做视频说...'即可。"
+
+**不输出** voice_id / avatar_id / external_id(UUID 全部不冒泡)。
+
+---
+
+## Edge cases
+
+### 1. 用户没给视频但说"训练 X"
+
+反问:"X 的视频附件没看到,把视频发我(2-5 min,正面拍摄,干净背景)。"
+**不要** 凭印象搜索 X 的公开视频去训(法律 + 同意书风险)。
+
+### 2. 用户上传多个视频
+
+主动列出最近上传的视频文件(文件名 + 时长),**让用户选哪一个用于训练**。不要假设最后一个 = 训练用。
+
+### 3. 用户给了视频但意图模糊
+
+视频可能是"复刻这条视频" / "把这条视频翻译" / "训分身"。如果不明确是后者,**不要触发本 skill**。问一句:
+> "你想要 (a) 用这条视频训练 X 的数字分身(以后用分身做新视频),还是 (b) 复刻这条视频做产品宣传 / (c) 把视频翻译成其他语言?"
+
+分别走 digital-human / video-gen / video-gen 视频翻译。
+
+### 4. 用户中途改主意
+
+- 想换视频 → 旧 task 让它跑完(训练资源已扣,不阻塞);用户拿新参数重新走 §1-§7
+- 想取消 → `gen task cancel <task_id>` 各自 cancel(尽力而为,上游可能已 in-flight 不可中止)
+
+---
+
+## Common Mistakes
+
+| ❌ Mistake | ✅ 正确做法 | 为什么 |
+|---|---|---|
+| 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 |
+| 凭印象搜公开视频去训(§Edge 1) | 反问用户上传视频 | 法律 + 同意书风险,无授权训练他人形象 |
+| 假设最后一个上传的视频 = 训练用(§Edge 2) | 列出所有让用户选 | 错训不该训的人 |
+| 视频含糊意图直接触发 skill(§Edge 3) | 三岔反问 (a) 训分身 / (b) 复刻 / (c) 翻译 | 错走训练流程浪费训练配额(训练成本 > 复刻) |
+| 没视频但有意图就调 onboard | 反问"把视频发我",并明确质量要求 | onboard 没视频会立即失败,白调一次 |
+| 训完报告里写 voice_id / avatar_id UUID | 只展示名字 + preview | UUID 不冒泡是核心 UX 原则 |
+| 跳过 §9 写 avatars.md | 训完必须写一行 | 不写下次会话用户说"用张医生"找不到,得记 dh-* slug |