@optima-chat/optima-agent 0.5.0 → 0.5.2

package/.claude/skills/ffmpeg/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: ffmpeg
+description: "Audio and video processing for e-commerce. Use when user needs to: merge audio with video (视频配音/添加背景音乐/音视频合成), compress videos (压缩视频/视频压缩), generate thumbnails (生成缩略图/视频封面), concatenate videos (视频拼接/合并视频), trim videos (视频裁切/截取片段/剪辑视频), convert formats (格式转换/转换视频)."
+---
+
+# FFmpeg 音视频处理
+
+## 电商场景常用任务
+
+### 1. 音视频合成（产品视频配音/背景音乐）
+
+```bash
+# 视频配背景音乐（音频较短时循环）
+ffmpeg -i video.mp4 -stream_loop -1 -i audio.mp3 -shortest -c:v copy -c:a aac output.mp4
+
+# 视频配音频（音频较长时截断）
+ffmpeg -i video.mp4 -i audio.mp3 -shortest -c:v copy -c:a aac output.mp4
+
+# 替换视频原有音频
+ffmpeg -i video.mp4 -i new_audio.mp3 -c:v copy -c:a aac -map 0:v:0 -map 1:a:0 output.mp4
+```
+
+**参数说明**：
+- `-stream_loop -1` - 无限循环音频（直到视频结束）
+- `-shortest` - 以最短的流为准（视频或音频）
+- `-map 0:v:0 -map 1:a:0` - 手动选择第1个文件的视频+第2个文件的音频
+
+### 2. 视频压缩（上传优化，保证展示质量）
+
+```bash
+# 产品视频压缩（推荐：CRF 20，高质量）
+ffmpeg -i product.mp4 -c:v libx264 -crf 20 -c:a aac output.mp4
+
+# 标准压缩（CRF 23，平衡质量和大小）
+ffmpeg -i video.mp4 -crf 23 output.mp4
+```
+
+**电商场景 CRF 建议**：
+- **18-20** - 产品主图视频（质量优先）
+- **23** - 一般营销视频（平衡）
+- **25-28** - 内部使用视频（文件大小优先）
+
+### 3. 生成视频缩略图（产品封面）
+
+```bash
+# 从5秒处生成缩略图
+ffmpeg -i product_video.mp4 -ss 00:00:05 -frames:v 1 thumbnail.jpg
+
+# 批量生成所有产品视频的缩略图
+for video in *.mp4; do
+  ffmpeg -i "$video" -ss 00:00:05 -frames:v 1 "${video%.mp4}_thumb.jpg"
+done
+```
+
+### 4. 视频拼接（多个片段合并）
+
+```bash
+# 创建拼接列表文件
+cat > concat_list.txt << 'EOF'
+file 'video1.mp4'
+file 'video2.mp4'
+file 'video3.mp4'
+EOF
+
+# 拼接视频（所有视频参数相同时，快速无损）
+ffmpeg -f concat -safe 0 -i concat_list.txt -c copy output.mp4
+
+# 拼接视频（参数不同时，重新编码）
+ffmpeg -f concat -safe 0 -i concat_list.txt -c:v libx264 -crf 20 -c:a aac output.mp4
+```
+
+**参数说明**：
+- `-f concat` - 使用 concat 分离器
+- `-safe 0` - 允许不安全的文件路径（本地文件需要）
+- `-c copy` - 无损拼接（仅当所有视频格式完全相同）
+
+### 5. 视频裁切（截取指定片段）
+
+```bash
+# 从第10秒开始，截取30秒
+ffmpeg -i video.mp4 -ss 00:00:10 -t 30 -c copy output.mp4
+
+# 从第10秒到第40秒
+ffmpeg -i video.mp4 -ss 00:00:10 -to 00:00:40 -c copy output.mp4
+
+# 去掉前5秒（从第5秒到结尾）
+ffmpeg -i video.mp4 -ss 00:00:05 -c copy output.mp4
+```
+
+**参数说明**：
+- `-ss HH:MM:SS` - 开始时间
+- `-t <秒数>` - 持续时长
+- `-to HH:MM:SS` - 结束时间
+- `-c copy` - 无损裁切（快速）
+
+### 6. 格式转换（确保兼容性）
+
+```bash
+# 快速转换（只改容器，不重新编码）
+ffmpeg -i video.mov -c copy video.mp4
+
+# 标准转换（重新编码）
+ffmpeg -i video.mov -c:v libx264 -c:a aac video.mp4
+```
+
+## 电商工作流程
+
+### 场景1：产品视频配背景音乐
+
+```bash
+# 1. 检查文件
+ls -lh product_video.mp4 background_music.mp3
+
+# 2. 合成（音乐循环播放）
+ffmpeg -i product_video.mp4 -stream_loop -1 -i background_music.mp3 \
+  -shortest -c:v copy -c:a aac -b:a 192k final_video.mp4
+
+# 3. 检查输出
+ls -lh final_video.mp4
+
+# 4. 告知用户：文件大小、是否需要压缩
+```
+
+### 场景2：压缩产品视频后生成缩略图
+
+```bash
+# 1. 压缩视频（保证产品展示质量）
+ffmpeg -i raw_product.mp4 -c:v libx264 -crf 20 -c:a aac product.mp4
+
+# 2. 生成缩略图
+ffmpeg -i product.mp4 -ss 00:00:05 -frames:v 1 product_thumb.jpg
+
+# 3. 告知用户文件大小变化
+ls -lh raw_product.mp4 product.mp4
+```
+
+### 场景3：批量处理多个产品视频
+
+```bash
+# 批量压缩并生成缩略图
+for video in product_*.mp4; do
+  # 压缩
+  ffmpeg -i "$video" -c:v libx264 -crf 20 -c:a aac "compressed_${video}"
+
+  # 生成缩略图
+  ffmpeg -i "compressed_${video}" -ss 00:00:05 -frames:v 1 "${video%.mp4}_thumb.jpg"
+done
+```
+
+## 重要提示
+
+### 电商场景特殊要求
+
+- 🎨 **质量优先** - 产品视频使用 CRF 18-20，不要过度压缩
+- 📏 **文件大小监控** - 始终告知用户处理前后的文件大小变化
+- 🖼️ **缩略图质量** - 选择展示效果好的时间点（通常5秒处）
+- 🎵 **音频音量** - 合成时注意背景音乐不要盖过产品解说
+
+### 常用参数
+
+- `-c:v copy` - 视频流无损复制（音视频合成时推荐，保持原质量）
+- `-shortest` - 以最短流为准（音视频合成必备）
+- `-stream_loop -1` - 循环音频（背景音乐常用）
+- `-crf 20` - 产品视频推荐质量

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

@@ -0,0 +1,324 @@
+---
+name: homepage
+description: 店铺首页配置。管理首页区块（Banner、集合列表、集合商品、特色推荐）。当用户需要配置店铺首页布局、添加轮播图、展示集合时使用。
+---
+
+## 概念
+
+Homepage（首页）是店铺的入口页面，由多个 Section（区块）组成。每个商户有一个激活的首页配置。
+
+- 区块按 position 排序，从上到下显示
+- 每个区块有唯一的 handle，用于 URL 锚点定位
+- 区块通过 settings 存储类型特定的配置
+
+**与 Collection 的关系**：多个区块类型引用 Collection：
+- `collections` 区块：展示多个集合入口（引用 collection slugs）
+- `collection_products` 区块：展示某个集合的商品（引用单个 collection slug）
+- `featured` 区块：可推荐某个集合（target_type=collection）
+
+## 结构
+
+```
+Homepage
+├── HomepageConfig（商户唯一）
+│   ├── id: 配置 ID
+│   ├── is_active: 是否激活
+│   └── sections: 区块列表
+│
+└── HomepageSection（区块）
+    ├── 基本信息
+    │   ├── id: 区块 ID
+    │   ├── type: 类型（见下方）
+    │   ├── handle: URL 标识
+    │   └── position: 显示顺序（0 开始）
+    │
+    ├── settings: 类型特定配置（JSONB）
+    │
+    └── translations: 多语言标题/描述（JSONB）
+        └── { "zh-CN": { "title": "...", "description": "..." }, ... }
+```
+
+**注意**：区块的 title 和 description 存储在 `translations` 字段中，需要指定语言代码。
+
+## 区块类型详解
+
+### 1. banner（图片轮播）
+
+首页顶部的轮播广告图，支持多张图片自动轮播，每张图可设置点击跳转。
+
+**Settings 字段**：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| images | array | 图片数组（见下方） |
+| autoplay | boolean | 是否自动播放，默认 true |
+| interval | number | 轮播间隔（毫秒），默认 5000 |
+
+**images 数组元素**：
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| url | ✓ | 图片 URL |
+| alt | ✓ | 图片描述（SEO + 可访问性） |
+| action_type | ✓ | 点击动作类型（见下方） |
+| action_value | | 动作目标值 |
+
+**action_type 取值**：
+| 值 | 说明 | action_value |
+|----|------|--------------|
+| `none` | 无跳转 | null |
+| `collection` | 跳转到集合页 | collection slug |
+| `product` | 跳转到商品页 | product handle |
+| `url` | 跳转到 URL | 完整 URL 或相对路径 |
+| `section` | 滚动到页面区块 | section handle |
+
+**示例**：
+```json
+{
+  "images": [
+    {"url": "https://cdn.../summer.jpg", "alt": "夏日促销", "action_type": "collection", "action_value": "summer-sale"},
+    {"url": "https://cdn.../promo.jpg", "alt": "活动页面", "action_type": "url", "action_value": "https://promo.example.com/event"},
+    {"url": "https://cdn.../hero.jpg", "alt": "品牌形象", "action_type": "none", "action_value": null}
+  ],
+  "autoplay": true,
+  "interval": 5000
+}
+```
+
+### 2. collections（集合入口列表）
+
+展示多个集合的入口卡片，用户点击可进入对应集合页。
+
+**Settings 字段**：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| collection_slugs | array | 集合 slug 数组，按顺序展示 |
+| layout | string | 布局方式：`grid`（网格）/ `carousel`（轮播） |
+| show_product_count | boolean | 是否显示集合商品数量 |
+
+**示例**：
+```json
+{
+  "collection_slugs": ["summer-sale", "new-arrivals", "best-sellers"],
+  "layout": "grid",
+  "show_product_count": true
+}
+```
+
+### 3. collection_products（集合商品展示）
+
+展示某个集合内的商品列表，支持自动获取或手动指定。
+
+**Settings 字段**：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| collection_slug | string | 集合 slug（必需） |
+| mode | string | `auto`（自动获取）/ `manual`（手动指定） |
+| product_handles | array | mode=manual 时，手动指定的商品 handle 列表 |
+| limit | number | mode=auto 时，最多展示数量，默认 8 |
+| sort_by | string | 排序字段：`created_at` / `price` / `title` |
+| sort_order | string | 排序方向：`asc` / `desc` |
+
+**示例**：
+```json
+{
+  "collection_slug": "new-arrivals",
+  "mode": "auto",
+  "limit": 8,
+  "sort_by": "created_at",
+  "sort_order": "desc"
+}
+```
+
+### 4. featured（特色推荐）
+
+突出展示某个集合或商品，通常带有大图和 CTA 按钮。
+
+**Settings 字段**：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| target_type | string | `collection`（推荐集合）/ `product`（推荐商品） |
+| target_handle | string | 目标的 slug/handle |
+| media_id | string | 封面图片的 media ID |
+| media_url | string | 或直接提供封面图片 URL |
+| cta_text | string | CTA 按钮文字，如 "立即查看" |
+| background_color | string | 背景颜色，如 "#f5f5f5" |
+
+**示例（推荐集合）**：
+```json
+{
+  "target_type": "collection",
+  "target_handle": "summer-sale",
+  "media_url": "https://cdn.../featured.jpg",
+  "cta_text": "查看夏日精选",
+  "background_color": "#fff8e1"
+}
+```
+
+**示例（推荐商品）**：
+```json
+{
+  "target_type": "product",
+  "target_handle": "ceramic-cup-white",
+  "media_url": "https://cdn.../product-hero.jpg",
+  "cta_text": "立即购买"
+}
+```
+
+## 典型场景
+
+当用户说：
+- "查看首页配置" → `commerce homepage get-config`
+- "查看首页区块" → `commerce homepage list`
+- "添加轮播图" → `commerce homepage create-banner --title "主Banner" --lang <识别语言> --images '[{"url":"..."}]'`
+- "添加集合入口" → `commerce homepage create-collections --title "精选系列" --lang <识别语言> --slugs "a,b,c"`
+- "添加集合商品" → `commerce homepage create-collection-products --title "新品" --lang <识别语言> --slug new-arrivals`
+- "添加特色推荐" → `commerce homepage create-featured --title "推荐" --lang <识别语言> --target-type collection --target-handle xx --cta "查看" --image-url "..."`
+- "更新轮播图图片" → `commerce homepage update-images --id xx --images '[...]'`
+- "修改区块标题" → `commerce i18n homepage set --section-id xx --lang <识别语言> --title "新标题"`
+- "给区块添加描述" → `commerce i18n homepage set --section-id xx --lang <识别语言> --description "描述"`
+- "调整区块顺序" → `commerce homepage reorder --moves '[{"section_id":"id1","new_position":0}]'`
+- "使用模板" → `commerce homepage switch-template --template-key minimal`
+- "删除区块" → `commerce homepage delete --id xx --yes`
+
+## 命令参考
+
+### 配置管理
+- `commerce homepage get-config` - 查看首页配置
+- `commerce homepage list-templates` - 列出可用模板
+- `commerce homepage switch-template --template-key <key>` - 切换模板（minimal|standard）
+- `commerce homepage delete-config --yes` - 删除首页配置
+
+### 创建区块（支持 --title --description --lang）
+- `commerce homepage create-banner --title <title> --lang <code> --images <json>` - 创建轮播图
+- `commerce homepage create-collections --title <title> --lang <code> --slugs <slugs>` - 创建集合入口
+- `commerce homepage create-collection-products --title <title> --lang <code> --slug <slug>` - 创建集合商品
+- `commerce homepage create-featured --title <title> --lang <code> --target-type <type> --target-handle <handle> --cta <text> --image-url <url>` - 创建特色推荐
+
+### 区块管理
+- `commerce homepage list` - 列出所有区块
+- `commerce homepage get --id <id>` - 查看区块详情
+- `commerce homepage update --id <id>` - 更新区块
+- `commerce homepage delete --id <id> --yes` - 删除区块
+- `commerce homepage reorder --moves <json>` - 重新排序（JSON 格式：`[{"section_id":"xx","new_position":0}]`）
+
+### 区块设置
+- `commerce homepage update-images --id <id> --images <json>` - 更新 banner 图片
+- `commerce homepage update-collections --id <id> --slugs <slugs>` - 更新 collections 集合
+- `commerce homepage update-target --id <id> --type <type> --handle <handle>` - 更新 featured 目标
+- `commerce homepage patch-settings --id <id> --settings <json>` - 通用设置更新
+
+### 多语言翻译
+- `commerce i18n homepage list --section-id <id>` - 查看区块所有翻译
+- `commerce i18n homepage set --section-id <id> --lang <code> --title <title> --description <desc>` - 设置翻译
+- `commerce i18n homepage delete --section-id <id> --lang <code> --yes` - 删除翻译
+- `commerce i18n languages` - 查看支持的语言列表
+
+## 语言代码
+
+设置标题和描述时必须指定 `--lang`。
+
+支持的语言：`zh-CN`、`en-US`、`ja-JP`、`es-ES`、`vi-VN`
+
+根据用户提供的文字内容识别语言。如果无法确定，询问用户。
+
+## 典型操作示例
+
+### 快速开始：使用模板
+
+```bash
+# 查看可用模板
+commerce homepage list-templates
+
+# 切换到标准模板（会创建预设区块）
+commerce homepage switch-template --template-key standard --yes
+```
+
+### 创建轮播图
+
+```bash
+# 创建 banner 并设置图片
+commerce homepage create-banner \
+  --title "首页轮播" \
+  --lang zh-CN \
+  --images '[{"url":"https://cdn.../img1.jpg","link":"/sale"}]'
+
+# 后续更新图片
+commerce homepage update-images \
+  --id section_xxx \
+  --images '[{"url":"https://cdn.../img2.jpg","alt":"夏日促销","link":"/summer"}]'
+```
+
+### 创建集合入口
+
+```bash
+# 创建 collections 区块
+commerce homepage create-collections \
+  --title "精选系列" \
+  --lang zh-CN \
+  --slugs "new-arrivals,best-sellers,summer-sale"
+
+# 后续更新集合列表
+commerce homepage update-collections --id section_xxx --slugs "a,b,c"
+```
+
+### 创建集合商品展示
+
+```bash
+# 创建 collection_products 区块
+commerce homepage create-collection-products \
+  --title "新品上市" \
+  --lang zh-CN \
+  --slug new-arrivals \
+  --limit 8
+```
+
+### 创建特色推荐
+
+```bash
+# 推荐集合
+commerce homepage create-featured \
+  --title "本周推荐" \
+  --description "精选好物，限时优惠" \
+  --lang zh-CN \
+  --target-type collection \
+  --target-handle weekly-picks \
+  --cta "立即查看" \
+  --image-url "https://cdn.../featured.jpg"
+
+# 推荐商品
+commerce homepage create-featured \
+  --title "爆款单品" \
+  --lang zh-CN \
+  --target-type product \
+  --target-handle ceramic-cup-white \
+  --cta "立即购买" \
+  --image-url "https://cdn.../product.jpg"
+
+# 后续更新目标
+commerce homepage update-target --id section_xxx --type collection --handle "new-picks"
+```
+
+### 更新标题和描述
+
+```bash
+# 更新中文
+commerce i18n homepage set \
+  --section-id section_xxx \
+  --lang zh-CN \
+  --title "新标题" \
+  --description "新描述"
+
+# 添加英文翻译
+commerce i18n homepage set \
+  --section-id section_xxx \
+  --lang en-US \
+  --title "New Title" \
+  --description "New description"
+```
+
+## 注意事项
+
+- **区块顺序**：使用 `reorder` 调整，position 从 0 开始
+- **模板切换**：会创建新区块并停用旧区块，谨慎操作
+- **图片格式**：banner images 需要完整的 JSON 数组，每个元素必须有 url 和 alt
+- **集合引用**：确保引用的 collection slug 存在，否则前端可能显示空
+- **删除确认**：删除操作需要 `--yes` 参数