@optima-chat/optima-agent 0.9.3 → 0.9.4

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

@@ -7,6 +7,25 @@ description: "帮商家用 AI 生成产品视频（社媒投放 / 产品详情
 
 帮电商商家用 AI 视频生成替代传统实拍。核心价值：**帮用户形成一份满意的 Storyboard，然后按 Storyboard 执行生成。**
 
+## Global Rules
+
+优先级高于任何 pipeline 步骤。违反会导致泄漏、超支或数据丢失。
+
+1. **User-facing 不出现模型名或服务名**
+   status / 成本 / 进度 / 错误 / 总结 统一用"标准模式 / 高保真模式 / 视频生成中"。模型名仅用于 skill 内部路由，**代码注释里的也不能抄给用户**。`--provider piapi` 作为 CLI flag 的字面值可存在，但不要把整条命令回显给用户。
+
+2. **花钱前必走 COST-GATE**
+   任何 `gen video` / `gen image` 调用之前必走一次成本确认（§执行生成）。**Fast-path、迭代、重试均无例外**。成本按秒估算：`Σ(seg.duration_s) × per_second_rate_usd[mode]`，rate 从所选模板的 `production_cost.per_second_rate_usd` 读取。rate 为 TBD 时成本前缀"~"明示粗估。
+
+3. **任何 pipeline 第一步必须 Per-video init**
+   分析 / Storyboard / Plan / 生成 / Review 执行前先跑 §Per-video init（建目录 + cd）。否则后续 write 写错位置。迭代场景用 `{旧id}-vN`。
+
+4. **Anti-fabrication**
+   未在本 skill 显式列出的命令 / flag / 参数，**不允许凭印象拼**。要么走 §相关工具 里的精确命令，要么 ask user。ffmpeg / gen / scout 子命令同样适用。
+
+5. **git 只前进，不 reset**
+   每步完成立刻 commit。迭代用 `-vN` 目录不覆盖。**禁止** `git reset --hard` / `git checkout .` / `git clean -f`。
+
 ## 工作目录
 
 所有状态都在 `~/video-gen/`，整个目录是一个 git repo。
@@ -44,26 +63,31 @@ description: "帮商家用 AI 生成产品视频（社媒投放 / 产品详情
    - 有 → 在回复用户前主动提一次："你有 N 个视频没完成..."
    - 无 → 继续步骤 3
 3. **读 preferences.md** 和 **history.md**
-4. **按用户意图分流**：
+4. **按用户意图分流**（**任何路径的第一步都是 Per-video init，见下文专段**）：
    - 有视频 + 有产品图 → Fast-path：直接走「分析 → Storyboard → Production Plan → 生成」全管道
    - 有视频，无产品图 → 问"换成哪个产品？"
-   - 只有产品图/文字，信息充分 → Fast-path：走「Storyboard → Production Plan → 生成」
-   - 只有产品图/文字，信息不足 → 问"这个视频用在哪？"
-     - 社媒 → "要不要找 3 个爆款参考？"
-       - 要 → 走「参考发现」，用户选后继续管道
-       - 不要 → 从模板构建 Storyboard
-     - PDP → 从 PDP 模板构建 Storyboard
+   - **只有产品图（社媒目标）** → **爆款驱动默认流程**：
+     1. agent 从产品图 + preferences 推断**品类 + 平台 + 关键词**
+     2. 走「参考发现」（见下段）：自动跑 scout 取 Top 3 爆款
+     3. 展示候选 → 用户选一条 → 进「分析源视频」→ 复刻 storyboard
+     4. 用户说**"跳过"/"不要参考"** → 从模板构建 storyboard（opt-out 必须显式）
+   - **只有产品图（PDP 目标）** → 从 PDP 模板构建 Storyboard（PDP 场景**不走爆款**，因为 PDP 视频不是社交叙事）
+   - **用户意图模糊**（没说社媒 vs PDP）→ 问**一个**关键问题确认 → 再分流
    - "再试 / 更活泼 / 改 X" → 走「迭代」
 
+**为什么社媒默认走爆款驱动**：单靠模板 + 产品图生成的视频是"平均水平"——爆款的节奏 / Hook / 卡点来自具体成功案例，不来自抽象模板。agent 主动拉爆款 → 分析 → 复刻，是把 video-gen 从"出得来"升级到"出得好"。用户想要纯模板产出 → 一句"跳过"即可，opt-out 成本为 0。
+
 **Fast-path 触发条件**（必须全部满足才走 fast-path，否则先问）：
 
 | 场景 | 必须有 | 可从 preferences 兜底 |
 |---|---|---|
-| **复刻** | 视频文件/链接 + 产品图 | 调性、平台 |
-| **生成（社媒）** | 产品图 + 明确的意图动词（"做视频"/"生成"） + 平台 | 调性 |
+| **复刻（用户自带参考）** | 视频文件/链接 + 产品图 | 调性、平台 |
+| **生成（社媒）** | 产品图 + 明确意图动词 + 平台 | 调性；**品类关键词从产品图 + preferences 推**，不够时追问 1 次 |
 | **生成（PDP）** | 产品图 + 明确说"详情页"/"PDP" | 调性 |
 | **迭代** | 明确的 delta（"更活泼"/"暖一点"）+ history 无歧义匹配 | — |
 
+**社媒 Fast-path 的"爆款发现"不算"问用户"**——agent 自动拉 Top 3 + 展示让用户选 1 条是**必要数据输入**（和"选模板"同级），不是"审批"。用户选条或"跳过"都保持在 Fast-path 内。
+
 **Fast-path 行为**：Storyboard 展示后告知而非审批，但**生成前必须告知预估成本**（见「执行生成」的成本确认）。用户可随时喊停。
 
 ## First-time init
@@ -130,47 +154,94 @@ git add -A && git commit -m "init: video-gen workspace"
 
 每次有新信息写入 preferences → `git commit -m "prefs: update <field>"`
 
-## 参考发现（仅社媒 + 用户同意时）
+## 参考发现（社媒默认触发 · 用户可跳过）
 
-1. 根据产品品类 + 平台，调 scout 相关命令搜近期爆款
-2. 品牌契合 + 产品形态匹配过滤
-3. 展示 3 个候选：平台 + 时间 + 指标 + 风格摘要
-4. **用户选一个** → 继续「分析源视频」
-5. "都不要" → 从模板构建 Storyboard
+**触发**：按上方「分流」的第 3 条（社媒目标 · 无用户自带参考视频）自动进入。
 
-**绝不自动选参考。**
+**不触发**：用户自带参考视频（走"分析源视频"）/ PDP 目标 / 用户明确说"跳过"。
 
-## 分析源视频
+### 步骤
 
-有源视频时执行。产出 `videos/{id}/analysis.md`。
+1. **推断品类 + 关键词**（不打断用户）
+   - 从产品图（文件名、用户文字、先前 preferences）推断，例："懒人拖把" → 品类=家居清洁 / 关键词="拖把"
+   - preferences 有 `default_platform` 用 preferences；无则按"TikTok（海外）/ 抖音（国内）"默认，等用户纠正
+   - 关键词低置信（产品图模糊或全新品类）→ 追问 1 次 `"产品属于哪个品类？（如美妆/家居/数码）"`，否则不打断
+2. **调 scout**
+   - 平台=TikTok → `scout tiktok search-videos "<关键词>" --region <US|...>`
+   - 平台=抖音 → `scout douyin search-videos "<关键词>"` 或 `scout douyin hot-search`（按品类筛）
+   - 其他平台：按 scout 可用命令对应（见 `storyboard-learning/analyses/2026-04-21-viral-top5-reverse-breakdown.md` 的 SOP 段）
+3. **过滤 + 排序**：品牌契合（不违反 preferences.forbidden）+ 产品形态匹配 + 按 likes 降序取 Top 3
+4. **展示 3 个候选**：平台 / 时间 / 指标（点赞 · 分享 · 评论）/ 风格摘要（hook 类型 · 时长 · BGM 类型）
+5. **用户选一条** → 写入 `assets/reference.mp4` 或保留 URL → 继续「分析源视频」
+6. **用户说"跳过"/"都不要"/"不要参考"** → 记录到 preferences.Learned（"此类任务偏好无参考"）→ 从模板构建 Storyboard
+
+### 硬规则
 
-1. 创建项目目录：
+- **绝不自动选参考**——Top 3 必须让用户选 1 条（或明说跳过）
+- **"跳过"必须是一键**，不问理由（用户说过就记 preferences，未来同类不再默认拉爆款）
+- **scout 调用成本算进 COST-GATE**——参考发现本身消耗 Optima credits（scout API 不免费）
+
+## Per-video init
+
+**触发条件**：走任何管道（分析 / Storyboard / Production Plan / 生成）前**必须**先执行此段。否则后续 write 操作会失败或写到错位置。
+
+**每次新 video session 第一步**：
 
 ```bash
+# <slug> = 由 agent 从产品名 / 用户意图提取的 kebab-case 短语（前 20 字符内）
+# 例："懒人拖把" → "lazy-mop"；"免洗洗手液" → "no-rinse-sanitizer"
 VIDEO_ID="$(date +%Y%m%d-%H%M)-<slug>"
 mkdir -p ~/video-gen/videos/$VIDEO_ID/{assets/keyframes,prompts,clips}
+cd ~/video-gen/videos/$VIDEO_ID
+echo "Using VIDEO_ID=$VIDEO_ID"
+```
+
+**迭代场景**（用户说"再试" / "改 X"）：保留旧版本、写入新目录。用自动递增版本号防覆盖：
+
+```bash
+BASE_ID="<旧 video-id>"   # 例如 20260422-1430-product-demo
+n=2
+while [ -d ~/video-gen/videos/${BASE_ID}-v${n} ]; do n=$((n+1)); done
+VIDEO_ID="${BASE_ID}-v${n}"
+mkdir -p ~/video-gen/videos/$VIDEO_ID/{assets/keyframes,prompts,clips}
+cd ~/video-gen/videos/$VIDEO_ID
+echo "Using VIDEO_ID=$VIDEO_ID"
 ```
 
-2. 保存素材到 `assets/`
+**场景路由**：
+
+| 用户输入 | 触发 Per-video init 的路径 |
+|---|---|
+| 产品图 + 意图（无参考视频） | 进 Storyboard 前先跑 Per-video init |
+| 产品图 + 参考视频 | 进「分析源视频」前先跑 Per-video init |
+| 迭代（沿用旧 video） | 建 `{旧id}-vN` 目录（N 自动递增）+ cd |
+
+## 分析源视频
+
+**前置**：已完成 Per-video init。
+
+有源视频时执行。产出 `videos/{id}/analysis.md`。
+
+1. 保存素材到 `assets/`
 
-3. ffmpeg 场景检测：
+2. ffmpeg 场景检测：
 
 ```bash
 ffprobe -v quiet -print_format json -show_format -show_streams assets/reference.mp4
 ffmpeg -i assets/reference.mp4 -vf "select='gt(scene,0.3)',showinfo" -vsync 0 -f null - 2>&1 | grep showinfo
 ```
 
-4. 每段抽 3 帧（首/中/尾）：
+3. 每段抽 3 帧（首/中/尾）：
 
 ```bash
 ffmpeg -i assets/reference.mp4 -vf "select='eq(n\,<FRAME_NUM>)'" -vsync 0 assets/keyframes/seg-<N>-<pos>.jpg
 ```
 
-5. 读取关键帧图片，分析每段的 subject / composition / camera / lighting / palette / description
+4. 读取关键帧图片，分析每段的 subject / composition / camera / lighting / palette / description
 
-6. 验证 ffmpeg 切段合理性（修正软切/漏切）
+5. 验证 ffmpeg 切段合理性（修正软切/漏切）
 
-7. 以表格写入 `analysis.md`：
+6. 以表格写入 `analysis.md`：
 
 ```markdown
 # Analysis
@@ -203,9 +274,11 @@ ffmpeg -i assets/reference.mp4 -vf "select='eq(n\,<FRAME_NUM>)'" -vsync 0 assets
 
 ## 形成 Storyboard
 
+**前置**：已完成 Per-video init。
+
 核心产出。**用户语言写，用户能读能改。**
 
-1. 读输入：preferences + analysis（如有）+ history 匹配 liked 记录 + 匹配模板（从 `$CLAUDE_SKILL_DIR/templates/` 读）
+1. 读输入：preferences + analysis（如有）+ history 匹配 liked 记录 + 匹配模板（**先读 `$CLAUDE_SKILL_DIR/templates/INDEX.md` 路由决定选哪个，再读选中的那一份**，不要把所有模板都读一遍）
 
 2. 有模板则以模板为骨架填入产品/品牌信息；否则从零构建
 
@@ -232,6 +305,8 @@ ffmpeg -i assets/reference.mp4 -vf "select='eq(n\,<FRAME_NUM>)'" -vsync 0 assets
 | 1 | 0-1.5s | <内容> | <运镜> | <替换或"原创"> |
 | ... |
 
+> **段时长约束**：推荐 2-10s。<2s 或 >10s 需在展示时警告用户（不阻断）。单段 >15s 必须拆段，不允许进入 Production Plan。段时长精度到 0.5s（3.73s 四舍五入到 3.5s）。
+
 ## Hook
 <第 1 秒如何抓注意力>
 
@@ -250,38 +325,69 @@ ffmpeg -i assets/reference.mp4 -vf "select='eq(n\,<FRAME_NUM>)'" -vsync 0 assets
 
 ## 产出 Production Plan
 
+**前置**：已完成 Per-video init + Storyboard。
+
 Storyboard 确认后自动推导。用户通常不改。
 
-1. 选策略：
+### 0. 音频决策（先于策略选择）
+
+**两种模式都默认有音频**（`gen video --audio` 默认开启），**真正差异在"对口型精度"**：
+
+- **标准模式**（wan2.6，no `--provider`）：自动配音，对口型精度低。适合无人物讲话 / 不叠原音频的场景
+- **高保真模式**（`--provider piapi`，Kling 3.0）：对口型精度高，适合讲话镜头 / 叠原音频场景
+- **彻底无音频**：任一模式加 `--no-audio`
+
+**复刻 + 原音频叠加**的真实风险：用标准模式生成的视频，嘴型节奏和原音频不匹配（wan2.6 对口型弱）→ 叠原音听起来"嘴型错位"。所以模式选择必须先过这道决策：
+
+| 场景 | 决策 | 模式 | CLI flag |
+|---|---|---|---|
+| 复刻 + 参考带音频，用户想保留原音频 | 强制高保真（标准模式对口型太差，叠原音会明显错位）| 高保真 | `--provider piapi` |
+| 复刻 + 参考带音频，愿意重生音频 | 高保真（默认）| 高保真 | `--provider piapi` |
+| 纯生成，未指定音频需求 | **问**："需要音频吗？（人声 / 旁白 / 音效）" | ↓ | ↓ |
+| &nbsp;&nbsp;→ 需要人声 / 旁白 | 高保真 | 高保真 | `--provider piapi` |
+| &nbsp;&nbsp;→ 只要环境配音，不讲话 | 标准（便宜 ~10×，自动配音够用）| 标准 | *(默认)* |
+| &nbsp;&nbsp;→ 不要音频（后期自配 BGM）| 标准 + 无音频 | 标准 | `--no-audio` |
+| 高度还原 / 严格对口型 / premium | 强制高保真（忽略音频决策）| 高保真 | `--provider piapi` |
+| 用户明确说"便宜版" / "省 credits" | 标准 + 警告"对口型精度低"| 标准 | *(默认)* 或 `--no-audio` |
+
+**Fast-path 集成**：Fast-path 不单独问音频，在 COST-GATE 里追加"含同步音频（对口型精度依模式而定），不需要可说'静音版'"。用户喊"静音版" → 回退标准模式 + `--no-audio`，重走 COST-GATE。
 
-| 特征 | 策略 | 默认 provider |
+**冲突检测**：复刻场景 + 用户说"便宜版" → 不直接降级，先问：
+
+> 复刻场景用标准模式对口型精度低，叠原音频会听起来错位。确认要降级吗？
+
+### 1. 选策略
+
+| 特征 | 策略 | 模式（见 §0） |
 |---|---|---|
-| 1 镜头，无参考 | single-shot | DashScope（默认） |
-| 多镜头，无参考 | multi-shot-concat | DashScope（默认） |
-| **有参考，大致复刻** | **clone-loose** | **`piapi`（Kling 3.0）** |
-| **有参考，高度还原** | **clone-strict** | **`piapi`（Kling 3.0）** |
-| PDP 多卖点 | pdp-feature-concat | DashScope（默认） |
-| 人物讲话 + 严格对口型 | talking-head | `piapi`（Kling 3.0） |
-| 用户明确要求"便宜版" / "省 credits" | 任一 | DashScope |
-| 用户明确要 premium 质量 | 任一 + premium | `piapi` |
+| 1 镜头，无参考 | single-shot | 依 §0 |
+| 多镜头，无参考 | multi-shot-concat | 依 §0 |
+| 有参考，大致复刻 | clone-loose | 依 §0（含参考音频时强制高保真）|
+| **有参考，高度还原** | **clone-strict** | **高保真（强制）** |
+| PDP 多卖点 | pdp-feature-concat | 依 §0 |
+| **人物讲话 + 严格对口型** | **talking-head** | **高保真（强制）** |
+| 用户明确要 premium 质量 | 任一 + premium | 高保真（强制）|
 
-**规则**：**凡是有参考视频的复刻场景，默认走 Kling 3.0**。理由：复刻任务对主体一致性和视觉保真度要求高，Kling 3.0 质量明显优于 DashScope，省的 credits 不值得牺牲质量。只有当用户明确说"便宜版"或"省 credits"时才降级到 DashScope。纯生成（无参考）继续用 DashScope 默认，性价比最好。
+**高保真模式 CLI flag**：`--provider piapi`。标准模式不加 flag。
 
-2. 写 `videos/{id}/production-plan.md`：
+### 2. 写 `videos/{id}/production-plan.md`
 
 ```markdown
 # Production Plan
 
 ## 策略
 <策略名>
+模式: <标准 / 高保真>（依 §0 决策）
 原因: <选择理由>
 
 ## 步骤
-| Step | 工具 | 输入 | 输出 | 依赖 | Prompt 摘要 |
-|---|---|---|---|---|---|
-| 1 | <工具> | <输入> | <输出> | — | <prompt 或 N/A> |
+| Step | 工具 | 输入 | 输出 | 依赖 | duration_s | seed | negative | audio | Prompt 摘要 |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 | <工具> | <输入> | <输出> | — | <storyboard 段时长> | <seed 或 `-`> | <NEGATIVE 短摘要 或 `-`> | <`default` / `--no-audio`> | <prompt 或 N/A> |
 | ... |
 
+**seed 规则**：同一产品的镜头（如 template PRODUCT_LOCK 指定的 #4/#5/#6/#9）**共用一个 seed**（任选一个固定整数记录下来）。PAIN / 场景段（如 #1/#2/#3）无产品时可填 `-`。
+
 ## 验收标准
 - 比例: <从 Storyboard>
 - 时长: <从 Storyboard ±20%>
@@ -289,27 +395,36 @@ Storyboard 确认后自动推导。用户通常不改。
 - CTA: <从 Storyboard>
 ```
 
-3. 为每个需 prompt 的步骤生成 `prompts/seg-N.txt`
+`duration_s` 字段直接 = storyboard 该段时长（精度 0.5s）。不允许四舍五入到 5 或 10。
+
+### 3. 为每个需 prompt 的步骤生成 `prompts/seg-N.txt`
 
-4. `git commit -m "video: plan $VIDEO_ID — <strategy>"`
+### 4. `git commit -m "video: plan $VIDEO_ID — <strategy>"`
 
 ## 执行生成
 
+**前置**：已完成 Per-video init + Storyboard + Production Plan。
+
 <COST-GATE>
 **生成前成本确认（必做，包括 Fast-path）**：在执行任何 `gen video` / `gen image` 调用之前，必须向用户展示一次成本摘要：
 
-> 即将生成 N 段视频（策略: <策略名>），预计：
+> 即将生成 N 段视频（策略: <策略名>，模式: <标准 / 高保真>），预计：
 > - 调用次数: N 次 gen video + M 次 gen image（首帧编辑）
+> - 总时长: <Σ seg.duration_s>s
 > - 预估耗时: ~X 分钟
 > - 预估成本: ~$Y（扣 Optima credits）
+> - 音频: <含同步音频 / 无音频>
+>
+> <若高保真模式>不需要音频可说"静音版"降级到标准模式。</若高保真模式>
 >
 > 继续？
 
 用户说"继续"/"好"/"OK" → 开始执行。
 用户说"太贵"/"换个便宜的" → 回到 Production Plan，换策略（如 strict → loose）。
+用户说"静音版" → 若当前高保真且非强制（clone-strict / talking-head / premium）则回退标准模式，重走 COST-GATE；否则告知冲突。
 用户不回应超过合理时间 → 不执行，等用户。
 
-**即使是 Fast-path 也必须走这一步。** 这是花钱步骤的唯一确认点。
+**即使是 Fast-path 也必须走这一步。** 这是花钱步骤的唯一确认点。**迭代、重试同样无例外。**
 </COST-GATE>
 
 按 production-plan.md 步骤表逐步执行。
@@ -328,20 +443,34 @@ Storyboard 确认后自动推导。用户通常不改。
 **工具调用**：
 
 ```bash
-# 纯生成（无参考视频）— DashScope Wan 2.6，便宜快（默认）
+# 标准模式（自动配音对口型弱，适合纯生成 / 环境音 / 无讲话）
 gen video <input_image> \
-  --prompt "<from prompts/seg-N.txt>" \
-  --duration <5|10> \
+  --prompt "$(cat prompts/seg-N.txt)" \
+  --negative "$NEGATIVE" \
+  --duration <seg_duration_s> \
   --resolution <720P|1080P> \
+  --seed $PRODUCT_SEED \
+  $AUDIO_FLAG \
   -o clips/seg-<N>.mp4
 
-# 复刻（有参考视频）/ 对口型 / premium 质量 — Kling 3.0（默认）
+# 高保真模式（对口型精度高，复刻带原音频 / 讲话 / premium）
 gen video <input_image> \
-  --prompt "<from prompts/seg-N.txt>" \
-  --duration <5|10> \
+  --prompt "$(cat prompts/seg-N.txt)" \
+  --negative "$NEGATIVE" \
+  --duration <seg_duration_s> \
   --provider piapi \
+  --seed $PRODUCT_SEED \
+  $AUDIO_FLAG \
   -o clips/seg-<N>.mp4
 
+# 变量约定（production-plan.md 每个 step 提供）：
+#   $NEGATIVE      = 该镜的 negative prompt（从 storyboard 或 template NEGATIVE 字段）
+#   $PRODUCT_SEED  = 锁定产品一致性的 seed（同一产品的所有镜头共用一个值，如 #4/#5/#6/#9）
+#   $AUDIO_FLAG    = 空字符串（默认有音频）/ "--no-audio"（用户说静音版）
+
+# 注意 --seed 必须 wire：否则每段 gen 产品外观随机变，templates 的 PRODUCT_LOCK
+# 规范（same seed across shots）会失效，电商视频产品一致性崩塌。
+
 # 首帧编辑（产品替换）— 双图模式
 gen image "<编辑指令>" -i <原始首帧> -i <产品图> -o assets/keyframes/seg-<N>-edited.jpg
 
@@ -355,22 +484,13 @@ gen task cancel <task_id>
 gen task retry <task_id>
 ```
 
-**Provider 选择逻辑**（在产出 Production Plan 时决定）：
+**模式选择**：按 §产出 Production Plan §0 音频决策 + §1 策略表决定。命令层面差异仅是否加 `--provider piapi`：高保真加，标准不加。
 
-| 场景 | Provider | 理由 |
-|---|---|---|
-| **所有复刻场景（有参考视频）** | **`--provider piapi`（Kling 3.0）** | **默认。主体一致性、保真度明显更高** |
-| 人物讲话 + 严格对口型 | `--provider piapi` | Kling 3.0 口型精度更高 |
-| 用户明确要 premium 质量 | `--provider piapi` | — |
-| 纯生成（无参考，社媒短视频 / PDP 展示） | 默认（DashScope） | 无参考时质量差异较小，便宜 ~10x |
-| 用户明确说"便宜版"/"省 credits" | 默认（DashScope） | 用户主动降级 |
-| 高质量严格复刻（用户明确要求 premium） | `--provider piapi` | Kling 3.0 保真度更高 |
-
-**时长限制**：`gen video --duration` 仅支持 5 或 10 秒。多段视频用多次 `gen video` + `ffmpeg concat` 拼接。
+**Duration**：`--duration` 直接传 production-plan.md 里该步的 `duration_s`（= storyboard 段时长，精度 0.5s）。**不允许**四舍五入到 5 或 10。多段视频仍用多次 `gen video` + `ffmpeg concat` 拼接（按段拆是 storyboard 层的决定，不是 duration 层的）。
 
 **每步完成后**：
 - 删 `seg-N.pending.json`
-- 写 `seg-N.meta.json`（duration / resolution / status）
+- 写 `seg-N.meta.json`（duration_s / resolution / mode / has_audio / status）
 - `git commit -m "video: receive $VIDEO_ID seg-N"`
 
 **全部完成**：`git commit -m "video: done $VIDEO_ID"`
@@ -412,7 +532,9 @@ gen task retry <task_id>
    - "效果不对" → storyboard 不动 → 改 production-plan → 重新生成
 4. 新 video-id = `{旧id}-v2`，history 的 parent 指向旧 id
 
-## 核心规则
+## 核心规则（流程偏好）
+
+> 硬规则见 §Global Rules。以下为流程偏好。
 
 - **信息够就直接做（Fast-path）**——最重要的一条
 - **Storyboard 是核心产物**，所有路径汇聚于它
@@ -422,14 +544,14 @@ gen task retry <task_id>
 - **参考视频永远让用户选**
 - **生成完给迭代建议**
 - **新会话有未完成任务先告知一次**
-- **不暴露模型名**——说"视频生成中"
-- **git 记录一切，不允许 reset**
 
 ## 错误处理
 
 | 故障 | 处理 |
 |---|---|
 | gen 返回 failed | 重试 1 次 → 仍失败告知用户 |
+| gen video 返回 "duration out of range" | **不**自动重试/裁剪，告知用户并建议调整该段 storyboard 时长后重新 Production Plan |
+| 复刻场景用户选标准模式（便宜版） | 告知"标准模式无音频，与原音频叠加会嘴型错位"，问是否确认降级；确认后在 COST-GATE 明示"无音频" |
 | ffmpeg 失败 | 检查输入完整性，告知用户 |
 | 源视频无法下载 | 建议手动下载后重试 |
 | scout 无结果 | 告知，转模板构建 |

package/.claude/skills/video-gen/templates/INDEX.md

@@ -0,0 +1,78 @@
+---
+name: templates-index
+purpose: "路由表 · 在读任何模板前先读这份，决定选哪个"
+design_principle: "三问内定位到唯一模板；不能定位的走兜底"
+---
+
+# Templates Index
+
+> **用法**：Agent 在「形成 Storyboard」第 1 步读这份，决定下一步读哪一个具体模板文件。**不要先把 8 个模板全读一遍**——那会白烧 context 而且更容易选错。
+
+---
+
+## 三问路由
+
+### 问 1：放哪里投？
+
+| 投放目的 | 跳到 |
+|---|---|
+| 详情页 / PDP / 产品档案（不带 CTA）| **问 2a** |
+| 社媒（抖音 / TikTok / 小红书 / IG）| **问 2b** |
+| 两者都要 | 先按社媒选，发布时按 `G · 平台 delta` 裁切成 PDP 版本 |
+
+### 问 2a：PDP 重外观还是重卖点？
+
+| 产品特征 | 模板 | 时长 |
+|---|---|---|
+| 重外观 / 造型导向（家居 · 服装 · 配饰 · 玩具 · 礼盒） | `pdp-360-showcase.md` | 15-25s |
+| 重功能 / 参数导向（数码 · 小家电 · 工具 · 办公设备） | `pdp-feature-highlight.md` | 20-30s |
+
+### 问 2b：按产品品类选
+
+| 产品品类 | 模板 | 形态 | 客单带 | 时长 |
+|---|---|---|---|---|
+| 家居 / 日用 / 清洁 / 收纳 | `pain-solution-home.md` | 痛点-解决 | ¥50–300 | 18-22s |
+| 美妆 / 护肤 / 洗护 / 清洁工具 | `before-after-beauty.md` | 效果对比 | ¥80–500 | 20-25s |
+| 数码 / 3C / 智能硬件 | `scene-digital.md` | 场景化 | — | 25-35s |
+| 服装 / 鞋帽 / 配饰 | `multi-point-apparel.md` | 多卖点 | — | 20-30s |
+| 食品 / 饮料 / 零食（重口味体验）| `kol-reaction-food.md` | KOL 反应 | — | 30-45s |
+| 快消 / 咖啡 / 功能饮料 / 办公零食 | `drama-fmcg.md` | 剧情植入 | ¥20–100 | 25-35s |
+
+---
+
+## 疑难消歧（两个看似都能套时）
+
+| 冲突 | 选择规则 |
+|---|---|
+| 家居痛点类 vs 美妆效果类（如清洁美容工具） | 看"证据类型"：销量/评论驱动 → `pain-solution-home`；视觉前后对比 → `before-after-beauty` |
+| 数码场景 vs 家居痛点（如智能清洁机器人） | 看"核心卖点语言"：功能参数主导 → `scene-digital`；解决具体痛点主导 → `pain-solution-home` |
+| 食品 KOL 反应 vs FMCG 剧情（如新品咖啡） | 看"客单 × 使用频次"：¥20-100 高频日饮 → `drama-fmcg`；≥¥50 单次体验性 → `kol-reaction-food` |
+| 服装多卖点 vs PDP 功能 | 看"投放位置"：社媒 → `multi-point-apparel`；详情页 → `pdp-feature-highlight` |
+
+---
+
+## 兜底（现有 8 个模板都不合适时）
+
+先检查是否属于下列**已知不适合**的场景，再决定如何处理：
+
+| 场景 | 推荐做法 |
+|---|---|
+| 客单价 ≥ ¥500 的信任型购买（美容仪 · 高端数码 · 奢品） | 跳过模板，按 KOL 信任型自由 storyboard（长讲解 + 深度测评，现有模板都偏短 + 偏转化） |
+| 香水 / 酒类等**不可视化**品类 | 走 `kol-reaction-food` 的 KOL 反应骨架，但主镜头替换为品牌叙事 |
+| 工业 B2B / 服务类（非实物商品） | 现有模板均不适用，回到零构建 |
+| 品类在表里但形态诉求不符（如美妆做剧情植入） | 优先按品类选，再从 `drama-fmcg.md` 的 B 段骨架**借"剧情结构"** |
+| 多品类组合套装 | 选主品类模板 + 每镜 PRODUCT_LOCK 列出所有 SKU |
+
+**什么时候应该跳过模板**：
+- 复刻场景，源视频形态不在上表覆盖内（按 `analysis.md` 的结构自由构建）
+- 用户显式说"别用模板 / 按我这个参考做"
+- 迭代场景（`再试` / `改 X`），沿用旧 storyboard 即可，不用重新路由
+
+---
+
+## Agent 交互规则
+
+1. **展示选择结果**：选完模板，告诉用户一句话"我准备用 `<模板名>`（<形态描述>）给你做 storyboard，合适吗？"，用户否认才换。
+2. **不展示路由过程**：用户看不到 INDEX 推理过程，只看结论。
+3. **写入 history**：最终用的模板名写进 `history.md` 的 `template` 列，方便迭代时追溯。
+4. **模板冲突优先级**：用户明示 > 品类匹配 > 形态匹配 > 时长匹配。