@optima-chat/optima-agent 0.4.16 → 0.4.18

package/.claude/settings.local.json

@@ -40,7 +40,15 @@
       "Bash(git -C /Users/verypro/optima-agent log --oneline --all -- \".claude/\")",
       "Bash(wc:*)",
       "Bash(grep:*)",
-      "Bash(find:*)"
+      "Bash(find:*)",
+      "Bash(commerce collection --help:*)",
+      "Bash(commerce collection update --help:*)",
+      "Bash(commerce collection set-cover:*)",
+      "Bash(commerce collection get --help:*)",
+      "Bash(commerce collection list --help:*)",
+      "Bash(commerce collection create --help:*)",
+      "Bash(commerce collection remove-products:*)",
+      "Bash(commerce collection list-products:*)"
     ],
     "deny": [],
     "ask": []

package/.claude/skills/collection/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: collection
-description: 商品集合管理。创建、编辑集合，管理集合中的商品。当用户需要对商品进行分组、创建促销专区、管理商品分类时使用。
+description: 商品集合管理。创建、编辑集合，设置封面图，管理集合中的商品。当用户需要对商品进行分组、创建促销专区、管理商品分类、设置集合封面时使用。
 ---
 
 ## 概念
@@ -37,40 +37,47 @@ Collection
 当用户说：
 - "查看所有集合" / "集合列表" → `commerce collection list`
 - "创建集合 XX" → `commerce collection create --name "XX" --slug xx`
-- "查看集合详情" → `commerce collection get --slug xx`
-- "删除集合 XX" → `commerce collection delete --slug xx --yes`
-- "把商品加到集合" → `commerce collection add-products --slug xx --product-ids p1,p2`
-- "从集合移除商品" → `commerce collection remove-products --slug xx --product-ids p1`
-- "查看集合里有哪些商品" → `commerce collection list-products --slug xx`
+- "查看集合详情" → `commerce collection get --id xx`
+- "删除集合 XX" → `commerce collection delete --id xx --yes`
+- "把商品加到集合" → `commerce collection add-products --id xx --product-ids p1,p2`
+- "从集合移除商品" → `commerce collection remove-products --id xx --product-ids p1`
+- "查看集合里有哪些商品" → `commerce collection list-products --id xx`
+- "设置集合封面" / "给集合加封面图" → `commerce collection set-cover --id xx --path ./cover.jpg`
 
 ## 命令参考
 
 ### 集合 CRUD
 - `commerce collection list` - 列出所有集合
-- `commerce collection create` - 创建集合
-- `commerce collection get --slug <slug>` - 查看集合详情
-- `commerce collection update --slug <slug>` - 更新集合
-- `commerce collection delete --slug <slug> --yes` - 删除集合
-- `commerce collection set-cover --slug <slug> --media-id <id>` - 设置封面图
+- `commerce collection create --name <name> --slug <slug>` - 创建集合
+- `commerce collection get --id <id>` - 查看集合详情
+- `commerce collection update --id <id>` - 更新集合（支持 --name, --slug, --description 等）
+- `commerce collection delete --id <id> --yes` - 删除集合
+- `commerce collection set-cover --id <id>` - 设置封面图（支持 --media-id, --url, --path）
 
 ### 商品管理
-- `commerce collection add-products --slug <slug> --product-ids <ids>` - 添加商品
-- `commerce collection remove-products --slug <slug> --product-ids <ids>` - 移除商品
-- `commerce collection list-products --slug <slug>` - 列出集合中的商品
+- `commerce collection add-products --id <id> --product-ids <ids>` - 添加商品
+- `commerce collection remove-products --id <id> --product-ids <ids>` - 移除商品
+- `commerce collection list-products --id <id>` - 列出集合中的商品
 
 ## 创建集合示例
 
 ```bash
-# 创建促销集合
+# 创建促销集合（返回 id，用于后续操作）
 commerce collection create \
   --name "Summer Sale 2024" \
   --slug summer-sale-2024 \
   --description "Hot deals for summer"
+# 输出: { "id": "coll_xxx", ... }
 
-# 添加商品到集合
+# 添加商品到集合（使用返回的 id）
 commerce collection add-products \
-  --slug summer-sale-2024 \
+  --id coll_xxx \
   --product-ids prod_123,prod_456,prod_789
+
+# 设置封面图
+commerce collection set-cover \
+  --id coll_xxx \
+  --path ./summer-sale-cover.jpg
 ```
 
 ## 注意事项

package/.claude/skills/homepage/SKILL.md

@@ -16,8 +16,6 @@ Homepage（首页）是店铺的入口页面，由多个 Section（区块）组
 - `collection_products` 区块：展示某个集合的商品（引用单个 collection slug）
 - `featured` 区块：可推荐某个集合（target_type=collection）
 
-→ 参考 [Collection Skill](../collection/SKILL.md) 了解集合管理
-
 ## 结构
 
 ```

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

@@ -11,7 +11,7 @@ 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 决定发货方式（见下方流程）
 - "取消订单XX" → `commerce order cancel --id XX --yes`
 - "标记订单已送达" → `commerce order mark-delivered --id XX`
 - "查询运费" → `commerce shipping calculate --country XX --weight YY`
@@ -36,6 +36,144 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 5. **物流跟踪** - 定期 `commerce shipping 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`: 运单标签下载链接（可打印）
+- `carrier`: 快递公司名称
+
+**查看可用快递**：
+```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]
+      发货成功！
+      - 运单号：ES123456789
+      - 快递公司：FedEx
+      - 标签下载：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. **审核评估** - 检查商品状态、退货凭证、历史记录
@@ -132,6 +270,11 @@ commerce order ship --id order_789 --tracking DHL123458 --carrier DHL
 - `commerce shipping track` - 物流追踪
 - `commerce shipping update-status` - 更新物流状态
 
+### Easyship 集成
+- `commerce easyship couriers` - 查看可用快递公司
+- `commerce easyship rates --order-id <id>` - 获取订单运费报价
+- `commerce easyship track --order-id <id>` - 跟踪 Easyship 运单
+
 ## 详细示例
 
 ### 查看待处理订单
@@ -142,7 +285,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 \

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

@@ -1,11 +1,11 @@
 ---
 name: product
-description: Product catalog management for e-commerce stores. Create and update products, manage variants/SKUs, upload product images, organize tags, manage collections. Use when user needs to add new products, update pricing, manage product inventory, upload photos, organize product catalog, or manage product collections.
+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.
 ---
 
 # Commerce CLI - Product Management
 
-商品管理模块，用于电商商品目录的创建、编辑、组织和集合管理。
+商品管理模块，用于电商商品目录的创建、编辑和组织。
 
 ## 典型场景
 
@@ -73,45 +73,6 @@ commerce upload image --path ./new-photo.jpg  # 获得 media_new
 commerce product add-images --id prod_123 --media-id media_new
 ```
 
-### 场景6：创建商品集合
-
-**推荐集合类型**：
-- **时令集合** - 春夏秋冬、节日促销（如"Christmas Sale"）
-- **品类集合** - 按商品类型分组（如"T-Shirts", "Dresses"）
-- **主题集合** - 按场景分组（如"Office Wear", "Casual Style"）
-- **促销集合** - 新品、热卖、折扣（如"New Arrivals", "Best Sellers"）
-
-**创建流程**：
-```bash
-# 1. 创建集合
-commerce collection create \
-  --name "Summer Sale 2024" \
-  --slug "summer-sale-2024" \
-  --description "Hot deals for summer"
-
-# 2. 添加商品到集合
-commerce collection add-products \
-  --slug summer-sale-2024 \
-  --product-ids prod_123,prod_456,prod_789
-```
-
-### 场景7：设置集合封面图
-
-**三种方式**：
-
-```bash
-# 方式 1：使用 Media ID（推荐，可复用已上传图片）
-commerce upload image --path ./cover.jpg
-# 获取 media_id: media_456
-commerce collection set-cover --id coll-123 --media-id media_456
-
-# 方式 2：使用 URL
-commerce collection set-cover --id coll-123 --url "https://example.com/cover.jpg"
-
-# 方式 3：上传本地文件
-commerce collection set-cover --id coll-123 --path ./cover.jpg
-```
-
 ### 场景决策表
 
 | 用户需求 | 推荐命令 | 关键注意点 |
@@ -122,8 +83,6 @@ commerce collection set-cover --id coll-123 --path ./cover.jpg
 | 更新价格 | `product update --price` | 如有变体，需逐个更新变体价格 |
 | 促销标签 | `product update --tags` | 用逗号分隔，保留原有标签 |
 | 图片更新 | `upload` + `add-images` | 先上传再关联，不要直接删除旧图 |
-| 创建促销集合 | `collection create --slug sale` | slug 简短有意义，添加10-30个商品 |
-| 设置集合封面 | `collection set-cover --id XX` | 支持 media-id/url/path 三种方式 |
 
 ## 卓越标准
 
@@ -219,54 +178,6 @@ commerce product update --id prod_123 --tags "featured,new,sale"
 commerce product create --title "T恤" --price 99 --stock 50  # 确保真实有50件
 ```
 
-### ❌ 问题6：集合命名随意，无规划
-
-**错误做法**：
-```bash
-# 命名不规范，slug 无意义
-commerce collection create --name "aaa" --slug "test123"
-commerce collection create --name "商品111" --slug "product-collection"
-```
-
-**正确做法**：
-```bash
-# 命名清晰，slug 符合 SEO 规范
-commerce collection create --name "Summer Sale 2024" --slug "summer-sale-2024"
-commerce collection create --name "Men's T-Shirts" --slug "mens-tshirts"
-```
-
-### ❌ 问题7：集合缺少商品
-
-**错误做法**：
-```bash
-# 创建集合后忘记添加商品
-commerce collection create --name "New Arrivals" --slug "new-arrivals"
-# 集合页面显示空白
-```
-
-**正确做法**：
-```bash
-# 创建集合后立即添加商品（至少5个）
-commerce collection create --name "New Arrivals" --slug "new-arrivals"
-commerce collection add-products --slug new-arrivals --product-ids prod_1,prod_2,prod_3,prod_4,prod_5
-```
-
-### ❌ 问题8：slug 使用中文或特殊字符
-
-**错误做法**：
-```bash
-# slug 包含中文或特殊字符，影响 SEO 和 URL 可读性
-commerce collection create --name "夏季促销" --slug "夏季促销"
-commerce collection create --name "Sale!!!" --slug "sale!!!"
-```
-
-**正确做法**：
-```bash
-# slug 使用英文、数字、连字符
-commerce collection create --name "夏季促销" --slug "summer-sale"
-commerce collection create --name "Sale!!!" --slug "sale"
-```
-
 ## 命令参考
 
 ### 自然语言映射
@@ -278,11 +189,6 @@ commerce collection create --name "Sale!!!" --slug "sale"
 - "更新商品价格" → `commerce product update --id XX --price YY`
 - "给商品打标签" → `commerce product update --id XX --tags "featured,new"`
 - "查看所有商品" → `commerce product list`
-- "创建商品集合" → `commerce collection create --name XX --slug YY`
-- "把商品添加到集合" → `commerce collection add-products --slug XX --product-ids YY`
-- "设置集合封面图" → `commerce collection set-cover --id XX --media-id YY`
-- "上传集合封面" → `commerce collection set-cover --id XX --path ./cover.jpg`
-- "集合封面图 URL 是 https://..." → `commerce collection set-cover --id XX --url "https://..."`
 
 ### 核心功能
 
@@ -304,15 +210,6 @@ commerce collection create --name "Sale!!!" --slug "sale"
 - `commerce product add-images` - 关联图片到商品
 - `commerce product remove-images` - 移除商品图片
 
-**商品集合**:
-- `commerce collection create` - 创建集合
-- `commerce collection list` - 查看集合列表
-- `commerce collection update` - 更新集合
-- `commerce collection delete` - 删除集合
-- `commerce collection add-products` - 添加商品到集合
-- `commerce collection remove-products` - 从集合移除商品
-- `commerce collection set-cover` - 设置集合封面图（支持 media-id/url/path）
-
 ## 详细示例
 
 ### 示例1：创建单个商品
@@ -398,38 +295,6 @@ commerce product add-images --id prod_123 --media-id media_red,media_blue
 commerce product get --id prod_123
 ```
 
-### 示例7：创建商品集合
-```bash
-# 用户说："创建夏季促销集合"
-commerce collection create \
-  --name "Summer Sale" \
-  --slug summer-sale \
-  --description "Hot deals for summer"
-```
-
-### 示例8：添加商品到集合
-```bash
-# 用户说："把商品prod_123和prod_456添加到summer-sale集合"
-commerce collection add-products \
-  --slug summer-sale \
-  --product-ids prod_123,prod_456
-```
-
-### 示例9：设置集合封面图
-```bash
-# 用户说："给集合设置封面图"
-
-# 方式 1：使用 Media ID（推荐）
-commerce upload image --path ./cover.jpg  # 获得 media_456
-commerce collection set-cover --id coll-123 --media-id media_456
-
-# 方式 2：使用 URL
-commerce collection set-cover --id coll-123 --url "https://example.com/cover.jpg"
-
-# 方式 3：上传本地文件
-commerce collection set-cover --id coll-123 --path ./cover.jpg
-```
-
 ## 重要提示
 
 - 所有命令默认 JSON 输出，便于 AI 解析
@@ -440,5 +305,3 @@ commerce collection set-cover --id coll-123 --path ./cover.jpg
 - 使用 `--help` 查看命令详细参数
 - 删除商品会同时删除所有变体和图片关联
 - 价格单位默认为美元（USD），可通过后台配置修改
-- 集合 slug 必须唯一，用于 URL，使用英文和连字符
-- 集合封面支持三种方式：`--media-id`（推荐）、`--url`、`--path`

package/package.json

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