@optima-chat/optima-agent 0.9.12 → 0.9.14

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

@@ -1,328 +1,328 @@
----
-name: inventory
-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
-
-库存管理模块，用于监控库存水平、补货、预留和历史跟踪。
-
-## 典型场景
-
-### ⚠️ 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 adjust --id XX --quantity N` | 增量补货（+=） |
-| 盘点调整 | `inventory set --id XX --quantity N` | 以实际盘点数量为准 |
-| 预留库存 | `inventory reserve --id XX --quantity N` | 订单创建时立即预留，避免超卖 |
-| 查看历史 | `inventory history --id XX` | 分析库存变化趋势，优化补货策略 |
-
-### 1. 查看低库存预警
-
-**场景**：每日检查需要补货的商品
-
-```bash
-# 用户说："查看库存低于5的商品"
-commerce inventory low-stock --threshold 5
-```
-
-### 2. 补货操作
-
-**场景**：根据销售速度和品类特性进行科学补货
-
-```bash
-# 用户说："商品prod_123补货100个"（增量）
-commerce inventory adjust --id prod_123 --quantity 100
-
-# 根据销售数据决定补货量
-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. 预留库存
-
-**场景**：订单创建时立即预留库存，防止超卖
-
-```bash
-# 用户说："为订单预留5个商品"
-commerce inventory reserve --id prod_123 --quantity 5
-```
-
-**库存预留机制**：
-- **订单创建时预留** - 避免超卖，保证订单可履行
-- **发货后扣减** - 商品发货后从可用库存扣减
-
-### 4. 盘点调整
-
-**场景**：定期盘点发现账实差异，需要调整库存
-
-```bash
-# 实际库存95，直接设置为实际数量
-commerce inventory set --id prod_123 --quantity 95
-```
-
-### 5. 处理超卖
-
-**场景**：发现库存不足以满足所有订单
-
-**预防措施**：
-- 订单创建时立即预留库存
-- 使用实时库存同步机制
-
-**发生后处理**：
-1. 优先处理早期订单，确保先到先得
-2. 联系后续客户协商延期或退款
-3. 紧急补货，缩短等待时间
-
-**长期优化**：
-- 检查库存同步机制，修复bug
-- 加强预留机制的可靠性
-- 设置安全库存缓冲
-
-### 6. 查看库存历史
-
-**场景**：分析库存变化趋势，优化补货策略
-
-```bash
-# 用户说："查看商品prod_123的库存变更记录"
-commerce inventory history --id prod_123
-```
-
-## 卓越标准
-
-### 库存管理质量指标
-- **库存准确率**: 账实相符率 ≥ 98%，定期盘点验证
-- **低库存预警响应**: 检测到低库存后24小时内补货
-- **缺货率**: < 2%，避免影响客户体验和转化率
-- **超卖率**: 0%，通过预留机制和实时同步防止超卖
-- **库存周转率**: 根据品类优化，畅销品 > 6次/年，滞销品及时清理
-
-### 库存管理原则
-- **实时同步**: 订单创建时立即预留库存，发货后扣减，取消后释放
-- **安全库存**: 设置合理的低库存阈值（畅销品 > 30天销量，滞销品 > 7天销量）
-- **先进先出**: 先入库的商品优先出库，减少积压和过期
-- **定期盘点**: 每月盘点核对账实差异，及时调整
-- **历史追踪**: 所有库存变更必须记录原因，便于审计
-
-### 日常库存监控流程
-1. **查看低库存** - 每日 `commerce inventory low-stock --threshold 10`
-2. **分析销售趋势** - 结合订单数据判断补货优先级
-3. **制定补货计划** - 畅销品加大补货量，滞销品谨慎补货
-4. **执行补货** - `commerce inventory adjust --id XX --quantity YY`
-5. **验证更新** - `commerce product get --id XX` 确认库存正确
-6. **定期盘点** - 每月实地盘点，调整账面库存
-
-## 常见问题
-
-### ❌ 问题1：批量补货不分析，造成库存积压
-
-**错误做法**：
-```bash
-# 不分析就盲目补货，可能造成库存积压
-for product_id in $(commerce inventory low-stock --json | jq -r '.[].id'); do
-  commerce inventory adjust --id $product_id --quantity 100
-done
-```
-
-**✅ 正确做法**：
-```bash
-# 先分析低库存商品，按销售速度分级补货
-commerce inventory low-stock --threshold 10
-
-# 根据销售数据决定补货量
-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%未深入调查
-
-**场景**：定期盘点发现差异
-
-**处理流程**：
-1. 核实实际库存，调整账面库存
-2. 记录差异原因（损耗、盗窃、系统错误等）
-3. 差异率 > 5%需要深入调查根本原因
-
-```bash
-# 盘点调整：实际95，直接设为95
-commerce inventory set --id prod_123 --quantity 95
-```
-
-### ❌ 问题3：滞销商品长期占用库存
-
-**滞销商品处理策略**：
-
-| 滞销时长 | 处理方式 | 命令示例 |
-|---------|---------|---------|
-| 库存周转率低 | 降价促销、捆绑销售 | 调整价格，增加曝光 |
-| 3个月未动销 | 考虑清仓处理 | 大幅降价或买一送一 |
-| 6个月未动销 | 下架并清理库存 | 捐赠、报废或转移 |
-
-```bash
-# 查看库存历史判断是否滞销
-commerce inventory history --id prod_slow
-```
-
-### ❌ 问题4：不分析销售数据就补货
-
-**错误做法**：直接设置固定数量，不考虑销售速度
-
-**✅ 正确做法**：
-```bash
-# 根据销售数据决定补货量（如上周销量50，预计2周销量）
-commerce inventory adjust --id prod_123 --quantity 100
-```
-
-### ❌ 问题5：超卖后处理不当
-
-**预防措施**：
-- 订单创建时立即预留库存
-- 使用实时库存同步机制
-
-**发生后正确处理**：
-1. ✅ 优先处理早期订单（先到先得）
-2. ✅ 主动联系后续客户，提供补偿方案
-3. ✅ 紧急补货，缩短等待时间
-4. ❌ 不要直接取消订单不解释
-5. ❌ 不要让客户长时间等待无反馈
-
-## 命令参考
-
-### 自然语言映射
-
-当用户说：
-- "库存设置为/设为/改为 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`
-- "预留库存" → `commerce inventory reserve --id XX --quantity YY`
-- "查看库存历史" → `commerce inventory history --id XX`
-
-### 核心功能
-
-- `commerce inventory set` - 设置库存为目标值（覆盖当前值）
-- `commerce inventory adjust` - 增减库存（增量 +=/-=）
-- `commerce inventory low-stock` - 查看低库存商品
-- `commerce inventory history` - 查看库存变更历史
-- `commerce inventory reserve` - 预留库存
-
-## 详细示例
-
-### 查看低库存预警
-```bash
-# 用户说："查看库存低于5的商品"
-commerce inventory low-stock --threshold 5
-```
-
-### 设置库存
-```bash
-# 用户说："商品prod_123库存设为100"
-commerce inventory set --id prod_123 --quantity 100
-```
-
-### 补货操作
-```bash
-# 用户说："商品prod_123补货100个"（在现有基础上增加100）
-commerce inventory adjust --id prod_123 --quantity 100
-```
-
-### 预留库存
-```bash
-# 用户说："为订单预留5个商品"
-commerce inventory reserve \
-  --id prod_123 \
-  --quantity 5
-```
-
-### 查看库存历史
-```bash
-# 用户说："查看商品prod_123的库存变更记录"
-commerce inventory history --id prod_123
-```
-
-## 变体库存管理（重要）
-
-**这是最常见的库存管理错误，务必理解！**
-
-### 核心规则
-
-| 产品类型 | 库存设置方式 | 说明 |
-|---------|-------------|------|
-| **有变体的产品** | 必须设置**变体库存** | 产品库存 = 所有变体库存之和（自动计算） |
-| **无变体的产品** | 直接设置**产品库存** | 正常更新即可 |
-
-### 正确的库存更新流程
-
-```bash
-# 1. 先查看产品是否有变体
-commerce product get --id prod_123
-
-# 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 set --id prod_123 --quantity 30
-```
-
-### ❌ 常见错误
-
-```bash
-# 错误1：直接设置有变体产品的产品级库存（会被 API 拒绝）
-commerce inventory set --id prod_123 --quantity 30
-
-# 错误2：想设为18，却用了 adjust（结果是当前值+18）
-commerce inventory adjust --id var_abc --quantity 18  # ❌ 增加了18，不是设为18
-```
-
-### ✅ 正确做法
-
-```bash
-# 用户说："把所有变体库存都设置为10"
-
-# 1. 先获取产品和变体信息
-commerce product get --id prod_123
-
-# 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）
-```
-
-### 批量设置变体库存
-
-当用户说"所有变体库存设置为 N"时：
-
-1. 先用 `commerce product get --id XX` 获取变体列表
-2. 遍历每个变体，用 `commerce inventory set --id <variant_id> --quantity N` 设置
-3. 确认更新成功后，产品总库存会自动计算
-
-## 重要提示
-
-- **`inventory set`** 设为目标值，**`inventory adjust`** 增减库存 — 务必区分
-- **有变体的产品必须设置变体库存，不能直接设置产品库存**（会被 API 拒绝）
-- 库存变更会自动记录历史
-- 预留库存不会减少可用库存数量
-- 低库存阈值可自定义（默认5）
-- 使用 `--help` 查看命令详细参数
+---
+name: inventory
+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
+
+库存管理模块，用于监控库存水平、补货、预留和历史跟踪。
+
+## 典型场景
+
+### ⚠️ 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 adjust --id XX --quantity N` | 增量补货（+=） |
+| 盘点调整 | `inventory set --id XX --quantity N` | 以实际盘点数量为准 |
+| 预留库存 | `inventory reserve --id XX --quantity N` | 订单创建时立即预留，避免超卖 |
+| 查看历史 | `inventory history --id XX` | 分析库存变化趋势，优化补货策略 |
+
+### 1. 查看低库存预警
+
+**场景**：每日检查需要补货的商品
+
+```bash
+# 用户说："查看库存低于5的商品"
+commerce inventory low-stock --threshold 5
+```
+
+### 2. 补货操作
+
+**场景**：根据销售速度和品类特性进行科学补货
+
+```bash
+# 用户说："商品prod_123补货100个"（增量）
+commerce inventory adjust --id prod_123 --quantity 100
+
+# 根据销售数据决定补货量
+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. 预留库存
+
+**场景**：订单创建时立即预留库存，防止超卖
+
+```bash
+# 用户说："为订单预留5个商品"
+commerce inventory reserve --id prod_123 --quantity 5
+```
+
+**库存预留机制**：
+- **订单创建时预留** - 避免超卖，保证订单可履行
+- **发货后扣减** - 商品发货后从可用库存扣减
+
+### 4. 盘点调整
+
+**场景**：定期盘点发现账实差异，需要调整库存
+
+```bash
+# 实际库存95，直接设置为实际数量
+commerce inventory set --id prod_123 --quantity 95
+```
+
+### 5. 处理超卖
+
+**场景**：发现库存不足以满足所有订单
+
+**预防措施**：
+- 订单创建时立即预留库存
+- 使用实时库存同步机制
+
+**发生后处理**：
+1. 优先处理早期订单，确保先到先得
+2. 联系后续客户协商延期或退款
+3. 紧急补货，缩短等待时间
+
+**长期优化**：
+- 检查库存同步机制，修复bug
+- 加强预留机制的可靠性
+- 设置安全库存缓冲
+
+### 6. 查看库存历史
+
+**场景**：分析库存变化趋势，优化补货策略
+
+```bash
+# 用户说："查看商品prod_123的库存变更记录"
+commerce inventory history --id prod_123
+```
+
+## 卓越标准
+
+### 库存管理质量指标
+- **库存准确率**: 账实相符率 ≥ 98%，定期盘点验证
+- **低库存预警响应**: 检测到低库存后24小时内补货
+- **缺货率**: < 2%，避免影响客户体验和转化率
+- **超卖率**: 0%，通过预留机制和实时同步防止超卖
+- **库存周转率**: 根据品类优化，畅销品 > 6次/年，滞销品及时清理
+
+### 库存管理原则
+- **实时同步**: 订单创建时立即预留库存，发货后扣减，取消后释放
+- **安全库存**: 设置合理的低库存阈值（畅销品 > 30天销量，滞销品 > 7天销量）
+- **先进先出**: 先入库的商品优先出库，减少积压和过期
+- **定期盘点**: 每月盘点核对账实差异，及时调整
+- **历史追踪**: 所有库存变更必须记录原因，便于审计
+
+### 日常库存监控流程
+1. **查看低库存** - 每日 `commerce inventory low-stock --threshold 10`
+2. **分析销售趋势** - 结合订单数据判断补货优先级
+3. **制定补货计划** - 畅销品加大补货量，滞销品谨慎补货
+4. **执行补货** - `commerce inventory adjust --id XX --quantity YY`
+5. **验证更新** - `commerce product get --id XX` 确认库存正确
+6. **定期盘点** - 每月实地盘点，调整账面库存
+
+## 常见问题
+
+### ❌ 问题1：批量补货不分析，造成库存积压
+
+**错误做法**：
+```bash
+# 不分析就盲目补货，可能造成库存积压
+for product_id in $(commerce inventory low-stock --json | jq -r '.[].id'); do
+  commerce inventory adjust --id $product_id --quantity 100
+done
+```
+
+**✅ 正确做法**：
+```bash
+# 先分析低库存商品，按销售速度分级补货
+commerce inventory low-stock --threshold 10
+
+# 根据销售数据决定补货量
+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%未深入调查
+
+**场景**：定期盘点发现差异
+
+**处理流程**：
+1. 核实实际库存，调整账面库存
+2. 记录差异原因（损耗、盗窃、系统错误等）
+3. 差异率 > 5%需要深入调查根本原因
+
+```bash
+# 盘点调整：实际95，直接设为95
+commerce inventory set --id prod_123 --quantity 95
+```
+
+### ❌ 问题3：滞销商品长期占用库存
+
+**滞销商品处理策略**：
+
+| 滞销时长 | 处理方式 | 命令示例 |
+|---------|---------|---------|
+| 库存周转率低 | 降价促销、捆绑销售 | 调整价格，增加曝光 |
+| 3个月未动销 | 考虑清仓处理 | 大幅降价或买一送一 |
+| 6个月未动销 | 下架并清理库存 | 捐赠、报废或转移 |
+
+```bash
+# 查看库存历史判断是否滞销
+commerce inventory history --id prod_slow
+```
+
+### ❌ 问题4：不分析销售数据就补货
+
+**错误做法**：直接设置固定数量，不考虑销售速度
+
+**✅ 正确做法**：
+```bash
+# 根据销售数据决定补货量（如上周销量50，预计2周销量）
+commerce inventory adjust --id prod_123 --quantity 100
+```
+
+### ❌ 问题5：超卖后处理不当
+
+**预防措施**：
+- 订单创建时立即预留库存
+- 使用实时库存同步机制
+
+**发生后正确处理**：
+1. ✅ 优先处理早期订单（先到先得）
+2. ✅ 主动联系后续客户，提供补偿方案
+3. ✅ 紧急补货，缩短等待时间
+4. ❌ 不要直接取消订单不解释
+5. ❌ 不要让客户长时间等待无反馈
+
+## 命令参考
+
+### 自然语言映射
+
+当用户说：
+- "库存设置为/设为/改为 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`
+- "预留库存" → `commerce inventory reserve --id XX --quantity YY`
+- "查看库存历史" → `commerce inventory history --id XX`
+
+### 核心功能
+
+- `commerce inventory set` - 设置库存为目标值（覆盖当前值）
+- `commerce inventory adjust` - 增减库存（增量 +=/-=）
+- `commerce inventory low-stock` - 查看低库存商品
+- `commerce inventory history` - 查看库存变更历史
+- `commerce inventory reserve` - 预留库存
+
+## 详细示例
+
+### 查看低库存预警
+```bash
+# 用户说："查看库存低于5的商品"
+commerce inventory low-stock --threshold 5
+```
+
+### 设置库存
+```bash
+# 用户说："商品prod_123库存设为100"
+commerce inventory set --id prod_123 --quantity 100
+```
+
+### 补货操作
+```bash
+# 用户说："商品prod_123补货100个"（在现有基础上增加100）
+commerce inventory adjust --id prod_123 --quantity 100
+```
+
+### 预留库存
+```bash
+# 用户说："为订单预留5个商品"
+commerce inventory reserve \
+  --id prod_123 \
+  --quantity 5
+```
+
+### 查看库存历史
+```bash
+# 用户说："查看商品prod_123的库存变更记录"
+commerce inventory history --id prod_123
+```
+
+## 变体库存管理（重要）
+
+**这是最常见的库存管理错误，务必理解！**
+
+### 核心规则
+
+| 产品类型 | 库存设置方式 | 说明 |
+|---------|-------------|------|
+| **有变体的产品** | 必须设置**变体库存** | 产品库存 = 所有变体库存之和（自动计算） |
+| **无变体的产品** | 直接设置**产品库存** | 正常更新即可 |
+
+### 正确的库存更新流程
+
+```bash
+# 1. 先查看产品是否有变体
+commerce product get --id prod_123
+
+# 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 set --id prod_123 --quantity 30
+```
+
+### ❌ 常见错误
+
+```bash
+# 错误1：直接设置有变体产品的产品级库存（会被 API 拒绝）
+commerce inventory set --id prod_123 --quantity 30
+
+# 错误2：想设为18，却用了 adjust（结果是当前值+18）
+commerce inventory adjust --id var_abc --quantity 18  # ❌ 增加了18，不是设为18
+```
+
+### ✅ 正确做法
+
+```bash
+# 用户说："把所有变体库存都设置为10"
+
+# 1. 先获取产品和变体信息
+commerce product get --id prod_123
+
+# 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）
+```
+
+### 批量设置变体库存
+
+当用户说"所有变体库存设置为 N"时：
+
+1. 先用 `commerce product get --id XX` 获取变体列表
+2. 遍历每个变体，用 `commerce inventory set --id <variant_id> --quantity N` 设置
+3. 确认更新成功后，产品总库存会自动计算
+
+## 重要提示
+
+- **`inventory set`** 设为目标值，**`inventory adjust`** 增减库存 — 务必区分
+- **有变体的产品必须设置变体库存，不能直接设置产品库存**（会被 API 拒绝）
+- 库存变更会自动记录历史
+- 预留库存不会减少可用库存数量
+- 低库存阈值可自定义（默认5）
+- 使用 `--help` 查看命令详细参数