@optima-chat/optima-agent 0.9.13 → 0.9.14

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

@@ -1,177 +1,177 @@
----
-name: homepage
-description: 店铺首页配置。管理首页区块（Banner、集合列表、集合商品、特色推荐）和页面级设置（背景图、叠加层）。当用户需要配置店铺首页布局、添加轮播图、展示集合、设置背景图片、设置 Banner 不裁切/完整显示时使用。
----
-
-## 重要：先查后做
-
-1. 不确定参数时，先运行 `<command> --help` 查看完整参数说明
-2. 修改 settings 字段时，必须使用下方「Settings 合法字段」中列出的字段名，不要猜测
-3. 操作已有区块前，先 `commerce homepage list` 获取区块 ID
-
-## 用户意图 → 命令
-
-### 查看
-
-| 用户说 | 命令 |
-|-------|------|
-| 查看首页配置 | `commerce homepage get-config` |
-| 查看首页区块列表 | `commerce homepage list` |
-| 查看区块详情 | `commerce homepage get --id <id>` |
-| 查看可用模板 | `commerce homepage list-templates` |
-
-### Banner（轮播图）
-
-| 用户说 | 命令 |
-|-------|------|
-| 添加/创建轮播图 | `commerce homepage create-banner --title <title> --lang <lang> --images '<json>'` |
-| Banner 不裁切 / 完整显示 / 按原始比例 | 新建时加 `--image-fit contain`；已有 banner 用 `patch-settings --id <id> --settings '{"image_fit":"contain"}'` |
-| 更换所有图片 | `commerce homepage update-images --id <id> --images '<json>'`（全量替换，见下方说明） |
-| 给第 N 张图加/换手机版 | `commerce homepage patch-banner-image --id <id> --index N --mobile-url "https://..."` |
-| 改第 N 张图的描述/动作 | `commerce homepage patch-banner-image --id <id> --index N --alt "..." --action-type collection --action-value slug` |
-| 移除第 N 张图的手机版 | `commerce homepage patch-banner-image --id <id> --index N --remove-mobile-url` |
-| 关闭自动播放 | `commerce homepage patch-settings --id <id> --settings '{"autoplay":false}'` |
-| 修改轮播间隔 | `commerce homepage patch-settings --id <id> --settings '{"interval":3000}'` |
-
-### 集合
-
-| 用户说 | 命令 |
-|-------|------|
-| 添加集合入口区块 | `commerce homepage create-collections --title <title> --lang <lang> --slugs "a,b,c"` |
-| 更新集合列表 | `commerce homepage update-collections --id <id> --slugs "a,b,c"` |
-| 添加集合商品区块 | `commerce homepage create-collection-products --title <title> --lang <lang> --slug <slug>` |
-
-### 特色推荐
-
-| 用户说 | 命令 |
-|-------|------|
-| 添加特色推荐 | `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 upload --file bg.png` 拿到 media_id，再 `commerce homepage update-page-settings --background-media-id <id> --background-mode repeat-y` |
-| 设置固定背景（照片） | 先上传，再 `commerce homepage update-page-settings --background-media-id <id> --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` |
-
-### 品牌色
-
-| 用户说 | 命令 |
-|-------|------|
-| "修改品牌色" / "设置主题色" | **merchant skill**：`commerce merchant update --primary-color "#xxx"` |
-
-### 通用操作
-
-| 用户说 | 命令 |
-|-------|------|
-| 调整区块顺序 | `commerce homepage reorder --moves '[{"section_id":"<id>","new_position":0}]'` |
-| 修改区块标题/描述 | `commerce i18n homepage set --section-id <id> --lang <lang> --title "新标题"` |
-| 删除区块 | `commerce homepage delete --id <id> --yes` |
-| 切换模板 | `commerce homepage switch-template --template-key <minimal\|standard> --yes` |
-
-## Settings 合法字段
-
-使用 `patch-settings` 修改设置时，只能使用以下字段名。**使用未列出的字段会被后端拒绝（extra="forbid"）。**
-
-### banner
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| images | array | 图片数组（通过 `update-images` 或 `patch-banner-image` 修改，不要用 patch-settings） |
-| autoplay | boolean | 是否自动播放，默认 true |
-| interval | number | 轮播间隔（毫秒），1000-30000，默认 5000 |
-| image_fit | string | `cover`（默认，裁切填充）/ `contain`（完整显示，高度自适应，无裁切） |
-
-### collections
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| collection_slugs | array | 集合 slug 数组（通过 `update-collections` 修改更方便） |
-| layout | string | `grid` / `carousel` |
-| show_product_count | boolean | 是否显示商品数量 |
-
-### collection_products
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| collection_slug | string | 集合 slug |
-| mode | string | `auto` / `manual` |
-| product_handles | array | manual 模式下的商品 handle 列表 |
-| limit | number | auto 模式最多展示数量，默认 8 |
-| sort_by | string | `created_at` / `price` / `title` |
-| sort_order | string | `asc` / `desc` |
-
-### featured
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| target_type | string | `collection` / `product` |
-| target_handle | string | 目标 slug/handle |
-| media_id | string | 封面图片 ID |
-| url | string | 封面图片 URL（新上传用 url，后端自动转 media_id） |
-| cta_text | string | CTA 按钮文字 |
-| background_color | string | 背景颜色，如 `#f5f5f5` |
-
-### page_settings（页面级设置）
-
-通过 `update-page-settings` 命令修改，不是 `patch-settings`。
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| background_media_id | string / null | 背景图片 Media ID（通过 `commerce upload` 获取，推荐） |
-| background_image | string / null | 背景图片 URL（不推荐直接使用，应通过 media_id 设置） |
-| background_mode | string | `repeat-y`（横向填满纵向平铺，默认）/ `fixed`（固定视口） |
-| background_overlay_color | string | 叠加颜色（hex 格式，默认 `#ffffff`） |
-| background_overlay_opacity | number | 叠加透明度 0-1（默认 0.85，越大越不透明） |
-
-## 复杂操作说明
-
-### update-images 全量替换
-
-`update-images` 会覆盖整个 images 数组。操作步骤：
-
-1. `commerce homepage get --id <id>` 获取现有图片（含 media_id）
-2. 构建完整数组：已有图原样透传 media_id，新图用 url
-3. 执行替换
-
-```bash
-commerce homepage update-images --id section_xxx --images '[
-  {"media_id":"med_abc","mobile_media_id":"med_def","alt":"图1","action_type":"collection","action_value":"sale"},
-  {"url":"https://new-image.jpg","alt":"新图","action_type":"none"}
-]'
-```
-
-**注意：漏传的字段（如 `mobile_media_id`）会导致手机图丢失。务必完整复制现有图片的所有字段。**
-
-### Banner 图片字段说明
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| url | △ | 桌面端图片 URL（url 或 media_id 至少一个） |
-| media_id | △ | 已有图片 ID（从 `homepage get` 获取） |
-| mobile_url | | 手机端图片 URL（3:4 竖向，可选） |
-| mobile_media_id | | 手机端已有图片 ID |
-| alt | ✓ | 图片描述 |
-| action_type | ✓ | `none` / `collection` / `product` / `url` / `section` |
-| action_value | | 动作目标（slug / URL / section handle） |
-
-### patch-banner-image vs update-images
-
-| 场景 | 用哪个 |
-|------|--------|
-| 改单张图的属性（alt、mobile_url 等） | `patch-banner-image --index N` |
-| 添加/删除图片、重新排序 | `update-images`（全量替换） |
-
-## 注意事项
-
-- **语言代码**：设置标题/描述时必须指定 `--lang`（zh-CN、en-US、ja-JP、es-ES、vi-VN），根据用户文字识别语言
-- **区块顺序**：position 从 0 开始
-- **media_id 生命周期**：URL → 传给 API → 后端自动转为 media_id → 后续 `homepage get` 返回 media_id
-- **手机端图片**：mobile_url 为 3:4 竖向，有时手机端显示竖版大图，无则保持横向
-- **image_fit**：默认 `cover`（裁切），设 `contain` 可按原始比例完整显示，适合纯切图首页
-- **模板切换**：会创建新区块并停用旧区块，谨慎操作
-- **删除确认**：删除操作需要 `--yes`
+---
+name: homepage
+description: 店铺首页配置。管理首页区块（Banner、集合列表、集合商品、特色推荐）和页面级设置（背景图、叠加层）。当用户需要配置店铺首页布局、添加轮播图、展示集合、设置背景图片、设置 Banner 不裁切/完整显示时使用。
+---
+
+## 重要：先查后做
+
+1. 不确定参数时，先运行 `<command> --help` 查看完整参数说明
+2. 修改 settings 字段时，必须使用下方「Settings 合法字段」中列出的字段名，不要猜测
+3. 操作已有区块前，先 `commerce homepage list` 获取区块 ID
+
+## 用户意图 → 命令
+
+### 查看
+
+| 用户说 | 命令 |
+|-------|------|
+| 查看首页配置 | `commerce homepage get-config` |
+| 查看首页区块列表 | `commerce homepage list` |
+| 查看区块详情 | `commerce homepage get --id <id>` |
+| 查看可用模板 | `commerce homepage list-templates` |
+
+### Banner（轮播图）
+
+| 用户说 | 命令 |
+|-------|------|
+| 添加/创建轮播图 | `commerce homepage create-banner --title <title> --lang <lang> --images '<json>'` |
+| Banner 不裁切 / 完整显示 / 按原始比例 | 新建时加 `--image-fit contain`；已有 banner 用 `patch-settings --id <id> --settings '{"image_fit":"contain"}'` |
+| 更换所有图片 | `commerce homepage update-images --id <id> --images '<json>'`（全量替换，见下方说明） |
+| 给第 N 张图加/换手机版 | `commerce homepage patch-banner-image --id <id> --index N --mobile-url "https://..."` |
+| 改第 N 张图的描述/动作 | `commerce homepage patch-banner-image --id <id> --index N --alt "..." --action-type collection --action-value slug` |
+| 移除第 N 张图的手机版 | `commerce homepage patch-banner-image --id <id> --index N --remove-mobile-url` |
+| 关闭自动播放 | `commerce homepage patch-settings --id <id> --settings '{"autoplay":false}'` |
+| 修改轮播间隔 | `commerce homepage patch-settings --id <id> --settings '{"interval":3000}'` |
+
+### 集合
+
+| 用户说 | 命令 |
+|-------|------|
+| 添加集合入口区块 | `commerce homepage create-collections --title <title> --lang <lang> --slugs "a,b,c"` |
+| 更新集合列表 | `commerce homepage update-collections --id <id> --slugs "a,b,c"` |
+| 添加集合商品区块 | `commerce homepage create-collection-products --title <title> --lang <lang> --slug <slug>` |
+
+### 特色推荐
+
+| 用户说 | 命令 |
+|-------|------|
+| 添加特色推荐 | `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 upload --file bg.png` 拿到 media_id，再 `commerce homepage update-page-settings --background-media-id <id> --background-mode repeat-y` |
+| 设置固定背景（照片） | 先上传，再 `commerce homepage update-page-settings --background-media-id <id> --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` |
+
+### 品牌色
+
+| 用户说 | 命令 |
+|-------|------|
+| "修改品牌色" / "设置主题色" | **merchant skill**：`commerce merchant update --primary-color "#xxx"` |
+
+### 通用操作
+
+| 用户说 | 命令 |
+|-------|------|
+| 调整区块顺序 | `commerce homepage reorder --moves '[{"section_id":"<id>","new_position":0}]'` |
+| 修改区块标题/描述 | `commerce i18n homepage set --section-id <id> --lang <lang> --title "新标题"` |
+| 删除区块 | `commerce homepage delete --id <id> --yes` |
+| 切换模板 | `commerce homepage switch-template --template-key <minimal\|standard> --yes` |
+
+## Settings 合法字段
+
+使用 `patch-settings` 修改设置时，只能使用以下字段名。**使用未列出的字段会被后端拒绝（extra="forbid"）。**
+
+### banner
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| images | array | 图片数组（通过 `update-images` 或 `patch-banner-image` 修改，不要用 patch-settings） |
+| autoplay | boolean | 是否自动播放，默认 true |
+| interval | number | 轮播间隔（毫秒），1000-30000，默认 5000 |
+| image_fit | string | `cover`（默认，裁切填充）/ `contain`（完整显示，高度自适应，无裁切） |
+
+### collections
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| collection_slugs | array | 集合 slug 数组（通过 `update-collections` 修改更方便） |
+| layout | string | `grid` / `carousel` |
+| show_product_count | boolean | 是否显示商品数量 |
+
+### collection_products
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| collection_slug | string | 集合 slug |
+| mode | string | `auto` / `manual` |
+| product_handles | array | manual 模式下的商品 handle 列表 |
+| limit | number | auto 模式最多展示数量，默认 8 |
+| sort_by | string | `created_at` / `price` / `title` |
+| sort_order | string | `asc` / `desc` |
+
+### featured
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| target_type | string | `collection` / `product` |
+| target_handle | string | 目标 slug/handle |
+| media_id | string | 封面图片 ID |
+| url | string | 封面图片 URL（新上传用 url，后端自动转 media_id） |
+| cta_text | string | CTA 按钮文字 |
+| background_color | string | 背景颜色，如 `#f5f5f5` |
+
+### page_settings（页面级设置）
+
+通过 `update-page-settings` 命令修改，不是 `patch-settings`。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| background_media_id | string / null | 背景图片 Media ID（通过 `commerce upload` 获取，推荐） |
+| background_image | string / null | 背景图片 URL（不推荐直接使用，应通过 media_id 设置） |
+| background_mode | string | `repeat-y`（横向填满纵向平铺，默认）/ `fixed`（固定视口） |
+| background_overlay_color | string | 叠加颜色（hex 格式，默认 `#ffffff`） |
+| background_overlay_opacity | number | 叠加透明度 0-1（默认 0.85，越大越不透明） |
+
+## 复杂操作说明
+
+### update-images 全量替换
+
+`update-images` 会覆盖整个 images 数组。操作步骤：
+
+1. `commerce homepage get --id <id>` 获取现有图片（含 media_id）
+2. 构建完整数组：已有图原样透传 media_id，新图用 url
+3. 执行替换
+
+```bash
+commerce homepage update-images --id section_xxx --images '[
+  {"media_id":"med_abc","mobile_media_id":"med_def","alt":"图1","action_type":"collection","action_value":"sale"},
+  {"url":"https://new-image.jpg","alt":"新图","action_type":"none"}
+]'
+```
+
+**注意：漏传的字段（如 `mobile_media_id`）会导致手机图丢失。务必完整复制现有图片的所有字段。**
+
+### Banner 图片字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| url | △ | 桌面端图片 URL（url 或 media_id 至少一个） |
+| media_id | △ | 已有图片 ID（从 `homepage get` 获取） |
+| mobile_url | | 手机端图片 URL（3:4 竖向，可选） |
+| mobile_media_id | | 手机端已有图片 ID |
+| alt | ✓ | 图片描述 |
+| action_type | ✓ | `none` / `collection` / `product` / `url` / `section` |
+| action_value | | 动作目标（slug / URL / section handle） |
+
+### patch-banner-image vs update-images
+
+| 场景 | 用哪个 |
+|------|--------|
+| 改单张图的属性（alt、mobile_url 等） | `patch-banner-image --index N` |
+| 添加/删除图片、重新排序 | `update-images`（全量替换） |
+
+## 注意事项
+
+- **语言代码**：设置标题/描述时必须指定 `--lang`（zh-CN、en-US、ja-JP、es-ES、vi-VN），根据用户文字识别语言
+- **区块顺序**：position 从 0 开始
+- **media_id 生命周期**：URL → 传给 API → 后端自动转为 media_id → 后续 `homepage get` 返回 media_id
+- **手机端图片**：mobile_url 为 3:4 竖向，有时手机端显示竖版大图，无则保持横向
+- **image_fit**：默认 `cover`（裁切），设 `contain` 可按原始比例完整显示，适合纯切图首页
+- **模板切换**：会创建新区块并停用旧区块，谨慎操作
+- **删除确认**：删除操作需要 `--yes`