@optima-chat/optima-agent 0.5.0 → 0.5.1

package/.claude/skills/storefront/SKILL.md

@@ -1,532 +0,0 @@
----
-name: storefront
-description: "店铺前台配置管理。使用场景：配置首页(homepage/首页)、管理商品集合(collections/集合)、商品详情页区块(sections/区块)、调整模块顺序和布局。使用 commerce homepage/collection/section 命令。"
----
-
-# Commerce CLI - Storefront Configuration
-
-店铺前台配置模块，用于首页设置、商品集合管理和商品详情页区块配置。
-
-## 典型场景
-
-### 场景决策表
-
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 创建轮播图 | `commerce homepage module create --type banner` | 图片尺寸1920x600px，≤5张，配置跳转链接 |
-| 显示精选商品 | `commerce homepage module create --type featured` | 选择高转化商品，数量8-12个 |
-| 创建促销集合 | `commerce collection create --slug sale` | slug 简短有意义，添加10-30个商品 |
-| 调整模块顺序 | `commerce homepage module reorder --position X` | 重要模块靠前（轮播图position=1） |
-
-### 场景 1：首页配置
-
-**标准首页布局**（position顺序）：
-1. **轮播图** (position=1) - 展示促销、新品、品牌故事
-2. **分类导航** (position=2) - 快速引导到商品分类
-3. **精选商品** (position=3) - 展示高转化或高利润商品
-4. **热门集合** (position=4) - 展示2-3个核心集合
-5. **品牌故事** (position=5) - 建立信任和品牌认知
-
-**标准流程**：
-1. **规划布局** - 确定首页模块顺序（轮播图 → 分类 → 精选商品 → 集合）
-2. **创建模块** - 依次 `commerce homepage module create` 创建各模块
-3. **配置顺序** - 使用 position 1, 2, 3... 排序
-4. **设置参数** - `commerce homepage settings update` 配置搜索、精选数量
-5. **验证效果** - `commerce homepage module list` 检查配置
-6. **定期优化** - 根据数据调整模块顺序和内容
-
-### 场景 2：创建轮播图
-
-**配置要点**：
-- 图片尺寸：1920x600px（桌面端）
-- 数量限制：≤ 5张（避免影响加载速度）
-- 格式支持：WebP（优先）、JPG、PNG
-- 跳转链接：配置促销页面或集合页面
-- 懒加载：启用图片懒加载优化性能
-
-```bash
-commerce homepage module create \
-  --slug hero-banner \
-  --type banner \
-  --position 1 \
-  --enabled true \
-  --config '{"images":[{"url":"https://example.com/banner1.jpg","link":"/collections/summer-sale"}]}'
-```
-
-### 场景 3：创建商品集合
-
-**推荐集合类型**：
-- **时令集合** - 春夏秋冬、节日促销（如"Christmas Sale"）
-- **品类集合** - 按商品类型分组（如"T-Shirts", "Dresses"）
-- **主题集合** - 按场景分组（如"Office Wear", "Casual Style"）
-- **促销集合** - 新品、热卖、折扣（如"New Arrivals", "Best Sellers"）
-
-**创建流程**：
-```bash
-# 1. 创建集合
-commerce collection create \
-  --name "Summer Sale 2024" \
-  --slug "summer-sale-2024" \
-  --description "Hot deals for summer"
-
-# 2. 添加商品到集合
-commerce collection add-products \
-  --slug summer-sale-2024 \
-  --product-ids prod_123,prod_456,prod_789
-```
-
-### 场景 4：调整模块顺序
-
-**重新排序原则**：
-- 重要模块靠前（轮播图 position=1）
-- 高转化模块优先级高
-- 移动端体验优先
-- 定期根据数据优化
-
-```bash
-# 调整精选商品模块到第2位
-commerce homepage module reorder \
-  --module-id module_123 \
-  --position 2
-```
-
-### 场景 5：优化转化率
-
-**数据驱动优化**：
-- 分析首页点击热图，调整模块顺序
-- A/B测试不同轮播图和精选商品
-- 根据转化率隐藏低效集合
-- 精选商品选择高利润或高评分商品
-
-**性能优化建议**：
-- 轮播图：懒加载，压缩图片，支持WebP格式
-- 精选商品：限制8-12个，缓存1小时
-- 集合：按点击率排序，隐藏低转化集合
-
-
-## 卓越标准
-
-### 店铺配置质量指标
-- **页面加载速度**: 首页加载 < 3秒，移动端 < 5秒
-- **视觉设计**: 轮播图尺寸统一（1920x600px），图片清晰无水印
-- **导航体验**: 分类层级 ≤ 3层，集合数量 5-15个最佳
-- **内容更新频率**: 轮播图每周更新，精选商品每3天更新
-- **转化率**: 首页访客转化率 > 3%，集合页转化率 > 5%
-
-### 店铺配置原则
-- **移动优先**: 所有配置考虑移动端体验，图片支持响应式
-- **性能优化**: 轮播图 ≤ 5张，精选商品 ≤ 12个，减少加载负担
-- **SEO友好**: 集合slug使用英文，标题包含关键词
-- **一致性**: 风格统一（色彩、字体、间距），提升品牌辨识度
-- **数据驱动**: 根据点击率和转化率优化首页布局和集合内容
-
-### 首页配置检查清单
-
-**上线前必查**：
-- [ ] 轮播图尺寸统一，图片清晰
-- [ ] 所有链接可点击，无404
-- [ ] 移动端显示正常
-- [ ] 加载速度 < 3秒
-- [ ] SEO信息完整（标题、描述、关键词）
-- [ ] 精选商品有库存
-- [ ] 集合至少包含5个商品
-- [ ] 首页模块顺序合理
-
-## 常见问题
-
-### ❌ 问题 1：集合命名随意，无规划
-
-**错误做法**：
-```bash
-# 命名不规范，slug 无意义
-commerce collection create --name "aaa" --slug "test123"
-commerce collection create --name "商品111" --slug "product-collection"
-commerce collection create --name "Sale!!!" --slug "promotion"
-```
-
-**✅ 正确做法**：
-```bash
-# 命名清晰，slug 符合 SEO 规范
-commerce collection create --name "Summer Sale 2024" --slug "summer-sale-2024"
-commerce collection create --name "Men's T-Shirts" --slug "mens-tshirts"
-commerce collection create --name "New Arrivals" --slug "new-arrivals"
-```
-
-### ❌ 问题 2：轮播图过多影响性能
-
-**错误做法**：
-```bash
-# 创建10张轮播图，导致首页加载缓慢
-commerce homepage module create --type banner --config '{"images":[...10张图片...]}'
-```
-
-**✅ 正确做法**：
-```bash
-# 限制≤5张，压缩图片，启用懒加载
-commerce homepage module create --type banner --config '{"images":[...3-5张图片...]}'
-```
-
-### ❌ 问题 3：精选商品数量过多
-
-**错误做法**：
-```bash
-# 显示30个精选商品，影响用户决策
-commerce homepage settings update --featured-limit 30
-```
-
-**✅ 正确做法**：
-```bash
-# 限制8-12个，选择高转化商品
-commerce homepage settings update --featured-limit 10
-```
-
-### ❌ 问题 4：集合缺少商品
-
-**错误做法**：
-```bash
-# 创建集合后忘记添加商品
-commerce collection create --name "New Arrivals" --slug "new-arrivals"
-# 集合页面显示空白
-```
-
-**✅ 正确做法**：
-```bash
-# 创建集合后立即添加商品（至少5个）
-commerce collection create --name "New Arrivals" --slug "new-arrivals"
-commerce collection add-products --slug new-arrivals --product-ids prod_1,prod_2,prod_3,prod_4,prod_5
-```
-
-### ❌ 问题 5：首页模块顺序混乱
-
-**错误做法**：
-```bash
-# position 随意设置，导致布局混乱
-commerce homepage module create --type banner --position 10
-commerce homepage module create --type featured --position 2
-commerce homepage module create --type categories --position 50
-```
-
-**✅ 正确做法**：
-```bash
-# 按重要性依次设置 position 1, 2, 3...
-commerce homepage module create --type banner --position 1
-commerce homepage module create --type categories --position 2
-commerce homepage module create --type featured --position 3
-```
-
-### ❌ 问题 6：slug 使用中文或特殊字符
-
-**错误做法**：
-```bash
-# slug 包含中文或特殊字符，影响 SEO 和 URL 可读性
-commerce collection create --name "夏季促销" --slug "夏季促销"
-commerce collection create --name "Sale!!!" --slug "sale!!!"
-```
-
-**✅ 正确做法**：
-```bash
-# slug 使用英文、数字、连字符
-commerce collection create --name "夏季促销" --slug "summer-sale"
-commerce collection create --name "Sale!!!" --slug "sale"
-```
-
-## 命令参考
-
-### 自然语言映射
-
-当用户说：
-- "创建首页轮播图" → `commerce homepage module create --type banner ...`
-- "更新首页设置" → `commerce homepage settings update --show-search true`
-- "创建商品集合" → `commerce collection create --name XX --slug YY`
-- "把商品添加到集合" → `commerce collection add-products --slug XX --product-ids YY`
-
-### 核心功能
-
-**首页模块管理**:
-- `commerce homepage module create` - 创建首页模块
-- `commerce homepage module list` - 查看所有模块
-- `commerce homepage module update` - 更新模块
-- `commerce homepage module delete` - 删除模块
-- `commerce homepage module reorder` - 重新排序
-
-**首页设置**:
-- `commerce homepage settings get` - 查看首页设置
-- `commerce homepage settings update` - 更新首页设置
-
-**商品集合**:
-- `commerce collection create` - 创建集合
-- `commerce collection list` - 查看集合列表
-- `commerce collection update` - 更新集合
-- `commerce collection delete` - 删除集合
-- `commerce collection add-products` - 添加商品到集合
-- `commerce collection remove-products` - 从集合移除商品
-
-## 详细示例
-
-### 创建首页轮播图
-```bash
-# 用户说："创建首页轮播图模块"
-commerce homepage module create \
-  --slug hero-banner \
-  --type banner \
-  --position 1 \
-  --enabled true \
-  --config '{"images":[{"url":"https://example.com/banner1.jpg"}]}'
-```
-
-### 更新首页设置
-```bash
-# 用户说："启用首页搜索功能，显示8个精选商品"
-commerce homepage settings update \
-  --show-search true \
-  --featured-limit 8
-```
-
-### 创建商品集合
-```bash
-# 用户说："创建夏季促销集合"
-commerce collection create \
-  --name "Summer Sale" \
-  --slug summer-sale \
-  --description "Hot deals for summer"
-```
-
-### 添加商品到集合
-```bash
-# 用户说："把商品prod_123和prod_456添加到summer-sale集合"
-commerce collection add-products \
-  --slug summer-sale \
-  --product-ids prod_123,prod_456
-```
-
-
-### 重新排序首页模块
-```bash
-# 用户说："调整首页模块顺序"
-commerce homepage module reorder \
-  --module-id module_123 \
-  --position 2
-```
-
-### 完整首页配置示例
-```bash
-# 1. 创建轮播图模块
-commerce homepage module create \
-  --slug hero-banner \
-  --type banner \
-  --position 1 \
-  --config '{"images":[{"url":"https://example.com/banner1.jpg","link":"/collections/summer-sale"},{"url":"https://example.com/banner2.jpg","link":"/collections/new-arrivals"}]}'
-
-# 2. 创建分类导航模块
-commerce homepage module create \
-  --slug category-nav \
-  --type categories \
-  --position 2 \
-  --config '{"columns":4}'
-
-# 3. 创建精选商品模块
-commerce homepage module create \
-  --slug featured-products \
-  --type featured \
-  --position 3 \
-  --config '{"limit":10}'
-
-# 4. 更新首页设置
-commerce homepage settings update \
-  --show-search true \
-  --featured-limit 10
-
-# 5. 验证配置
-commerce homepage module list
-```
-
-## 场景 7：商品详情页区块管理
-
-### 三层继承模型
-
-商品详情页区块采用三层继承架构，实现灵活的内容定制：
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  System Layer (系统默认)                                 │
-│  - 7个预设区块: highlights, details, guarantee,          │
-│    care, shipping-policies, return, eco-friendly        │
-│  - 支持7种语言的默认翻译                                  │
-│  - 不可删除，只能覆盖或隐藏                               │
-└─────────────────────────────────────────────────────────┘
-                          ↓ 继承
-┌─────────────────────────────────────────────────────────┐
-│  Merchant Layer (商户定制)                               │
-│  - 覆盖系统默认区块内容                                   │
-│  - 创建商户专属新区块                                     │
-│  - 隐藏不需要的系统区块                                   │
-│  - 适用于所有商品（除非商品级覆盖）                        │
-└─────────────────────────────────────────────────────────┘
-                          ↓ 继承
-┌─────────────────────────────────────────────────────────┐
-│  Product Layer (商品定制)                                │
-│  - 覆盖商户/系统区块内容                                  │
-│  - 创建商品专属区块                                       │
-│  - 隐藏特定商品不需要的区块                               │
-│  - 最高优先级，仅影响单个商品                             │
-└─────────────────────────────────────────────────────────┘
-```
-
-### 查看区块配置
-
-```bash
-# 查看商户级配置（推荐使用 --resolved 查看完整视图）
-commerce section list --resolved
-
-# 查看特定商品的区块配置
-commerce section product list prod-123 --resolved
-```
-
-**关键字段说明**：
-- `source`: 区块来源 (system/merchant/product)
-- `is_hidden`: 是否被隐藏
-- `translations`: 各语言的标题和内容
-
-### 覆盖系统默认区块
-
-```bash
-# 商户级：覆盖所有商品的"护理说明"
-commerce section create \
-  --handle care \
-  --operation-type override \
-  --type collapsible \
-  --position 4 \
-  --content "我们的产品均可机洗，30度冷水。"
-
-# 商品级：为特定商品定制"护理说明"
-commerce section product create prod-123 \
-  --handle care \
-  --operation-type override \
-  --type collapsible \
-  --position 4 \
-  --content "此款真丝产品需要干洗。"
-```
-
-### 创建自定义区块
-
-```bash
-# 商户级：创建"品牌故事"区块（所有商品显示）
-commerce section create \
-  --handle brand-story \
-  --operation-type new \
-  --type collapsible \
-  --position 8 \
-  --content "## 我们的故事\n\n创立于2020年..."
-
-# 商品级：创建"成分说明"区块（仅此商品显示）
-commerce section product create prod-123 \
-  --handle ingredients \
-  --operation-type new \
-  --type collapsible \
-  --position 5 \
-  --content "主要成分：有机棉100%"
-```
-
-### 隐藏不需要的区块
-
-```bash
-# 商户级：隐藏"环保包装"区块（所有商品不显示）
-commerce section hide eco-friendly
-
-# 商品级：隐藏特定商品的"退货政策"
-commerce section product hide prod-123 return
-```
-
-### 添加多语言翻译
-
-```bash
-# 为商户级区块添加中文翻译
-commerce section translation set care \
-  --lang zh-CN \
-  --title "护理说明" \
-  --content "机洗，30度冷水。"
-
-# 为商品级区块添加日文翻译
-commerce section translation set care \
-  --product-id prod-123 \
-  --lang ja-JP \
-  --title "お手入れ方法" \
-  --content "洗濯機で洗えます。水温30度。"
-```
-
-### 调整区块顺序
-
-```bash
-# 商户级排序
-commerce section reorder --sections '[
-  {"handle":"highlights","position":1},
-  {"handle":"details","position":2},
-  {"handle":"care","position":3}
-]'
-
-# 商品级排序
-commerce section product reorder prod-123 --sections '[...]'
-```
-
-### Section 常见问题
-
-#### ❌ 问题：不理解三层继承，直接在商品级创建
-
-**错误做法**：
-```bash
-# 想要所有商品都显示"品牌故事"，却在商品级创建
-commerce section product create prod-123 --handle brand-story ...
-commerce section product create prod-456 --handle brand-story ...  # 重复操作
-```
-
-**✅ 正确做法**：
-```bash
-# 在商户级创建，自动应用到所有商品
-commerce section create --handle brand-story --operation-type new ...
-```
-
-#### ❌ 问题：不使用 --resolved 查看配置
-
-**错误做法**：
-```bash
-# 只看商户自定义，看不到系统默认
-commerce section list
-# 返回空列表（新商户通常没有自定义）
-```
-
-**✅ 正确做法**：
-```bash
-# 使用 --resolved 查看完整的合并后视图
-commerce section list --resolved
-# 返回 System + Merchant 合并后的所有区块
-```
-
-### Section 自然语言映射
-
-当用户说：
-- "查看商品详情页区块" → `commerce section list --resolved`
-- "查看商品X的区块配置" → `commerce section product list <id> --resolved`
-- "修改护理说明" → `commerce section create --handle care --operation-type override ...`
-- "隐藏退货政策区块" → `commerce section hide return`
-- "为商品添加自定义区块" → `commerce section product create <id> --handle XX --operation-type new ...`
-- "添加区块的中文翻译" → `commerce section translation set <handle> --lang zh-CN ...`
-
-## 重要提示
-
-### 首页配置
-- 首页模块支持类型：banner（轮播图）、featured（精选商品）、categories（分类）
-- 集合 slug 必须唯一，用于 URL
-- 模块的 position 决定显示顺序（从小到大）
-- config 字段使用 JSON 格式
-- 集合可以手动管理商品，也可以设置自动规则
-
-### 商品页区块
-- 系统默认区块：highlights, details, guarantee, care, shipping-policies, return, eco-friendly
-- `--resolved` 查看完整合并视图（推荐）
-- `source` 字段标识来源：system | merchant | product
-- 想改所有商品用 `section create`，只改一个商品用 `section product create`
-
-### 通用
-- 使用 `--help` 查看命令详细参数
-- 所有配置创建后需要验证是否正确
-- 定期根据数据分析优化布局和内容