@optima-chat/optima-agent 0.1.0

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

@@ -0,0 +1,307 @@
+---
+name: commerce-product
+description: Product catalog management for e-commerce stores. Create and update products, manage variants/SKUs, upload product images, organize tags. Use when user needs to add new products, update pricing, manage product inventory, upload photos, or organize product catalog.
+---
+
+# Commerce CLI - Product Management
+
+商品管理模块，用于电商商品目录的创建、编辑和组织。
+
+## 典型场景
+
+### 场景1：单个商品上架
+**流程**: 准备素材 → 上传图片 → 创建商品 → 验证
+```bash
+# 1. 上传商品图片
+commerce upload image --path ./tshirt-main.jpg  # 获得 media_123
+
+# 2. 创建商品
+commerce product create \
+  --title "纯棉T恤" \
+  --price 99 \
+  --stock 20 \
+  --description "100% 纯棉，舒适透气" \
+  --media-id media_123
+```
+
+### 场景2：多规格商品上架
+**流程**: 创建主商品 → 创建所有变体 → 关联图片
+```bash
+# 1. 创建主商品
+commerce product create --title "T恤" --price 99
+# 获得 product_id: prod_123
+
+# 2. 创建所有变体
+commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" \
+  --attributes '{"颜色":"红色","尺寸":"S"}' --price 99 --stock 50
+commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" \
+  --attributes '{"颜色":"红色","尺寸":"M"}' --price 99 --stock 50
+commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
+  --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 50
+```
+
+### 场景3：批量商品导入
+**流程**: 先上传共享资源 → 循环创建商品
+```bash
+# 1. 上传品牌logo（所有商品共享）
+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
+done
+```
+
+### 场景4：促销活动准备
+**任务**: 批量更新价格和标签
+```bash
+# 1. 查找目标商品
+commerce product list --query "T恤" --limit 50
+
+# 2. 批量更新价格和促销标签
+commerce product update --id prod_123 --price 79 --tags "featured,sale"
+commerce product update --id prod_456 --price 79 --tags "featured,sale"
+```
+
+### 场景5：商品图片更新
+**任务**: 更换主图或添加详情图
+```bash
+# 1. 上传新图片
+commerce upload image --path ./new-photo.jpg  # 获得 media_new
+
+# 2. 添加到商品
+commerce product add-images --id prod_123 --media-id media_new
+```
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 单个商品 | `product create` | 先上传图片，准备好所有必填字段 |
+| 多规格商品 | `product create` + `variant create` | 主商品设置基础价格，变体设置差异价 |
+| 批量上架 | 脚本循环 `product create` | 复用共享图片的media_id，避免重复上传 |
+| 更新价格 | `product update --price` | 如有变体，需逐个更新变体价格 |
+| 促销标签 | `product update --tags` | 用逗号分隔，保留原有标签 |
+| 图片更新 | `upload` + `add-images` | 先上传再关联，不要直接删除旧图 |
+
+## 卓越标准
+
+### 商品质量维度
+- **图片质量**: 至少3张不同角度，主图尺寸 ≥ 1200x1200px
+- **描述完整性**: 必填字段100%填写，描述文字 ≥ 50字
+- **SEO优化**: 标题包含核心关键词，使用3-5个相关标签
+- **变体规范**: 使用统一的attributes key（如"颜色"、"尺寸"），避免同义词混用
+- **库存准确**: 创建时设置真实库存，避免超卖和缺货
+
+### 上架流程原则
+- **图片先行**: 先批量上传所有图片获取media_id，再创建商品（避免重复上传）
+- **主商品后变体**: 先创建主商品获取product_id，再创建所有变体
+- **数据完整性**: 每个变体必须有独立SKU、库存、价格
+- **标签策略**: 精选(featured)、新品(new)、促销(sale)等核心标签要及时更新
+
+### 质量检查清单
+- [ ] 商品标题简洁有力，包含关键词
+- [ ] 描述文字 ≥ 50字，突出卖点
+- [ ] 至少3张图片，主图清晰
+- [ ] 价格和库存准确无误
+- [ ] 变体SKU不重复
+- [ ] 标签使用合理（3-5个）
+
+## 常见问题
+
+### ❌ 问题1：重复上传图片
+**错误做法**：
+```bash
+# 每个商品都上传相同的logo
+for product in products; do
+  commerce upload image --path ./logo.jpg
+  commerce product create --title "$product" --media-id $NEW_ID
+done
+```
+
+**正确做法**：
+```bash
+# 先上传一次，复用media_id
+commerce upload image --path ./logo.jpg  # 获得 media_123
+for product in products; do
+  commerce product create --title "$product" --media-id media_123
+done
+```
+
+### ❌ 问题2：忘记创建变体
+**症状**: 多规格商品只有主商品，无法选择颜色/尺寸
+**解决**: 创建主商品后，立即创建所有变体
+
+```bash
+# 错误：只创建主商品
+commerce product create --title "T恤" --price 99
+
+# 正确：创建主商品 + 所有变体
+commerce product create --title "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" ...
+```
+
+### ❌ 问题3：变体attributes不一致
+**症状**: 规格筛选混乱，如"颜色"、"color"、"Color"混用
+**解决**: 统一使用中文或英文，全局保持一致
+
+```bash
+# 错误：同义词混用
+--attributes '{"颜色":"红色"}'
+--attributes '{"color":"蓝色"}'
+
+# 正确：统一使用
+--attributes '{"颜色":"红色"}'
+--attributes '{"颜色":"蓝色"}'
+```
+
+### ❌ 问题4：批量更新时覆盖标签
+**症状**: 更新标签时把原有标签清空
+**解决**: 先查看原有标签，追加新标签
+
+```bash
+# 错误：直接覆盖
+commerce product update --id prod_123 --tags "sale"  # featured标签丢失
+
+# 正确：先查看再追加
+commerce product get --id prod_123  # 查看原有标签: featured,new
+commerce product update --id prod_123 --tags "featured,new,sale"
+```
+
+### ❌ 问题5：库存设置不准确
+**症状**: 超卖或缺货
+**解决**: 创建时设置真实库存，定期同步ERP数据
+
+```bash
+# 先确认真实库存，再创建
+commerce product create --title "T恤" --price 99 --stock 50  # 确保真实有50件
+```
+
+## 命令参考
+
+### 自然语言映射
+
+当用户说：
+- "创建XX商品，价格YY" → `commerce product create --title XX --price YY`
+- "上传商品图片" → `commerce upload image --path ./photo.jpg`
+- "添加商品变体" → `commerce variant create --product-id XX --sku YY`
+- "更新商品价格" → `commerce product update --id XX --price YY`
+- "给商品打标签" → `commerce product update --id XX --tags "featured,new"`
+- "查看所有商品" → `commerce product list`
+
+### 核心功能
+
+**商品 CRUD**:
+- `commerce product create` - 创建商品
+- `commerce product list` - 查看商品列表
+- `commerce product get` - 查看商品详情
+- `commerce product update` - 更新商品信息
+- `commerce product delete` - 删除商品
+
+**变体/SKU 管理**:
+- `commerce variant create` - 创建商品变体
+- `commerce variant list` - 查看变体列表
+- `commerce variant update` - 更新变体信息
+- `commerce variant delete` - 删除变体
+
+**图片管理**:
+- `commerce upload image` - 上传图片
+- `commerce product add-images` - 关联图片到商品
+- `commerce product remove-images` - 移除商品图片
+
+## 详细示例
+
+### 示例1：创建单个商品
+```bash
+# 用户说："创建T恤商品，99美元，库存20"
+commerce product create \
+  --title "T恤" \
+  --price 99 \
+  --stock 20 \
+  --description "100% 纯棉T恤"
+```
+
+### 示例2：上传商品图片
+```bash
+# 用户说："上传商品主图"
+commerce upload image --path ./tshirt-main.jpg
+# 返回: { media_id: "media_123" }
+
+# 关联到商品
+commerce product add-images \
+  --id prod_123 \
+  --media-id media_123
+```
+
+### 示例3：创建商品变体
+```bash
+# 用户说："给商品添加红色S码的变体"
+commerce variant create \
+  --product-id prod_123 \
+  --sku "TSHIRT-RED-S" \
+  --price 99 \
+  --stock 50 \
+  --attributes '{"颜色":"红色","尺寸":"S"}'
+```
+
+### 示例4：管理商品标签
+```bash
+# 用户说："把商品标记为精选和新品"
+commerce product update \
+  --id prod_123 \
+  --tags "featured,new"
+
+# 查看带特定标签的商品
+commerce product list --tags "featured"
+```
+
+### 示例5：批量更新价格
+```bash
+# 用户说："把所有T恤价格改成89"
+# 1. 先查找T恤商品
+commerce product list --query "T恤"
+
+# 2. 逐个更新
+commerce product update --id prod_123 --price 89
+commerce product update --id prod_456 --price 89
+```
+
+### 示例6：完整的多规格商品上架
+```bash
+# 完整流程演示
+# 1. 上传图片
+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
+# 获得 product_id: prod_123
+
+# 3. 创建变体
+commerce variant create --product-id prod_123 --sku "TSHIRT-RED-S" \
+  --attributes '{"颜色":"红色","尺寸":"S"}' --price 99 --stock 50
+
+commerce variant create --product-id prod_123 --sku "TSHIRT-RED-M" \
+  --attributes '{"颜色":"红色","尺寸":"M"}' --price 99 --stock 30
+
+commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
+  --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 40
+
+# 4. 关联图片
+commerce product add-images --id prod_123 --media-id media_red,media_blue
+
+# 5. 验证
+commerce product get --id prod_123
+```
+
+## 重要提示
+
+- 所有命令默认 JSON 输出，便于 AI 解析
+- 图片需要先上传获取 `media_id`，再关联到商品
+- 变体的 `attributes` 使用 JSON 格式
+- 标签使用逗号分隔的字符串
+- 支持的图片格式：JPG, PNG, WebP
+- 使用 `--help` 查看命令详细参数
+- 删除商品会同时删除所有变体和图片关联
+- 价格单位默认为美元（USD），可通过后台配置修改