@optima-chat/optima-agent 0.8.95 → 0.8.97

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

@@ -1,199 +0,0 @@
----
-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)、用户贴视频链接+产品图要求出同款视频、或用户提供图片/文字描述要求直接生成视频(生成视频/图生视频/做一个视频)。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`) 已废弃。
-> 旧项目继续用旧脚本完成，新项目全部走本版本流程。
-
-## 前置依赖
-
-- **`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)）
-
-触发 skill 后第一步：运行 `python scripts/preflight.py`，确认上述依赖。
-
-## 脚本 Pipeline 一览
-
-单门模型：所有 prep 脚本自由运行，preview 之后只有一个 GATE。
-
-```
-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)。
-
-<HARD-GATE>
-**Gate 由脚本机械强制，不是文本约定。** 任何绕过 gate 的方式都会留下证据：
-  1. 手工编辑 `.state/phase.json` — history 字段会显示断点
-  2. 伪造 `--quote` 调用 `confirm.py` — user_quote 字段留痕，事后可倒查
-
-**USER GATE 不可被用户单方面取消。** 即使用户说"不要问问题/我信任你/自己判断"，
-仍必须展示 preview bundle 并等待确认。用户可以说"可以，开始"以确认，但不能
-预先豁免整个 GATE 机制。
-
-每个 Phase 产物必须版本化命名（脚本通过 `_project.next_version()` 自动处理），
-绝不覆盖已有文件。
-</HARD-GATE>
-
-## Rationalization Counter
-
-以下是最常见的"合理化借口"及其反驳。遇到这些想法时必须 STOP。
-
-| 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** 这一步仍是必须的 |
-
-## Phase 0: 理解需求 + 匹配 Workflow
-
-**在动手之前，先搞清楚用户到底要什么，再看有没有现成的好方案。**
-
-快速判断任务类型：有源视频 + 产品图 → 视频复刻；无源视频 → 纯视频生成。
-
-**仅做轻量元数据识别，不执行工具调用**。不下载视频、不调 ffprobe、不抽帧。
-
-按需提问（不一次全问）：产品是什么、替换目标、音频需求（有音频 ~$1.50/10s，无音频 ~$0.02/10s，扣 Optima credits 由服务端中间件完成）、时长期望。
-
-先查 `gen-output/video-clone/workflows/README.md` — 完全匹配 → 复用；部分匹配 → 调整；
-无匹配 → 走通用 pipeline。详见 [workflow-system.md](references/workflow-system.md)。
-
-## Phase 1-2: Prep（自主运行，无 gate）
-
-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>
-```
-
-`preview.py` 检查所有 prep 产物是否齐全，输出 `preview_vN.md`（六节）。
-
-**[USER GATE] 把 preview 展示给用户，等待确认，然后运行：**
-
-```bash
-python scripts/confirm.py --project <slug> --quote "<用户原话>"
-```
-
-## Phase 3-5: 生成 + 后处理 + 沉淀
-
-```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
-
-# Phase 4 — 后处理
-python scripts/assemble.py --project <slug> --single videos/video_vN.mp4
-
-# Phase 5 — 沉淀（可选）
-python scripts/save_workflow.py --project <slug> \
-    --name <workflow-slug> --scene "<适用场景>" \
-    --rating <1-5> --strategy "<关键策略>"
-```
-
-## 铁律
-
-1. 先理解再动手 — 出 preview 前先跑完所有 prep 脚本
-2. 先查 workflow 再造轮子 — 已有经验不要浪费
-3. 首帧质量决定一切 — 自动选产品最清晰+手部最自然的帧
-4. Prompt 质量 = 视频质量 — preview 里展示给用户，用户可能修改
-5. 永远不覆盖文件 — 脚本通过 next_version() 自动 v{N} 递增
-6. 不要自己编辑 .state/phase.json — 还不如走 confirm.py 正常路径
-
-## 项目目录
-
-```
-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>` 看当前状态和下一步。
-
-## 工具分工
-
-| 工具 | 脚本 | 职责 |
-|---|---|---|
-| 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"）。
-只说"视频生成中..."或"已提交生成任务"。
-
-## 首帧编辑策略
-
-**单片段**：`edit_first_frame.py` 用双图（`-i 源帧 -i 产品图`），保持场景只替换产品。
-**多片段**：每段仅 `-i 产品图`，prompt 描述完整场景，产品描述跨段重复。
-
-## Anti-Pattern
-
-| 你在想... | 应该做的 |
-|---|---|
-| 用户给了素材直接开干 | **先 preflight + 跑完 prep + 出 preview + confirm.py** |
-| 不看 workflow 库直接走通用 | 先查 `workflows/README.md` |
-| 直接取 t=1s 当首帧 | 自动选产品最清晰的帧 |
-| prompt 不给用户看 | **必须在 preview 里展示，用户可能修改** |
-| 跳过 preview 直接 confirm | preview.py 会验证所有 prep 产物是否齐全 |
-| 告诉用户具体模型名称 | 只说 "视频生成中..." 不透露底层模型 |
-| 做出好效果不保存 workflow | **效果好 + 新场景 = 必须沉淀** |
-| 覆盖之前生成的文件 | 脚本自动 v{N} 递增 |
-| 把 `--quote "ok"` 当成真实确认 | 伪造 quote 会在 history 留痕，事后可倒查 |
-
-## 已知限制
-
-- 单段最长 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

@@ -1,11 +0,0 @@
-{
-  "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,42 +0,0 @@
-# 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.
-
-| 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` |
-
-## Single vs multi-segment heuristic
-
-`analyze_source.py` classifies automatically:
-
-- 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.
-
-## 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.
-
-## Raw command reference (only when debugging outside the scripts)
-
-```bash
-# probe metadata
-ffprobe -v quiet -print_format json -show_format -show_streams video.mp4
-
-# concat list format (scripts generate this automatically)
-file 'clip1_norm.mp4'
-file 'clip2_norm.mp4'
-```

package/.claude/skills/video-clone/references/gate-enforcement.md

@@ -1,144 +0,0 @@
-# Gate Enforcement
-
-This skill enforces its HARD-GATE mechanically, not textually. Every
-executor script that costs money or generates output calls `require_gate()`
-at startup and exits with code 1 if the gate isn't set. You cannot
-rationalize past a CLI that won't produce output.
-
-## State location
-
-Each project has its own state file:
-
-```
-gen-output/video-clone/<project>/.state/phase.json
-```
-
-## Schema (single-gate model — PR #65)
-
-```json
-{
-  "schema_version": 1,
-  "project": "handheld-phone-swap",
-  "task_type": "video_clone",
-  "created_at": "2026-04-11T16:55:00Z",
-  "current_phase": 0,
-  "gates": {
-    "preview_confirmed": {"status": false, "confirmed_at": null, "user_quote": null}
-  },
-  "history": []
-}
-```
-
-There is **one gate**: `preview_confirmed`. It is set by `confirm.py`
-after the user reviews the complete prep preview (analysis + grid +
-prompt + edited frame). The prep scripts (analyze_source, extract_frames,
-edit_first_frame) run freely before confirmation — only the generation
-scripts are gated.
-
-Gates are never un-set. Each set operation appends an entry to `history`
-with timestamp + user quote + caller script name, giving you an audit
-trail to answer "did the user actually confirm this?"
-
-## Which script needs which gate
-
-| Script | Required gate |
-|---|---|
-| `analyze_source.py` | (none — prep runs freely) |
-| `extract_frames.py` | (none — prep runs freely) |
-| `edit_first_frame.py` | (none — prep runs freely) |
-| `preview.py` | (none — collects artifacts, no cost) |
-| `kling_generate.py` | **preview_confirmed** |
-| `gen_video.py` | **preview_confirmed** |
-| `save_workflow.py` | **preview_confirmed** |
-| `assemble.py` | (none — post-processes already-generated videos) |
-| `init_project.py` | (none — must run before any gate exists) |
-| `confirm.py` | (none — sets the gate) |
-| `preflight.py` | (none — environment check) |
-| `status.py` | (none — read-only) |
-
-## How to set the gate
-
-```bash
-python scripts/confirm.py --project <name> --quote "<user's actual words>"
-```
-
-- **`--quote` is required** and must be non-empty.
-- **Quote heuristic**: if the quote contains negation markers (`不`, `改`,
-  `no`, `not`, `change`, `modify`, `wrong`, …), the script refuses to set
-  the gate unless you also pass `--force`. This prevents Claude from
-  using a correction ("不需要音频") as a confirmation.
-- **Use `--force` sparingly**: only when the user said something like
-  "no audio, otherwise good" — a genuine confirmation that contains a
-  negation word.
-- The gate records `caller` (the script name) in history. Fabricated
-  quotes are detectable in post-mortem review.
-
-## How a blocked script looks
-
-```
-[HARD-GATE BLOCKED] kling_generate.py needs preview_confirmed=True
-Current state: preview_confirmed=False
-Project: /abs/path/to/gen-output/video-clone/handheld-phone-swap
-
-To proceed:
-  1. Show the preview bundle to the user and wait for their confirmation.
-  2. Run: python scripts/confirm.py --project <name> --quote "<user's actual words>"
-  3. Retry this command.
-
-Claude: do NOT rationalize past this. The gate exists because text
-instructions alone did not stop prior bypass attempts. Go get the real
-user confirmation.
-```
-
-Exit code is always 1. Downstream pipes will break; you can't accidentally
-feed "locked" output into the next step.
-
-## Old 3-gate schema (pre-PR #65)
-
-If you have a project created before the single-gate refactor, the state
-file will have `plan_confirmed`, `prompt_confirmed`, `frame_confirmed`
-instead of `preview_confirmed`. Any gated script will exit 1 with:
-
-```
-[HARD-GATE BLOCKED] expected gate 'preview_confirmed' but it is not
-present. This is most likely an old 3-gate schema project.
-Either: complete this project with PR #65 scripts, or start a new project.
-```
-
-Do NOT manually edit old phase.json files to add `preview_confirmed`.
-Start a new project with `init_project.py` and re-run prep.
-
-## Common bypass attempts (and why the gate still wins)
-
-| Attempt | Outcome |
-|---|---|
-| "analyze_source is just analysis, no cost" | Runs freely — no gate on prep scripts. Correct behavior. |
-| "I'll edit phase.json to set the gate" | Possible, but leaves a gap in `history`. Audit trail shows no `confirm.py` call. |
-| `confirm.py --quote 'ok'` without asking user | Sets gate with `user_quote: "ok"`. No user types that in isolation — obvious in post-mortem. |
-| "I'll skip preview.py and confirm directly" | `confirm.py` doesn't require preview_v*.md — but `preview.py` must have run first for artifacts to be present for the user to review. |
-| "I'll symlink phase.json to /dev/null" | Exit 1 on read. |
-| "I'll delete .state/" | Exit 1 — "phase.json not found". |
-
-The cheapest path is always to actually get the user's confirmation.
-
-## When to read history
-
-The `history` array is append-only. Useful cases:
-
-- **Resuming a multi-session project** — read history to know what gate
-  is set and what the user said. Use `status.py` for a human-readable view.
-- **Debugging bad output** — if a video is wrong, history shows the exact
-  quote the user gave when confirming the preview.
-- **Verifying gate authenticity** — `caller` field shows which script set
-  the gate. `confirm.py` is the only legitimate caller.
-
-## Why this exists
-
-Previous versions had HARD-GATE rules in SKILL.md text with a
-Rationalization Counter table. They did not stop Claude from running
-ffprobe / downloading videos / calling `gen image` before the user
-confirmed. The failure mode was always the same: Claude decided "my action
-doesn't count as execution" and rationalized past the text rule.
-
-Mechanical gates end the argument. The script either runs or it doesn't,
-and the decision doesn't depend on how Claude interprets the rules.

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

@@ -1,85 +0,0 @@
-# Video generation with audio — what the script handles + what you need to know
-
-The `kling_generate.py` script calls the **Optima generation backend**, which
-routes to Kling 3.0 internally. The script itself knows nothing about the
-upstream provider — only the backend does.
-
-```bash
-python scripts/kling_generate.py --project <name> --frame <confirmed-frame.png>
-# options: --duration 5|10  --aspect-ratio 9:16  --mode std|pro
-#          --cfg-scale 0.5  --no-audio
-```
-
-## When to use `kling_generate.py` vs `gen_video.py`
-
-| Need audio / lip sync? | Use |
-|---|---|
-| Yes | `kling_generate.py` ($0.15/s ≈ $1.50 per 10s equivalent) |
-| No | `gen_video.py` (~$0.02 per 10s equivalent) |
-
-Both scripts go through the same generation backend and the same billing
-middleware — the difference is server-side provider selection.
-
-## Auth + API URL discovery
-
-`kling_generate.py` mirrors the `@optima-chat/gen-cli` auth convention, so
-any user who has run `optima login` is automatically ready — no extra env
-setup needed.
-
-Token resolution (first match wins):
-
-1. `OPTIMA_TOKEN` env var
-2. `~/.optima/token.json` (`access_token` field)
-
-Generation API URL resolution (first match wins):
-
-1. `GENERATION_API_URL` env var
-2. `~/.optima/token.json` `env` field → `ci` / `stage` / `prod` mapping
-3. default: `https://gen-api.optima.onl` (prod)
-
-If neither token source resolves, the script exits 1 with a clear hint
-(`Run `optima login` or set OPTIMA_TOKEN`). **No fallback to direct upstream
-calls** — that would bypass billing.
-
-Run `scripts/preflight.py` to verify the auth state and other deps.
-
-The `requests` Python package is also required.
-
-## Billing
-
-Billing is entirely server-side. When `kling_generate.py` calls
-`POST /api/video/generate`, the backend's billing middleware pre-deducts
-credits from the user's Optima wallet based on `metadata.duration`. If the
-upstream task later fails, the server refunds the credits automatically
-(see `billingClient.refund()` in the generation service worker).
-
-This means the skill never sees raw USD pricing — it just sends a request
-and waits. The user's wallet is the source of truth for how much was spent.
-
-## Error handling
-
-`_submit()` translates the common billing errors into readable messages:
-
-- HTTP 402 `INSUFFICIENT_CREDITS` — user does not have enough credits
-- HTTP 403 `PLAN_RESTRICTED` — user's plan does not include video generation
-
-Other HTTP errors propagate via `raise_for_status()`. Polling uses the
-backend's unified `GET /api/task/{id}` endpoint.
-
-## Non-obvious traps (now handled server-side)
-
-The `cfg_scale`-must-be-float / lowercase-status / 3.0-vs-2.6 response
-differences / freeimage-vs-catbox quirks are all handled by the server's
-PiAPI adapter (`optima-gen: packages/generation/src/adapters/piapi-video.ts`).
-The skill no longer has to know about them.
-
-## What changed vs the old direct-PiAPI version
-
-Before: script uploaded to freeimage.host, submitted to PiAPI, polled PiAPI,
-downloaded from Kling CDN. No billing. Shared PiAPI key hardcoded in the
-skill.
-
-After: script sends one POST + polls one endpoint on the Optima backend.
-Billing is automatic. No upstream API keys in the skill. Provider switches
-(if the Kling API ever changes) happen server-side without touching any
-client code.

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

@@ -1,71 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# URL / Source Download — decision table
-
-**Do not use WebFetch** for source videos (anti-scraping, auth walls).
-Choose the right tool based on the URL shape and use it manually — there
-is no script wrapper because the right approach varies by platform.
-
-| URL shape | Command |
-|---|---|
-| `tiktok.com/@user/video/<id>` | `scout tiktok video-detail <id>` → grab video URL → `wget` |
-| `vm.tiktok.com/<short>` | `curl -sI <url>` → `Location:` header → extract id → see TikTok row |
-| `douyin.com/video/<id>` | `scout douyin video-download <id>` → `wget` |
-| `v.douyin.com/<short>` | `scout douyin video-by-url "<url>"` |
-| Instagram Reels (`instagram.com/reel/...`) | `scout instagram download-reel "<url>"` |
-| 小红书视频 (`xiaohongshu.com/explore/<id>`) | `scout xhs note-detail <id>` → grab video link → `wget` |
-| Local file path | Pass directly to `--video` |
-
-After download, save to `gen-output/video-clone/<project>/source/` and
-then feed the local path to `analyze_source.py --video <path>`.
-
-## Why the script pipeline starts after download
-
-Downloading is the *only* step that remains manual because platform APIs
-change faster than the script would. Everything downstream of
-`--video <local-file>` is automated by the Python scripts.
-
-## Sanity checks before running analyze_source.py
-
-1. File size > 0
-2. `ffprobe -v error <file>` returns no errors
-3. Duration makes sense for the source (`ffprobe -show_entries format=duration`)
-
-If any of these fail, re-download with a different tool before proceeding.

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

@@ -1,92 +0,0 @@
-# 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。