@optima-chat/optima-agent 0.8.95 → 0.8.96

package/.claude/skills/gen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gen
-description: "生成和编辑图片/语音/虚拟试穿。使用场景：生成图片(generate images/生成图片/画图)、编辑图片(edit images/编辑图片/图生图/风格转换)、文本转语音(TTS/语音合成/朗读)、语音识别(ASR/语音转文字/转录)、虚拟试穿(virtual try-on/试穿/换装/试衣)。视频生成请使用 video-clone skill。"
+description: "生成和编辑图片/语音/虚拟试穿。使用场景：生成图片(generate images/生成图片/画图)、编辑图片(edit images/编辑图片/图生图/风格转换)、文本转语音(TTS/语音合成/朗读)、语音识别(ASR/语音转文字/转录)、虚拟试穿(virtual try-on/试穿/换装/试衣)。视频生成请使用 video-gen skill。"
 ---
 
 # AI 内容生成工具

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

@@ -0,0 +1,443 @@
+---
+name: video-gen
+description: "帮商家用 AI 生成产品视频（社媒投放 / 产品详情页）。触发场景：用户要做视频(做视频/生成视频/产品视频/宣传视频/图生视频)、用户给视频链接+产品图要复刻(复刻/翻拍/仿拍/做同款/爆款复刻)、用户给产品图想发社媒(TikTok视频/IG视频/短视频)、用户给产品图想放详情页(PDP视频/产品展示视频)。"
+---
+
+# Video Generation Skill
+
+帮电商商家用 AI 视频生成替代传统实拍。核心价值：**帮用户形成一份满意的 Storyboard，然后按 Storyboard 执行生成。**
+
+## 工作目录
+
+所有状态都在 `~/video-gen/`，整个目录是一个 git repo。
+
+```
+~/video-gen/
+├── preferences.md
+├── history.md
+└── videos/{video-id}/
+    ├── analysis.md
+    ├── storyboard.md
+    ├── production-plan.md
+    ├── quality-report.md
+    ├── assets/
+    │   ├── product.jpg
+    │   ├── reference.mp4
+    │   └── keyframes/
+    ├── prompts/
+    │   └── seg-N.txt
+    ├── clips/
+    │   ├── seg-N.pending.json
+    │   ├── seg-N.meta.json
+    │   └── seg-N.mp4
+    └── final.mp4
+```
+
+## 每次 session 的启动流程
+
+按顺序执行：
+
+1. **检查工作目录**：`ls ~/video-gen/preferences.md`
+   - 不存在 → 走「First-time init」
+   - 存在 → 继续步骤 2
+2. **扫描未完成任务**：找 `~/video-gen/videos/` 下无 `quality-report.md` 且创建 < 7 天的目录
+   - 有 → 在回复用户前主动提一次："你有 N 个视频没完成..."
+   - 无 → 继续步骤 3
+3. **读 preferences.md** 和 **history.md**
+4. **按用户意图分流**：
+   - 有视频 + 有产品图 → Fast-path：直接走「分析 → Storyboard → Production Plan → 生成」全管道
+   - 有视频，无产品图 → 问"换成哪个产品？"
+   - 只有产品图/文字，信息充分 → Fast-path：走「Storyboard → Production Plan → 生成」
+   - 只有产品图/文字，信息不足 → 问"这个视频用在哪？"
+     - 社媒 → "要不要找 3 个爆款参考？"
+       - 要 → 走「参考发现」，用户选后继续管道
+       - 不要 → 从模板构建 Storyboard
+     - PDP → 从 PDP 模板构建 Storyboard
+   - "再试 / 更活泼 / 改 X" → 走「迭代」
+
+**Fast-path 触发条件**（必须全部满足才走 fast-path，否则先问）：
+
+| 场景 | 必须有 | 可从 preferences 兜底 |
+|---|---|---|
+| **复刻** | 视频文件/链接 + 产品图 | 调性、平台 |
+| **生成（社媒）** | 产品图 + 明确的意图动词（"做视频"/"生成"） + 平台 | 调性 |
+| **生成（PDP）** | 产品图 + 明确说"详情页"/"PDP" | 调性 |
+| **迭代** | 明确的 delta（"更活泼"/"暖一点"）+ history 无歧义匹配 | — |
+
+**Fast-path 行为**：Storyboard 展示后告知而非审批，但**生成前必须告知预估成本**（见「执行生成」的成本确认）。用户可随时喊停。
+
+## First-time init
+
+首次使用时执行：
+
+```bash
+mkdir -p ~/video-gen/videos
+cd ~/video-gen
+git init -b main
+```
+
+创建 `~/video-gen/preferences.md`：
+
+```markdown
+# Preferences
+
+## Brand
+name:
+palette:
+tone:
+forbidden:
+
+## Defaults
+platform:
+aspect_ratio:
+duration_seconds:
+
+## Learned
+```
+
+创建 `~/video-gen/history.md`：
+
+```markdown
+# History
+
+| date | video-id | product | purpose | template | storyboard-summary | parent | status | liked |
+|---|---|---|---|---|---|---|---|---|
+```
+
+创建 `.gitignore`：
+
+```
+videos/**/assets/reference.mp4
+videos/**/assets/*.mov
+videos/**/clips/*.mp4
+videos/**/clips/*.mov
+videos/**/final.mp4
+videos/**/final.mov
+```
+
+```bash
+git add -A && git commit -m "init: video-gen workspace"
+```
+
+**Minimal init**：不要在首次使用时做问卷。只建骨架文件，preferences 留空。
+
+如果用户的首条消息已经包含了足够的信息（产品图 + 意图），**直接进管道**，在过程中自然补充 preferences：
+- 用户说了"TikTok" → 默默填 Defaults.platform = TikTok
+- 用户说了"warm 风格" → 默默填 Brand.tone = warm
+- 都没说 → 从模板默认值兜底，不打断流程去问
+
+只有当管道完全无法推进时（例如连产品图都没有），才问**一个**关键问题。
+
+每次有新信息写入 preferences → `git commit -m "prefs: update <field>"`
+
+## 参考发现（仅社媒 + 用户同意时）
+
+1. 根据产品品类 + 平台，调 scout 相关命令搜近期爆款
+2. 品牌契合 + 产品形态匹配过滤
+3. 展示 3 个候选：平台 + 时间 + 指标 + 风格摘要
+4. **用户选一个** → 继续「分析源视频」
+5. "都不要" → 从模板构建 Storyboard
+
+**绝不自动选参考。**
+
+## 分析源视频
+
+有源视频时执行。产出 `videos/{id}/analysis.md`。
+
+1. 创建项目目录：
+
+```bash
+VIDEO_ID="$(date +%Y%m%d-%H%M)-<slug>"
+mkdir -p ~/video-gen/videos/$VIDEO_ID/{assets/keyframes,prompts,clips}
+```
+
+2. 保存素材到 `assets/`
+
+3. ffmpeg 场景检测：
+
+```bash
+ffprobe -v quiet -print_format json -show_format -show_streams assets/reference.mp4
+ffmpeg -i assets/reference.mp4 -vf "select='gt(scene,0.3)',showinfo" -vsync 0 -f null - 2>&1 | grep showinfo
+```
+
+4. 每段抽 3 帧（首/中/尾）：
+
+```bash
+ffmpeg -i assets/reference.mp4 -vf "select='eq(n\,<FRAME_NUM>)'" -vsync 0 assets/keyframes/seg-<N>-<pos>.jpg
+```
+
+5. 读取关键帧图片，分析每段的 subject / composition / camera / lighting / palette / description
+
+6. 验证 ffmpeg 切段合理性（修正软切/漏切）
+
+7. 以表格写入 `analysis.md`：
+
+```markdown
+# Analysis
+
+## 元数据
+| 项目 | 值 |
+|---|---|
+| 总时长 | 7.0s |
+| 比例 | 9:16 |
+| FPS | 30 |
+| 片段数 | 4 |
+
+## 镜头分析
+
+| 段 | 时长 | 主体 | 角色 | 构图 | 运镜 | 光线 | 色调 | 描述 |
+|---|---|---|---|---|---|---|---|---|
+| 1 | 0-1.5s | ... | ... | ... | ... | ... | ... | ... |
+| ... |
+
+## 整体风格
+| 项目 | 值 |
+|---|---|
+| Pacing | slow |
+| Mood | aspirational, minimalist |
+| Hook | subtle visual intrigue |
+| CTA | logo reveal |
+```
+
+8. `git commit -m "video: analyze $VIDEO_ID — N segments, Xs"`
+
+## 形成 Storyboard
+
+核心产出。**用户语言写，用户能读能改。**
+
+1. 读输入：preferences + analysis（如有）+ history 匹配 liked 记录 + 匹配模板（从 `$CLAUDE_SKILL_DIR/templates/` 读）
+
+2. 有模板则以模板为骨架填入产品/品牌信息；否则从零构建
+
+3. 复刻场景做**物理合理性预检**：原主体和用户产品形态是否兼容
+   - 不合理 → 告知原因，降级策略或建议换参考
+
+4. 写 `videos/{id}/storyboard.md`：
+
+```markdown
+# Storyboard
+
+## 基本信息
+| 项目 | 值 |
+|---|---|
+| 产品 | <名称> |
+| 平台 | <TikTok / IG / PDP> |
+| 时长目标 | <Ns> |
+| 调性 | <调性> |
+| 参考来源 | <来源或"从模板构建"> |
+
+## 镜头表
+| 段 | 时长 | 内容 | 运镜 | 替换说明 |
+|---|---|---|---|---|
+| 1 | 0-1.5s | <内容> | <运镜> | <替换或"原创"> |
+| ... |
+
+## Hook
+<第 1 秒如何抓注意力>
+
+## CTA
+<末尾留什么>
+
+## 物理合理性预检
+<复刻时：替换是否合理。无参考时写 N/A>
+```
+
+5. 展示给用户：
+   - Fast-path：告知（不等审批），用户可喊停
+   - 非 Fast-path：问"OK 吗？想改哪段告诉我。"
+
+6. 确认后 `git commit -m "video: storyboard $VIDEO_ID — <summary>"`
+
+## 产出 Production Plan
+
+Storyboard 确认后自动推导。用户通常不改。
+
+1. 选策略：
+
+| 特征 | 策略 | 默认 provider |
+|---|---|---|
+| 1 镜头，无参考 | single-shot | 默认 |
+| 多镜头，无参考 | multi-shot-concat | 默认 |
+| 有参考，大致复刻 | clone-loose | 默认 |
+| 有参考，高度还原 | clone-strict | 默认 |
+| PDP 多卖点 | pdp-feature-concat | 默认 |
+| 人物讲话 + 严格对口型 | talking-head | `piapi`（Kling 3.0） |
+| 用户明确要 premium 质量 | 任一 + premium | `piapi` |
+
+2. 写 `videos/{id}/production-plan.md`：
+
+```markdown
+# Production Plan
+
+## 策略
+<策略名>
+原因: <选择理由>
+
+## 步骤
+| Step | 工具 | 输入 | 输出 | 依赖 | Prompt 摘要 |
+|---|---|---|---|---|---|
+| 1 | <工具> | <输入> | <输出> | — | <prompt 或 N/A> |
+| ... |
+
+## 验收标准
+- 比例: <从 Storyboard>
+- 时长: <从 Storyboard ±20%>
+- Hook: <从 Storyboard>
+- CTA: <从 Storyboard>
+```
+
+3. 为每个需 prompt 的步骤生成 `prompts/seg-N.txt`
+
+4. `git commit -m "video: plan $VIDEO_ID — <strategy>"`
+
+## 执行生成
+
+<COST-GATE>
+**生成前成本确认（必做，包括 Fast-path）**：在执行任何 `gen video` / `gen image` 调用之前，必须向用户展示一次成本摘要：
+
+> 即将生成 N 段视频（策略: <策略名>），预计：
+> - 调用次数: N 次 gen video + M 次 gen image（首帧编辑）
+> - 预估耗时: ~X 分钟
+> - 预估成本: ~$Y（扣 Optima credits）
+>
+> 继续？
+
+用户说"继续"/"好"/"OK" → 开始执行。
+用户说"太贵"/"换个便宜的" → 回到 Production Plan，换策略（如 strict → loose）。
+用户不回应超过合理时间 → 不执行，等用户。
+
+**即使是 Fast-path 也必须走这一步。** 这是花钱步骤的唯一确认点。
+</COST-GATE>
+
+按 production-plan.md 步骤表逐步执行。
+
+**每步执行前**写 `clips/seg-N.pending.json`：
+
+```json
+{
+  "task_id": "",
+  "submitted_at": "<ISO>",
+  "step": 1,
+  "tool": "<gen video | gen image | ffmpeg>"
+}
+```
+
+**工具调用**：
+
+```bash
+# I2V（图生视频）— 默认走 DashScope Wan 2.6，便宜快
+gen video <input_image> \
+  --prompt "<from prompts/seg-N.txt>" \
+  --duration <5|10> \
+  --resolution <720P|1080P> \
+  -o clips/seg-<N>.mp4
+
+# I2V 需要精确口型/人物动作（talking head）— 用 Kling 3.0
+gen video <input_image> \
+  --prompt "<from prompts/seg-N.txt>" \
+  --duration <5|10> \
+  --provider piapi \
+  -o clips/seg-<N>.mp4
+
+# 首帧编辑（产品替换）— 双图模式
+gen image "<编辑指令>" -i <原始首帧> -i <产品图> -o assets/keyframes/seg-<N>-edited.jpg
+
+# 拼接
+printf "file '%s'\n" clips/seg-*.mp4 > concat_list.txt
+ffmpeg -f concat -safe 0 -i concat_list.txt -c copy final.mp4
+
+# 任务查询 / 取消 / 重试
+gen task get <task_id>
+gen task cancel <task_id>
+gen task retry <task_id>
+```
+
+**Provider 选择逻辑**（在产出 Production Plan 时决定）：
+
+| 场景 | Provider | 理由 |
+|---|---|---|
+| 默认（产品展示 / 生活场景 / 大部分复刻） | 默认（DashScope） | 便宜（~10x 差距），质量足够 |
+| 人物讲话 + 严格对口型 | `--provider piapi`（Kling 3.0） | Kling 3.0 口型精度更高 |
+| 高质量严格复刻（用户明确要求 premium） | `--provider piapi` | Kling 3.0 保真度更高 |
+
+**时长限制**：`gen video --duration` 仅支持 5 或 10 秒。多段视频用多次 `gen video` + `ffmpeg concat` 拼接。
+
+**每步完成后**：
+- 删 `seg-N.pending.json`
+- 写 `seg-N.meta.json`（duration / resolution / status）
+- `git commit -m "video: receive $VIDEO_ID seg-N"`
+
+**全部完成**：`git commit -m "video: done $VIDEO_ID"`
+
+**失败**：自动重试 1 次 → 仍失败标记 `needs_user_review`
+
+**无依赖步骤可并行。生成过程中不问用户。**
+
+## Review
+
+生成完成后对照 storyboard.md 检查：
+
+1. **硬约束**（不过 → 告知用户）：
+   - 比例匹配
+   - 时长 ±20%
+   - 文件可播放（`ffprobe final.mp4`）
+
+2. **软推荐**（不过 → 写入迭代建议）：
+   - 产品可见性（抽 5 帧）
+   - 主体一致性（5 帧比对）
+   - 首帧质量
+
+3. 写 `quality-report.md` → `git commit -m "video: review $VIDEO_ID"`
+
+4. 展示结果 + 质量摘要 + **2-3 个迭代建议**
+
+5. 更新 `~/video-gen/history.md` 追加一行
+
+6. 用户说"好/完美" → 在 preferences.md Learned 追加一条 → `git commit -m "prefs: learn from $VIDEO_ID — <pattern>"`
+
+## 迭代
+
+用户说"再试 / 更 X / 改 Y"：
+
+1. history.md 找匹配项
+2. 读该 video 的 storyboard.md
+3. 判断：
+   - "故事不对" → 改 storyboard → production-plan 重推 → 重新生成
+   - "效果不对" → storyboard 不动 → 改 production-plan → 重新生成
+4. 新 video-id = `{旧id}-v2`，history 的 parent 指向旧 id
+
+## 核心规则
+
+- **信息够就直接做（Fast-path）**——最重要的一条
+- **Storyboard 是核心产物**，所有路径汇聚于它
+- **Production Plan 由 skill 自动推导**
+- **每步完成立刻 git commit**
+- **生成过程零打扰**
+- **参考视频永远让用户选**
+- **生成完给迭代建议**
+- **新会话有未完成任务先告知一次**
+- **不暴露模型名**——说"视频生成中"
+- **git 记录一切，不允许 reset**
+
+## 错误处理
+
+| 故障 | 处理 |
+|---|---|
+| gen 返回 failed | 重试 1 次 → 仍失败告知用户 |
+| ffmpeg 失败 | 检查输入完整性，告知用户 |
+| 源视频无法下载 | 建议手动下载后重试 |
+| scout 无结果 | 告知，转模板构建 |
+| 产品替换不合理 | 告知原因，降级策略或换参考 |
+| 会话关闭 | 状态在文件系统 + git，下次接续 |
+| gen task 超时 | 按 pending.json 重提 |
+| git commit 失败 | 说明原因，不 reset |
+
+## 相关工具
+
+- `gen video` — 图/文 → 视频
+- `gen image` — 文 → 图
+- `gen image` — 文生图，也是图像编辑（`-i` 传入输入图，可多次使用最多 8 张；产品替换首帧用 `-i 源帧 -i 产品图`）
+- `gen task get/cancel/retry` — 异步任务控制
+- `gen tts` — 文本 → 语音
+- `ffmpeg` / `ffprobe` — 视频分析、抽帧、拼接
+- `scout` — 爆款视频发现

package/.claude/skills/video-gen/templates/lifestyle-scene.md

@@ -0,0 +1,18 @@
+# Template: 生活场景
+
+适合：需要展示使用场景的产品，强调生活方式
+
+## 镜头表
+| 段 | 时长 | 内容 | 运镜 |
+|---|---|---|---|
+| 1 | 0-2s | 场景建立（环境全景）| 广角/慢推 |
+| 2 | 2-5s | {product} 出现在场景中 | 中景 |
+| 3 | 5-8s | 使用中（手部交互/操作）| 特写/跟手 |
+| 4 | 8-{duration}s | 使用效果 + {product} 回归 + {cta} | 中景 |
+
+## 默认值
+- Hook: 场景氛围（光线/色调）
+- CTA: 产品 + 场景回味
+- Pacing: moderate
+- Duration: 8-15s
+- Aspect: 9:16（社媒）或 16:9（PDP）

package/.claude/skills/video-gen/templates/pdp-360-showcase.md

@@ -0,0 +1,17 @@
+# Template: PDP 360 度展示
+
+适合：产品详情页主视频，强调产品外观
+
+## 镜头表
+| 段 | 时长 | 内容 | 运镜 |
+|---|---|---|---|
+| 1 | 0-5s | {product} 正面 → 缓慢旋转一圈 | 环绕 |
+| 2 | 5-10s | {product} 细节特写（材质/按钮/接口）| 推近 |
+| 3 | 10-{duration}s | {product} 全景 + 尺寸参照 | 拉远 |
+
+## 默认值
+- Hook: 干净的产品正面
+- CTA: 产品名（无侵入式 CTA）
+- Pacing: slow, steady
+- Duration: 15-25s
+- Aspect: 1:1 或 16:9

package/.claude/skills/video-gen/templates/pdp-feature-highlight.md

@@ -0,0 +1,18 @@
+# Template: PDP 卖点逐个讲
+
+适合：功能性产品，有多个卖点需要展示
+
+## 镜头表
+| 段 | 时长 | 内容 | 运镜 |
+|---|---|---|---|
+| 1 | 0-3s | {product} 全景介绍 | 缓推 |
+| 2 | 3-8s | 卖点 A 细节 + 文字标注 | 推近 |
+| 3 | 8-13s | 卖点 B 细节 + 文字标注 | 推近 |
+| 4 | 13-{duration}s | {product} 全景收尾 | 拉远 |
+
+## 默认值
+- Hook: 产品全景建立认知
+- CTA: 产品名（简洁）
+- Pacing: moderate, informative
+- Duration: 15-30s
+- Aspect: 1:1 或 16:9

package/.claude/skills/video-gen/templates/tiktok-before-after.md

@@ -0,0 +1,17 @@
+# Template: TikTok 前后对比
+
+适合：效果类产品（美妆、清洁、改造）
+
+## 镜头表
+| 段 | 时长 | 内容 | 运镜 |
+|---|---|---|---|
+| 1 | 0-2s | 痛点场景（before） | 手持/抖动 |
+| 2 | 2-3s | {product} 介入 | 快切 |
+| 3 | 3-{duration}s | 效果场景（after）+ {cta} | 稳定/慢推 |
+
+## 默认值
+- Hook: 痛点的视觉冲击
+- CTA: 产品名 + "立即体验"
+- Pacing: fast
+- Duration: 6-10s
+- Aspect: 9:16

package/.claude/skills/video-gen/templates/tiktok-product-reveal.md

@@ -0,0 +1,17 @@
+# Template: TikTok 产品揭晓
+
+适合：新品首发、产品亮点展示
+
+## 镜头表
+| 段 | 时长 | 内容 | 运镜 |
+|---|---|---|---|
+| 1 | 0-1.5s | {product} 暗场渐入特写 | 静止→缓推 |
+| 2 | 1.5-4s | {product} 使用场景 | {camera_style} |
+| 3 | 4-{duration}s | {product} + {cta} | 静止 |
+
+## 默认值
+- Hook: 暗场渐入的视觉悬念
+- CTA: logo reveal
+- Pacing: moderate
+- Duration: 6-10s
+- Aspect: 9:16

package/.claude/skills/video-gen/templates/tiktok-unboxing.md

@@ -0,0 +1,18 @@
+# Template: TikTok 开箱
+
+适合：有包装的产品、礼盒套装
+
+## 镜头表
+| 段 | 时长 | 内容 | 运镜 |
+|---|---|---|---|
+| 1 | 0-2s | 包装盒全景 / 桌面摆拍 | 俯拍静止 |
+| 2 | 2-5s | 手打开包装，缓缓取出 {product} | 跟手 |
+| 3 | 5-7s | {product} 特写展示 | 缓推 |
+| 4 | 7-{duration}s | {product} + 场景 + {cta} | 中景 |
+
+## 默认值
+- Hook: 包装的视觉吸引力
+- CTA: 产品 + logo
+- Pacing: slow to moderate
+- Duration: 8-12s
+- Aspect: 9:16

package/package.json

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