@optima-chat/optima-agent 0.8.90 → 0.8.91

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

@@ -1,492 +1,291 @@
 ---
 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)、用户贴视频链接+产品图要求出同款视频、或用户提供图片/文字描述要求直接生成视频(生成视频/图生视频/做一个视频)。Requires `gen` CLI (gen image / gen video) and Kling 3.0 API (via PiAPI)."
 ---
 
 # Video Clone
 
-## 典型场景
+通过产品替换或文字描述，复刻源视频或生成全新视频。
 
-当用户说：
-- "帮我复刻这个视频" + 视频 + 产品图 → **视频复刻**：判断单/多片段，走 Pipeline
-- "帮我做同款视频" + 视频 + 产品图 → 同上
-- "帮我分析一下这个视频" + 视频 → 只跑 Phase 1（分析+场景拆分）
-- "换个首帧试试" → 回到 Phase 2 重跑
-- "prompt 改一下" → 用户修改 prompt 后重跑 Phase 3
-- "帮我生成一个视频" + 图片 + 描述 → **纯视频生成**（无源视频）
-- "用这张图做个视频" + 图片 → 同上
+## 前置依赖
 
-### 单片段 vs 多片段（复刻时首先判断）
+此 skill 依赖以下外部工具，缺失其中任何一项会导致 pipeline 中断：
 
-```
-源视频 → ffmpeg 场景检测
-  ├─ scene change ≤ 1 → 单片段：1 首帧 → 1 clip → 成品
-  └─ scene change ≥ 2 → 多片段：N 首帧 → N clips → 拼接 → 成品
-```
+- **`gen` CLI** — `gen image`（首帧编辑）、`gen video`（Wan 2.6 I2V，无音频时使用）
+- **Kling 3.0 API**（通过 PiAPI，`PIAPI_KEY` 环境变量）— 有音频/口型同步时使用
+- **ffmpeg / ffprobe** — 场景检测、抽帧、后处理
+- **freeimage.host** — Kling 上传首帧时的公开 URL 托管（详见 [kling-api.md](references/kling-api.md)）
 
-### 纯视频生成（无源视频）
+触发 skill 前若检测到 `gen` CLI 不可用，必须立即告知用户，不要进入 Phase 0。
 
-```
-图片 + 描述 → Claude 编写中文 6 段 prompt → 用户确认
-  → 不需要音频 → gen video（Wan 2.6，~$0.02）
-  → 需要音频   → Kling 3.0 API（~$1.00）
-```
+<HARD-GATE>
+在技术方案获得用户确认前，禁止执行以下全部操作：下载源视频、ffprobe/ffmpeg 调用、抽帧、产品图处理、调用 gen image/gen video、调用 Kling API、创建 `gen-output/video-clone/{project}/` 项目目录。Phase 0.1 的"立即做"仅在 **用户已提供本地文件且未明确要求立即执行** 时方可进行；若用户要求"现在就开始/立刻执行/别问了"，这些操作同样被阻断。
 
-## URL 解析
+在 Phase 1 prompt 获得用户确认前，禁止进入 Phase 2（首帧编辑）。
+在 Phase 2 首帧获得用户确认前，禁止进入 Phase 3（视频生成）。
 
-**不要用 WebFetch**（反爬/登录墙），按规则处理：
+**USER GATE 不可被用户单方面取消。** 即使用户说"不要问问题/我信任你/自己判断"，仍必须输出技术方案并等待确认。用户可以说"方案我同意，继续"以确认，但不能预先豁免整个 GATE 机制。
 
-| 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>` → 视频链接 |
-| 本地文件 | 直接使用 |
+每个 Phase 产物必须版本化命名，绝不覆盖已有文件。
+</HARD-GATE>
 
-## 交互流程
+## Rationalization Counter
 
-### 视频复刻（单片段/多片段共用）
+以下是 Claude 最常用的"合理化借口"及其反驳。遇到这些想法时必须 STOP。
 
-```
-源视频 + 产品图
-  → 创建 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 实时更新
-```
+| Claude 的想法 | 现实 |
+|---|---|
+| "我只是在做 Phase 0 分析，下载视频不算执行" | 下载 = 工具调用 = 被 GATE 阻断。分析要基于用户提供的元数据（URL/文件名/描述），不是基于已下载的文件 |
+| "用户说'急用'/'现在就开始'，所以我可以跳过确认" | 用户的紧迫感不是跳过 GATE 的理由。相反，越急越要用技术方案快速对齐，避免返工 |
+| "用户说'不要问问题，自己判断'" | 这是覆盖 0.2 提问环节的授权，**不是**覆盖 0.4 技术方案展示的授权。自己判断后仍要出方案 |
+| "信息已经完整了，方案只是走过场" | 方案展示是用户发现隐含错误的最后机会。"完整"是你的判断，不是用户的判断 |
+| "用户给了产品图，显然要直接开始" | 给产品图 ≠ 同意全部参数。音频/时长/风格/workflow 选择仍需确认 |
+| "Phase 0.1 的场景检测是只读分析" | ffmpeg 抽帧会写盘，创建项目目录会写盘。任何文件系统写入都属于"执行"范畴 |
 
-### 纯视频生成
+若 Claude 发现自己在使用上述任一借口，立刻停止并回到技术方案步骤。
 
-```
-图片 + 描述
-  → 创建 gen-output/video-clone/{project}/ 目录
-  → Claude 编写中文 6 段 prompt → 写入 prompt.md + 打印给用户
-  → 用户确认或编辑 prompt.md → "视频生成中..." → 保存到 videos/
-  → 交付 → 更新 log.md 结果
-```
+## Phase 0: 理解需求 + 匹配 Workflow + 技术方案
 
----
+**在动手之前，先搞清楚用户到底要什么，再看有没有现成的好方案。**
 
-## 铁律
+### 0.1 素材收集与初步分析
+
+收集用户提供的所有素材，快速判断任务类型：
 
 ```
-1. 首帧质量决定一切 — 自动选产品最清晰+手部最自然的帧
-2. 让模型做简单的事 — 产品保持静止，人做简单动作
-3. Prompt 质量 = 视频质量 — 必须打印给用户，用户可能修改
-4. 永远不覆盖文件 — 所有产物版本化命名，保留完整迭代历史
+用户输入 → 有源视频？
+  ├─ 有视频 + 有产品图 → 视频复刻
+  ├─ 有视频 + 无产品图 → 追问：要替换什么产品？
+  ├─ 无视频 + 有图片   → 纯视频生成
+  └─ 只有文字描述       → 纯视频生成（需要更多信息）
 ```
 
----
+**仅做轻量元数据识别，不执行工具调用**：
+- 识别 URL 平台（TikTok/抖音/Instagram/小红书/本地文件）并告知用户将使用哪种解析方式
+- 如果用户已提供本地视频文件路径，可以读取文件大小/类型（不抽帧）
+- 基于 URL/文件名/用户描述推断大致内容和复杂度
 
-## 项目目录与文件管理
+**不要在此步骤**：下载视频、调用 ffprobe/ffmpeg、抽帧、创建项目目录。这些操作属于 Phase 1，必须在技术方案确认后才能执行。
 
-所有产物保存在 `gen-output/video-clone/{project}/`，`{project}` 由产品名或任务简称命名（如 `fishing-scale`、`car-creeper`）。
+**例外**：如果用户明确提供了元数据（"这是 15 秒的手持 vlog，单场景"），直接用，不需要自己验证。
 
-### 新任务 vs 修改已有任务
+### 0.2 关键问题（按需提问，不要一次全问）
 
-```
-"帮我复刻这个视频" + 新产品图     → ls gen-output/video-clone/ → 新建 {project}/ 目录
-"帮我做另一个视频" + 新素材       → 新建 {project}/ 目录
-"换个首帧试试" / "prompt 改一下"  → 继续当前 {project}/ 目录，v{N}+1
-"上次那个电子秤视频再改改"        → 进入已有 fishing-scale/ 目录，读 log.md 续接
-```
+根据已有信息，挑最关键的 1-2 个问题问：
 
-**判断逻辑**：有新源视频或新产品 → 新目录；改 prompt/换 seed/重跑 → 同目录递增版本。
+| 需要了解的 | 什么时候问 | 示例 |
+|---|---|---|
+| 产品是什么 | 用户没提供产品图 | "你要在视频里展示什么产品？有产品图吗？" |
+| 替换目标 | 源视频里有多个物品 | "视频里有手机和平板，你要替换哪个？" |
+| 视频用途 | 影响风格和质量选择 | "这个视频是发抖音/TikTok/电商详情页？" |
+| 音频需求 | 影响工具选择和成本 | "需要保留人声/口型同步吗？（有音频用 Kling ~$1，无音频 ~$0.02）" |
+| 时长期望 | 源视频很长或用户没说 | "源视频 30s，要复刻全部还是选一段？" |
+| 风格偏好 | 纯生成时 | "想要什么感觉？真实纪录片风？还是广告感？" |
 
-### 目录结构
+**不要问用户已经给出答案的问题。**
+
+### 0.3 匹配 Workflow
+
+理解需求后，读取 `gen-output/video-clone/workflows/README.md` 查找匹配的 workflow。
 
 ```
-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                           ← 迭代日志（版本历史 + 用户反馈）
+读取 workflows/README.md
+  → 找到匹配的 workflow？
+    ├─ 有 → 读取该 workflow 文件，复用其策略（prompt 风格、首帧技巧、参数配置）
+    ├─ 部分匹配 → 基于已有 workflow 调整，执行后保存为新 workflow
+    └─ 无 → 走通用 pipeline，效果好则保存为新 workflow
 ```
 
-### 命名规则
+**Workflow 是经验的积累。** 每个 workflow 记录了在特定场景下"什么方法效果最好"——包括 prompt 写法、首帧编辑策略、工具选择、踩过的坑。随着使用次数增加，workflow 库会越来越强。
 
-- 首帧：`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} 递增，绝不覆盖**
+详见 [workflow-system.md](references/workflow-system.md)
 
-### prompt.md（当前 prompt，用户可直接编辑）
+### 0.4 技术方案（必须展示给用户）
 
-Claude 分析后写入，用户确认或修改后，Phase 3 从此文件读取 prompt 生成视频。
+基于分析结果 + workflow 匹配，输出技术方案：
 
 ```markdown
-# fishing-scale — Prompt
-
-### 视觉风格
-竖屏手持vlog，自然饱和色彩，明亮日光，无滤镜，纪实感。
+## 技术方案
 
-### 场景叙述
-阳光白天，戴眼镜、深蓝头巾、黑色运动上衣的女子跪坐沙滩...
+**任务**: [视频复刻 / 纯视频生成]
+**源视频**: [时长]s, [分辨率], [单/多片段(N段)]
+**产品**: [产品名称+关键特征]
+**参考 Workflow**: [workflow 名称] / 无（新场景）
 
-### 摄影技术
-...
+**执行计划**:
+1. 首帧编辑 — gen image [单图/双图] 替换 [目标物品] 为 [新产品]
+2. 视频生成 — [Kling 3.0(有音频) / gen video(无音频)], [时长]s
+3. 后处理 — [直出 / N段拼接]
 
-### 动作清单
-...
+**预估成本**: ~$[X.XX]
+**预估耗时**: ~[N]分钟
 
-### 对话
-...
-
-### 背景声音
-...
+确认后开始？需要调整什么？
 ```
 
-**prompt.md 工作流**：
-1. Claude 分析 → 写入 prompt.md → 打印给用户
-2. 用户说"OK" → 直接用；用户说"改一下动作" → 用户自行编辑 prompt.md 或告诉 Claude 改
-3. Phase 3 从 prompt.md 读取生成视频
-4. 需要重跑时：修改 prompt.md → 旧版本自动记录到 log.md
-
-### 迭代日志（log.md）
+如果匹配到 workflow，技术方案中说明"基于 [workflow名] 的经验，这类视频建议 [具体策略]"。
 
-记录每次迭代的版本快照。**不存完整 prompt**（prompt.md 是唯一来源），只记变更摘要。
+### Anti-Pattern: 跳过 Phase 0
 
-```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
-```
+| 你在想... | 应该做的 |
+|---|---|
+| 用户给了视频和产品图，直接开干 | **先出技术方案**，用户可能对时长/音频/风格有想法 |
+| 用户说"急用/立刻开始"，我应该加速 | **紧迫感不是跳过 GATE 的理由**，方案对齐反而避免返工 |
+| 用户说"不要问问题，自己判断"，所以不用确认 | **"不问问题" ≠ "不确认方案"**，自己判断后仍要出方案等确认 |
+| 下载视频/抽帧只是"前期分析"不算执行 | **所有工具调用都被 GATE 阻断**，分析必须基于用户提供的元数据 |
+| 问用户一堆技术问题 | 只问不清楚的，已知信息自己分析 |
+| 不看 workflows 直接走通用流程 | **先查 workflow 库**，可能有更好的方案 |
+| 用户说"复刻这个"，假设我全懂了 | 至少确认：替换什么？要不要音频？ |
 
-**日志规则**：
-- 首帧没变就写"复用 vX"，变了就写新文件名
-- Prompt 修改只记差异摘要（完整内容始终在 prompt.md）
-- 结果必须记录用户反馈（满意/不满意+原因）
-- 跨会话续接时，先读 log.md 获取上次版本号，再读 prompt.md 获取当前 prompt
+**[USER GATE] 用户确认技术方案后，进入 Phase 1。**
 
 ---
 
-## Pipeline 总览
+## Phase 1-4: 执行 Pipeline
 
-```
-单片段：源视频 → 分析 → gen image 首帧编辑 → I2V → 后处理 → 成品
-多片段：源视频 → 场景拆分 → 每段 gen image 首帧 → 每段 I2V → 拼接 → 成品
-纯生成：图片 → prompt → gen video(无音频) 或 Kling(有音频) → 成品
-```
+技术方案确认后，按 Checklist 顺序执行。如果匹配到 workflow，优先按 workflow 的策略执行。
 
-## 工具分工
+### 视频复刻 Checklist
 
-| 工具 | 职责 |
-|------|------|
-| **Claude Opus** | 逐帧分析 → 中文 6 段 prompt；纯生成时根据用户描述编写 prompt |
-| **gen image** | 首帧编辑（多图输入：`-i 源帧 -i 产品图`）|
-| **gen video** | Wan 2.6 I2V（不需要音频时）|
-| **Kling 3.0**（PiAPI） | I2V（需要音频时，口型同步）|
-| **ffmpeg** | 抽帧、场景拆分、后处理、拼接 |
+**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 2 — 首帧编辑**
 
-## Phase 1: 预处理与分析
+5. **首帧编辑** — gen image 产品替换 → 版本化保存到 `frames/`
+6. **[USER GATE] 首帧质检** — 展示给用户，确认产品清晰/位置自然/人物保持/背景一致。未获确认前禁止进入 Phase 3
 
-### 1.1 场景拆分
+**Phase 3 — 视频生成**
 
-```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 -
-```
+7. **视频生成** — 对用户只显示 "视频生成中..."。详见 [kling-api.md](references/kling-api.md)
 
-切换点 ≤1 → 单片段 | ≥2 → 多片段（过滤 <0.5s 片段）
+**Phase 4 — 后处理与交付**
 
-### 1.2 抽帧 + 帧网格
+8. **后处理** — ffmpeg 标准化/拼接 → `final_v{N}.mp4`。详见 [ffmpeg-commands.md](references/ffmpeg-commands.md)
+9. **更新日志** — 结果写入 `log.md`，交付
 
-**单片段**：等间距抽 10 帧 → 5×2 网格。
-**多片段**：每段 3-10 帧 → 每段网格 + 总网格。标注时间戳。
+### 纯视频生成 Checklist
 
-### 1.3 Claude Opus 分析（核心）
+**Phase 1 — Prompt 生成**
+1. **创建项目目录** — 保存素材到 `source/`
+2. **生成 prompt** — 根据技术方案编写 → 写入 `prompt.md` → **打印给用户**
+3. **[USER GATE] prompt 确认** — 未获确认前禁止进入 Phase 3
 
-将所有帧 + 产品图分析，输出**中文 6 段 motion prompt**（格式见 Phase 3.3）。
+**Phase 3 — 视频生成**（无首帧编辑，跳过 Phase 2）
 
-- 逐帧看清动作序列（哪只手做什么）
-- 精确描述产品外观（颜色/形状/特征，从产品图提取）
-- 精确描述背景和光线（从源帧提取）
+4. **视频生成** — 不需要音频用 gen video，需要音频用 Kling 3.0
 
-**⚠️ 必须打印给用户。用户可能修改场景/人物/动作。**
+**Phase 4 — 交付**
 
-### 1.4 首帧选择（自动，不需要用户确认）
+5. **更新 log.md** — 交付
 
-从全视频自动选：产品最清晰 + 手部最自然 + 占比适中 + 面部清晰。
+## Phase 5: 经验沉淀
 
----
-
-## Phase 2: 首帧编辑
-
-### 单片段：gen image 双图编辑
+任务完成且用户满意后，判断是否值得保存为 workflow：
 
-```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
 ```
-
-### 多片段：gen image 产品参考生成（仅 -i 产品图）
-
-每段独立生成首帧，不用源帧，只用产品图作参考。
-
-```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
+用户满意？
+  ├─ 满意 + 新场景（无匹配 workflow） → 保存为新 workflow
+  ├─ 满意 + 基于已有 workflow 调整    → 更新已有 workflow 或另存变体
+  └─ 不满意 / 已有 workflow 完全复用   → 不操作
 ```
 
-⚠️ 每段 prompt 中产品描述重复（防遗忘），人物外貌跨段一致
+保存时：在 `workflows/` 创建 `.md` 文件，更新 `README.md` 索引。
+详见 [workflow-system.md](references/workflow-system.md)
 
-### 首帧质检（展示给用户确认）
+## Process Flow
 
-```
-□ 产品清晰？ □ 位置自然？ □ 人物保持？ □ 背景一致？
-不合格 → 换 seed(-s 43) → 调 prompt → 重新确认
-```
+```dot
+digraph video_clone {
+    rankdir=TB;
+    node [shape=box];
 
----
+    "用户确认方案?" [shape=diamond];
+    "用户确认 prompt?" [shape=diamond];
+    "用户确认首帧?" [shape=diamond];
 
-## Phase 3: I2V 视频生成
+    "素材收集 + 初步分析" -> "关键问题（按需）";
+    "关键问题（按需）" -> "查 workflows/README.md";
+    "查 workflows/README.md" -> "输出技术方案\n（含 workflow 推荐）";
+    "输出技术方案\n（含 workflow 推荐）" -> "用户确认方案?";
 
-### 3.1 模型选择（内部逻辑，对用户只显示 "视频生成中..."）
+    "用户确认方案?" -> "输出技术方案\n（含 workflow 推荐）" [label="调整"];
+    "用户确认方案?" -> "抽帧分析 + 生成 prompt" [label="确认"];
 
-| 场景 | 工具 | 音频 |
-|------|------|------|
-| 复刻（默认） | Kling 3.0 API | 有（口型同步） |
-| 纯生成 + 需要音频 | Kling 3.0 API | 有 |
-| 纯生成 + 不需要音频 | gen video | 无 |
+    "抽帧分析 + 生成 prompt" -> "用户确认 prompt?";
+    "用户确认 prompt?" -> "抽帧分析 + 生成 prompt" [label="修改"];
+    "用户确认 prompt?" -> "gen image 首帧编辑" [label="确认"];
 
-### 3.2 gen video（Wan 2.6，不需要音频时）
+    "gen image 首帧编辑" -> "用户确认首帧?";
+    "用户确认首帧?" -> "gen image 首帧编辑" [label="换seed/调prompt"];
+    "用户确认首帧?" -> "视频生成 → 后处理 → 交付" [label="满意"];
 
-```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，绝不覆盖
+    "视频生成 → 后处理 → 交付" -> "经验沉淀\n（保存/更新 workflow）";
+}
 ```
 
-### 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']
-```
+## 铁律
 
-**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)
 ```
-
-**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)
+1. 先理解再动手 — 技术方案未确认前不执行任何生成操作
+2. 先查 workflow 再造轮子 — 已有经验不要浪费
+3. 首帧质量决定一切 — 自动选产品最清晰+手部最自然的帧
+4. 让模型做简单的事 — 产品保持静止，人做简单动作
+5. Prompt 质量 = 视频质量 — 必须打印给用户，用户可能修改
+6. 永远不覆盖文件 — 所有产物 v{N} 递增，保留完整迭代历史
 ```
 
-### 3.4 Motion Prompt（中文 6 段模板）
-
-**复刻时**：Claude Opus 分析源帧后生成。**纯生成时**：Claude 根据用户描述编写。
-两种都写入 `prompt.md` 并打印给用户，用户可直接编辑文件。Phase 3 从 `prompt.md` 读取。
+## 项目目录
 
 ```
-### 视觉风格
-[拍摄设备感 + 画面质感 + 色彩方案 + 光线 + 氛围]
-
-### 场景叙述
-[时间地点 + 人物外貌 + 产品描述(重复颜色/特征) + 背景环境]
-
-### 摄影技术
-[景别 + 运镜 + 焦段 + 景深 + 光线]  情绪：[...]
-
-### 动作清单
-- [时间顺序，精确到哪只手]
-- [产品交互，避免复杂手部操作]
-
-### 对话
-- [语言和风格]
-
-### 背景声音
-- [环境音 + 人声 + 无背景音乐]
-```
-
-**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                ← 索引：每个 workflow 一行摘要
+│   └── {workflow-name}.md       ← 具体 workflow
+├── {project}/                   ← 项目产物
+│   ├── source/
+│   ├── frames/
+│   ├── videos/
+│   ├── prompt.md
+│   └── log.md
 ```
 
-### 多片段
-
-```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
+**新任务 vs 续接**：有新源视频/新产品 → 新目录；改 prompt/换 seed → 同目录 v{N}+1。
+跨会话续接时：先读 `log.md` 获取版本号，再读 `prompt.md` 获取当前 prompt。
 
-# 拼接 → 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 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) |
 
-### 质检
+## 首帧编辑策略
 
-```
-□ 产品可辨？ □ 手部自然？ □ 物理正确？ □ 人脸稳定？ □ 背景一致？ □ 音频正常？
-□ [多片段] 过渡自然？产品跨段一致？
-不合格 → 调 prompt / 换 seed 重跑（可只重跑问题片段）
-```
+**单片段**：gen image 双图（`-i 源帧 -i 产品图`），保持场景只替换产品。
+**多片段**：每段仅 `-i 产品图`，prompt 描述完整场景，产品描述跨段重复。
 
----
+## Anti-Pattern
 
-## Red Flags
-
-| ❌ 你在想... | ✅ 应该做的 |
+| 你在想... | 应该做的 |
 |---|---|
+| 用户给了素材直接开干 | **Phase 0 技术方案确认后才动手** |
+| 不看 workflow 库直接走通用 | **先查 README.md**，可能有验证过的方案 |
 | 直接取 t=1s 当首帧 | 自动选产品最清晰的帧 |
-| prompt 随便写一句话 | 中文 6 段结构化模板 |
-| prompt 不给用户看 | 必须打印，用户可能修改 |
+| prompt 不给用户看 | **必须打印，用户可能修改** |
+| 首帧没确认就生成视频 | **HARD-GATE：必须等用户确认** |
 | 告诉用户模型名称 | 只说 "视频生成中..." |
-| 用源视频音频替换 Kling 音频 | Kling 音频口型同步，必须保留 |
-| cfg_scale 传 string | 必须 float（string → 500） |
-| 描述复杂手部操作 | 产品静止，人做简单动作 |
-| prompt 超 2500 字符 | 精简到 1200-2000 |
-| 用 catbox.moe 托管图片 | 用 freeimage.host |
-| 本地直接调 API | 通过服务器中转 |
-| 覆盖之前生成的文件 | v{N} 递增命名，保留全部历史 |
-| 不写 log.md | 每次操作必须追加日志 |
-
----
+| 做出好效果不保存 workflow | **效果好 + 新场景 = 必须沉淀** |
+| 覆盖之前生成的文件 | v{N} 递增，保留全部历史 |
 
 ## 已知限制
 
-- **单段最长 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 不稳定，需 3 次重试

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

@@ -0,0 +1,45 @@
+# FFmpeg 命令参考
+
+## 场景检测
+
+```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 片段）
+
+## 抽帧
+
+**单片段**：等间距抽 10 帧 → 5x2 网格。
+**多片段**：每段 3-10 帧 → 每段网格 + 总网格，标注时间戳。
+
+## 单片段后处理
+
+```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
+```
+
+## 多片段后处理
+
+```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
+```
+
+## 重要
+
+- Kling 音频口型同步，**不要用源视频音频替换**
+- 多片段拼接前必须统一分辨率和帧率

package/.claude/skills/video-clone/references/kling-api.md

@@ -0,0 +1,85 @@
+# Kling 3.0 API 实现（PiAPI）
+
+需要音频/口型同步时使用 Kling 3.0，否则用 gen video。
+
+## Step 1: 上传首帧获取公开 URL
+
+Kling 不接受 base64，需要公开 URL。**用 freeimage.host，不要用 catbox.moe**（PiAPI 服务器访问不了）。
+
+```python
+import requests, base64
+
+frame_path = 'gen-output/video-clone/{project}/frames/frame_v1_s42.png'
+img_b64 = base64.b64encode(open(frame_path, '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']
+```
+
+## 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': open('gen-output/video-clone/{project}/prompt.md').read(),
+            '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！string → 500
+            'enable_audio': True,
+        },
+        'config': {'service_mode': 'public'},
+    }, timeout=60)
+task_id = resp.json()['data']['task_id']
+```
+
+## 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)
+```
+
+## Step 4: 下载视频（CDN 不稳定需重试）
+
+```python
+output_path = 'gen-output/video-clone/{project}/videos/video_v1_10s.mp4'
+for attempt in range(3):
+    try:
+        data = requests.get(video_url, timeout=300).content
+        open(output_path, 'wb').write(data)
+        break
+    except Exception:
+        time.sleep(5)
+```
+
+## 关键陷阱
+
+- `cfg_scale` 必须 float，传 string 会变 500
+- `enable_audio` 只有 3.0 支持
+- 状态是小写 `"completed"`
+- 输出字段：3.0 用 `output.video`，2.6 用 `output.video_url`
+- freeimage.host key: `6d207e02198a847aa98d0a2a901485a5`
+- 国内网络通过服务器中转 API，本地大 payload 会断连

package/.claude/skills/video-clone/references/prompt-template.md

@@ -0,0 +1,71 @@
+# Motion Prompt 模板与规范
+
+## 中文 6 段模板
+
+复刻时由 Claude Opus 分析源帧生成，纯生成时根据用户描述编写。
+写入 `prompt.md` 并打印给用户，Phase 3 从 `prompt.md` 读取。
+
+```
+### 视觉风格
+[拍摄设备感 + 画面质感 + 色彩方案 + 光线 + 氛围]
+
+### 场景叙述
+[时间地点 + 人物外貌 + 产品描述(重复颜色/特征) + 背景环境]
+
+### 摄影技术
+[景别 + 运镜 + 焦段 + 景深 + 光线]  情绪：[...]
+
+### 动作清单
+- [时间顺序，精确到哪只手]
+- [产品交互，避免复杂手部操作]
+
+### 对话
+- [语言和风格]
+
+### 背景声音
+- [环境音 + 人声 + 无背景音乐]
+```
+
+## Anti-AI 风格（融入摄影技术段）
+
+手持拍摄/轻微晃动/自然光/无滤镜/纪实感
+
+## 禁用词
+
+梦幻/空灵/电影感/慢动作/丝滑/优雅
+
+## 长度控制
+
+1200-2000 字符，超 2500 必须精简。
+
+## prompt.md 工作流
+
+1. Claude 分析 → 写入 prompt.md → 打印给用户
+2. 用户说"OK" → 直接用；用户说"改一下" → 用户编辑或告诉 Claude 改
+3. Phase 3 从 prompt.md 读取生成视频
+4. 重跑时：修改 prompt.md → 旧版本记录到 log.md
+
+## 示例
+
+```markdown
+# fishing-scale — Prompt
+
+### 视觉风格
+竖屏手持vlog，自然饱和色彩，明亮日光，无滤镜，纪实感。
+
+### 场景叙述
+阳光白天，戴眼镜、深蓝头巾、黑色运动上衣的女子跪坐沙滩...
+
+### 摄影技术
+中景，手持拍摄，轻微晃动，自然光，浅景深。情绪：轻松日常
+
+### 动作清单
+- 左手托住电子秤底部，右手食指轻触屏幕
+- 产品保持静止，人物微笑看向镜头
+
+### 对话
+- 英语，日常对话风格
+
+### 背景声音
+- 海浪声、风声、远处人声，无背景音乐
+```

package/.claude/skills/video-clone/references/url-parsing.md

@@ -0,0 +1,13 @@
+# URL 解析规则
+
+**不要用 WebFetch**（反爬/登录墙），按平台处理：
+
+| 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>` → 视频链接 |
+| 本地文件 | 直接使用 |

package/.claude/skills/video-clone/references/workflow-system.md

@@ -0,0 +1,92 @@
+# Workflow 经验库系统
+
+## 什么是 Workflow
+
+Workflow 是一次成功视频制作的经验总结。它记录了在特定场景下"什么方法效果最好"，让相似任务不用从零摸索。
+
+## 目录结构
+
+```
+gen-output/video-clone/workflows/
+├── README.md                        ← 索引，每个 workflow 一行
+├── handheld-product-swap.md         ← 手持vlog产品替换
+├── multi-scene-product-demo.md      ← 多场景产品展示
+└── lifestyle-pure-gen.md            ← 生活方式纯生成
+```
+
+## README.md 格式
+
+索引文件，快速定位。每行一个 workflow，格式：
+
+```markdown
+# Video Clone Workflows
+
+| Workflow | 适用场景 | 效果 | 关键策略 |
+|---|---|---|---|
+| [handheld-product-swap](handheld-product-swap.md) | 手持vlog + 单物品替换 | ⭐⭐⭐⭐⭐ | 双图首帧, t=15s选帧, 简单手部动作 |
+| [multi-scene-product-demo](multi-scene-product-demo.md) | 多场景产品展示(>2段) | ⭐⭐⭐⭐ | 每段独立首帧, 产品描述跨段一致 |
+```
+
+## Workflow 文件格式
+
+每个 `.md` 文件包含：
+
+```markdown
+# {workflow-name}
+
+## 适用场景
+- 什么类型的视频适合用这个 workflow
+- 关键特征（单/多段、有无人物、产品类型等）
+
+## 策略
+
+### 首帧
+- 选帧策略（哪个时间点最好、为什么）
+- gen image 参数（单图/双图、prompt 关键词）
+- 踩坑记录（什么不 work）
+
+### Prompt
+- prompt 风格和重点（哪些段需要重点写）
+- 验证有效的 prompt 片段（可直接复用）
+- 禁用/低效的描述方式
+
+### 视频生成
+- 工具选择和参数
+- cfg_scale / duration / mode 配置
+
+### 后处理
+- 特殊的 ffmpeg 参数
+
+## 成功案例
+- 项目名 + 简要结果（链接到项目目录）
+
+## 踩坑记录
+- 试过但失败的方法，避免重蹈覆辙
+```
+
+## 何时创建新 Workflow
+
+满足以下全部条件：
+
+1. **用户满意** — 最终视频被用户认可
+2. **新场景** — 没有已有 workflow 完全覆盖
+3. **有可复用的经验** — 不是纯靠运气，有明确的策略可提炼
+
+## 何时更新已有 Workflow
+
+- 同类任务发现了更好的参数/策略
+- 踩了新坑，值得记录避免下次再踩
+- 工具更新导致旧策略需要调整
+
+## 匹配逻辑
+
+Phase 0 读取 README.md 后，按以下维度匹配：
+
+1. **视频类型**：手持vlog / 产品展示 / 口播 / 纯展示
+2. **片段结构**：单片段 / 多片段
+3. **产品交互**：手持 / 桌面摆放 / 穿戴 / 无人物
+4. **音频需求**：有口型同步 / 纯BGM / 无音频
+
+完全匹配 → 直接复用策略。
+部分匹配 → 以最接近的 workflow 为基础调整。
+无匹配 → 走通用 pipeline。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/optima-agent",
-  "version": "0.8.90",
+  "version": "0.8.91",
   "description": "基于 Claude Agent SDK 的电商运营 AI 助手",
   "type": "module",
   "main": "dist/src/index.js",