@optima-chat/optima-agent 0.5.0 → 0.5.2

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
@@ -14,11 +14,10 @@ description: Inventory management and stock monitoring. Track stock levels, upda
 | 用户需求 | 推荐命令 | 关键注意点 |
 |---------|---------|-----------|
 | 查看低库存 | `inventory low-stock --threshold 10` | 阈值根据品类和销售速度设定 |
-| 补货操作 | `inventory update --quantity XX --reason` | 必须填写原因，便于追踪 |
-| 预留库存 | `inventory reserve --order-id XX` | 订单创建时立即预留，避免超卖 |
-| 释放预留 | `inventory release --order-id XX` | 订单取消或支付超时时释放 |
-| 查看历史 | `inventory history --product-id XX` | 分析库存变化趋势，优化补货策略 |
-| 盘点调整 | `inventory update --reason "盘点调整"` | 账实不符时手动调整，记录差异原因 |
+| 补货操作 | `inventory update --id XX --quantity YY` | 使用 product list 获取商品 ID |
+| 预留库存 | `inventory reserve --id XX --quantity YY` | 订单创建时立即预留，避免超卖 |
+| 查看历史 | `inventory history --id XX` | 分析库存变化趋势，优化补货策略 |
+| 盘点调整 | `inventory update --id XX --quantity YY` | 账实不符时手动调整 |
 
 ### 1. 查看低库存预警
 
@@ -35,15 +34,12 @@ commerce inventory low-stock --threshold 5
 
 ```bash
 # 用户说："商品prod_123补货100个"
-commerce inventory update \
-  --id prod_123 \
-  --quantity 100 \
-  --reason "定期补货"
+commerce inventory update --id prod_123 --quantity 100
 
 # 根据销售数据决定补货量
-commerce inventory update --id prod_hot --quantity 500 --reason "畅销品大量补货"
-commerce inventory update --id prod_normal --quantity 100 --reason "常规补货"
-commerce inventory update --id prod_slow --quantity 20 --reason "滞销品少量补货"
+commerce inventory update --id prod_hot --quantity 500
+commerce inventory update --id prod_normal --quantity 100
+commerce inventory update --id prod_slow --quantity 20
 ```
 
 ### 3. 预留库存
@@ -52,16 +48,11 @@ commerce inventory update --id prod_slow --quantity 20 --reason "滞销品少量
 
 ```bash
 # 用户说："为订单预留5个商品"
-commerce inventory reserve \
-  --product-id prod_123 \
-  --quantity 5 \
-  --order-id order_456
+commerce inventory reserve --id prod_123 --quantity 5
 ```
 
 **库存预留机制**：
 - **订单创建时预留** - 避免超卖，保证订单可履行
-- **支付超时释放** - 未支付订单15分钟后自动释放预留
-- **取消订单释放** - 订单取消后立即释放预留
 - **发货后扣减** - 商品发货后从可用库存扣减
 
 ### 4. 盘点调整
@@ -70,13 +61,7 @@ commerce inventory reserve \
 
 ```bash
 # 实际库存95，账面库存100，差异5个
-commerce inventory update \
-  --id prod_123 \
-  --quantity 95 \
-  --reason "盘点调整：实际库存95，账面100，差异-5（仓库损耗）"
-
-# 验证更新
-commerce inventory get --id prod_123
+commerce inventory update --id prod_123 --quantity 95
 ```
 
 ### 5. 处理超卖
@@ -103,9 +88,7 @@ commerce inventory get --id prod_123
 
 ```bash
 # 用户说："查看商品prod_123的库存变更记录"
-commerce inventory history \
-  --product-id prod_123 \
-  --limit 20
+commerce inventory history --id prod_123
 ```
 
 ## 卓越标准
@@ -128,8 +111,8 @@ commerce inventory history \
 1. **查看低库存** - 每日 `commerce inventory low-stock --threshold 10`
 2. **分析销售趋势** - 结合订单数据判断补货优先级
 3. **制定补货计划** - 畅销品加大补货量，滞销品谨慎补货
-4. **执行补货** - `commerce inventory update --id XX --quantity YY --reason "补货"`
-5. **验证更新** - `commerce inventory get --id XX` 确认库存正确
+4. **执行补货** - `commerce inventory update --id XX --quantity YY`
+5. **验证更新** - `commerce product get --id XX` 确认库存正确
 6. **定期盘点** - 每月实地盘点，调整账面库存
 
 ## 常见问题
@@ -140,7 +123,7 @@ commerce inventory history \
 ```bash
 # 不分析就盲目补货，可能造成库存积压
 for product_id in $(commerce inventory low-stock --json | jq -r '.[].id'); do
-  commerce inventory update --id $product_id --quantity 100 --reason "批量补货"
+  commerce inventory update --id $product_id --quantity 100
 done
 ```
 
@@ -150,9 +133,9 @@ done
 commerce inventory low-stock --threshold 10
 
 # 根据销售数据决定补货量
-commerce inventory update --id prod_hot --quantity 500 --reason "畅销品大量补货"
-commerce inventory update --id prod_normal --quantity 100 --reason "常规补货"
-commerce inventory update --id prod_slow --quantity 20 --reason "滞销品少量补货"
+commerce inventory update --id prod_hot --quantity 500      # 畅销品大量补货
+commerce inventory update --id prod_normal --quantity 100   # 常规补货
+commerce inventory update --id prod_slow --quantity 20      # 滞销品少量补货
 ```
 
 ### ❌ 问题2：库存差异超过5%未深入调查
@@ -165,11 +148,8 @@ commerce inventory update --id prod_slow --quantity 20 --reason "滞销品少量
 3. 差异率 > 5%需要深入调查根本原因
 
 ```bash
-# 调整库存并详细记录原因
-commerce inventory update \
-  --id prod_123 \
-  --quantity 95 \
-  --reason "盘点调整：实际95，账面100，差异-5（仓库损耗，需检查存储条件）"
+# 调整库存（记录差异原因：实际95，账面100，差异-5，仓库损耗）
+commerce inventory update --id prod_123 --quantity 95
 ```
 
 ### ❌ 问题3：滞销商品长期占用库存
@@ -184,24 +164,17 @@ commerce inventory update \
 
 ```bash
 # 查看库存历史判断是否滞销
-commerce inventory history --product-id prod_slow --limit 50
+commerce inventory history --id prod_slow
 ```
 
-### ❌ 问题4：不记录库存变更原因
+### ❌ 问题4：不分析销售数据就补货
 
-**错误做法**：
-```bash
-# 缺少原因，无法追溯
-commerce inventory update --id prod_123 --quantity 100
-```
+**错误做法**：直接设置固定数量，不考虑销售速度
 
 **✅ 正确做法**：
 ```bash
-# 必须记录原因
-commerce inventory update \
-  --id prod_123 \
-  --quantity 100 \
-  --reason "定期补货：上周销量50，预计2周销量"
+# 根据销售数据决定补货量（如上周销量50，预计2周销量）
+commerce inventory update --id prod_123 --quantity 100
 ```
 
 ### ❌ 问题5：超卖后处理不当
@@ -223,23 +196,16 @@ commerce inventory update \
 
 当用户说：
 - "查看库存低于10的商品" → `commerce inventory low-stock --threshold 10`
-- "商品XX补货50个" → `commerce inventory update --id XX --quantity 50 --reason "补货"`
-- "预留库存" → `commerce inventory reserve --product-id XX --quantity YY`
-- "查看库存历史" → `commerce inventory history --product-id XX`
-- "查看所有商品库存" → `commerce inventory list`
+- "商品XX补货50个" → `commerce inventory update --id XX --quantity 50`
+- "预留库存" → `commerce inventory reserve --id XX --quantity YY`
+- "查看库存历史" → `commerce inventory history --id XX`
 
 ### 核心功能
 
-**库存查询**:
-- `commerce inventory list` - 查看所有商品库存
-- `commerce inventory get` - 查看单个商品库存
 - `commerce inventory low-stock` - 查看低库存商品
-- `commerce inventory history` - 查看库存变更历史
-
-**库存更新**:
 - `commerce inventory update` - 更新库存数量
+- `commerce inventory history` - 查看库存变更历史
 - `commerce inventory reserve` - 预留库存
-- `commerce inventory release` - 释放预留库存
 
 ## 详细示例
 
@@ -252,40 +218,85 @@ commerce inventory low-stock --threshold 5
 ### 补货操作
 ```bash
 # 用户说："商品prod_123补货100个"
-commerce inventory update \
-  --id prod_123 \
-  --quantity 100 \
-  --reason "定期补货"
+commerce inventory update --id prod_123 --quantity 100
 ```
 
 ### 预留库存
 ```bash
 # 用户说："为订单预留5个商品"
 commerce inventory reserve \
-  --product-id prod_123 \
-  --quantity 5 \
-  --order-id order_456
+  --id prod_123 \
+  --quantity 5
 ```
 
 ### 查看库存历史
 ```bash
 # 用户说："查看商品prod_123的库存变更记录"
-commerce inventory history \
-  --product-id prod_123 \
-  --limit 20
+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 list --limit 100
+# 错误：直接更新有变体产品的产品级库存
+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. 确认更新成功后，产品总库存会自动计算
+
 ## 重要提示
 
 - 库存变更会自动记录历史
 - 预留库存不会减少可用库存数量
-- 更新库存时建议添加 `--reason` 说明原因
-- 低库存阈值可以自定义
-- 支持批量库存更新（通过脚本循环调用）
+- 低库存阈值可自定义（默认5）
 - 使用 `--help` 查看命令详细参数
+- **有变体的产品必须更新变体库存，不能直接更新产品库存**

package/.claude/skills/markdown-pdf/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: markdown-pdf
+description: "Markdown to PDF conversion. Use when user needs to: export documents (导出成PDF/生成PDF/转换成PDF), create reports (保存为PDF), save as PDF (Export to PDF)."
+---
+
+# Markdown → PDF 转换
+
+## 标准命令格式
+
+```bash
+md-to-pdf <input.md> \
+  --launch-options '{"args":["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage"]}' \
+  --pdf-options '{"format":"A4","margin":"20mm","printBackground":true}'
+```
+
+**关键点**：
+- 输出文件默认生成为 `<input>.pdf`（与输入同名，在同一目录）
+- 支持 glob 模式批量处理：`md-to-pdf ./**/*.md`
+- `--launch-options` 中的参数**必须包含**（Docker 容器要求）
+
+## 常见场景
+
+### 单个文档转换
+
+```bash
+md-to-pdf report.md \
+  --launch-options '{"args":["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage"]}' \
+  --pdf-options '{"format":"A4","margin":"20mm","printBackground":true}'
+
+# 输出：report.pdf（同目录）
+```
+
+### 指定输出路径（使用 stdin/stdout）
+
+```bash
+cat document.md | md-to-pdf \
+  --launch-options '{"args":["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage"]}' \
+  --pdf-options '{"format":"A4","margin":"20mm","printBackground":true}' \
+  > /home/aiuser/project/final.pdf
+```
+
+### 批量转换（使用 glob）
+
+```bash
+# 转换当前目录所有 Markdown 文件
+md-to-pdf *.md \
+  --launch-options '{"args":["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage"]}' \
+  --pdf-options '{"format":"A4","margin":"20mm","printBackground":true}'
+
+# 递归转换所有子目录的 Markdown 文件
+md-to-pdf ./**/*.md \
+  --launch-options '{"args":["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage"]}' \
+  --pdf-options '{"format":"A4","margin":"20mm","printBackground":true}'
+```
+
+## 参数选项
+
+### --pdf-options 常用配置
+
+| 参数 | 可选值 | 说明 |
+|------|--------|------|
+| format | A4, Letter, A3, Legal | 纸张大小 |
+| margin | "20mm" 或 {"top":"20mm",...} | 页边距（支持 CSS 简写或对象） |
+| printBackground | true/false | 打印背景色（推荐 true） |
+| landscape | true/false | 横向/纵向 |
+
+## 重要提示
+
+- ⚠️ **必须使用** `--no-sandbox` 等参数（Docker 环境要求）
+- ✅ 已安装中文字体（fonts-noto-cjk），支持完美渲染中文
+- ✅ 已安装 Emoji 字体（fonts-noto-color-emoji）
+- 📝 支持完整 Markdown 语法（表格、代码块、Emoji）

package/.claude/skills/merchant/SKILL.md

@@ -1,101 +1,104 @@
 ---
 name: merchant
-description: "店铺管理和信息查询。使用场景：查看店铺信息(merchant info/店铺信息/商户信息)、更新店铺配置(update merchant/更新店铺)、查看店铺设置。使用 commerce merchant 命令。"
+description: "店铺基础信息管理。使用场景：查看店铺信息、更新店铺名称/描述/联系方式/发货地址。注意：运费设置用 shipping skill。"
 ---
 
 # 店铺管理
 
-## 标准操作
+## 典型场景
 
-### 查看店铺信息
-```bash
-commerce merchant info
-```
-返回店铺的完整信息：
-- 店铺名称、标识、描述
-- 默认货币、状态
-- 联系信息、发货地址
-- 创建和更新时间
+| 用户说 | 命令 |
+|--------|------|
+| "查看店铺信息" / "我的店铺" | `commerce merchant info` |
+| "修改店铺名称" / "更新店铺描述" | `commerce merchant update --name/--description` |
+| "设置联系方式" | `commerce merchant update --contact-*` |
+| "更新发货地址" | `commerce merchant update --origin-*` |
 
-### 更新店铺信息
-```bash
-commerce merchant update --name "新店铺名" --description "描述" --currency USD
-```
+## 不在此模块（重要）
+
+| 用户说 | 正确位置 |
+|--------|----------|
+| "运费设置" / "运费模式" / "运费区域" | **shipping skill**：`commerce shipping get-mode` |
+| "Easyship" / "快递公司" | **shipping skill**：`commerce easyship couriers` |
+| "Stripe/支付设置" | `commerce stripe status` |
+| "首页设置" | **homepage skill** |
 
-可更新的字段：
-- `--name`: 店铺名称
-- `--slug`: 店铺标识（URL 友好）
-- `--description`: 店铺描述
-- `--currency`: 默认货币（USD, CNY, EUR 等）
-- `--contact-name`: 联系人姓名
-- `--contact-phone`: 联系电话
-- `--contact-email`: 联系邮箱
-- `--company`: 公司名称
-- `--address-*`: 发货地址字段
+---
 
-## 完整命令列表
+## 查看店铺信息
 
 ```bash
-# 查看店铺信息
 commerce merchant info
+```
 
-# 更新基本信息
-commerce merchant update --name "我的店铺" --description "这是一个很棒的店铺"
-
-# 更新联系信息
-commerce merchant update --contact-name "张三" --contact-phone "1234567890" --contact-email "contact@example.com"
-
-# 更新发货地址
-commerce merchant update --address-country "CN" --address-city "深圳" --address-postal-code "518000"
+返回：店铺名称、描述、Logo、货币、联系信息、发货地址
 
-# 更新多个字段
-commerce merchant update --name "新店铺" --currency "CNY" --company "我的公司"
-```
+**注意**：此命令不返回运费设置，运费相关请用 `commerce shipping get-mode`
 
-## 工作流示例
+---
 
-### 示例 1：查看店铺基本信息
-用户："查看我的店铺信息"
+## 更新店铺信息
 
 ```bash
-commerce merchant info
+commerce merchant update [选项]
 ```
 
-展示表格格式的店铺信息，包括：
-- 店铺名称、标识、描述
-- 货币、状态、创建时间
-- 联系信息（如有）
-- 发货地址（如有）
+### 基础信息
+| 选项 | 说明 |
+|------|------|
+| `--name` | 店铺名称 |
+| `--slug` | 店铺标识（影响 URL） |
+| `--description` | 店铺描述 |
+| `--default-currency` | 默认货币（USD, CNY 等） |
+
+### 联系方式
+| 选项 | 说明 |
+|------|------|
+| `--contact-name` | 联系人 |
+| `--contact-phone` | 联系电话 |
+| `--contact-email` | 联系邮箱 |
+| `--company-name` | 公司名称 |
+
+### 发货地址
+| 选项 | 说明 |
+|------|------|
+| `--origin-country-alpha2` | 国家代码（CN, US 等） |
+| `--origin-city` | 城市 |
+| `--origin-postal-code` | 邮编 |
+| `--origin-line-1` | 地址行1 |
+| `--origin-line-2` | 地址行2 |
+| `--origin-state` | 省/州 |
+
+---
 
-### 示例 2：完善店铺信息
-用户："帮我设置店铺的联系方式和地址"
+## 示例
 
 ```bash
+# 更新名称和描述
+commerce merchant update --name "我的小店" --description "精选好物"
+
+# 更新联系方式
 commerce merchant update \
   --contact-name "张三" \
   --contact-phone "13800138000" \
-  --contact-email "shop@example.com" \
-  --address-country "CN" \
-  --address-city "深圳" \
-  --address-postal-code "518000"
-```
+  --contact-email "shop@example.com"
 
-### 示例 3：修改店铺名称
-用户："把店铺名改成'全球精品小店'"
-
-```bash
-commerce merchant update --name "全球精品小店"
+# 更新发货地址
+commerce merchant update \
+  --origin-country-alpha2 CN \
+  --origin-city 深圳 \
+  --origin-postal-code 518000 \
+  --origin-line-1 "科技园路1号" \
+  --origin-state 广东
 ```
 
-## 注意事项
+---
+
+## 命令参考
 
-- 店铺标识（slug）修改后会影响店铺 URL
-- 货币修改不会影响已创建的商品价格
-- 联系信息和发货地址建议完整填写
-- 更新后建议用 `commerce merchant info` 验证
+- `commerce merchant info` - 查看店铺信息
+- `commerce merchant update` - 更新店铺信息
 
-## 相关命令
+## 不确定用什么命令？
 
-- 查看商品：`commerce product list`
-- 查看订单：`commerce order list`
-- 查看集合：`commerce collection list`
+运行 `commerce --help` 查看所有模块，或 `commerce merchant --help` 查看子命令。