@optima-chat/optima-agent 0.4.23 → 0.4.25

package/.claude/skills/inventory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: inventory
-description: Inventory management and stock monitoring. Track stock levels, update inventory, check low stock alerts, view inventory history, reserve stock. Use when user needs to check stock, replenish inventory, monitor low stock warnings, or manage stock reservations.
+description: Inventory management and stock monitoring. Track stock levels, update inventory, check low stock alerts, view inventory history, reserve stock. Use when user needs to check stock, replenish inventory, monitor low stock warnings, manage stock reservations, or set variant stock quantities. IMPORTANT - Always load this skill when user wants to update/set stock or inventory for products or variants.
 ---
 
 # Commerce CLI - Inventory Management
@@ -235,9 +235,68 @@ commerce inventory reserve \
 commerce inventory history --id prod_123
 ```
 
+## 变体库存管理（重要）
+
+**这是最常见的库存管理错误，务必理解！**
+
+### 核心规则
+
+| 产品类型 | 库存设置方式 | 说明 |
+|---------|-------------|------|
+| **有变体的产品** | 必须设置**变体库存** | 产品库存 = 所有变体库存之和（自动计算） |
+| **无变体的产品** | 直接设置**产品库存** | 正常更新即可 |
+
+### 正确的库存更新流程
+
+```bash
+# 1. 先查看产品是否有变体
+commerce product get --id prod_123
+
+# 2. 如果 variants 数组不为空，需要逐个更新变体库存
+commerce inventory update --id var_abc --quantity 10  # 变体1
+commerce inventory update --id var_def --quantity 10  # 变体2
+commerce inventory update --id var_ghi --quantity 10  # 变体3
+
+# 3. 如果没有变体，直接更新产品库存
+commerce inventory update --id prod_123 --quantity 30
+```
+
+### ❌ 常见错误
+
+```bash
+# 错误：直接更新有变体产品的产品级库存
+commerce inventory update --id prod_123 --quantity 30
+# 这样做不会影响变体的可购买状态！
+```
+
+### ✅ 正确做法
+
+```bash
+# 用户说："把所有变体库存都设置为10"
+
+# 1. 先获取产品和变体信息
+commerce product get --id prod_123
+
+# 2. 逐个更新变体库存（假设返回了3个变体）
+commerce inventory update --id var_abc --quantity 10
+commerce inventory update --id var_def --quantity 10
+commerce inventory update --id var_ghi --quantity 10
+
+# 产品总库存会自动变为 30（10+10+10）
+```
+
+### 批量设置变体库存
+
+当用户说"所有变体库存设置为 N"时：
+
+1. 先用 `commerce product get --id XX` 获取变体列表
+2. 遍历每个变体，用 `commerce inventory update --id <variant_id> --quantity N` 更新
+3. 确认更新成功后，产品总库存会自动计算
+
 ## 重要提示
 
 - 库存变更会自动记录历史
 - 预留库存不会减少可用库存数量
 - 低库存阈值可自定义（默认5）
 - 使用 `--help` 查看命令详细参数
+- **有变体的产品必须更新变体库存，不能直接更新产品库存**

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

@@ -1,6 +1,6 @@
 ---
 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, manage product inventory, upload photos, or organize product catalog.
+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
@@ -216,11 +216,18 @@ commerce product create --title "T恤" --price 99 --stock 50  # 确保真实有5
 ### 示例1：创建单个商品
 ```bash
 # 用户说："创建T恤商品，99美元，库存20"
+# 描述支持 Markdown 格式
 commerce product create \
   --title "T恤" \
   --price 99 \
   --stock 20 \
-  --description "100% 纯棉T恤"
+  --description "## 产品特点
+
+- **材质**：100% 纯棉
+- **特性**：透气舒适，不易起球
+- **适合人群**：日常休闲、运动
+
+> 机洗建议：30°C 以下冷水洗涤"
 ```
 
 ### 示例2：上传商品图片
@@ -298,6 +305,8 @@ commerce product get --id prod_123
 
 ## 重要提示
 
+- **库存管理请使用 inventory skill** - 如果用户要求更新库存、设置库存数量、补货等，请加载 `/inventory` skill。特别是有变体的产品，必须通过 inventory skill 更新变体库存，不能直接更新产品库存。
+- **商品描述支持 Markdown 格式**，可以使用标题、列表、加粗、链接等排版
 - 所有命令默认 JSON 输出，便于 AI 解析
 - 图片需要先上传获取 `media_id`，再关联到商品
 - 变体的 `attributes` 使用 JSON 格式

package/dist/src/system-prompt.js

@@ -26,9 +26,9 @@ export function getSystemPrompt() {
 可用的 Skills：
 
 - **merchant** - 店铺信息查询和管理
-- **product** - 商品管理（创建、编辑、删除商品）
+- **product** - 商品管理（创建、编辑、删除商品、变体管理）
 - **order** - 订单处理（发货、退款、查询）
-- **inventory** - 库存管理（监控、调整库存）
+- **inventory** - 库存管理（**设置/更新库存必须用这个**，特别是变体库存）
 - **i18n** - 国际化翻译管理
 - **collection** - 商品集合管理（分组、促销专区）
 - **homepage** - 店铺首页配置（Banner、集合展示）

package/package.json

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