npm - @optima-chat/optima-agent - Versions diffs - 0.8.89 → 0.8.91 - Mend

@optima-chat/optima-agent 0.8.89 → 0.8.91

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/.claude/skills/homepage/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: homepage
-description: 店铺首页配置。管理首页区块（Banner、集合列表、集合商品、特色推荐）。当用户需要配置店铺首页布局、添加轮播图、展示集合、设置 Banner 不裁切/完整显示时使用。
+description: 店铺首页配置。管理首页区块（Banner、集合列表、集合商品、特色推荐）和页面级设置（背景图、叠加层）。当用户需要配置店铺首页布局、添加轮播图、展示集合、设置背景图片、设置 Banner 不裁切/完整显示时使用。
 ---
 ## 重要：先查后做
@@ -48,6 +48,16 @@ description: 店铺首页配置。管理首页区块（Banner、集合列表、
 | 添加特色推荐 | `commerce homepage create-featured --title <title> --lang <lang> --target-type collection --target-handle <handle> --cta "查看" --image-url "https://..."` |
 | 更新推荐目标 | `commerce homepage update-target --id <id> --type <type> --handle <handle>` |
+### 背景图
+| 用户说 | 命令 |
+|-------|------|
+| 设置首页背景图 | `commerce homepage update-page-settings --background-image "https://..." --background-mode repeat-y` |
+| 设置固定背景（照片） | `commerce homepage update-page-settings --background-image "https://..." --background-mode fixed` |
+| 调整背景叠加透明度 | `commerce homepage update-page-settings --overlay-opacity 0.7` |
+| 调整背景叠加颜色 | `commerce homepage update-page-settings --overlay-color "#f5f5f5"` |
+| 移除背景图 | `commerce homepage update-page-settings --remove-background` |
 ### 通用操作
 | 用户说 | 命令 |
@@ -100,6 +110,17 @@ description: 店铺首页配置。管理首页区块（Banner、集合列表、
 | cta_text | string | CTA 按钮文字 |
 | background_color | string | 背景颜色，如 `#f5f5f5` |
+### page_settings（页面级设置）
+通过 `update-page-settings` 命令修改，不是 `patch-settings`。
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| background_image | string / null | 背景图片 URL（HTTPS），null 表示无背景 |
+| background_mode | string | `repeat-y`（横向填满纵向平铺，默认）/ `fixed`（固定视口） |
+| background_overlay_color | string | 叠加颜色（hex 格式，默认 `#ffffff`） |
+| background_overlay_opacity | number | 叠加透明度 0-1（默认 0.85，越大越不透明） |
 ## 复杂操作说明
 ### update-images 全量替换

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

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