@optima-chat/optima-agent 0.8.90 → 0.8.92

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

@@ -1,492 +1,199 @@
 ---
 name: video-clone
-description: "视频复刻与视频生成。当用户需要：复刻视频(复刻/翻拍/仿拍/做同款/视频换产品/product swap/爆款复刻/video replication)、用户贴视频链接+产品图要求出同款视频、或用户提供图片/文字描述要求直接生成视频(生成视频/图生视频/做一个视频)时使用。"
+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
 
-## 典型场景
+通过产品替换或文字描述，复刻源视频或生成全新视频。
 
-当用户说：
-- "帮我复刻这个视频" + 视频 + 产品图 → **视频复刻**：判断单/多片段，走 Pipeline
-- "帮我做同款视频" + 视频 + 产品图 → 同上
-- "帮我分析一下这个视频" + 视频 → 只跑 Phase 1（分析+场景拆分）
-- "换个首帧试试" → 回到 Phase 2 重跑
-- "prompt 改一下" → 用户修改 prompt 后重跑 Phase 3
-- "帮我生成一个视频" + 图片 + 描述 → **纯视频生成**（无源视频）
-- "用这张图做个视频" + 图片 → 同上
+> **PR #65 升级注意**：本版本采用单门 (single-gate) 模型。旧版三门
+> (`plan_confirmed` / `prompt_confirmed` / `frame_confirmed`) 已废弃。
+> 旧项目继续用旧脚本完成，新项目全部走本版本流程。
 
-### 单片段 vs 多片段（复刻时首先判断）
+## 前置依赖
 
-```
-源视频 → ffmpeg 场景检测
-  ├─ scene change ≤ 1 → 单片段：1 首帧 → 1 clip → 成品
-  └─ scene change ≥ 2 → 多片段：N 首帧 → N clips → 拼接 → 成品
-```
-
-### 纯视频生成（无源视频）
-
-```
-图片 + 描述 → Claude 编写中文 6 段 prompt → 用户确认
-  → 不需要音频 → gen video（Wan 2.6，~$0.02）
-  → 需要音频   → Kling 3.0 API（~$1.00）
-```
-
-## URL 解析
-
-**不要用 WebFetch**（反爬/登录墙），按规则处理：
+- **`gen` CLI** — `gen image`（首帧编辑）、`gen video`（I2V，无音频时使用）
+- **视频生成 API via PiAPI** — 有音频/口型同步时使用。需要 `PIAPI_KEY` 环境变量
+- **ffmpeg / ffprobe** — 场景检测、抽帧、后处理
+- **Python ≥ 3.10** — 所有脚本运行时
+- **freeimage.host** — 首帧上传时的公开 URL 托管（详见 [kling-api.md](references/kling-api.md)）
 
-| URL 特征 | 处理 |
-|----------|------|
-| TikTok `tiktok.com/@xxx/video/数字` | `scout tiktok video-detail <id>` → wget |
-| TikTok 短链 `vm.tiktok.com/xxx` | `curl -sI` → Location → 提取 id |
-| 抖音 `douyin.com/video/数字` | `scout douyin video-download <id>` → wget |
-| 抖音短链 `v.douyin.com/xxx` | `scout douyin video-by-url "<url>"` |
-| Instagram Reels | `scout instagram download-reel "<url>"` |
-| 小红书视频 | `scout xhs note-detail <id>` → 视频链接 |
-| 本地文件 | 直接使用 |
+触发 skill 后第一步：运行 `python scripts/preflight.py`，确认上述依赖。
 
-## 交互流程
+## 脚本 Pipeline 一览
 
-### 视频复刻（单片段/多片段共用）
+单门模型：所有 prep 脚本自由运行，preview 之后只有一个 GATE。
 
 ```
-源视频 + 产品图
-  → 创建 gen-output/video-clone/{project}/ 目录，保存源素材
-  → Phase 1：自动抽帧、自动选首帧、Claude Opus 分析
-      ├─ [多片段] 报告片段数和每段描述
-      ├─ 写入 prompt.md + 打印给用户
-      └─ "这是分析出的 prompt，需要修改吗？可以直接编辑 prompt.md"
-  → 用户确认或编辑 prompt.md
-  → Phase 2：FLUX-PRO 首帧编辑 → 保存到 frames/
-      ├─ 展示首帧（Read 图片）
-      └─ "产品替换满意吗？"
-  → Phase 3："视频生成中..." → 保存到 videos/
-  → Phase 4：后处理 → final_v{N}.mp4 → 更新 log.md 结果
-
-⚠️ 两个交互点：prompt 确认 + 首帧质检
-⚠️ Phase 3/4 自动执行
-⚠️ 每步产物都保存，log.md 实时更新
+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 — 可选，效果好时沉淀)
 ```
 
-### 纯视频生成
+`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)。
 
-```
-图片 + 描述
-  → 创建 gen-output/video-clone/{project}/ 目录
-  → Claude 编写中文 6 段 prompt → 写入 prompt.md + 打印给用户
-  → 用户确认或编辑 prompt.md → "视频生成中..." → 保存到 videos/
-  → 交付 → 更新 log.md 结果
-```
-
----
+<HARD-GATE>
+**Gate 由脚本机械强制，不是文本约定。** 任何绕过 gate 的方式都会留下证据：
+  1. 手工编辑 `.state/phase.json` — history 字段会显示断点
+  2. 伪造 `--quote` 调用 `confirm.py` — user_quote 字段留痕，事后可倒查
 
-## 铁律
-
-```
-1. 首帧质量决定一切 — 自动选产品最清晰+手部最自然的帧
-2. 让模型做简单的事 — 产品保持静止，人做简单动作
-3. Prompt 质量 = 视频质量 — 必须打印给用户，用户可能修改
-4. 永远不覆盖文件 — 所有产物版本化命名，保留完整迭代历史
-```
-
----
-
-## 项目目录与文件管理
-
-所有产物保存在 `gen-output/video-clone/{project}/`，`{project}` 由产品名或任务简称命名（如 `fishing-scale`、`car-creeper`）。
-
-### 新任务 vs 修改已有任务
-
-```
-"帮我复刻这个视频" + 新产品图     → ls gen-output/video-clone/ → 新建 {project}/ 目录
-"帮我做另一个视频" + 新素材       → 新建 {project}/ 目录
-"换个首帧试试" / "prompt 改一下"  → 继续当前 {project}/ 目录，v{N}+1
-"上次那个电子秤视频再改改"        → 进入已有 fishing-scale/ 目录，读 log.md 续接
-```
-
-**判断逻辑**：有新源视频或新产品 → 新目录；改 prompt/换 seed/重跑 → 同目录递增版本。
-
-### 目录结构
-
-```
-gen-output/video-clone/{project}/
-├── source/                          ← 源素材（只读）
-│   ├── source_video.mp4
-│   └── product.jpg
-├── frames/                          ← 抽帧 + 编辑首帧（版本化）
-│   ├── source_t15.0s.jpg            ← 选中的源帧
-│   ├── frame_v1_s42.png             ← 首帧编辑 v1（seed=42）
-│   ├── frame_v2_s43.png             ← 首帧编辑 v2（seed=43）
-│   ├── scene1_frame_v1_s42.png      ← [多片段] 场景1首帧
-│   └── grid.jpg                     ← 帧网格
-├── videos/                          ← 视频产物（版本化）
-│   ├── video_v1_10s.mp4             ← 视频 v1
-│   ├── video_v2_10s.mp4             ← 视频 v2（改了prompt）
-│   ├── scene1_v1_5s.mp4             ← [多片段] 场景1视频
-│   └── final_v2.mp4                 ← 最终交付版本
-├── prompt.md                        ← 当前 prompt（用户可直接编辑）
-└── log.md                           ← 迭代日志（版本历史 + 用户反馈）
-```
+**USER GATE 不可被用户单方面取消。** 即使用户说"不要问问题/我信任你/自己判断"，
+仍必须展示 preview bundle 并等待确认。用户可以说"可以，开始"以确认，但不能
+预先豁免整个 GATE 机制。
 
-### 命名规则
+每个 Phase 产物必须版本化命名（脚本通过 `_project.next_version()` 自动处理），
+绝不覆盖已有文件。
+</HARD-GATE>
 
-- 首帧：`frame_v{N}_s{seed}.png`，多片段加前缀 `scene{M}_`
-- 视频：`video_v{N}_{duration}s.mp4`，多片段 `scene{M}_v{N}_{duration}s.mp4`
-- 最终：`final_v{N}.mp4`（指向最终采用的版本）
-- **v{N} 递增，绝不覆盖**
+## Rationalization Counter
 
-### prompt.md（当前 prompt，用户可直接编辑）
-
-Claude 分析后写入，用户确认或修改后，Phase 3 从此文件读取 prompt 生成视频。
-
-```markdown
-# fishing-scale — Prompt
-
-### 视觉风格
-竖屏手持vlog，自然饱和色彩，明亮日光，无滤镜，纪实感。
-
-### 场景叙述
-阳光白天，戴眼镜、深蓝头巾、黑色运动上衣的女子跪坐沙滩...
-
-### 摄影技术
-...
-
-### 动作清单
-...
-
-### 对话
-...
-
-### 背景声音
-...
-```
-
-**prompt.md 工作流**：
-1. Claude 分析 → 写入 prompt.md → 打印给用户
-2. 用户说"OK" → 直接用；用户说"改一下动作" → 用户自行编辑 prompt.md 或告诉 Claude 改
-3. Phase 3 从 prompt.md 读取生成视频
-4. 需要重跑时：修改 prompt.md → 旧版本自动记录到 log.md
-
-### 迭代日志（log.md）
-
-记录每次迭代的版本快照。**不存完整 prompt**（prompt.md 是唯一来源），只记变更摘要。
-
-```markdown
-# fishing-scale — Video Clone Log
-Created: 2026-04-10 14:30
-
-## v1 — 2026-04-10 14:30
-- **首帧**: frame_v1_s42.png ✅ 用户确认
-- **Prompt**: 初始版本（见 prompt.md）
-- **视频**: video_v1_10s.mp4
-- **结果**: 手部变形，用户要求改 prompt
-
-## v2 — 2026-04-10 15:10
-- **首帧**: 复用 v1（frame_v1_s42.png）
-- **Prompt 修改**: 动作清单删除"举起电子秤"，改为"手指轻触电子秤"
-- **视频**: video_v2_10s.mp4
-- **结果**: ✅ 用户满意 → final_v2.mp4
-```
-
-**日志规则**：
-- 首帧没变就写"复用 vX"，变了就写新文件名
-- Prompt 修改只记差异摘要（完整内容始终在 prompt.md）
-- 结果必须记录用户反馈（满意/不满意+原因）
-- 跨会话续接时，先读 log.md 获取上次版本号，再读 prompt.md 获取当前 prompt
-
----
-
-## Pipeline 总览
-
-```
-单片段：源视频 → 分析 → gen image 首帧编辑 → I2V → 后处理 → 成品
-多片段：源视频 → 场景拆分 → 每段 gen image 首帧 → 每段 I2V → 拼接 → 成品
-纯生成：图片 → prompt → gen video(无音频) 或 Kling(有音频) → 成品
-```
-
-## 工具分工
-
-| 工具 | 职责 |
-|------|------|
-| **Claude Opus** | 逐帧分析 → 中文 6 段 prompt；纯生成时根据用户描述编写 prompt |
-| **gen image** | 首帧编辑（多图输入：`-i 源帧 -i 产品图`）|
-| **gen video** | Wan 2.6 I2V（不需要音频时）|
-| **Kling 3.0**（PiAPI） | I2V（需要音频时，口型同步）|
-| **ffmpeg** | 抽帧、场景拆分、后处理、拼接 |
-
----
+以下是最常见的"合理化借口"及其反驳。遇到这些想法时必须 STOP。
 
-## Phase 1: 预处理与分析
-
-### 1.1 场景拆分
-
-```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 -
-```
-
-切换点 ≤1 → 单片段 | ≥2 → 多片段（过滤 <0.5s 片段）
-
-### 1.2 抽帧 + 帧网格
-
-**单片段**：等间距抽 10 帧 → 5×2 网格。
-**多片段**：每段 3-10 帧 → 每段网格 + 总网格。标注时间戳。
-
-### 1.3 Claude Opus 分析（核心）
+| Claude 的想法 | 现实 |
+|---|---|
+| "我只是在做 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** 这一步仍是必须的 |
 
-将所有帧 + 产品图分析，输出**中文 6 段 motion prompt**（格式见 Phase 3.3）。
+## Phase 0: 理解需求 + 匹配 Workflow
 
-- 逐帧看清动作序列（哪只手做什么）
-- 精确描述产品外观（颜色/形状/特征，从产品图提取）
-- 精确描述背景和光线（从源帧提取）
+**在动手之前，先搞清楚用户到底要什么，再看有没有现成的好方案。**
 
-**⚠️ 必须打印给用户。用户可能修改场景/人物/动作。**
+快速判断任务类型：有源视频 + 产品图 → 视频复刻；无源视频 → 纯视频生成。
 
-### 1.4 首帧选择（自动，不需要用户确认）
+**仅做轻量元数据识别，不执行工具调用**。不下载视频、不调 ffprobe、不抽帧。
 
-从全视频自动选：产品最清晰 + 手部最自然 + 占比适中 + 面部清晰。
+按需提问（不一次全问）：产品是什么、替换目标、音频需求（有音频 ~$1，无音频 ~$0.02）、时长期望。
 
----
+先查 `gen-output/video-clone/workflows/README.md` — 完全匹配 → 复用；部分匹配 → 调整；
+无匹配 → 走通用 pipeline。详见 [workflow-system.md](references/workflow-system.md)。
 
-## Phase 2: 首帧编辑
+## Phase 1-2: Prep（自主运行，无 gate）
 
-### 单片段：gen image 双图编辑
+Prep 阶段所有脚本均无 gate，可自主运行：
 
 ```bash
-gen image "Keep this exact same scene, same [人物特征], same [场景]. \
-  Replace ONLY the [原物品] with [新产品] from the reference image. \
-  [产品颜色+形状+特征]. Photorealistic, natural." \
-  -i source_frame.jpg -i product.jpg \
-  -W 576 -H 1024 -s 42 \
-  -o gen-output/video-clone/{project}/frames/frame_v1_s42.png
-Read gen-output/video-clone/{project}/frames/frame_v1_s42.png
-# 不满意 → 换 seed: frame_v2_s43.png，绝不覆盖 v1
+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>
 ```
 
-### 多片段：gen image 产品参考生成（仅 -i 产品图）
+`preview.py` 检查所有 prep 产物是否齐全，输出 `preview_vN.md`（六节）。
 
-每段独立生成首帧，不用源帧，只用产品图作参考。
+**[USER GATE] 把 preview 展示给用户，等待确认，然后运行：**
 
 ```bash
-gen image "[人物描述] [动作] [产品描述: the red MaxWorks creeper from \
-  the reference image - 颜色/logo/特征] [场景] Vertical 9:16. Photorealistic." \
-  -i product.jpg \
-  -W 576 -H 1024 -s 42 \
-  -o gen-output/video-clone/{project}/frames/scene1_frame_v1_s42.png
-Read gen-output/video-clone/{project}/frames/scene1_frame_v1_s42.png
-```
-
-⚠️ 每段 prompt 中产品描述重复（防遗忘），人物外貌跨段一致
-
-### 首帧质检（展示给用户确认）
-
+python scripts/confirm.py --project <slug> --quote "<用户原话>"
 ```
-□ 产品清晰？ □ 位置自然？ □ 人物保持？ □ 背景一致？
-不合格 → 换 seed(-s 43) → 调 prompt → 重新确认
-```
-
----
-
-## Phase 3: I2V 视频生成
 
-### 3.1 模型选择（内部逻辑，对用户只显示 "视频生成中..."）
-
-| 场景 | 工具 | 音频 |
-|------|------|------|
-| 复刻（默认） | Kling 3.0 API | 有（口型同步） |
-| 纯生成 + 需要音频 | Kling 3.0 API | 有 |
-| 纯生成 + 不需要音频 | gen video | 无 |
-
-### 3.2 gen video（Wan 2.6，不需要音频时）
+## Phase 3-5: 生成 + 后处理 + 沉淀
 
 ```bash
-gen video gen-output/video-clone/{project}/frames/frame_v1_s42.png \
-  --prompt "motion description..." \
-  -d 10 -r 1080P --no-audio \
-  -o gen-output/video-clone/{project}/videos/video_v1_10s.mp4
-Read gen-output/video-clone/{project}/videos/video_v1_10s.mp4
-# 重跑 → video_v2_10s.mp4，绝不覆盖
-```
-
-### 3.3 Kling 3.0 API（需要音频时）
-
-**Step 1: 上传首帧获取公开 URL**（Kling 不接受 base64，需要 URL）
-
-```python
-import requests, base64
-
-img_b64 = base64.b64encode(open('edited_frame.png', 'rb').read()).decode()
-resp = requests.post('https://freeimage.host/api/1/upload', data={
-    'key': '6d207e02198a847aa98d0a2a901485a5',
-    'action': 'upload',
-    'source': img_b64,
-    'format': 'json',
-})
-img_url = resp.json()['image']['url']
-# ⚠️ catbox.moe 不可用（PiAPI 服务器访问不了）
-```
-
-**Step 2: 提交生成任务**
-
-```python
-resp = requests.post('https://api.piapi.ai/api/v1/task',
-    headers={'x-api-key': PIAPI_KEY, 'Content-Type': 'application/json'},
-    json={
-        'model': 'kling',
-        'task_type': 'video_generation',
-        'input': {
-            'prompt': motion_prompt,
-            'negative_prompt': 'slow motion, dreamy, ethereal, cinematic, blurry, '
-                               'distorted, deformed hands, extra fingers',
-            'image_url': img_url,
-            'duration': 10,         # 或 5（多片段时）
-            'aspect_ratio': '9:16',
-            'mode': 'std',          # 720p
-            'version': '3.0',
-            'cfg_scale': 0.5,       # ⚠️ 必须 float！
-            'enable_audio': True,
-        },
-        'config': {'service_mode': 'public'},
-    }, timeout=60)
-task_id = resp.json()['data']['task_id']
-```
+# 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
 
-**Step 3: 轮询等待完成**
-
-```python
-import time
-while True:
-    r = requests.get(f'https://api.piapi.ai/api/v1/task/{task_id}',
-        headers={'x-api-key': PIAPI_KEY})
-    d = r.json().get('data', {})
-    status = d.get('status', '')
-    if status == 'completed':       # ⚠️ 小写！
-        video_url = d['output']['video']  # ⚠️ 3.0 用 video，2.6 用 video_url
-        break
-    if status == 'failed':
-        raise RuntimeError(d.get('error', {}))
-    time.sleep(15)
-```
+# Phase 4 — 后处理
+python scripts/assemble.py --project <slug> --single videos/video_vN.mp4
 
-**Step 4: 下载视频**（CDN 不稳定需重试）
-
-```python
-for attempt in range(3):
-    try:
-        data = requests.get(video_url, timeout=300).content
-        open('gen-output/video-clone/{project}/videos/video_v1_10s.mp4', 'wb').write(data)
-        break
-# 重跑 → video_v2_10s.mp4，绝不覆盖
-    except Exception:
-        time.sleep(5)
+# Phase 5 — 沉淀（可选）
+python scripts/save_workflow.py --project <slug> \
+    --name <workflow-slug> --scene "<适用场景>" \
+    --rating <1-5> --strategy "<关键策略>"
 ```
 
-### 3.4 Motion Prompt（中文 6 段模板）
-
-**复刻时**：Claude Opus 分析源帧后生成。**纯生成时**：Claude 根据用户描述编写。
-两种都写入 `prompt.md` 并打印给用户，用户可直接编辑文件。Phase 3 从 `prompt.md` 读取。
-
-```
-### 视觉风格
-[拍摄设备感 + 画面质感 + 色彩方案 + 光线 + 氛围]
-
-### 场景叙述
-[时间地点 + 人物外貌 + 产品描述(重复颜色/特征) + 背景环境]
-
-### 摄影技术
-[景别 + 运镜 + 焦段 + 景深 + 光线]  情绪：[...]
+## 铁律
 
-### 动作清单
-- [时间顺序，精确到哪只手]
-- [产品交互，避免复杂手部操作]
+1. 先理解再动手 — 出 preview 前先跑完所有 prep 脚本
+2. 先查 workflow 再造轮子 — 已有经验不要浪费
+3. 首帧质量决定一切 — 自动选产品最清晰+手部最自然的帧
+4. Prompt 质量 = 视频质量 — preview 里展示给用户，用户可能修改
+5. 永远不覆盖文件 — 脚本通过 next_version() 自动 v{N} 递增
+6. 不要自己编辑 .state/phase.json — 还不如走 confirm.py 正常路径
 
-### 对话
-- [语言和风格]
+## 项目目录
 
-### 背景声音
-- [环境音 + 人声 + 无背景音乐]
 ```
-
-**Anti-AI**（摄影技术段融入）：手持拍摄/轻微晃动/自然光/无滤镜/纪实感
-**禁用词**：梦幻/空灵/电影感/慢动作/丝滑/优雅
-
----
-
-## Phase 4: 后处理
-
-### 单片段
-
-```bash
-# video_v{N} → final_v{N}
-ffmpeg -y -i gen-output/video-clone/{project}/videos/video_v1_10s.mp4 \
-  -r 30 -c:v libx264 -crf 18 -c:a aac -b:a 192k \
-  gen-output/video-clone/{project}/videos/final_v1.mp4
+gen-output/video-clone/
+├── 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
 ```
 
-### 多片段
+新任务 → 新目录；改 prompt/换 seed → 同目录 v{N}+1。
+跨会话续接：先 `python scripts/status.py --project <slug>` 看当前状态和下一步。
 
-```bash
-# 标准化每个 clip
-ffmpeg -y -i gen-output/video-clone/{project}/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
-
-# 拼接 → final_v{N}
-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 \
-  gen-output/video-clone/{project}/videos/final_v1.mp4
-```
+## 工具分工
 
-**⚠️ Kling 音频口型同步，必须保留，不要用源视频音频替换。**
+| 工具 | 脚本 | 职责 |
+|---|---|---|
+| 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"）。
+只说"视频生成中..."或"已提交生成任务"。
 
-```
-□ 产品可辨？ □ 手部自然？ □ 物理正确？ □ 人脸稳定？ □ 背景一致？ □ 音频正常？
-□ [多片段] 过渡自然？产品跨段一致？
-不合格 → 调 prompt / 换 seed 重跑（可只重跑问题片段）
-```
+## 首帧编辑策略
 
----
+**单片段**：`edit_first_frame.py` 用双图（`-i 源帧 -i 产品图`），保持场景只替换产品。
+**多片段**：每段仅 `-i 产品图`，prompt 描述完整场景，产品描述跨段重复。
 
-## Red Flags
+## Anti-Pattern
 
-| ❌ 你在想... | ✅ 应该做的 |
+| 你在想... | 应该做的 |
 |---|---|
+| 用户给了素材直接开干 | **先 preflight + 跑完 prep + 出 preview + confirm.py** |
+| 不看 workflow 库直接走通用 | 先查 `workflows/README.md` |
 | 直接取 t=1s 当首帧 | 自动选产品最清晰的帧 |
-| prompt 随便写一句话 | 中文 6 段结构化模板 |
-| prompt 不给用户看 | 必须打印，用户可能修改 |
-| 告诉用户模型名称 | 只说 "视频生成中..." |
-| 用源视频音频替换 Kling 音频 | Kling 音频口型同步，必须保留 |
-| cfg_scale 传 string | 必须 float（string → 500） |
-| 描述复杂手部操作 | 产品静止，人做简单动作 |
-| prompt 超 2500 字符 | 精简到 1200-2000 |
-| 用 catbox.moe 托管图片 | 用 freeimage.host |
-| 本地直接调 API | 通过服务器中转 |
-| 覆盖之前生成的文件 | v{N} 递增命名，保留全部历史 |
-| 不写 log.md | 每次操作必须追加日志 |
-
----
+| prompt 不给用户看 | **必须在 preview 里展示，用户可能修改** |
+| 跳过 preview 直接 confirm | preview.py 会验证所有 prep 产物是否齐全 |
+| 告诉用户具体模型名称 | 只说 "视频生成中..." 不透露底层模型 |
+| 做出好效果不保存 workflow | **效果好 + 新场景 = 必须沉淀** |
+| 覆盖之前生成的文件 | 脚本自动 v{N} 递增 |
+| 把 `--quote "ok"` 当成真实确认 | 伪造 quote 会在 history 留痕，事后可倒查 |
 
 ## 已知限制
 
-- **单段最长 10s**：多段需拼接
-- **动作模型自编**：不还原源视频动作序列，等 Kling Omni video reference
-- **PiAPI CDN 不稳定**：3 次重试 + 流式下载
-
-## 实战参考
-
-**demo1 沙滩电子秤**：t=1s 无产品→失败，改 t=15s→完美。首帧选择 + prompt 质量 >> 一切。
-
-**demo2 汽车躺板-单片段**：PiAPI FLUX 单图+一句话=⭐⭐，BFL FLUX-PRO 双图+6段 prompt=⭐⭐⭐⭐⭐。
-
-**demo3 汽车躺板-多片段**：18s 源视频 4 场景 → 拆分 → 每段 gen image + Kling 5s → 拼接 20s。关键：产品描述跨段一致。
-
-## 重要提醒
-
-1. **BFL 轮询 "Task not found"** 持续约 60s，正常，继续轮询
-2. **Kling enable_audio 只有 3.0 支持**
-3. **Kling 状态小写 "completed"**，输出字段 `output.video`（3.0）
-4. **国内网络通过服务器中转** API，本地大 payload 会断连
-5. **freeimage.host key**: `6d207e02198a847aa98d0a2a901485a5`
+- 单段最长 10s，多段需拼接
+- 动作模型自编，不还原源视频动作序列
+- 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": []
+}