@optima-chat/optima-agent 0.5.0 → 0.5.2

package/.claude/skills/order/SKILL.md

@@ -11,10 +11,10 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 
 当用户说：
 - "查看待发货订单" → `commerce order list --status paid`
-- "订单XX发货" → `commerce order ship --id XX --tracking YY --carrier ZZ`
+- "订单XX发货" → 先查订单详情，根据 shipping_mode_used 决定发货方式（见下方流程）
+- "查询订单物流" / "运单标签好了吗" → `commerce order tracking --id XX`
 - "取消订单XX" → `commerce order cancel --id XX --yes`
 - "标记订单已送达" → `commerce order mark-delivered --id XX`
-- "查询运费" → `commerce shipping calculate --country XX --weight YY`
 - "处理退款" → `commerce refund create --order-id XX --amount YY`
 
 ### 场景决策表
@@ -25,17 +25,182 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 | 批量发货 | 循环 `order ship` | 必须有真实tracking号，避免虚假发货 |
 | 取消订单 | `order cancel --yes` | 检查是否已发货，避免错误取消 |
 | 处理退款 | `refund create` → `refund approve` | 先创建后审批，保留审计记录 |
-| 运费查询 | `shipping calculate` | 提供准确重量和邮编，避免运费纠纷 |
-| 物流异常 | `shipping track` → `shipping update-status` | 主动更新状态，及时通知客户 |
+| 物流异常 | `order tracking` → `order update-shipping-status` | 主动更新状态，及时通知客户 |
 
 ### 标准订单履行流程
 1. **查看待发货** - `commerce order list --status paid` 按时间升序
 2. **验证订单** - 检查库存、地址、特殊要求
 3. **批量打包** - 准备商品、包装材料、打印面单
 4. **标记发货** - 循环 `commerce order ship --id XX --tracking YY --carrier ZZ`
-5. **物流跟踪** - 定期 `commerce shipping track` 监控异常
+5. **物流跟踪** - 定期 `commerce order tracking` 或 `commerce easyship track` 监控异常
 6. **确认送达** - 签收后 `commerce order mark-delivered --id XX`
 
+### 发货流程详解（重要）
+
+订单发货需要根据 `shipping_mode_used` 字段选择正确的发货方式。
+
+#### 运费模式说明
+
+| shipping_mode_used | 含义 | 发货方式 |
+|--------------------|------|----------|
+| `easyship` | 买家选择了 Easyship 快递 | 可选 Easyship 自动发货 或 手动发货 |
+| `fixed` | 买家使用固定运费 | 只能手动发货 |
+| 空/null | 历史订单 | 只能手动发货 |
+
+#### 发货决策规则（必须严格遵守）
+
+当用户说"订单XXX发货"时，按以下步骤执行：
+
+**步骤1**：执行 `commerce order get --id XXX` 获取订单详情
+
+**步骤2**：在返回结果中找到 `shipping_mode_used` 字段的值
+
+**步骤3**：根据字段值决定下一步操作：
+
+- **如果 `shipping_mode_used = "easyship"`**：
+  1. **必须**使用 AskUserQuestion 工具询问用户
+  2. 提供两个选项让用户选择
+  3. **禁止**直接询问运单号
+  4. 等待用户选择后再执行对应命令
+
+- **如果 `shipping_mode_used = "fixed"` 或字段为空**：
+  1. 直接询问用户提供运单号和快递公司名称
+  2. 收集信息后执行手动发货命令
+
+#### Easyship 自动发货
+
+**适用场景**：`shipping_mode_used = "easyship"` 且用户选择使用 Easyship
+
+**命令**：
+```bash
+# 使用买家选择的快递（推荐）
+commerce order ship --id <order-id> --easyship
+
+# 或指定其他 Easyship 支持的快递
+commerce order ship --id <order-id> --easyship --courier-id <courier-id>
+```
+
+**返回结果包含**：
+- `tracking_number`: 自动生成的运单号
+- `tracking_url`: 快递跟踪链接
+- `label_url`: 运单标签下载链接（可能为空）
+- `label_state`: 标签状态
+- `carrier`: 快递公司名称
+
+**运单标签处理（重要）**：
+
+运单标签是用户必须打印并贴在包裹上的快递单。Easyship 生成标签需要几秒到几分钟。
+
+**发货后根据 label_state 处理**：
+
+| label_state | 含义 | 处理方式 |
+|-------------|------|----------|
+| `generated` / `printed` | 标签已生成 | 提供 `label_url` 让用户下载打印 |
+| `pending` / `generating` | 标签生成中 | 告知用户「标签正在生成，稍后可以让我帮你查询」 |
+| `failed` / `technical_failed` | 生成失败 | 告知用户需要检查 EasyShip 后台或重新发货 |
+
+**查询标签状态**：
+```bash
+commerce order tracking --id <order-id>
+```
+
+**查看可用快递**：
+```bash
+commerce easyship couriers
+```
+
+#### 手动发货
+
+**适用场景**：
+- `shipping_mode_used = "fixed"` 或为空
+- 或用户选择不使用 Easyship
+
+**命令**：
+```bash
+commerce order ship --id <order-id> \
+  --tracking <运单号> \
+  --carrier <快递公司名称> \
+  --tracking-url <跟踪链接>  # 可选
+```
+
+**示例**：
+```bash
+# 顺丰快递
+commerce order ship --id order_123 \
+  --tracking SF1234567890 \
+  --carrier "顺丰速运"
+
+# DHL（带跟踪链接）
+commerce order ship --id order_123 \
+  --tracking DHL9876543210 \
+  --carrier "DHL Express" \
+  --tracking-url "https://www.dhl.com/track?num=DHL9876543210"
+```
+
+#### 物流状态更新（手动发货后）
+
+```bash
+# 更新为运输中
+commerce order update-shipping-status --id <order-id> --status in_transit
+
+# 更新为派送中
+commerce order update-shipping-status --id <order-id> --status out_for_delivery
+
+# 标记已送达
+commerce order mark-delivered --id <order-id>
+```
+
+#### 发货场景示例对话
+
+**场景1：Easyship 订单**
+```
+用户：订单 order_abc 发货
+
+助手：[执行 Bash: commerce order get --id order_abc]
+      [发现 shipping_mode_used = "easyship"]
+      [使用 AskUserQuestion 工具]
+
+AskUserQuestion:
+  question: "该订单使用 Easyship 运费模式，请选择发货方式"
+  options:
+    - label: "Easyship 自动发货（推荐）"
+      description: "自动生成运单号和标签，使用买家选择的快递"
+    - label: "手动填写运单号"
+      description: "使用其他快递公司，需要提供运单号"
+
+用户：[选择 Easyship 自动发货]
+
+助手：[执行 Bash: commerce order ship --id order_abc --easyship]
+      [检查返回结果中的 label_state]
+
+      [情况A：label_state = "generated"，有 label_url]
+      发货成功！运单号 ES123456789，快递公司 FedEx。
+      运单标签已生成，请下载打印后贴在包裹上：https://...
+
+      [情况B：label_state = "pending" 或 "generating"]
+      发货成功！运单号 ES123456789，快递公司 FedEx。
+      运单标签正在生成中，稍后可以让我帮你查询。
+
+用户：查一下标签好了没
+
+助手：[执行 Bash: commerce order tracking --id order_abc]
+      运单标签已生成，请下载打印后贴在包裹上：https://...
+```
+
+**场景2：固定运费订单**
+```
+用户：订单 order_xyz 发货
+
+助手：[执行 Bash: commerce order get --id order_xyz]
+      [发现 shipping_mode_used = "fixed"]
+      该订单使用固定运费，请提供运单号和快递公司名称。
+
+用户：顺丰，单号 SF123456
+
+助手：[执行 Bash: commerce order ship --id order_xyz --tracking SF123456 --carrier 顺丰速运]
+      发货成功！
+```
+
 ### 退款处理流程
 1. **创建退款** - `commerce refund create` 填写详细原因
 2. **审核评估** - 检查商品状态、退货凭证、历史记录
@@ -116,6 +281,7 @@ commerce order ship --id order_789 --tracking DHL123458 --carrier DHL
 - `commerce order list` - 查看订单列表
 - `commerce order get` - 查看订单详情
 - `commerce order ship` - 标记订单发货
+- `commerce order tracking` - 查询物流跟踪和标签状态
 - `commerce order cancel` - 取消订单
 - `commerce order complete` - 完成订单
 - `commerce order mark-delivered` - 标记已送达
@@ -127,10 +293,15 @@ commerce order ship --id order_789 --tracking DHL123458 --carrier DHL
 - `commerce refund approve` - 批准退款
 - `commerce refund reject` - 拒绝退款
 
-### 物流管理
-- `commerce shipping calculate` - 计算运费
-- `commerce shipping track` - 物流追踪
-- `commerce shipping update-status` - 更新物流状态
+### 物流状态
+- `commerce order tracking` - 查询物流跟踪和标签状态
+- `commerce order update-shipping-status` - 更新物流状态
+- `commerce easyship track` - 查询 Easyship 详细物流轨迹
+
+### Easyship 集成
+- `commerce easyship couriers` - 查看可用快递公司
+- `commerce easyship rates --order-id <id>` - 获取订单运费报价
+- `commerce easyship track --order-id <id>` - 跟踪 Easyship 运单
 
 ## 详细示例
 
@@ -142,7 +313,14 @@ commerce order list --status paid --limit 50
 
 ### 订单发货
 ```bash
-# 用户说："订单order_123发货，快递单号DHL123456，承运商DHL"
+# 步骤1：先获取订单信息，检查 shipping_mode_used
+commerce order get --id order_123
+
+# 步骤2a：如果 shipping_mode_used = "easyship"，询问用户选择后
+# 用户选择 Easyship 自动发货
+commerce order ship --id order_123 --easyship
+
+# 步骤2b：如果用户选择手动发货，或 shipping_mode_used = "fixed"
 commerce order ship \
   --id order_123 \
   --tracking DHL123456 \
@@ -164,15 +342,6 @@ commerce order cancel \
 commerce order mark-delivered --id order_789
 ```
 
-### 计算运费
-```bash
-# 用户说："计算寄到美国纽约10001的运费，重量0.5kg"
-commerce shipping calculate \
-  --country US \
-  --postal-code 10001 \
-  --weight 0.5
-```
-
 ### 处理退款
 ```bash
 # 用户说："订单order_123要退款150美元"
@@ -187,8 +356,11 @@ commerce refund approve --id refund_456
 
 ### 物流追踪
 ```bash
-# 用户说："查询快递单号DHL123456的物流信息"
-commerce shipping track --tracking-number DHL123456
+# 用户说："查询订单order_123的物流信息"
+commerce order tracking --id order_123
+
+# 或查询 Easyship 详细轨迹
+commerce easyship track --order-id order_123
 ```
 
 ## 重要提示

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
@@ -58,9 +58,9 @@ done
 # 1. 查找目标商品
 commerce product list --query "T恤" --limit 50
 
-# 2. 批量更新价格和促销标签
-commerce product update --id prod_123 --price 79 --tags "featured,sale"
-commerce product update --id prod_456 --price 79 --tags "featured,sale"
+# 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：商品图片更新
@@ -73,6 +73,18 @@ commerce upload image --path ./new-photo.jpg  # 获得 media_new
 commerce product add-images --id prod_123 --media-id media_new
 ```
 
+### 场景6：创建促销商品
+**任务**: 创建带折扣显示的商品（显示划线价）
+```bash
+# 创建促销商品：售价79，原价99（显示划线价）
+commerce product create \
+  --title "夏日特惠T恤" \
+  --price 79 \
+  --original-price 99 \
+  --stock 100 \
+  --tags "sale"
+```
+
 ### 场景决策表
 
 | 用户需求 | 推荐命令 | 关键注意点 |
@@ -81,8 +93,24 @@ commerce product add-images --id prod_123 --media-id media_new
 | 多规格商品 | `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`，告诉用户"商品已删除"。
 
 ## 卓越标准
 
@@ -184,10 +212,14 @@ commerce product create --title "T恤" --price 99 --stock 50  # 确保真实有5
 
 当用户说：
 - "创建XX商品，价格YY" → `commerce product create --title XX --price YY`
+- "创建XX商品，售价YY，原价ZZ" → `commerce product create --title XX --price YY --original-price ZZ`
+- "创建促销商品，价格79，划线价99" → `commerce product create --title XX --price 79 --original-price 99`
 - "上传商品图片" → `commerce upload image --path ./photo.jpg`
 - "添加商品变体" → `commerce variant create --product-id XX --sku YY`
 - "更新商品价格" → `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`
 - "查看所有商品" → `commerce product list`
 
 ### 核心功能
@@ -215,11 +247,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：上传商品图片
@@ -297,11 +336,17 @@ commerce product get --id prod_123
 
 ## 重要提示
 
+- **库存管理请使用 inventory skill** - 如果用户要求更新库存、设置库存数量、补货等，请加载 `/inventory` skill。特别是有变体的产品，必须通过 inventory skill 更新变体库存，不能直接更新产品库存。
+- **商品描述支持 Markdown 格式**，可以使用标题、列表、加粗、链接等排版
 - 所有命令默认 JSON 输出，便于 AI 解析
 - 图片需要先上传获取 `media_id`，再关联到商品
 - 变体的 `attributes` 使用 JSON 格式
 - 标签使用逗号分隔的字符串
-- 支持的图片格式：JPG, PNG, WebP
+- 支持的图片格式：JPG, PNG, WebP（最大 10MB）
 - 使用 `--help` 查看命令详细参数
 - 删除商品会同时删除所有变体和图片关联
 - 价格单位默认为美元（USD），可通过后台配置修改
+- **重量单位：kg**（如 0.5 表示 500g）
+- **尺寸单位：cm**（length/width/height）
+- 集合 slug 必须唯一，用于 URL，使用英文和连字符
+- 集合封面支持三种方式：`--media-id`（推荐）、`--url`、`--path`

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

@@ -0,0 +1,200 @@
+---
+name: product-page
+description: 商品详情页配置。自定义商品详情页的可折叠区块内容（如护理说明、退货政策）。当用户需要编辑商品页信息区块、隐藏某些区块、或添加自定义区块时使用。
+---
+
+## 概念
+
+Product Page Section（商品页区块）是商品详情页上的信息模块，采用三层继承机制：
+
+```
+System（系统默认）
+    ↓ 可被覆盖
+Merchant（商户级自定义）
+    ↓ 可被覆盖
+Product（商品级覆盖）
+```
+
+- **System**：系统预设的区块（如退货政策、发货说明）
+- **Merchant**：商户对系统区块的自定义（适用于所有商品）
+- **Product**：单个商品对上层区块的覆盖（仅影响该商品）
+
+每层都可以执行三种操作：
+- `override`：覆盖上层的内容
+- `new`：创建全新的区块
+- `hidden`：隐藏某个区块
+
+## 结构
+
+```
+ProductPageSection
+├── 基本信息
+│   ├── handle: 区块标识符（唯一）
+│   ├── operation_type: override | new | hidden
+│   ├── type: collapsible（可折叠）| static（静态）
+│   └── position: 显示位置（1-10）
+│
+├── 内容
+│   ├── content: Markdown 内容（支持模板变量）
+│   └── tab_group: Tab 分组（可选）
+│
+└── 翻译
+    └── translations: 多语言翻译
+```
+
+### 系统默认区块
+
+| handle | 说明 | 默认类型 |
+|--------|------|----------|
+| `highlights` | 产品亮点 | static |
+| `details` | 产品详情 | collapsible |
+| `guarantee` | 品质保证 | collapsible |
+| `care` | 护理说明 | collapsible |
+| `shipping-policies` | 发货政策 | collapsible |
+| `return` | 退换政策 | collapsible |
+| `eco-friendly` | 环保说明 | collapsible |
+
+### 模板变量
+
+content 支持模板变量，在前端渲染时自动替换：
+
+| 变量 | 说明 |
+|------|------|
+| `{{product.name}}` | 商品名称 |
+| `{{product.description}}` | 商品描述 |
+| `{{variant.sku}}` | 当前变体 SKU |
+| `{{merchant.name}}` | 店铺名称 |
+
+## 典型场景
+
+当用户说：
+- "查看所有区块" → `commerce product-page list --resolved`
+- "覆盖护理说明" → `commerce product-page create --handle care --operation-type override ...`
+- "隐藏环保说明" → `commerce product-page hide --handle eco-friendly`
+- "添加品牌故事区块" → `commerce product-page create --handle brand-story --operation-type new ...`
+- "调整区块顺序" → `commerce product-page reorder --sections '[{"handle":"h1","position":1},{"handle":"h2","position":2}]'`
+- "给某商品单独设置" → `commerce product-page product create --product-handle xxx ...`
+
+## 命令参考
+
+### 商户级命令（影响所有商品）
+
+- `commerce product-page list` - 列出商户自定义
+- `commerce product-page list --resolved` - 列出合并后的完整视图（推荐）
+- `commerce product-page create` - 创建/覆盖区块
+- `commerce product-page update --handle <handle>` - 更新区块
+- `commerce product-page delete --handle <handle> --yes` - 删除自定义
+- `commerce product-page hide --handle <handle>` - 隐藏区块（快捷方式）
+- `commerce product-page reorder --sections <json>` - 重新排序（JSON 格式：`[{"handle":"xx","position":1}]`）
+
+### 商品级命令（仅影响单个商品）
+
+- `commerce product-page product list --product-handle <handle>` - 列出商品级覆盖
+- `commerce product-page product list --product-handle <handle> --resolved` - 列出合并视图
+- `commerce product-page product create --product-handle <handle> ...` - 创建商品级覆盖
+- `commerce product-page product update --product-handle <handle> --handle <section> ...` - 更新
+- `commerce product-page product delete --product-handle <handle> --handle <section> --yes` - 删除
+- `commerce product-page product hide --product-handle <handle> --handle <section>` - 隐藏
+
+### 翻译命令
+
+- `commerce product-page translation list --handle <handle>` - 查看区块翻译
+- `commerce product-page translation set --handle <handle> --lang <code>` - 设置翻译
+- `commerce product-page translation delete --handle <handle> --lang <code> --yes` - 删除翻译
+
+## 典型操作示例
+
+### 查看所有区块
+
+```bash
+# 查看合并后的完整视图（System + Merchant）
+commerce product-page list --resolved
+```
+
+### 覆盖系统默认区块
+
+```bash
+# 覆盖护理说明内容
+commerce product-page create \
+  --handle care \
+  --operation-type override \
+  --type collapsible \
+  --position 4 \
+  --content "## 洗涤说明\n\n- 可机洗，30°C\n- 请勿漂白\n- 低温烘干"
+```
+
+### 隐藏某个区块
+
+```bash
+# 快捷方式：隐藏环保说明区块
+commerce product-page hide --handle eco-friendly
+
+# 完整方式
+commerce product-page create --handle eco-friendly --operation-type hidden
+```
+
+### 创建自定义区块
+
+```bash
+# 添加品牌故事区块
+commerce product-page create \
+  --handle brand-story \
+  --operation-type new \
+  --type collapsible \
+  --position 8 \
+  --content "## 关于 {{merchant.name}}\n\n创立于2020年..."
+```
+
+### 使用 Tab 分组
+
+```bash
+# 创建属于同一 Tab 组的多个区块
+commerce product-page create \
+  --handle ingredients \
+  --operation-type new \
+  --type collapsible \
+  --position 5 \
+  --content "## 成分\n\n100% 有机棉" \
+  --tab-group product-info
+
+commerce product-page create \
+  --handle materials \
+  --operation-type new \
+  --type collapsible \
+  --position 6 \
+  --content "## 材质\n\n天然环保材料" \
+  --tab-group product-info
+```
+
+### 为单个商品设置不同内容
+
+```bash
+# 给某商品的护理说明设置特殊内容
+commerce product-page product create \
+  --product-handle ceramic-cup-white \
+  --handle care \
+  --operation-type override \
+  --type collapsible \
+  --position 4 \
+  --content "## 陶瓷护理\n\n- 可用洗碗机\n- 避免剧烈温度变化"
+```
+
+### 添加翻译
+
+```bash
+# 为护理说明添加英文翻译
+commerce product-page translation set \
+  --handle care \
+  --lang en-US \
+  --title "Care Instructions" \
+  --content "## Washing Instructions\n\n- Machine wash, 30°C\n- Do not bleach"
+```
+
+## 注意事项
+
+- **--resolved 参数**：查看列表时建议使用 `--resolved`，显示完整的合并视图
+- **handle 唯一性**：同一层级内 handle 必须唯一
+- **隐藏 vs 删除**：`hide` 是标记隐藏，`delete` 是删除自定义（恢复为上层默认）
+- **position 冲突**：不同区块可以有相同 position，显示时按 position 排序
+- **内容格式**：content 支持 Markdown，可使用模板变量
+- **Tab 分组**：tab_group 相同的区块会在前端合并为标签页显示