@optima-chat/optima-agent 0.9.11 → 0.9.12

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

@@ -1,379 +1,379 @@
----
-name: 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, upload photos, or organize product catalog. NOTE - For inventory/stock management, use the inventory skill instead.
----
-
-# Commerce CLI - Product Management
-
-商品管理模块，用于电商商品目录的创建、编辑和组织。
-
-## 典型场景
-
-### 场景1：单个商品上架
-**流程**: 准备素材 → 上传图片 → 创建商品 → 验证
-```bash
-# 1. 上传商品图片
-commerce upload image --path ./tshirt-main.jpg  # 获得 media_123
-
-# 2. 创建商品
-commerce product create \
-  --name "纯棉T恤" \
-  --price 99 \
-  --stock 20 \
-  --description "100% 纯棉，舒适透气" \
-  --media-id media_123
-```
-
-### 场景2：多规格商品上架
-**流程**: 创建主商品 → 创建所有变体 → 关联图片（共享+变体专属）
-```bash
-# 1. 创建主商品
-commerce product create --name "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
-# 获得 variant_id: var_red_s
-commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
-  --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 50
-# 获得 variant_id: var_blue_s
-
-# 3. 关联共享图片（所有变体都能看到）
-commerce product add-images --id prod_123 --media-id media_front,media_back
-
-# 4. 关联变体专属图片（选择该变体时显示）
-commerce variant add-images --product-id prod_123 --variant-id var_red_s --url "https://cdn.../red.jpg"
-commerce variant add-images --product-id prod_123 --variant-id var_blue_s --url "https://cdn.../blue.jpg"
-# 也可以用已有 media_id：--media-id media_red
-```
-
-### 场景3：批量商品导入
-**流程**: 先上传共享资源 → 循环创建商品
-```bash
-# 1. 上传品牌logo（所有商品共享）
-commerce upload image --path ./brand-logo.jpg  # 获得 media_shared
-
-# 2. 批量创建商品（复用media_id）
-for product in "T恤" "衬衫" "卫衣"; do
-  commerce product create --name "$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 --original-price 99 --tags "featured,sale"
-commerce product update --id prod_456 --price 79 --original-price 99 --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
-```
-
-### 场景6：创建促销商品
-**任务**: 创建带折扣显示的商品（显示划线价）
-```bash
-# 创建促销商品：售价79，原价99（显示划线价）
-commerce product create \
-  --name "夏日特惠T恤" \
-  --price 79 \
-  --original-price 99 \
-  --stock 100 \
-  --tags "sale"
-```
-
-### 场景决策表
-
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 单个商品 | `product create` | 先上传图片，准备好所有必填字段 |
-| 多规格商品 | `product create` + `variant create` | 主商品设置基础价格，变体设置差异价 |
-| 批量上架 | 脚本循环 `product create` | 复用共享图片的media_id，避免重复上传 |
-| 更新价格 | `product update --price` | 如有变体，需逐个更新变体价格 |
-| 促销商品 | `product create --original-price` | `--original-price` 必须大于 `--price` |
-| 促销标签 | `product update --tags` | 用逗号分隔，保留原有标签 |
-| 图片更新 | `upload` + `add-images` | 先上传再关联，不要直接删除旧图 |
-| 删除商品 | `product delete` | **软删除**，商品状态变为 archived |
-| 下架商品 | `product update --status inactive` | 暂时隐藏，可随时恢复 |
-
-## 商品状态说明（重要）
-
-| 状态 | 含义 | 用户可能说 |
-|------|------|-----------|
-| `active` | 正常上架，买家可见 | "上架"、"发布" |
-| `inactive` | 暂时下架，买家不可见 | "下架"、"隐藏" |
-| `draft` | 草稿，未发布 | "草稿"、"暂存" |
-| `archived` | **已删除（软删除）**，数据保留 | "删除"、"移除" |
-
-**`product delete` = 软删除**：删除商品会将状态设为 `archived`，数据保留但不再显示。
-
-**已归档商品不需要再删除**：如果商品状态已经是 `archived`，告诉用户"商品已删除"。
-
-## 卓越标准
-
-### 商品质量维度
-- **图片质量**: 至少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 --name "$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 --name "$product" --media-id media_123
-done
-```
-
-### ❌ 问题2：忘记创建变体
-**症状**: 多规格商品只有主商品，无法选择颜色/尺寸
-**解决**: 创建主商品后，立即创建所有变体
-
-```bash
-# 错误：只创建主商品
-commerce product create --name "T恤" --price 99
-
-# 正确：创建主商品 + 所有变体
-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" ...
-```
-
-### ❌ 问题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 --name "T恤" --price 99 --stock 50  # 确保真实有50件
-```
-
-## 命令参考
-
-### 自然语言映射
-
-当用户说：
-- "创建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 variant add-images --product-id XX --variant-id YY --url/--media-id`
-- "把已有图片指定给变体" → `commerce variant add-images --product-id XX --variant-id YY --media-id ZZ`
-- "更新商品价格" → `commerce product update --id XX --price YY`
-- "设置商品原价/划线价" → `commerce product update --id XX --original-price YY`
-- "给商品打标签" → `commerce product update --id XX --tags "featured,new"`
-- "设置商品重量和尺寸" → `commerce product update --id XX --weight 0.5 --length 10 --width 8 --height 5`
-- "库存设置为 N" → `commerce inventory set --id XX --quantity N`（加载 inventory skill）
-- "查看所有商品" → `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 variant add-images` - 给变体关联图片（支持 URL/本地文件/media_id）
-
-**图片管理**:
-- `commerce upload image` - 上传图片
-- `commerce product add-images` - 关联图片到商品（所有变体共享）
-- `commerce product remove-images` - 移除商品图片
-- `commerce variant add-images` - 关联图片到特定变体（变体专属）
-
-## 详细示例
-
-### 示例1：创建单个商品
-```bash
-# 用户说："创建T恤商品，99美元，库存20"
-# 描述支持 Markdown 格式
-commerce product create \
-  --name "T恤" \
-  --price 99 \
-  --stock 20 \
-  --description "## 产品特点
-
-- **材质**：100% 纯棉
-- **特性**：透气舒适，不易起球
-- **适合人群**：日常休闲、运动
-
-> 机洗建议：30°C 以下冷水洗涤"
-```
-
-### 示例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 --name "纯棉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
-```
-
-### 物流属性引导（物理产品）
-
-创建 `requires_shipping: true` 的物理产品时：
-
-1. **重量**：引导卖家填写准确重量（影响所有物流报价准确性）
-2. **cargo_type**：根据产品标题/描述自动推断（默认 general），向卖家确认
-   - 推断方式："根据产品信息，我推断这是普通商品，对吗？"（不要直接问"含电池吗？"）
-   - 可选值：general（普货）、battery（带电）、liquid（液体）、cosmetic（化妆品）、clothing（服装）、powder（粉末）、wood（木制品）
-   - 这是通用物流属性，不需要提及任何具体物流商
-3. **brand**：引导填写品牌（可选，用于物流限制检查）
-4. 用户可跳过，但告知"会影响物流方案选择和报价准确性"
-5. 数字产品跳过整个物流属性流程
-
-## 重要提示
-
-- **国际化策略** - 平台默认语言是英文（en-US）。当用户同时提供中英文内容时，用英文创建商品，中文通过 `i18n` skill 添加翻译。当用户要求"国际化"时，确保英文在主表，其他语言通过 i18n 添加。详见 i18n skill。
-- **库存管理统一使用 inventory skill** - 设置目标值用 `inventory set --id XX --quantity N`，增减库存用 `inventory adjust --id XX --quantity N`。**有变体的产品不能直接设置主产品库存**（会被拒绝），必须逐个设置变体的库存。
-- **商品描述支持 Markdown 格式**，可以使用标题、列表、加粗、链接等排版
-- 所有命令默认 JSON 输出，便于 AI 解析
-- 图片需要先上传获取 `media_id`，再关联到商品
-- 变体的 `attributes` 使用 JSON 格式
-- 标签使用逗号分隔的字符串
-- 支持的图片格式：JPG, PNG, WebP（最大 10MB）
-- 使用 `--help` 查看命令详细参数
-- 删除商品会同时删除所有变体和图片关联
-- 价格单位默认为美元（USD），可通过后台配置修改
-- **重量单位：kg**（如 0.5 表示 500g）
-- **尺寸单位：cm**（length/width/height）
-- 集合 slug 必须唯一，用于 URL，使用英文和连字符
-- 集合封面支持三种方式：`--media-id`（推荐）、`--url`、`--path`
+---
+name: 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, upload photos, or organize product catalog. NOTE - For inventory/stock management, use the inventory skill instead.
+---
+
+# Commerce CLI - Product Management
+
+商品管理模块，用于电商商品目录的创建、编辑和组织。
+
+## 典型场景
+
+### 场景1：单个商品上架
+**流程**: 准备素材 → 上传图片 → 创建商品 → 验证
+```bash
+# 1. 上传商品图片
+commerce upload image --path ./tshirt-main.jpg  # 获得 media_123
+
+# 2. 创建商品
+commerce product create \
+  --name "纯棉T恤" \
+  --price 99 \
+  --stock 20 \
+  --description "100% 纯棉，舒适透气" \
+  --media-id media_123
+```
+
+### 场景2：多规格商品上架
+**流程**: 创建主商品 → 创建所有变体 → 关联图片（共享+变体专属）
+```bash
+# 1. 创建主商品
+commerce product create --name "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
+# 获得 variant_id: var_red_s
+commerce variant create --product-id prod_123 --sku "TSHIRT-BLUE-S" \
+  --attributes '{"颜色":"蓝色","尺寸":"S"}' --price 99 --stock 50
+# 获得 variant_id: var_blue_s
+
+# 3. 关联共享图片（所有变体都能看到）
+commerce product add-images --id prod_123 --media-id media_front,media_back
+
+# 4. 关联变体专属图片（选择该变体时显示）
+commerce variant add-images --product-id prod_123 --variant-id var_red_s --url "https://cdn.../red.jpg"
+commerce variant add-images --product-id prod_123 --variant-id var_blue_s --url "https://cdn.../blue.jpg"
+# 也可以用已有 media_id：--media-id media_red
+```
+
+### 场景3：批量商品导入
+**流程**: 先上传共享资源 → 循环创建商品
+```bash
+# 1. 上传品牌logo（所有商品共享）
+commerce upload image --path ./brand-logo.jpg  # 获得 media_shared
+
+# 2. 批量创建商品（复用media_id）
+for product in "T恤" "衬衫" "卫衣"; do
+  commerce product create --name "$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 --original-price 99 --tags "featured,sale"
+commerce product update --id prod_456 --price 79 --original-price 99 --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
+```
+
+### 场景6：创建促销商品
+**任务**: 创建带折扣显示的商品（显示划线价）
+```bash
+# 创建促销商品：售价79，原价99（显示划线价）
+commerce product create \
+  --name "夏日特惠T恤" \
+  --price 79 \
+  --original-price 99 \
+  --stock 100 \
+  --tags "sale"
+```
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 单个商品 | `product create` | 先上传图片，准备好所有必填字段 |
+| 多规格商品 | `product create` + `variant create` | 主商品设置基础价格，变体设置差异价 |
+| 批量上架 | 脚本循环 `product create` | 复用共享图片的media_id，避免重复上传 |
+| 更新价格 | `product update --price` | 如有变体，需逐个更新变体价格 |
+| 促销商品 | `product create --original-price` | `--original-price` 必须大于 `--price` |
+| 促销标签 | `product update --tags` | 用逗号分隔，保留原有标签 |
+| 图片更新 | `upload` + `add-images` | 先上传再关联，不要直接删除旧图 |
+| 删除商品 | `product delete` | **软删除**，商品状态变为 archived |
+| 下架商品 | `product update --status inactive` | 暂时隐藏，可随时恢复 |
+
+## 商品状态说明（重要）
+
+| 状态 | 含义 | 用户可能说 |
+|------|------|-----------|
+| `active` | 正常上架，买家可见 | "上架"、"发布" |
+| `inactive` | 暂时下架，买家不可见 | "下架"、"隐藏" |
+| `draft` | 草稿，未发布 | "草稿"、"暂存" |
+| `archived` | **已删除（软删除）**，数据保留 | "删除"、"移除" |
+
+**`product delete` = 软删除**：删除商品会将状态设为 `archived`，数据保留但不再显示。
+
+**已归档商品不需要再删除**：如果商品状态已经是 `archived`，告诉用户"商品已删除"。
+
+## 卓越标准
+
+### 商品质量维度
+- **图片质量**: 至少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 --name "$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 --name "$product" --media-id media_123
+done
+```
+
+### ❌ 问题2：忘记创建变体
+**症状**: 多规格商品只有主商品，无法选择颜色/尺寸
+**解决**: 创建主商品后，立即创建所有变体
+
+```bash
+# 错误：只创建主商品
+commerce product create --name "T恤" --price 99
+
+# 正确：创建主商品 + 所有变体
+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" ...
+```
+
+### ❌ 问题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 --name "T恤" --price 99 --stock 50  # 确保真实有50件
+```
+
+## 命令参考
+
+### 自然语言映射
+
+当用户说：
+- "创建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 variant add-images --product-id XX --variant-id YY --url/--media-id`
+- "把已有图片指定给变体" → `commerce variant add-images --product-id XX --variant-id YY --media-id ZZ`
+- "更新商品价格" → `commerce product update --id XX --price YY`
+- "设置商品原价/划线价" → `commerce product update --id XX --original-price YY`
+- "给商品打标签" → `commerce product update --id XX --tags "featured,new"`
+- "设置商品重量和尺寸" → `commerce product update --id XX --weight 0.5 --length 10 --width 8 --height 5`
+- "库存设置为 N" → `commerce inventory set --id XX --quantity N`（加载 inventory skill）
+- "查看所有商品" → `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 variant add-images` - 给变体关联图片（支持 URL/本地文件/media_id）
+
+**图片管理**:
+- `commerce upload image` - 上传图片
+- `commerce product add-images` - 关联图片到商品（所有变体共享）
+- `commerce product remove-images` - 移除商品图片
+- `commerce variant add-images` - 关联图片到特定变体（变体专属）
+
+## 详细示例
+
+### 示例1：创建单个商品
+```bash
+# 用户说："创建T恤商品，99美元，库存20"
+# 描述支持 Markdown 格式
+commerce product create \
+  --name "T恤" \
+  --price 99 \
+  --stock 20 \
+  --description "## 产品特点
+
+- **材质**：100% 纯棉
+- **特性**：透气舒适，不易起球
+- **适合人群**：日常休闲、运动
+
+> 机洗建议：30°C 以下冷水洗涤"
+```
+
+### 示例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 --name "纯棉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
+```
+
+### 物流属性引导（物理产品）
+
+创建 `requires_shipping: true` 的物理产品时：
+
+1. **重量**：引导卖家填写准确重量（影响所有物流报价准确性）
+2. **cargo_type**：根据产品标题/描述自动推断（默认 general），向卖家确认
+   - 推断方式："根据产品信息，我推断这是普通商品，对吗？"（不要直接问"含电池吗？"）
+   - 可选值：general（普货）、battery（带电）、liquid（液体）、cosmetic（化妆品）、clothing（服装）、powder（粉末）、wood（木制品）
+   - 这是通用物流属性，不需要提及任何具体物流商
+3. **brand**：引导填写品牌（可选，用于物流限制检查）
+4. 用户可跳过，但告知"会影响物流方案选择和报价准确性"
+5. 数字产品跳过整个物流属性流程
+
+## 重要提示
+
+- **国际化策略** - 平台默认语言是英文（en-US）。当用户同时提供中英文内容时，用英文创建商品，中文通过 `i18n` skill 添加翻译。当用户要求"国际化"时，确保英文在主表，其他语言通过 i18n 添加。详见 i18n skill。
+- **库存管理统一使用 inventory skill** - 设置目标值用 `inventory set --id XX --quantity N`，增减库存用 `inventory adjust --id XX --quantity N`。**有变体的产品不能直接设置主产品库存**（会被拒绝），必须逐个设置变体的库存。
+- **商品描述支持 Markdown 格式**，可以使用标题、列表、加粗、链接等排版
+- 所有命令默认 JSON 输出，便于 AI 解析
+- 图片需要先上传获取 `media_id`，再关联到商品
+- 变体的 `attributes` 使用 JSON 格式
+- 标签使用逗号分隔的字符串
+- 支持的图片格式：JPG, PNG, WebP（最大 10MB）
+- 使用 `--help` 查看命令详细参数
+- 删除商品会同时删除所有变体和图片关联
+- 价格单位默认为美元（USD），可通过后台配置修改
+- **重量单位：kg**（如 0.5 表示 500g）
+- **尺寸单位：cm**（length/width/height）
+- 集合 slug 必须唯一，用于 URL，使用英文和连字符
+- 集合封面支持三种方式：`--media-id`（推荐）、`--url`、`--path`