@optima-chat/optima-agent 0.8.6 → 0.8.8

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

@@ -56,12 +56,16 @@ Homepage
 **images 数组元素**：
 | 字段 | 必填 | 说明 |
 |------|------|------|
-| url | ✓ | 桌面端图片 URL |
+| url | △ | 桌面端图片 URL（url 或 media_id 至少一个） |
+| media_id | △ | 桌面端已有图片 ID（从 homepage get 获取，用于 update-images 全量替换） |
 | mobile_url | | 手机端专用图片 URL（3:4 竖向，可选） |
+| mobile_media_id | | 手机端已有图片 ID（从 homepage get 获取，用于 update-images 全量替换） |
 | alt | ✓ | 图片描述（SEO + 可访问性） |
 | action_type | ✓ | 点击动作类型（见下方） |
 | action_value | | 动作目标值 |
 
+> △ = url 和 media_id 至少提供一个。新上传的图使用 url，已有的图使用 media_id。
+
 **action_type 取值**：
 | 值 | 说明 | action_value |
 |----|------|--------------|
@@ -71,13 +75,24 @@ Homepage
 | `url` | 跳转到 URL | 完整 URL 或相对路径 |
 | `section` | 滚动到页面区块 | section handle |
 
-**示例**：
+**创建时的示例**（使用 url）：
 ```json
 {
   "images": [
     {"url": "https://cdn.../summer.jpg", "mobile_url": "https://cdn.../summer-mobile.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}
+    {"url": "https://cdn.../promo.jpg", "alt": "活动页面", "action_type": "url", "action_value": "https://promo.example.com/event"}
+  ],
+  "autoplay": true,
+  "interval": 5000
+}
+```
+
+**`homepage get` 返回的真实格式**（url 已被后端自动转为 media_id）：
+```json
+{
+  "images": [
+    {"media_id": "med_abc123", "mobile_media_id": "med_def456", "alt": "夏日促销", "action_type": "collection", "action_value": "summer-sale"},
+    {"media_id": "med_ghi789", "alt": "活动页面", "action_type": "url", "action_value": "https://promo.example.com/event"}
   ],
   "autoplay": true,
   "interval": 5000
@@ -174,6 +189,9 @@ Homepage
 - "添加集合商品" → `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 '[...]'`
+- "给第N张 banner 加手机图" → `commerce homepage patch-banner-image --id xx --index N --mobile-url "https://..."`
+- "改第N张图的描述" → `commerce homepage patch-banner-image --id xx --index N --alt "新描述"`
+- "移除第N张图的手机版" → `commerce homepage patch-banner-image --id xx --index N --remove-mobile-url`
 - "修改区块标题" → `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}]'`
@@ -202,7 +220,8 @@ Homepage
 - `commerce homepage reorder --moves <json>` - 重新排序（JSON 格式：`[{"section_id":"xx","new_position":0}]`）
 
 ### 区块设置
-- `commerce homepage update-images --id <id> --images <json>` - 更新 banner 图片
+- `commerce homepage update-images --id <id> --images <json>` - 全量替换 banner 图片（支持 url 或 media_id）
+- `commerce homepage patch-banner-image --id <id> --index <N> [--url <url>] [--mobile-url <url>] [--remove-mobile-url] [--alt <text>] [--action-type <type>] [--action-value <value>]` - 更新单张 banner 图片（index 从 1 开始）
 - `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>` - 通用设置更新
@@ -316,11 +335,43 @@ commerce i18n homepage set \
   --description "New description"
 ```
 
+## Banner 图片更新：命令选择指南
+
+| 我要做什么 | 用哪个命令 | 说明 |
+|-----------|-----------|------|
+| 给第 N 张图加/换手机版 | `patch-banner-image --index N --mobile-url "https://..."` | 最简单，无需读取现有数据 |
+| 改第 N 张图的 alt/action | `patch-banner-image --index N --alt "..."` | 同上 |
+| 换第 N 张桌面图（新 URL） | `patch-banner-image --index N --url "https://..."` | 后端自动转 media_id |
+| 移除第 N 张图的手机版 | `patch-banner-image --index N --remove-mobile-url` | 设为 null |
+| 添加/删除图片 | `update-images --images '[完整数组]'` | 全量替换，需透传所有现有字段 |
+| 重新排列图片顺序 | `update-images --images '[新顺序数组]'` | 同上 |
+
+**关键区别**：
+- `patch-banner-image` 只接受 URL（`--url`, `--mobile-url`），不接受 `media_id`。后端自动将 URL 转为 media_id
+- `update-images` 接受 `url` 和 `media_id`。已有的图用 `media_id` 透传，新图用 `url`
+
+### update-images 全量替换示例（含 media_id 透传）
+
+**场景**：给已有的 2 张 banner 增加第 3 张图
+
+1. 先 `commerce homepage get --id section_xxx` 获取现有图片（含 media_id）
+2. 构建完整数组，已有图原样透传 media_id，新图用 url：
+
+```bash
+commerce homepage update-images --id section_xxx --images '[
+  {"media_id":"med_abc123","mobile_media_id":"med_def456","alt":"夏日促销","action_type":"collection","action_value":"summer-sale"},
+  {"media_id":"med_ghi789","alt":"活动页面","action_type":"url","action_value":"https://promo.example.com/event"},
+  {"url":"https://new-upload-url.../img3.jpg","alt":"新图片","action_type":"none"}
+]'
+```
+
+**注意：全量替换会覆盖整个 images 数组。漏传的字段（如 `mobile_media_id`）会导致手机图丢失。务必从 `homepage get` 完整复制现有图片的所有字段。**
+
 ## 注意事项
 
 - **区块顺序**：使用 `reorder` 调整，position 从 0 开始
 - **模板切换**：会创建新区块并停用旧区块，谨慎操作
-- **图片格式**：banner images 需要完整的 JSON 数组，每个元素必须有 url 和 alt
+- **media_id 生命周期**：上传图片（`upload file`）→ 返回临时 URL（无 media_id）→ 传给 banner API → 后端自动转为 media_id → 后续 `homepage get` 返回 media_id
 - **手机端图片**：可选提供 mobile_url（3:4 竖向），有 mobile_url 时手机端显示竖向大图，无则保持 16:9 横向
 - **集合引用**：确保引用的 collection slug 存在，否则前端可能显示空
 - **删除确认**：删除操作需要 `--yes` 参数

package/.claude/skills/product/SKILL.md

@@ -17,7 +17,7 @@ commerce upload image --path ./tshirt-main.jpg  # 获得 media_123
 
 # 2. 创建商品
 commerce product create \
-  --title "纯棉T恤" \
+  --name "纯棉T恤" \
   --price 99 \
   --stock 20 \
   --description "100% 纯棉，舒适透气" \
@@ -28,7 +28,7 @@ commerce product create \
 **流程**: 创建主商品 → 创建所有变体 → 关联图片
 ```bash
 # 1. 创建主商品
-commerce product create --title "T恤" --price 99
+commerce product create --name "T恤" --price 99
 # 获得 product_id: prod_123
 
 # 2. 创建所有变体
@@ -48,7 +48,7 @@ commerce upload image --path ./brand-logo.jpg  # 获得 media_shared
 
 # 2. 批量创建商品（复用media_id）
 for product in "T恤" "衬衫" "卫衣"; do
-  commerce product create --title "$product" --price 99 --media-id media_shared
+  commerce product create --name "$product" --price 99 --media-id media_shared
 done
 ```
 
@@ -78,7 +78,7 @@ commerce product add-images --id prod_123 --media-id media_new
 ```bash
 # 创建促销商品：售价79，原价99（显示划线价）
 commerce product create \
-  --title "夏日特惠T恤" \
+  --name "夏日特惠T恤" \
   --price 79 \
   --original-price 99 \
   --stock 100 \
@@ -143,7 +143,7 @@ commerce product create \
 # 每个商品都上传相同的logo
 for product in products; do
   commerce upload image --path ./logo.jpg
-  commerce product create --title "$product" --media-id $NEW_ID
+  commerce product create --name "$product" --media-id $NEW_ID
 done
 ```
 
@@ -152,7 +152,7 @@ done
 # 先上传一次，复用media_id
 commerce upload image --path ./logo.jpg  # 获得 media_123
 for product in products; do
-  commerce product create --title "$product" --media-id media_123
+  commerce product create --name "$product" --media-id media_123
 done
 ```
 
@@ -162,10 +162,10 @@ done
 
 ```bash
 # 错误：只创建主商品
-commerce product create --title "T恤" --price 99
+commerce product create --name "T恤" --price 99
 
 # 正确：创建主商品 + 所有变体
-commerce product create --title "T恤" --price 99  # 获得 prod_123
+commerce product create --name "T恤" --price 99  # 获得 prod_123
 commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" ...
 commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" ...
 ```
@@ -203,7 +203,7 @@ commerce product update --id prod_123 --tags "featured,new,sale"
 
 ```bash
 # 先确认真实库存，再创建
-commerce product create --title "T恤" --price 99 --stock 50  # 确保真实有50件
+commerce product create --name "T恤" --price 99 --stock 50  # 确保真实有50件
 ```
 
 ## 命令参考
@@ -211,9 +211,9 @@ commerce product create --title "T恤" --price 99 --stock 50  # 确保真实有5
 ### 自然语言映射
 
 当用户说：
-- "创建XX商品，价格YY" → `commerce product create --title XX --price YY`
-- "创建XX商品，售价YY，原价ZZ" → `commerce product create --title XX --price YY --original-price ZZ`
-- "创建促销商品，价格79，划线价99" → `commerce product create --title XX --price 79 --original-price 99`
+- "创建XX商品，价格YY" → `commerce product create --name XX --price YY`
+- "创建XX商品，售价YY，原价ZZ" → `commerce product create --name XX --price YY --original-price ZZ`
+- "创建促销商品，价格79，划线价99" → `commerce product create --name XX --price 79 --original-price 99`
 - "上传商品图片" → `commerce upload image --path ./photo.jpg`
 - "添加商品变体" → `commerce variant create --product-id XX --sku YY`
 - "更新商品价格" → `commerce product update --id XX --price YY`
@@ -249,7 +249,7 @@ commerce product create --title "T恤" --price 99 --stock 50  # 确保真实有5
 # 用户说："创建T恤商品，99美元，库存20"
 # 描述支持 Markdown 格式
 commerce product create \
-  --title "T恤" \
+  --name "T恤" \
   --price 99 \
   --stock 20 \
   --description "## 产品特点
@@ -314,7 +314,7 @@ commerce upload image --path ./tshirt-red.jpg    # media_red
 commerce upload image --path ./tshirt-blue.jpg   # media_blue
 
 # 2. 创建主商品
-commerce product create --title "纯棉T恤" --price 99
+commerce product create --name "纯棉T恤" --price 99
 # 获得 product_id: prod_123
 
 # 3. 创建变体

package/package.json

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