@optima-chat/optima-agent 0.8.91 → 0.8.93

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

@@ -1,291 +1,199 @@
 ---
 name: video-clone
-description: "Use when user wants to clone/replicate a reference video with product swap, or generate a new video from product images + text descriptions. 触发场景：复刻视频(复刻/翻拍/仿拍/做同款/视频换产品/product swap/爆款复刻/video replication)、用户贴视频链接+产品图要求出同款视频、或用户提供图片/文字描述要求直接生成视频(生成视频/图生视频/做一个视频)。Requires `gen` CLI (gen image / gen video) and Kling 3.0 API (via PiAPI)."
+description: "Use when user wants to clone/replicate a reference video with product swap, or generate a new video from product images + text descriptions. 触发场景：复刻视频(复刻/翻拍/仿拍/做同款/视频换产品/product swap/爆款复刻/video replication)、用户贴视频链接+产品图要求出同款视频、或用户提供图片/文字描述要求直接生成视频(生成视频/图生视频/做一个视频)。Pipeline is a script-based state machine under scripts/ — the generation scripts block until the user confirms the preview bundle. Requires `gen` CLI, video generation API via PiAPI, ffmpeg."
 ---
 
 # Video Clone
 
 通过产品替换或文字描述，复刻源视频或生成全新视频。
 
-## 前置依赖
+> **PR #65 升级注意**：本版本采用单门 (single-gate) 模型。旧版三门
+> (`plan_confirmed` / `prompt_confirmed` / `frame_confirmed`) 已废弃。
+> 旧项目继续用旧脚本完成，新项目全部走本版本流程。
 
-此 skill 依赖以下外部工具，缺失其中任何一项会导致 pipeline 中断：
+## 前置依赖
 
-- **`gen` CLI** — `gen image`（首帧编辑）、`gen video`（Wan 2.6 I2V，无音频时使用）
-- **Kling 3.0 API**（通过 PiAPI，`PIAPI_KEY` 环境变量）— 有音频/口型同步时使用
+- **`gen` CLI** — `gen image`（首帧编辑）、`gen video`（I2V，无音频时使用）
+- **视频生成 API via PiAPI** — 有音频/口型同步时使用。需要 `PIAPI_KEY` 环境变量
 - **ffmpeg / ffprobe** — 场景检测、抽帧、后处理
-- **freeimage.host** — Kling 上传首帧时的公开 URL 托管（详见 [kling-api.md](references/kling-api.md)）
-
-触发 skill 前若检测到 `gen` CLI 不可用，必须立即告知用户，不要进入 Phase 0。
-
-<HARD-GATE>
-在技术方案获得用户确认前，禁止执行以下全部操作：下载源视频、ffprobe/ffmpeg 调用、抽帧、产品图处理、调用 gen image/gen video、调用 Kling API、创建 `gen-output/video-clone/{project}/` 项目目录。Phase 0.1 的"立即做"仅在 **用户已提供本地文件且未明确要求立即执行** 时方可进行；若用户要求"现在就开始/立刻执行/别问了"，这些操作同样被阻断。
-
-在 Phase 1 prompt 获得用户确认前，禁止进入 Phase 2（首帧编辑）。
-在 Phase 2 首帧获得用户确认前，禁止进入 Phase 3（视频生成）。
-
-**USER GATE 不可被用户单方面取消。** 即使用户说"不要问问题/我信任你/自己判断"，仍必须输出技术方案并等待确认。用户可以说"方案我同意，继续"以确认，但不能预先豁免整个 GATE 机制。
-
-每个 Phase 产物必须版本化命名，绝不覆盖已有文件。
-</HARD-GATE>
-
-## Rationalization Counter
-
-以下是 Claude 最常用的"合理化借口"及其反驳。遇到这些想法时必须 STOP。
-
-| Claude 的想法 | 现实 |
-|---|---|
-| "我只是在做 Phase 0 分析，下载视频不算执行" | 下载 = 工具调用 = 被 GATE 阻断。分析要基于用户提供的元数据（URL/文件名/描述），不是基于已下载的文件 |
-| "用户说'急用'/'现在就开始'，所以我可以跳过确认" | 用户的紧迫感不是跳过 GATE 的理由。相反，越急越要用技术方案快速对齐，避免返工 |
-| "用户说'不要问问题，自己判断'" | 这是覆盖 0.2 提问环节的授权，**不是**覆盖 0.4 技术方案展示的授权。自己判断后仍要出方案 |
-| "信息已经完整了，方案只是走过场" | 方案展示是用户发现隐含错误的最后机会。"完整"是你的判断，不是用户的判断 |
-| "用户给了产品图，显然要直接开始" | 给产品图 ≠ 同意全部参数。音频/时长/风格/workflow 选择仍需确认 |
-| "Phase 0.1 的场景检测是只读分析" | ffmpeg 抽帧会写盘，创建项目目录会写盘。任何文件系统写入都属于"执行"范畴 |
-
-若 Claude 发现自己在使用上述任一借口，立刻停止并回到技术方案步骤。
+- **Python ≥ 3.10** — 所有脚本运行时
+- **freeimage.host** — 首帧上传时的公开 URL 托管（详见 [kling-api.md](references/kling-api.md)）
 
-## Phase 0: 理解需求 + 匹配 Workflow + 技术方案
+触发 skill 后第一步：运行 `python scripts/preflight.py`，确认上述依赖。
 
-**在动手之前，先搞清楚用户到底要什么，再看有没有现成的好方案。**
-
-### 0.1 素材收集与初步分析
-
-收集用户提供的所有素材，快速判断任务类型：
-
-```
-用户输入 → 有源视频？
-  ├─ 有视频 + 有产品图 → 视频复刻
-  ├─ 有视频 + 无产品图 → 追问：要替换什么产品？
-  ├─ 无视频 + 有图片   → 纯视频生成
-  └─ 只有文字描述       → 纯视频生成（需要更多信息）
-```
-
-**仅做轻量元数据识别，不执行工具调用**：
-- 识别 URL 平台（TikTok/抖音/Instagram/小红书/本地文件）并告知用户将使用哪种解析方式
-- 如果用户已提供本地视频文件路径，可以读取文件大小/类型（不抽帧）
-- 基于 URL/文件名/用户描述推断大致内容和复杂度
-
-**不要在此步骤**：下载视频、调用 ffprobe/ffmpeg、抽帧、创建项目目录。这些操作属于 Phase 1，必须在技术方案确认后才能执行。
+## 脚本 Pipeline 一览
 
-**例外**：如果用户明确提供了元数据（"这是 15 秒的手持 vlog，单场景"），直接用，不需要自己验证。
-
-### 0.2 关键问题（按需提问，不要一次全问）
-
-根据已有信息，挑最关键的 1-2 个问题问：
-
-| 需要了解的 | 什么时候问 | 示例 |
-|---|---|---|
-| 产品是什么 | 用户没提供产品图 | "你要在视频里展示什么产品？有产品图吗？" |
-| 替换目标 | 源视频里有多个物品 | "视频里有手机和平板，你要替换哪个？" |
-| 视频用途 | 影响风格和质量选择 | "这个视频是发抖音/TikTok/电商详情页？" |
-| 音频需求 | 影响工具选择和成本 | "需要保留人声/口型同步吗？（有音频用 Kling ~$1，无音频 ~$0.02）" |
-| 时长期望 | 源视频很长或用户没说 | "源视频 30s，要复刻全部还是选一段？" |
-| 风格偏好 | 纯生成时 | "想要什么感觉？真实纪录片风？还是广告感？" |
-
-**不要问用户已经给出答案的问题。**
-
-### 0.3 匹配 Workflow
-
-理解需求后，读取 `gen-output/video-clone/workflows/README.md` 查找匹配的 workflow。
+单门模型：所有 prep 脚本自由运行，preview 之后只有一个 GATE。
 
 ```
-读取 workflows/README.md
-  → 找到匹配的 workflow？
-    ├─ 有 → 读取该 workflow 文件，复用其策略（prompt 风格、首帧技巧、参数配置）
-    ├─ 部分匹配 → 基于已有 workflow 调整，执行后保存为新 workflow
-    └─ 无 → 走通用 pipeline，效果好则保存为新 workflow
+preflight.py
+    ↓
+init_project.py           (Phase 0 — 创建项目目录 + 状态文件)
+    ↓
+analyze_source.py         (Phase 1, 复刻才需要)
+extract_frames.py         (Phase 1, 复刻才需要)
+    ↓
+Claude 分析帧网格，写 prompt.md
+edit_first_frame.py       (Phase 2, 复刻才需要)
+写 cost.json              (可选，估算成本)
+    ↓
+preview.py                (汇总所有 prep 产物 → preview_vN.md)
+    ↓
+        [展示 preview 给用户，等待确认]
+    ↓
+confirm.py --quote "<用户原话>"    ← 唯一 GATE
+    ↓
+kling_generate.py         (Phase 3, 有音频)
+gen_video.py              (Phase 3, 无音频)
+    ↓
+assemble.py               (Phase 4 — 标准化/拼接)
+    ↓
+save_workflow.py          (Phase 5 — 可选，效果好时沉淀)
 ```
 
-**Workflow 是经验的积累。** 每个 workflow 记录了在特定场景下"什么方法效果最好"——包括 prompt 写法、首帧编辑策略、工具选择、踩过的坑。随着使用次数增加，workflow 库会越来越强。
-
-详见 [workflow-system.md](references/workflow-system.md)
+`kling_generate.py`、`gen_video.py`、`save_workflow.py` 启动时调用
+`require_gate("preview_confirmed")`，未确认就 exit 1 并打印
+`[HARD-GATE BLOCKED]`。详见 [gate-enforcement.md](references/gate-enforcement.md)。
 
-### 0.4 技术方案（必须展示给用户）
-
-基于分析结果 + workflow 匹配，输出技术方案：
-
-```markdown
-## 技术方案
-
-**任务**: [视频复刻 / 纯视频生成]
-**源视频**: [时长]s, [分辨率], [单/多片段(N段)]
-**产品**: [产品名称+关键特征]
-**参考 Workflow**: [workflow 名称] / 无（新场景）
-
-**执行计划**:
-1. 首帧编辑 — gen image [单图/双图] 替换 [目标物品] 为 [新产品]
-2. 视频生成 — [Kling 3.0(有音频) / gen video(无音频)], [时长]s
-3. 后处理 — [直出 / N段拼接]
+<HARD-GATE>
+**Gate 由脚本机械强制，不是文本约定。** 任何绕过 gate 的方式都会留下证据：
+  1. 手工编辑 `.state/phase.json` — history 字段会显示断点
+  2. 伪造 `--quote` 调用 `confirm.py` — user_quote 字段留痕，事后可倒查
 
-**预估成本**: ~$[X.XX]
-**预估耗时**: ~[N]分钟
+**USER GATE 不可被用户单方面取消。** 即使用户说"不要问问题/我信任你/自己判断"，
+仍必须展示 preview bundle 并等待确认。用户可以说"可以，开始"以确认，但不能
+预先豁免整个 GATE 机制。
 
-确认后开始？需要调整什么？
-```
+每个 Phase 产物必须版本化命名（脚本通过 `_project.next_version()` 自动处理），
+绝不覆盖已有文件。
+</HARD-GATE>
 
-如果匹配到 workflow，技术方案中说明"基于 [workflow名] 的经验，这类视频建议 [具体策略]"。
+## Rationalization Counter
 
-### Anti-Pattern: 跳过 Phase 0
+以下是最常见的"合理化借口"及其反驳。遇到这些想法时必须 STOP。
 
-| 你在想... | 应该做的 |
+| Claude 的想法 | 现实 |
 |---|---|
-| 用户给了视频和产品图，直接开干 | **先出技术方案**，用户可能对时长/音频/风格有想法 |
-| 用户说"急用/立刻开始"，我应该加速 | **紧迫感不是跳过 GATE 的理由**，方案对齐反而避免返工 |
-| 用户说"不要问问题，自己判断"，所以不用确认 | **"不问问题" ≠ "不确认方案"**，自己判断后仍要出方案等确认 |
-| 下载视频/抽帧只是"前期分析"不算执行 | **所有工具调用都被 GATE 阻断**，分析必须基于用户提供的元数据 |
-| 问用户一堆技术问题 | 只问不清楚的，已知信息自己分析 |
-| 不看 workflows 直接走通用流程 | **先查 workflow 库**，可能有更好的方案 |
-| 用户说"复刻这个"，假设我全懂了 | 至少确认：替换什么？要不要音频？ |
-
-**[USER GATE] 用户确认技术方案后，进入 Phase 1。**
-
----
-
-## Phase 1-4: 执行 Pipeline
-
-技术方案确认后，按 Checklist 顺序执行。如果匹配到 workflow，优先按 workflow 的策略执行。
-
-### 视频复刻 Checklist
+| "我只是在做 Phase 0 分析，下载视频不算执行" | 下载 = 工具调用。分析基于用户提供的元数据，不是基于已下载的文件 |
+| "用户说'急用'/'现在就开始'，所以可以跳过确认" | 紧迫感不是跳过 GATE 的理由。越急越要快速对齐，避免返工 |
+| "用户说'不要问问题，自己判断'" | 覆盖提问，**不覆盖** preview 展示。自己判断后仍要出 preview |
+| "信息已经完整了，preview 只是走过场" | preview 是用户发现隐含错误的最后机会 |
+| "我直接运行 kling_generate 只是测试" | 脚本 exit 1，测试什么都看不到 |
+| "我 `python -c 'import _gate; _gate.set_gate(...)'` 自己设 gate" | history 字段暴露没走 confirm.py 正常路径 |
+| "prep 脚本没有 gate，所以我可以随意运行" | prep 脚本确实无 gate — 但 **preview → confirm** 这一步仍是必须的 |
 
-**Phase 1 — Prompt 生成**
-1. **创建项目目录** — `gen-output/video-clone/{project}/`，保存素材到 `source/`
-2. **抽帧分析** — 等间距抽帧 → 帧网格 → Claude Opus 逐帧分析
-3. **生成 prompt** — 中文 6 段 motion prompt → 写入 `prompt.md` → **打印给用户**。详见 [prompt-template.md](references/prompt-template.md)
-4. **[USER GATE] prompt 确认** — 未获确认前禁止进入 Phase 2
+## Phase 0: 理解需求 + 匹配 Workflow
 
-**Phase 2 — 首帧编辑**
-
-5. **首帧编辑** — gen image 产品替换 → 版本化保存到 `frames/`
-6. **[USER GATE] 首帧质检** — 展示给用户，确认产品清晰/位置自然/人物保持/背景一致。未获确认前禁止进入 Phase 3
-
-**Phase 3 — 视频生成**
-
-7. **视频生成** — 对用户只显示 "视频生成中..."。详见 [kling-api.md](references/kling-api.md)
-
-**Phase 4 — 后处理与交付**
-
-8. **后处理** — ffmpeg 标准化/拼接 → `final_v{N}.mp4`。详见 [ffmpeg-commands.md](references/ffmpeg-commands.md)
-9. **更新日志** — 结果写入 `log.md`，交付
-
-### 纯视频生成 Checklist
-
-**Phase 1 — Prompt 生成**
-1. **创建项目目录** — 保存素材到 `source/`
-2. **生成 prompt** — 根据技术方案编写 → 写入 `prompt.md` → **打印给用户**
-3. **[USER GATE] prompt 确认** — 未获确认前禁止进入 Phase 3
+**在动手之前，先搞清楚用户到底要什么，再看有没有现成的好方案。**
 
-**Phase 3 — 视频生成**（无首帧编辑，跳过 Phase 2）
+快速判断任务类型：有源视频 + 产品图 → 视频复刻；无源视频 → 纯视频生成。
 
-4. **视频生成** — 不需要音频用 gen video，需要音频用 Kling 3.0
+**仅做轻量元数据识别，不执行工具调用**。不下载视频、不调 ffprobe、不抽帧。
 
-**Phase 4 — 交付**
+按需提问（不一次全问）：产品是什么、替换目标、音频需求（有音频 ~$1.50/10s，无音频 ~$0.02/10s，扣 Optima credits 由服务端中间件完成）、时长期望。
 
-5. **更新 log.md** — 交付
+先查 `gen-output/video-clone/workflows/README.md` — 完全匹配 → 复用；部分匹配 → 调整；
+无匹配 → 走通用 pipeline。详见 [workflow-system.md](references/workflow-system.md)。
 
-## Phase 5: 经验沉淀
+## Phase 1-2: Prep（自主运行，无 gate）
 
-任务完成且用户满意后，判断是否值得保存为 workflow：
+Prep 阶段所有脚本均无 gate，可自主运行：
 
+```bash
+python scripts/init_project.py --name <slug> --task-type video_clone
+python scripts/analyze_source.py --project <slug> --source <path>
+python scripts/extract_frames.py --project <slug> --source <path>
+# Claude 分析帧网格，写 prompt.md
+python scripts/edit_first_frame.py --project <slug> --image <frame> --product <img>
+# 写 cost.json（可选）
+python scripts/preview.py --project <slug>
 ```
-用户满意？
-  ├─ 满意 + 新场景（无匹配 workflow） → 保存为新 workflow
-  ├─ 满意 + 基于已有 workflow 调整    → 更新已有 workflow 或另存变体
-  └─ 不满意 / 已有 workflow 完全复用   → 不操作
-```
-
-保存时：在 `workflows/` 创建 `.md` 文件，更新 `README.md` 索引。
-详见 [workflow-system.md](references/workflow-system.md)
 
-## Process Flow
+`preview.py` 检查所有 prep 产物是否齐全，输出 `preview_vN.md`（六节）。
 
-```dot
-digraph video_clone {
-    rankdir=TB;
-    node [shape=box];
+**[USER GATE] 把 preview 展示给用户，等待确认，然后运行：**
 
-    "用户确认方案?" [shape=diamond];
-    "用户确认 prompt?" [shape=diamond];
-    "用户确认首帧?" [shape=diamond];
-
-    "素材收集 + 初步分析" -> "关键问题（按需）";
-    "关键问题（按需）" -> "查 workflows/README.md";
-    "查 workflows/README.md" -> "输出技术方案\n（含 workflow 推荐）";
-    "输出技术方案\n（含 workflow 推荐）" -> "用户确认方案?";
+```bash
+python scripts/confirm.py --project <slug> --quote "<用户原话>"
+```
 
-    "用户确认方案?" -> "输出技术方案\n（含 workflow 推荐）" [label="调整"];
-    "用户确认方案?" -> "抽帧分析 + 生成 prompt" [label="确认"];
+## Phase 3-5: 生成 + 后处理 + 沉淀
 
-    "抽帧分析 + 生成 prompt" -> "用户确认 prompt?";
-    "用户确认 prompt?" -> "抽帧分析 + 生成 prompt" [label="修改"];
-    "用户确认 prompt?" -> "gen image 首帧编辑" [label="确认"];
+```bash
+# Phase 3 — 视频生成（需要 preview_confirmed）
+python scripts/kling_generate.py --project <slug> --frame frames/frame_vN.png
+# 或无音频版本：
+python scripts/gen_video.py --project <slug> --frame frames/frame_vN.png
 
-    "gen image 首帧编辑" -> "用户确认首帧?";
-    "用户确认首帧?" -> "gen image 首帧编辑" [label="换seed/调prompt"];
-    "用户确认首帧?" -> "视频生成 → 后处理 → 交付" [label="满意"];
+# Phase 4 — 后处理
+python scripts/assemble.py --project <slug> --single videos/video_vN.mp4
 
-    "视频生成 → 后处理 → 交付" -> "经验沉淀\n（保存/更新 workflow）";
-}
+# Phase 5 — 沉淀（可选）
+python scripts/save_workflow.py --project <slug> \
+    --name <workflow-slug> --scene "<适用场景>" \
+    --rating <1-5> --strategy "<关键策略>"
 ```
 
 ## 铁律
 
-```
-1. 先理解再动手 — 技术方案未确认前不执行任何生成操作
+1. 先理解再动手 — 出 preview 前先跑完所有 prep 脚本
 2. 先查 workflow 再造轮子 — 已有经验不要浪费
 3. 首帧质量决定一切 — 自动选产品最清晰+手部最自然的帧
-4. 让模型做简单的事 — 产品保持静止，人做简单动作
-5. Prompt 质量 = 视频质量 — 必须打印给用户，用户可能修改
-6. 永远不覆盖文件 — 所有产物 v{N} 递增，保留完整迭代历史
-```
+4. Prompt 质量 = 视频质量 — preview 里展示给用户，用户可能修改
+5. 永远不覆盖文件 — 脚本通过 next_version() 自动 v{N} 递增
+6. 不要自己编辑 .state/phase.json — 还不如走 confirm.py 正常路径
 
 ## 项目目录
 
 ```
 gen-output/video-clone/
-├── workflows/                   ← Workflow 经验库
-│   ├── README.md                ← 索引：每个 workflow 一行摘要
-│   └── {workflow-name}.md       ← 具体 workflow
-├── {project}/                   ← 项目产物
-│   ├── source/
-│   ├── frames/
-│   ├── videos/
-│   ├── prompt.md
-│   └── log.md
+├── workflows/             ← Workflow 经验库（README.md 索引）
+└── {project}/
+    ├── .state/phase.json  ← Gate 状态机
+    ├── source/            ← 原始素材 + analysis_vN.json
+    ├── frames/            ← extract_vN/ + frame_vN.png
+    ├── videos/            ← video_vN.mp4 + final_vN.mp4
+    ├── prompt.md  cost.json  preview_vN.md  log.md
 ```
 
-**新任务 vs 续接**：有新源视频/新产品 → 新目录；改 prompt/换 seed → 同目录 v{N}+1。
-跨会话续接时：先读 `log.md` 获取版本号，再读 `prompt.md` 获取当前 prompt。
+新任务 → 新目录；改 prompt/换 seed → 同目录 v{N}+1。
+跨会话续接：先 `python scripts/status.py --project <slug>` 看当前状态和下一步。
 
 ## 工具分工
 
-| 工具 | 职责 |
-|------|------|
-| **Claude Opus** | 需求理解 + 逐帧分析 → 中文 6 段 prompt |
-| **gen image** | 首帧编辑（`-i 源帧 -i 产品图`）|
-| **gen video** | Wan 2.6 I2V（不需要音频） |
-| **Kling 3.0 API** | I2V（需要音频/口型同步）。详见 [kling-api.md](references/kling-api.md) |
-| **ffmpeg** | 抽帧、场景检测、后处理。详见 [ffmpeg-commands.md](references/ffmpeg-commands.md) |
+| 工具 | 脚本 | 职责 |
+|---|---|---|
+| Claude | — | 需求理解 + 逐帧分析 → 中文 6 段 prompt |
+| gen image | `edit_first_frame.py` | 首帧编辑（双图模式） |
+| gen video | `gen_video.py` | I2V（不需要音频） |
+| 视频生成 API | `kling_generate.py` | 有音频/口型同步。详见 [kling-api.md](references/kling-api.md) |
+| ffmpeg | `analyze_source.py` / `extract_frames.py` / `assemble.py` | 抽帧、场景检测、后处理 |
+
+**不要在回复中提及具体模型名称**（如 "Kling 3.0"、"Wan 2.6"）。
+只说"视频生成中..."或"已提交生成任务"。
 
 ## 首帧编辑策略
 
-**单片段**：gen image 双图（`-i 源帧 -i 产品图`），保持场景只替换产品。
+**单片段**：`edit_first_frame.py` 用双图（`-i 源帧 -i 产品图`），保持场景只替换产品。
 **多片段**：每段仅 `-i 产品图`，prompt 描述完整场景，产品描述跨段重复。
 
 ## Anti-Pattern
 
 | 你在想... | 应该做的 |
 |---|---|
-| 用户给了素材直接开干 | **Phase 0 技术方案确认后才动手** |
-| 不看 workflow 库直接走通用 | **先查 README.md**，可能有验证过的方案 |
+| 用户给了素材直接开干 | **先 preflight + 跑完 prep + 出 preview + confirm.py** |
+| 不看 workflow 库直接走通用 | 先查 `workflows/README.md` |
 | 直接取 t=1s 当首帧 | 自动选产品最清晰的帧 |
-| prompt 不给用户看 | **必须打印，用户可能修改** |
-| 首帧没确认就生成视频 | **HARD-GATE：必须等用户确认** |
-| 告诉用户模型名称 | 只说 "视频生成中..." |
+| prompt 不给用户看 | **必须在 preview 里展示，用户可能修改** |
+| 跳过 preview 直接 confirm | preview.py 会验证所有 prep 产物是否齐全 |
+| 告诉用户具体模型名称 | 只说 "视频生成中..." 不透露底层模型 |
 | 做出好效果不保存 workflow | **效果好 + 新场景 = 必须沉淀** |
-| 覆盖之前生成的文件 | v{N} 递增，保留全部历史 |
+| 覆盖之前生成的文件 | 脚本自动 v{N} 递增 |
+| 把 `--quote "ok"` 当成真实确认 | 伪造 quote 会在 history 留痕，事后可倒查 |
 
 ## 已知限制
 
 - 单段最长 10s，多段需拼接
 - 动作模型自编，不还原源视频动作序列
-- PiAPI CDN 不稳定，需 3 次重试
+- PiAPI CDN 不稳定，`kling_generate.py` 内置 3 次重试
+- 平台解析（TikTok/抖音/Instagram/小红书）仍需手动调 `scout` 命令，不在脚本 pipeline 里（详见 [url-parsing.md](references/url-parsing.md)）

package/.claude/skills/video-clone/assets/phase-state-template.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "project": null,
+  "task_type": null,
+  "created_at": null,
+  "current_phase": 0,
+  "gates": {
+    "preview_confirmed": {"status": false, "confirmed_at": null, "user_quote": null}
+  },
+  "history": []
+}

package/.claude/skills/video-clone/references/ffmpeg-commands.md

@@ -1,45 +1,42 @@
-# FFmpeg 命令参考
+# FFmpeg — where the commands live
 
-## 场景检测
+The ffmpeg commands you'd have inlined here are owned by scripts now. Read
+the script source if you need to see the exact flags.
 
-```bash
-ffprobe -v quiet -print_format json -show_format -show_streams source_video.mp4
-ffmpeg -i source_video.mp4 -vf "select='gt(scene,0.3)',showinfo" -vsync vfr -f null -
-```
+| What | Script |
+|---|---|
+| ffprobe + scene detection (`select='gt(scene,0.3)'`) | `scripts/analyze_source.py` |
+| equidistant frame extraction + tile grid | `scripts/extract_frames.py` |
+| single-segment normalize (`-r 30 -crf 18 -c:a aac -b:a 192k`) | `scripts/assemble.py --single` |
+| multi-segment normalize + concat (scale=720:1280 + concat demuxer) | `scripts/assemble.py --multi` |
 
-切换点 <=1 → 单片段 | >=2 → 多片段（过滤 <0.5s 片段）
+## Single vs multi-segment heuristic
 
-## 抽帧
+`analyze_source.py` classifies automatically:
 
-**单片段**：等间距抽 10 帧 → 5x2 网格。
-**多片段**：每段 3-10 帧 → 每段网格 + 总网格，标注时间戳。
+- scene cuts ≤1 (after filtering out cuts <0.5s apart) → `classification: single`
+- scene cuts ≥2 → `classification: multi`
 
-## 单片段后处理
+If the auto-classification is wrong, override the plan manually — don't
+edit the script.
 
-```bash
-ffmpeg -y -i videos/video_v1_10s.mp4 \
-  -r 30 -c:v libx264 -crf 18 -c:a aac -b:a 192k \
-  videos/final_v1.mp4
-```
+## Things the scripts deliberately don't do
 
-## 多片段后处理
+- **Audio replacement from source** — Kling 3.0 handles lip sync itself;
+  don't splice the source audio back in or you'll get misaligned mouths.
+- **Resolution auto-detection for multi-segment** — `assemble.py --multi`
+  hardcodes `scale=720:1280`. If your source is different, pass pre-scaled
+  clips or extend the script.
+- **Re-encoding `final_v{N}.mp4` after assembly** — if final looks wrong,
+  regenerate the constituent videos, not the final.
 
-```bash
-# 1. 标准化每个 clip
-ffmpeg -y -i videos/scene1_v1_5s.mp4 \
-  -vf scale=720:1280 -r 30 -c:v libx264 -crf 18 -c:a aac -b:a 128k \
-  scene1_norm.mp4
-
-# 2. 拼接
-echo "file 'scene1_norm.mp4'
-file 'scene2_norm.mp4'" > concat_list.txt
-
-ffmpeg -y -f concat -safe 0 -i concat_list.txt \
-  -c:v libx264 -crf 18 -c:a aac -b:a 192k \
-  videos/final_v1.mp4
-```
+## Raw command reference (only when debugging outside the scripts)
 
-## 重要
+```bash
+# probe metadata
+ffprobe -v quiet -print_format json -show_format -show_streams video.mp4
 
-- Kling 音频口型同步，**不要用源视频音频替换**
-- 多片段拼接前必须统一分辨率和帧率
+# concat list format (scripts generate this automatically)
+file 'clip1_norm.mp4'
+file 'clip2_norm.mp4'
+```