@optima-chat/optima-agent 0.8.7 → 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/package.json

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