@optima-chat/optima-agent 0.8.30 → 0.8.32

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, 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.
+description: Inventory management and stock monitoring. Set stock to exact values, adjust stock incrementally, check low stock alerts, view history, reserve stock. Use when user needs to set/update stock, replenish inventory, monitor low stock, or manage reservations. Two key commands - `inventory set` (set to exact number) and `inventory adjust` (add/remove incrementally).
 ---
 
 # Commerce CLI - Inventory Management
@@ -9,15 +9,29 @@ description: Inventory management and stock monitoring. Track stock levels, upda
 
 ## 典型场景
 
+### ⚠️ set vs adjust — 必须区分！
+
+| 命令 | 作用 | 示例 | 效果 |
+|------|------|------|------|
+| `inventory set --id XX --quantity 18` | **设置为**目标值 | 当前库存13，设为18 | 库存变为 18 |
+| `inventory adjust --id XX --quantity 5` | **增加**库存 | 当前库存13，加5 | 库存变为 18 |
+| `inventory adjust --id XX --quantity -3` | **减少**库存 | 当前库存13，减3 | 库存变为 10 |
+
+**判断用哪个**：
+- 用户说"库存设置为/设为/改为 N" → `inventory set`
+- 用户说"补货/加 N 个" → `inventory adjust`（正数）
+- 用户说"扣减/减 N 个" → `inventory adjust`（负数）
+
 ### 场景决策表
 
 | 用户需求 | 推荐命令 | 关键注意点 |
 |---------|---------|-----------|
+| 设置库存为 N | `inventory set --id XX --quantity N` | 直接设为目标值 |
 | 查看低库存 | `inventory low-stock --threshold 10` | 阈值根据品类和销售速度设定 |
-| 补货操作 | `inventory update --id XX --quantity YY` | 使用 product list 获取商品 ID |
-| 预留库存 | `inventory reserve --id XX --quantity YY` | 订单创建时立即预留，避免超卖 |
+| 补货操作 | `inventory adjust --id XX --quantity N` | 增量补货（+=） |
+| 盘点调整 | `inventory set --id XX --quantity N` | 以实际盘点数量为准 |
+| 预留库存 | `inventory reserve --id XX --quantity N` | 订单创建时立即预留，避免超卖 |
 | 查看历史 | `inventory history --id XX` | 分析库存变化趋势，优化补货策略 |
-| 盘点调整 | `inventory update --id XX --quantity YY` | 账实不符时手动调整 |
 
 ### 1. 查看低库存预警
 
@@ -33,13 +47,13 @@ commerce inventory low-stock --threshold 5
 **场景**：根据销售速度和品类特性进行科学补货
 
 ```bash
-# 用户说："商品prod_123补货100个"
-commerce inventory update --id prod_123 --quantity 100
+# 用户说："商品prod_123补货100个"（增量）
+commerce inventory adjust --id prod_123 --quantity 100
 
 # 根据销售数据决定补货量
-commerce inventory update --id prod_hot --quantity 500
-commerce inventory update --id prod_normal --quantity 100
-commerce inventory update --id prod_slow --quantity 20
+commerce inventory adjust --id prod_hot --quantity 500
+commerce inventory adjust --id prod_normal --quantity 100
+commerce inventory adjust --id prod_slow --quantity 20
 ```
 
 ### 3. 预留库存
@@ -60,8 +74,8 @@ commerce inventory reserve --id prod_123 --quantity 5
 **场景**：定期盘点发现账实差异，需要调整库存
 
 ```bash
-# 实际库存95，账面库存100，差异5个
-commerce inventory update --id prod_123 --quantity 95
+# 实际库存95，直接设置为实际数量
+commerce inventory set --id prod_123 --quantity 95
 ```
 
 ### 5. 处理超卖
@@ -111,7 +125,7 @@ commerce inventory history --id prod_123
 1. **查看低库存** - 每日 `commerce inventory low-stock --threshold 10`
 2. **分析销售趋势** - 结合订单数据判断补货优先级
 3. **制定补货计划** - 畅销品加大补货量，滞销品谨慎补货
-4. **执行补货** - `commerce inventory update --id XX --quantity YY`
+4. **执行补货** - `commerce inventory adjust --id XX --quantity YY`
 5. **验证更新** - `commerce product get --id XX` 确认库存正确
 6. **定期盘点** - 每月实地盘点，调整账面库存
 
@@ -123,7 +137,7 @@ commerce inventory history --id prod_123
 ```bash
 # 不分析就盲目补货，可能造成库存积压
 for product_id in $(commerce inventory low-stock --json | jq -r '.[].id'); do
-  commerce inventory update --id $product_id --quantity 100
+  commerce inventory adjust --id $product_id --quantity 100
 done
 ```
 
@@ -133,9 +147,9 @@ done
 commerce inventory low-stock --threshold 10
 
 # 根据销售数据决定补货量
-commerce inventory update --id prod_hot --quantity 500      # 畅销品大量补货
-commerce inventory update --id prod_normal --quantity 100   # 常规补货
-commerce inventory update --id prod_slow --quantity 20      # 滞销品少量补货
+commerce inventory adjust --id prod_hot --quantity 500      # 畅销品大量补货
+commerce inventory adjust --id prod_normal --quantity 100   # 常规补货
+commerce inventory adjust --id prod_slow --quantity 20      # 滞销品少量补货
 ```
 
 ### ❌ 问题2：库存差异超过5%未深入调查
@@ -148,8 +162,8 @@ commerce inventory update --id prod_slow --quantity 20      # 滞销品少量补
 3. 差异率 > 5%需要深入调查根本原因
 
 ```bash
-# 调整库存（记录差异原因：实际95，账面100，差异-5，仓库损耗）
-commerce inventory update --id prod_123 --quantity 95
+# 盘点调整：实际95，直接设为95
+commerce inventory set --id prod_123 --quantity 95
 ```
 
 ### ❌ 问题3：滞销商品长期占用库存
@@ -174,7 +188,7 @@ commerce inventory history --id prod_slow
 **✅ 正确做法**：
 ```bash
 # 根据销售数据决定补货量（如上周销量50，预计2周销量）
-commerce inventory update --id prod_123 --quantity 100
+commerce inventory adjust --id prod_123 --quantity 100
 ```
 
 ### ❌ 问题5：超卖后处理不当
@@ -195,15 +209,18 @@ commerce inventory update --id prod_123 --quantity 100
 ### 自然语言映射
 
 当用户说：
+- "库存设置为/设为/改为 N" → `commerce inventory set --id XX --quantity N`
+- "商品XX补货50个" → `commerce inventory adjust --id XX --quantity 50`
+- "扣减库存5个" → `commerce inventory adjust --id XX --quantity -5`
 - "查看库存低于10的商品" → `commerce inventory low-stock --threshold 10`
-- "商品XX补货50个" → `commerce inventory update --id XX --quantity 50`
 - "预留库存" → `commerce inventory reserve --id XX --quantity YY`
 - "查看库存历史" → `commerce inventory history --id XX`
 
 ### 核心功能
 
+- `commerce inventory set` - 设置库存为目标值（覆盖当前值）
+- `commerce inventory adjust` - 增减库存（增量 +=/-=）
 - `commerce inventory low-stock` - 查看低库存商品
-- `commerce inventory update` - 更新库存数量
 - `commerce inventory history` - 查看库存变更历史
 - `commerce inventory reserve` - 预留库存
 
@@ -215,10 +232,16 @@ commerce inventory update --id prod_123 --quantity 100
 commerce inventory low-stock --threshold 5
 ```
 
+### 设置库存
+```bash
+# 用户说："商品prod_123库存设为100"
+commerce inventory set --id prod_123 --quantity 100
+```
+
 ### 补货操作
 ```bash
-# 用户说："商品prod_123补货100个"
-commerce inventory update --id prod_123 --quantity 100
+# 用户说："商品prod_123补货100个"（在现有基础上增加100）
+commerce inventory adjust --id prod_123 --quantity 100
 ```
 
 ### 预留库存
@@ -252,21 +275,23 @@ commerce inventory history --id prod_123
 # 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
+# 2. 如果 variants 数组不为空，逐个设置变体库存
+commerce inventory set --id var_abc --quantity 10  # 变体1
+commerce inventory set --id var_def --quantity 10  # 变体2
+commerce inventory set --id var_ghi --quantity 10  # 变体3
 
-# 3. 如果没有变体，直接更新产品库存
-commerce inventory update --id prod_123 --quantity 30
+# 3. 如果没有变体，直接设置产品库存
+commerce inventory set --id prod_123 --quantity 30
 ```
 
 ### ❌ 常见错误
 
 ```bash
-# 错误：直接更新有变体产品的产品级库存
-commerce inventory update --id prod_123 --quantity 30
-# 这样做不会影响变体的可购买状态！
+# 错误1：直接设置有变体产品的产品级库存（会被 API 拒绝）
+commerce inventory set --id prod_123 --quantity 30
+
+# 错误2：想设为18，却用了 adjust（结果是当前值+18）
+commerce inventory adjust --id var_abc --quantity 18  # ❌ 增加了18，不是设为18
 ```
 
 ### ✅ 正确做法
@@ -277,10 +302,10 @@ commerce inventory update --id prod_123 --quantity 30
 # 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
+# 2. 逐个设置变体库存
+commerce inventory set --id var_abc --quantity 10
+commerce inventory set --id var_def --quantity 10
+commerce inventory set --id var_ghi --quantity 10
 
 # 产品总库存会自动变为 30（10+10+10）
 ```
@@ -290,13 +315,14 @@ commerce inventory update --id var_ghi --quantity 10
 当用户说"所有变体库存设置为 N"时：
 
 1. 先用 `commerce product get --id XX` 获取变体列表
-2. 遍历每个变体，用 `commerce inventory update --id <variant_id> --quantity N` 更新
+2. 遍历每个变体，用 `commerce inventory set --id <variant_id> --quantity N` 设置
 3. 确认更新成功后，产品总库存会自动计算
 
 ## 重要提示
 
+- **`inventory set`** 设为目标值，**`inventory adjust`** 增减库存 — 务必区分
+- **有变体的产品必须设置变体库存，不能直接设置产品库存**（会被 API 拒绝）
 - 库存变更会自动记录历史
 - 预留库存不会减少可用库存数量
 - 低库存阈值可自定义（默认5）
 - 使用 `--help` 查看命令详细参数
-- **有变体的产品必须更新变体库存，不能直接更新产品库存**

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

@@ -220,6 +220,7 @@ commerce product create --name "T恤" --price 99 --stock 50  # 确保真实有50
 - "设置商品原价/划线价" → `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`
 
 ### 核心功能
@@ -337,7 +338,7 @@ commerce product get --id prod_123
 ## 重要提示
 
 - **国际化策略** - 平台默认语言是英文（en-US）。当用户同时提供中英文内容时，用英文创建商品，中文通过 `i18n` skill 添加翻译。当用户要求"国际化"时，确保英文在主表，其他语言通过 i18n 添加。详见 i18n skill。
-- **库存管理请使用 inventory skill** - 如果用户要求更新库存、设置库存数量、补货等，请加载 `/inventory` skill。特别是有变体的产品，必须通过 inventory skill 更新变体库存，不能直接更新产品库存。
+- **库存管理统一使用 inventory skill** - 设置目标值用 `inventory set --id XX --quantity N`，增减库存用 `inventory adjust --id XX --quantity N`。**有变体的产品不能直接设置主产品库存**（会被拒绝），必须逐个设置变体的库存。
 - **商品描述支持 Markdown 格式**，可以使用标题、列表、加粗、链接等排版
 - 所有命令默认 JSON 输出，便于 AI 解析
 - 图片需要先上传获取 `media_id`，再关联到商品

package/package.json

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