@optima-chat/optima-agent 0.9.10 → 0.9.12

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

@@ -1,452 +1,452 @@
----
-name: order
-description: Order fulfillment and shipping management. Process orders, ship packages, handle cancellations, manage refunds, track shipments. Use when user needs to fulfill orders, ship products, cancel orders, process refunds, or check shipping status.
----
-
-# Commerce CLI - Order Fulfillment
-
-订单履行模块，用于处理订单、发货、售后和物流跟踪。
-
-## 典型场景
-
-当用户说：
-- "查看待发货订单" → `commerce order list --status paid`
-- "订单XX发货" → 先查订单详情，根据 shipping_mode_used 决定发货方式（见下方流程）
-- "单号XX发货" / "只有运单号" → 只需提供运单号即可发货，carrier 可选，后端自动检测快递公司
-- "查询订单物流" / "包裹到哪了" → `commerce order tracking --id XX`
-- "运单标签好了吗" / "查标签" → `commerce order refresh-label --id XX`
-- "取消订单XX" → `commerce order cancel --id XX --yes`
-- "标记订单已送达" → `commerce order mark-delivered --id XX`
-- "处理退款" → `commerce refund create --order-id XX --amount YY`
-
-### 场景决策表
-
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 查看待发货订单 | `order list --status paid` | 按付款时间升序，优先处理早期订单 |
-| 批量发货 | 循环 `order ship` | 必须有真实tracking号，避免虚假发货 |
-| 取消订单 | `order cancel --yes` | 检查是否已发货，避免错误取消 |
-| 处理退款 | `refund create` → `refund approve` | 先创建后审批，保留审计记录 |
-| 物流异常 | `order tracking` → `order update-shipping-status` | 主动更新状态，及时通知客户 |
-
-### 标准订单履行流程
-1. **查看待发货** - `commerce order list --status paid` 按时间升序
-2. **验证订单** - 检查库存、地址、特殊要求
-3. **批量打包** - 准备商品、包装材料、打印面单
-4. **标记发货** - 循环 `commerce order ship --id XX --tracking YY`（carrier 可选）
-5. **物流跟踪** - 定期 `commerce order tracking` 监控异常
-6. **确认送达** - 签收后 `commerce order mark-delivered --id XX`
-
-### 发货流程详解（重要）
-
-订单发货需要根据 `shipping_mode_used` 字段选择正确的发货方式。
-
-#### 运费模式说明
-
-| shipping_mode_used | 含义 | 发货方式 |
-|--------------------|------|----------|
-| `easyship` | 买家选择了动态运费快递（DYNAMIC） | 自动发货 / 指定方案 / 手动 |
-| `fixed` | 买家使用固定运费 | 指定方案 / 手动 |
-| `free` | 全球免运费 | 指定方案 / 手动 |
-| 空/null | 历史订单 | 指定方案 / 手动 |
-
-#### 发货流程
-
-卖家说"发货" → 查订单 → AskUserQuestion "如何发货？"
-
-**DYNAMIC 订单**（买家已选物流方案，有 selected_courier_id）:
-- 选项 1: 使用买家选择的物流方案 → `commerce order ship --id <order-id> --auto`
-- 选项 2: 使用其他系统物流方案 → 先 `logistics rates query` 查报价 → AskUserQuestion 展示方案 → 卖家选 → `commerce order ship --id <order-id> --rate-id <selected-rate-id>`
-- 选项 3: 自己处理 → 卖家提供 tracking number → `commerce order ship --id <order-id> --tracking <number> [--carrier <name>]`
-
-**FREE/FIXED 订单**（无 selected_courier_id）:
-- 选项 1: 使用系统物流 → 先 `logistics rates query` 查报价 → AskUserQuestion 展示方案 → 卖家选 → `commerce order ship --id <order-id> --rate-id <selected-rate-id>`
-- 选项 2: 自己处理 → 卖家提供 tracking number → `commerce order ship --id <order-id> --tracking <number> [--carrier <name>]`
-
-三种 CLI 路径：
-- `--auto`：仅 DYNAMIC 默认方案（使用买家 checkout 时选的 courier）
-- `--rate-id <id>`：任意模式，卖家/AI 指定方案
-- `--tracking <number>`：手动发货
-
-#### 发货决策规则（必须严格遵守）
-
-当用户说"订单XXX发货"时，按以下步骤执行：
-
-**步骤1**：执行 `commerce order get --id XXX` 获取订单详情
-
-**步骤2**：在返回结果中找到 `shipping_mode_used` 字段的值
-
-**步骤3**：根据字段值决定下一步操作：
-
-- **如果 `shipping_mode_used = "easyship"`（DYNAMIC 订单）**：
-  1. **必须**使用 AskUserQuestion 工具询问用户
-  2. 提供三个选项：使用买家方案（--auto）、选择其他方案（--rate-id）、手动发货（--tracking）
-  3. **禁止**直接询问运单号
-  4. 等待用户选择后再执行对应命令
-
-- **如果 `shipping_mode_used = "fixed"` 或 `"free"` 或字段为空**：
-  1. **必须**使用 AskUserQuestion 工具询问用户
-  2. 提供两个选项：使用系统物流（--rate-id）、手动发货（--tracking）
-  3. 如果用户选择系统物流，先 `logistics rates query` 查报价，再用 AskUserQuestion 展示可用方案
-  4. 如果用户选择手动发货：询问运单号，快递公司名称为**可选**
-  5. **即使用户提供了快递公司名称，发货时也统一不传 carrier**，让后端根据运单号自动检测并存储准确的快递公司名称（人类可读，如 "SF Express"、"UPS"）。发货成功后对比响应中的 carrier 与用户所说的：
-     - 一致 → 正常告知
-     - 不一致 → 告知用户："您提供的是 XX，系统根据运单号识别为 YY，已按识别结果记录。如有误请告知。"
-
-#### 系统物流发货
-
-**适用场景**：任意 shipping_mode_used，用户选择使用系统物流
-
-**命令**：
-```bash
-# DYNAMIC 订单 — 使用买家选择的快递（推荐）
-commerce order ship --id <order-id> --auto
-
-# DYNAMIC 订单 — 指定其他快递
-commerce order ship --id <order-id> --auto --courier-id <courier-id>
-
-# 任意模式 — 使用指定的物流方案（先查 logistics rates query）
-commerce order ship --id <order-id> --rate-id <rate-id>
-```
-
-**返回结果包含**：
-- `tracking_number`: 自动生成的运单号
-- `tracking_url`: 快递跟踪链接
-- `label_url`: 运单标签下载链接（可能为空）
-- `label_state`: 标签状态
-- `carrier`: 快递公司名称
-
-**运单标签处理（重要）**：
-
-运单标签是用户必须打印并贴在包裹上的快递单。物流服务生成标签需要几秒到几分钟。
-
-**发货后根据 label_state 处理**：
-
-| label_state | 含义 | 处理方式 |
-|-------------|------|----------|
-| `generated` / `printed` | 标签已生成 | 提供 `label_url` 让用户下载打印 |
-| `pending` / `generating` | 标签生成中 | 告知用户「标签正在生成，稍后可以让我帮你查询」 |
-| `failed` / `technical_failed` | 生成失败 | 告知用户需要检查物流服务后台或重新发货 |
-
-**查询标签状态**：
-
-如果发货时 label_state 为 pending/generating，稍后使用 `order refresh-label` 同步最新状态：
-```bash
-commerce order refresh-label --id <order-id>
-```
-返回最新的 `label_state` 和 `label_url`（如已生成）。
-
-**查看可用快递**：
-```bash
-commerce easyship couriers
-```
-
-#### 手动发货
-
-**适用场景**：
-- `shipping_mode_used = "fixed"` 或 `"free"` 或为空
-- 或用户选择不使用 Easyship
-
-**命令**：
-```bash
-# 推荐：只提供运单号，后端自动检测快递公司并生成追踪链接
-commerce order ship --id <order-id> --tracking <运单号>
-
-# 可选参数（一般不需要手动指定）
-#   --carrier <快递公司名称>    后端会自动检测，通常无需手动指定
-#   --tracking-url <跟踪链接>   后端自动生成 AfterShip 链接
-```
-
-**示例**：
-```bash
-# 只提供运单号（推荐，后端自动检测快递公司和生成追踪链接）
-commerce order ship --id order_123 --tracking SF1234567890
-
-# 指定快递公司
-commerce order ship --id order_123 \
-  --tracking SF1234567890 \
-  --carrier "顺丰速运"
-
-# 完整参数（带跟踪链接）
-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：DYNAMIC 订单（买家已选物流方案）**
-```
-用户：订单 order_abc 发货
-
-助手：[执行 Bash: commerce order get --id order_abc]
-      [发现 shipping_mode_used = "easyship"，有 selected_courier_id]
-      [使用 AskUserQuestion 工具]
-
-AskUserQuestion:
-  question: "该订单买家已选择物流方案，请选择发货方式"
-  options:
-    - label: "使用买家选择的物流方案（推荐）"
-      description: "自动生成运单号和标签，使用买家 checkout 时选的快递"
-    - label: "选择其他系统物流方案"
-      description: "查询可用物流方案，选择后创建运单"
-    - label: "手动填写运单号"
-      description: "自己处理物流，需要提供运单号"
-
-用户：[选择使用买家方案]
-
-助手：[执行 Bash: commerce order ship --id order_abc --auto]
-      [检查返回结果中的 label_state]
-      发货成功！运单号 ES123456789，快递公司 FedEx。
-      运单标签已生成，请下载打印后贴在包裹上：https://...
-```
-
-**场景2：FREE/FIXED 订单（使用系统物流）**
-```
-用户：订单 order_xyz 发货
-
-助手：[执行 Bash: commerce order get --id order_xyz]
-      [发现 shipping_mode_used = "fixed"，无 selected_courier_id]
-      [使用 AskUserQuestion 工具]
-
-AskUserQuestion:
-  question: "该订单使用固定运费模式，请选择发货方式"
-  options:
-    - label: "使用系统物流"
-      description: "查询可用物流方案，选择后自动创建运单和标签"
-    - label: "手动填写运单号"
-      description: "自己处理物流，需要提供运单号"
-
-用户：[选择系统物流]
-
-助手：[执行 Bash: logistics rates query --origin '...' --destination '...' --items '...']
-      [查到 3 个可用方案]
-      [使用 AskUserQuestion 展示方案]
-
-AskUserQuestion:
-  question: "以下是可用的物流方案，请选择"
-  options:
-    - label: "Standard Shipping (7-15 days) - ¥72.00 CNY"
-    - label: "Economy Shipping (15-25 days) - ¥45.00 CNY"
-    - label: "Express Shipping (3-7 days) - ¥128.00 CNY"
-
-用户：[选择 Standard Shipping]
-
-助手：[执行 Bash: commerce order ship --id order_xyz --rate-id rate_abc123]
-      发货成功！运单号 JD123456789。
-```
-
-**场景3：手动发货（用户直接提供运单号）**
-```
-用户：订单 order_abc 发货，单号 YT9876543210
-
-助手：[执行 Bash: commerce order get --id order_abc]
-      [发现 shipping_mode_used = "fixed"]
-      [用户已提供运单号，直接发货]
-      [执行 Bash: commerce order ship --id order_abc --tracking YT9876543210]
-      发货成功！运单号 YT9876543210，快递公司 YTO Express（自动识别）。
-      随时可以让我帮你查询物流状态。
-```
-
-**场景4：用户提供了快递公司名称（carrier 确认）**
-```
-用户：订单 order_def 发货，顺丰，单号 773456789012
-
-助手：[执行 Bash: commerce order get --id order_def]
-      [发现 shipping_mode_used = "fixed"]
-      [用户提供了 carrier "顺丰"，但统一不传 carrier，让后端自动检测]
-      [执行 Bash: commerce order ship --id order_def --tracking 773456789012]
-
-      [情况A：检测结果与用户一致]
-      发货成功！运单号 773456789012，快递公司 SF Express（自动识别）。
-      随时可以让我帮你查询物流状态。
-
-      [情况B：检测结果与用户不一致]
-      发货成功！运单号 773456789012。
-      提示：您说的快递公司是顺丰，但系统根据运单号识别为 YTO Express，已按识别结果记录。如有误请告知我修正。
-      随时可以让我帮你查询物流状态。
-```
-
-### 退款处理流程
-1. **创建退款** - `commerce refund create` 填写详细原因
-2. **审核评估** - 检查商品状态、退货凭证、历史记录
-3. **批准/拒绝** - `commerce refund approve/reject` 并通知客户
-4. **跟踪反馈** - 记录退款原因，优化产品和服务
-
-## 卓越标准
-
-### 订单处理质量指标
-- **发货及时性**: 付款后24小时内发货（标品），48小时内发货（定制品）
-- **物流信息准确性**: 100%订单有tracking number，无虚假单号
-- **客户满意度**: 退款率 < 5%，客服投诉响应 < 2小时
-- **订单完成率**: 取消率 < 3%，拒收率 < 2%
-
-### 订单状态管理原则
-- **3-5-7原则**: 3分钟确认订单，5小时内完成打包，7天内跟踪售后
-- **自动化优先**: 批量处理相同状态订单，优先处理付款时间早的订单
-- **数据完整性**: 发货前验证库存、收货地址、物流商可达性
-- **客户沟通**: 关键状态变更后及时通知（发货、延迟、退款、取消）
-- **审计留痕**: 所有操作记录原因和操作人，便于问题追溯
-
-## 常见问题
-
-### 批量发货错误
-
-❌ **危险做法 - 不验证就批量发货**：
-```bash
-# 可能发错货或虚假发货
-for order_id in $(commerce order list --status paid --json | jq -r '.[].id'); do
-  commerce order ship --id $order_id --tracking FAKE123 --carrier DHL
-done
-```
-
-✅ **正确做法 - 先验证再批量发货**：
-```bash
-# 先查看订单列表
-commerce order list --status paid
-
-# 准备好所有真实tracking号后，逐个发货（carrier 可选）
-commerce order ship --id order_123 --tracking DHL123456
-commerce order ship --id order_456 --tracking DHL123457
-commerce order ship --id order_789 --tracking DHL123458
-```
-
-### 订单取消场景
-
-❌ **错误操作 - 已发货还取消**：
-- 不检查订单状态直接取消，导致客户收到货但订单已取消
-
-✅ **正确处理**：
-- **客户主动取消** → 检查是否已发货，未发货立即取消
-- **地址错误无法送达** → 联系客户更新地址或取消退款
-- **库存不足** → 立即通知客户，协商补货或退款
-
-### 退款处理错误
-
-❌ **错误流程 - 直接批准未审核的退款**：
-- 不检查商品状态、退货凭证就批准，容易被恶意退款
-
-✅ **正确流程**：
-- **商品质量问题** → 无需退货，直接全额退款
-- **客户不满意** → 要求退货，收到货后退款
-- **物流丢失** → 联系物流商理赔，先行退款给客户
-
-### 物流延迟处理
-
-❌ **错误做法 - 不主动通知客户**：
-- 物流延迟不告知客户，导致客户投诉和差评
-
-✅ **正确处理**：
-- **国内延迟 > 3天** → 主动联系客户说明情况
-- **国际延迟 > 7天** → 提供物流追踪链接，协商解决方案
-- **物流丢失** → 联系物流商查询，必要时补发或退款
-
-## 命令参考
-
-### 订单管理
-- `commerce order list` - 查看订单列表
-- `commerce order get` - 查看订单详情
-- `commerce order ship` - 标记订单发货（carrier 可选，后端自动检测）
-- `commerce order tracking` - 查询物流跟踪（含轨迹、预计送达）
-- `commerce order refresh-label` - 刷新 Easyship 运单标签状态
-- `commerce order update-shipping-status` - 更新物流状态
-- `commerce order cancel` - 取消订单
-- `commerce order complete` - 完成订单
-- `commerce order mark-delivered` - 标记已送达
-
-### 退款管理
-- `commerce refund create` - 创建退款
-- `commerce refund list` - 查看退款列表
-- `commerce refund get` - 查看退款详情
-- `commerce refund approve` - 批准退款
-- `commerce refund reject` - 拒绝退款
-
-### Easyship 集成
-- `commerce easyship couriers` - 查看可用快递公司
-- `commerce easyship rates --order-id <id>` - 获取订单运费报价
-
-## 详细示例
-
-### 查看待处理订单
-```bash
-# 用户说："查看今天待发货的订单"
-commerce order list --status paid --limit 50
-```
-
-### 订单发货
-```bash
-# 步骤1：先获取订单信息，检查 shipping_mode_used
-commerce order get --id order_123
-
-# DYNAMIC 订单 — 使用买家选择的方案
-commerce order ship --id order_123 --auto
-
-# 任意模式 — 指定物流方案（先查 logistics rates query 获取 rate-id）
-commerce order ship --id order_123 --rate-id rate_abc123
-
-# 手动发货 — 只需提供运单号，carrier 可选
-commerce order ship --id order_123 --tracking DHL123456
-```
-
-### 取消订单
-```bash
-# 用户说："取消订单order_456，原因是客户要求"
-commerce order cancel \
-  --id order_456 \
-  --reason "客户要求取消" \
-  --yes
-```
-
-### 标记订单完成
-```bash
-# 用户说："标记订单order_789已送达"
-commerce order mark-delivered --id order_789
-```
-
-### 处理退款
-```bash
-# 用户说："订单order_123要退款150美元"
-commerce refund create \
-  --order-id order_123 \
-  --amount 150 \
-  --reason "商品有瑕疵"
-
-# 批准退款
-commerce refund approve --id refund_456
-```
-
-### 物流追踪
-```bash
-# 用户说："查询订单order_123的物流信息"
-# 返回物流轨迹（checkpoints）、预计送达时间、当前状态
-commerce order tracking --id order_123
-```
-
-**响应指导**：
-- **有 checkpoints**：展示当前状态、预计送达时间、轨迹列表
-- **checkpoints 为空**：告诉用户"物流信息同步中，快递公司通常需要几小时更新，稍后可以再查"
-- **可以**：展示返回的 tracking_url（用户自己决定是否点击）
-- **禁止**：主动建议用户"去快递官网查询"或"用小程序/APP查询"。平台提供物流追踪服务，应引导用户通过平台查询
-
-## 重要提示
-
-- 订单状态流转：pending → paid → shipped → delivered → completed
-- 取消和删除操作需要 `--yes` 确认
-- 发货后订单状态自动变为 shipped
-- 退款需要先创建，然后批准才会实际退款
-- 发货后**主动告知用户**"随时可以让我帮你查询物流状态"
-- 使用 `--help` 查看命令详细参数
+---
+name: order
+description: Order fulfillment and shipping management. Process orders, ship packages, handle cancellations, manage refunds, track shipments. Use when user needs to fulfill orders, ship products, cancel orders, process refunds, or check shipping status.
+---
+
+# Commerce CLI - Order Fulfillment
+
+订单履行模块，用于处理订单、发货、售后和物流跟踪。
+
+## 典型场景
+
+当用户说：
+- "查看待发货订单" → `commerce order list --status paid`
+- "订单XX发货" → 先查订单详情，根据 shipping_mode_used 决定发货方式（见下方流程）
+- "单号XX发货" / "只有运单号" → 只需提供运单号即可发货，carrier 可选，后端自动检测快递公司
+- "查询订单物流" / "包裹到哪了" → `commerce order tracking --id XX`
+- "运单标签好了吗" / "查标签" → `commerce order refresh-label --id XX`
+- "取消订单XX" → `commerce order cancel --id XX --yes`
+- "标记订单已送达" → `commerce order mark-delivered --id XX`
+- "处理退款" → `commerce refund create --order-id XX --amount YY`
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 查看待发货订单 | `order list --status paid` | 按付款时间升序，优先处理早期订单 |
+| 批量发货 | 循环 `order ship` | 必须有真实tracking号，避免虚假发货 |
+| 取消订单 | `order cancel --yes` | 检查是否已发货，避免错误取消 |
+| 处理退款 | `refund create` → `refund approve` | 先创建后审批，保留审计记录 |
+| 物流异常 | `order tracking` → `order update-shipping-status` | 主动更新状态，及时通知客户 |
+
+### 标准订单履行流程
+1. **查看待发货** - `commerce order list --status paid` 按时间升序
+2. **验证订单** - 检查库存、地址、特殊要求
+3. **批量打包** - 准备商品、包装材料、打印面单
+4. **标记发货** - 循环 `commerce order ship --id XX --tracking YY`（carrier 可选）
+5. **物流跟踪** - 定期 `commerce order tracking` 监控异常
+6. **确认送达** - 签收后 `commerce order mark-delivered --id XX`
+
+### 发货流程详解（重要）
+
+订单发货需要根据 `shipping_mode_used` 字段选择正确的发货方式。
+
+#### 运费模式说明
+
+| shipping_mode_used | 含义 | 发货方式 |
+|--------------------|------|----------|
+| `easyship` | 买家选择了动态运费快递（DYNAMIC） | 自动发货 / 指定方案 / 手动 |
+| `fixed` | 买家使用固定运费 | 指定方案 / 手动 |
+| `free` | 全球免运费 | 指定方案 / 手动 |
+| 空/null | 历史订单 | 指定方案 / 手动 |
+
+#### 发货流程
+
+卖家说"发货" → 查订单 → AskUserQuestion "如何发货？"
+
+**DYNAMIC 订单**（买家已选物流方案，有 selected_courier_id）:
+- 选项 1: 使用买家选择的物流方案 → `commerce order ship --id <order-id> --auto`
+- 选项 2: 使用其他系统物流方案 → 先 `logistics rates query` 查报价 → AskUserQuestion 展示方案 → 卖家选 → `commerce order ship --id <order-id> --rate-id <selected-rate-id>`
+- 选项 3: 自己处理 → 卖家提供 tracking number → `commerce order ship --id <order-id> --tracking <number> [--carrier <name>]`
+
+**FREE/FIXED 订单**（无 selected_courier_id）:
+- 选项 1: 使用系统物流 → 先 `logistics rates query` 查报价 → AskUserQuestion 展示方案 → 卖家选 → `commerce order ship --id <order-id> --rate-id <selected-rate-id>`
+- 选项 2: 自己处理 → 卖家提供 tracking number → `commerce order ship --id <order-id> --tracking <number> [--carrier <name>]`
+
+三种 CLI 路径：
+- `--auto`：仅 DYNAMIC 默认方案（使用买家 checkout 时选的 courier）
+- `--rate-id <id>`：任意模式，卖家/AI 指定方案
+- `--tracking <number>`：手动发货
+
+#### 发货决策规则（必须严格遵守）
+
+当用户说"订单XXX发货"时，按以下步骤执行：
+
+**步骤1**：执行 `commerce order get --id XXX` 获取订单详情
+
+**步骤2**：在返回结果中找到 `shipping_mode_used` 字段的值
+
+**步骤3**：根据字段值决定下一步操作：
+
+- **如果 `shipping_mode_used = "easyship"`（DYNAMIC 订单）**：
+  1. **必须**使用 AskUserQuestion 工具询问用户
+  2. 提供三个选项：使用买家方案（--auto）、选择其他方案（--rate-id）、手动发货（--tracking）
+  3. **禁止**直接询问运单号
+  4. 等待用户选择后再执行对应命令
+
+- **如果 `shipping_mode_used = "fixed"` 或 `"free"` 或字段为空**：
+  1. **必须**使用 AskUserQuestion 工具询问用户
+  2. 提供两个选项：使用系统物流（--rate-id）、手动发货（--tracking）
+  3. 如果用户选择系统物流，先 `logistics rates query` 查报价，再用 AskUserQuestion 展示可用方案
+  4. 如果用户选择手动发货：询问运单号，快递公司名称为**可选**
+  5. **即使用户提供了快递公司名称，发货时也统一不传 carrier**，让后端根据运单号自动检测并存储准确的快递公司名称（人类可读，如 "SF Express"、"UPS"）。发货成功后对比响应中的 carrier 与用户所说的：
+     - 一致 → 正常告知
+     - 不一致 → 告知用户："您提供的是 XX，系统根据运单号识别为 YY，已按识别结果记录。如有误请告知。"
+
+#### 系统物流发货
+
+**适用场景**：任意 shipping_mode_used，用户选择使用系统物流
+
+**命令**：
+```bash
+# DYNAMIC 订单 — 使用买家选择的快递（推荐）
+commerce order ship --id <order-id> --auto
+
+# DYNAMIC 订单 — 指定其他快递
+commerce order ship --id <order-id> --auto --courier-id <courier-id>
+
+# 任意模式 — 使用指定的物流方案（先查 logistics rates query）
+commerce order ship --id <order-id> --rate-id <rate-id>
+```
+
+**返回结果包含**：
+- `tracking_number`: 自动生成的运单号
+- `tracking_url`: 快递跟踪链接
+- `label_url`: 运单标签下载链接（可能为空）
+- `label_state`: 标签状态
+- `carrier`: 快递公司名称
+
+**运单标签处理（重要）**：
+
+运单标签是用户必须打印并贴在包裹上的快递单。物流服务生成标签需要几秒到几分钟。
+
+**发货后根据 label_state 处理**：
+
+| label_state | 含义 | 处理方式 |
+|-------------|------|----------|
+| `generated` / `printed` | 标签已生成 | 提供 `label_url` 让用户下载打印 |
+| `pending` / `generating` | 标签生成中 | 告知用户「标签正在生成，稍后可以让我帮你查询」 |
+| `failed` / `technical_failed` | 生成失败 | 告知用户需要检查物流服务后台或重新发货 |
+
+**查询标签状态**：
+
+如果发货时 label_state 为 pending/generating，稍后使用 `order refresh-label` 同步最新状态：
+```bash
+commerce order refresh-label --id <order-id>
+```
+返回最新的 `label_state` 和 `label_url`（如已生成）。
+
+**查看可用快递**：
+```bash
+commerce easyship couriers
+```
+
+#### 手动发货
+
+**适用场景**：
+- `shipping_mode_used = "fixed"` 或 `"free"` 或为空
+- 或用户选择不使用 Easyship
+
+**命令**：
+```bash
+# 推荐：只提供运单号，后端自动检测快递公司并生成追踪链接
+commerce order ship --id <order-id> --tracking <运单号>
+
+# 可选参数（一般不需要手动指定）
+#   --carrier <快递公司名称>    后端会自动检测，通常无需手动指定
+#   --tracking-url <跟踪链接>   后端自动生成 AfterShip 链接
+```
+
+**示例**：
+```bash
+# 只提供运单号（推荐，后端自动检测快递公司和生成追踪链接）
+commerce order ship --id order_123 --tracking SF1234567890
+
+# 指定快递公司
+commerce order ship --id order_123 \
+  --tracking SF1234567890 \
+  --carrier "顺丰速运"
+
+# 完整参数（带跟踪链接）
+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：DYNAMIC 订单（买家已选物流方案）**
+```
+用户：订单 order_abc 发货
+
+助手：[执行 Bash: commerce order get --id order_abc]
+      [发现 shipping_mode_used = "easyship"，有 selected_courier_id]
+      [使用 AskUserQuestion 工具]
+
+AskUserQuestion:
+  question: "该订单买家已选择物流方案，请选择发货方式"
+  options:
+    - label: "使用买家选择的物流方案（推荐）"
+      description: "自动生成运单号和标签，使用买家 checkout 时选的快递"
+    - label: "选择其他系统物流方案"
+      description: "查询可用物流方案，选择后创建运单"
+    - label: "手动填写运单号"
+      description: "自己处理物流，需要提供运单号"
+
+用户：[选择使用买家方案]
+
+助手：[执行 Bash: commerce order ship --id order_abc --auto]
+      [检查返回结果中的 label_state]
+      发货成功！运单号 ES123456789，快递公司 FedEx。
+      运单标签已生成，请下载打印后贴在包裹上：https://...
+```
+
+**场景2：FREE/FIXED 订单（使用系统物流）**
+```
+用户：订单 order_xyz 发货
+
+助手：[执行 Bash: commerce order get --id order_xyz]
+      [发现 shipping_mode_used = "fixed"，无 selected_courier_id]
+      [使用 AskUserQuestion 工具]
+
+AskUserQuestion:
+  question: "该订单使用固定运费模式，请选择发货方式"
+  options:
+    - label: "使用系统物流"
+      description: "查询可用物流方案，选择后自动创建运单和标签"
+    - label: "手动填写运单号"
+      description: "自己处理物流，需要提供运单号"
+
+用户：[选择系统物流]
+
+助手：[执行 Bash: logistics rates query --origin '...' --destination '...' --items '...']
+      [查到 3 个可用方案]
+      [使用 AskUserQuestion 展示方案]
+
+AskUserQuestion:
+  question: "以下是可用的物流方案，请选择"
+  options:
+    - label: "Standard Shipping (7-15 days) - ¥72.00 CNY"
+    - label: "Economy Shipping (15-25 days) - ¥45.00 CNY"
+    - label: "Express Shipping (3-7 days) - ¥128.00 CNY"
+
+用户：[选择 Standard Shipping]
+
+助手：[执行 Bash: commerce order ship --id order_xyz --rate-id rate_abc123]
+      发货成功！运单号 JD123456789。
+```
+
+**场景3：手动发货（用户直接提供运单号）**
+```
+用户：订单 order_abc 发货，单号 YT9876543210
+
+助手：[执行 Bash: commerce order get --id order_abc]
+      [发现 shipping_mode_used = "fixed"]
+      [用户已提供运单号，直接发货]
+      [执行 Bash: commerce order ship --id order_abc --tracking YT9876543210]
+      发货成功！运单号 YT9876543210，快递公司 YTO Express（自动识别）。
+      随时可以让我帮你查询物流状态。
+```
+
+**场景4：用户提供了快递公司名称（carrier 确认）**
+```
+用户：订单 order_def 发货，顺丰，单号 773456789012
+
+助手：[执行 Bash: commerce order get --id order_def]
+      [发现 shipping_mode_used = "fixed"]
+      [用户提供了 carrier "顺丰"，但统一不传 carrier，让后端自动检测]
+      [执行 Bash: commerce order ship --id order_def --tracking 773456789012]
+
+      [情况A：检测结果与用户一致]
+      发货成功！运单号 773456789012，快递公司 SF Express（自动识别）。
+      随时可以让我帮你查询物流状态。
+
+      [情况B：检测结果与用户不一致]
+      发货成功！运单号 773456789012。
+      提示：您说的快递公司是顺丰，但系统根据运单号识别为 YTO Express，已按识别结果记录。如有误请告知我修正。
+      随时可以让我帮你查询物流状态。
+```
+
+### 退款处理流程
+1. **创建退款** - `commerce refund create` 填写详细原因
+2. **审核评估** - 检查商品状态、退货凭证、历史记录
+3. **批准/拒绝** - `commerce refund approve/reject` 并通知客户
+4. **跟踪反馈** - 记录退款原因，优化产品和服务
+
+## 卓越标准
+
+### 订单处理质量指标
+- **发货及时性**: 付款后24小时内发货（标品），48小时内发货（定制品）
+- **物流信息准确性**: 100%订单有tracking number，无虚假单号
+- **客户满意度**: 退款率 < 5%，客服投诉响应 < 2小时
+- **订单完成率**: 取消率 < 3%，拒收率 < 2%
+
+### 订单状态管理原则
+- **3-5-7原则**: 3分钟确认订单，5小时内完成打包，7天内跟踪售后
+- **自动化优先**: 批量处理相同状态订单，优先处理付款时间早的订单
+- **数据完整性**: 发货前验证库存、收货地址、物流商可达性
+- **客户沟通**: 关键状态变更后及时通知（发货、延迟、退款、取消）
+- **审计留痕**: 所有操作记录原因和操作人，便于问题追溯
+
+## 常见问题
+
+### 批量发货错误
+
+❌ **危险做法 - 不验证就批量发货**：
+```bash
+# 可能发错货或虚假发货
+for order_id in $(commerce order list --status paid --json | jq -r '.[].id'); do
+  commerce order ship --id $order_id --tracking FAKE123 --carrier DHL
+done
+```
+
+✅ **正确做法 - 先验证再批量发货**：
+```bash
+# 先查看订单列表
+commerce order list --status paid
+
+# 准备好所有真实tracking号后，逐个发货（carrier 可选）
+commerce order ship --id order_123 --tracking DHL123456
+commerce order ship --id order_456 --tracking DHL123457
+commerce order ship --id order_789 --tracking DHL123458
+```
+
+### 订单取消场景
+
+❌ **错误操作 - 已发货还取消**：
+- 不检查订单状态直接取消，导致客户收到货但订单已取消
+
+✅ **正确处理**：
+- **客户主动取消** → 检查是否已发货，未发货立即取消
+- **地址错误无法送达** → 联系客户更新地址或取消退款
+- **库存不足** → 立即通知客户，协商补货或退款
+
+### 退款处理错误
+
+❌ **错误流程 - 直接批准未审核的退款**：
+- 不检查商品状态、退货凭证就批准，容易被恶意退款
+
+✅ **正确流程**：
+- **商品质量问题** → 无需退货，直接全额退款
+- **客户不满意** → 要求退货，收到货后退款
+- **物流丢失** → 联系物流商理赔，先行退款给客户
+
+### 物流延迟处理
+
+❌ **错误做法 - 不主动通知客户**：
+- 物流延迟不告知客户，导致客户投诉和差评
+
+✅ **正确处理**：
+- **国内延迟 > 3天** → 主动联系客户说明情况
+- **国际延迟 > 7天** → 提供物流追踪链接，协商解决方案
+- **物流丢失** → 联系物流商查询，必要时补发或退款
+
+## 命令参考
+
+### 订单管理
+- `commerce order list` - 查看订单列表
+- `commerce order get` - 查看订单详情
+- `commerce order ship` - 标记订单发货（carrier 可选，后端自动检测）
+- `commerce order tracking` - 查询物流跟踪（含轨迹、预计送达）
+- `commerce order refresh-label` - 刷新 Easyship 运单标签状态
+- `commerce order update-shipping-status` - 更新物流状态
+- `commerce order cancel` - 取消订单
+- `commerce order complete` - 完成订单
+- `commerce order mark-delivered` - 标记已送达
+
+### 退款管理
+- `commerce refund create` - 创建退款
+- `commerce refund list` - 查看退款列表
+- `commerce refund get` - 查看退款详情
+- `commerce refund approve` - 批准退款
+- `commerce refund reject` - 拒绝退款
+
+### Easyship 集成
+- `commerce easyship couriers` - 查看可用快递公司
+- `commerce easyship rates --order-id <id>` - 获取订单运费报价
+
+## 详细示例
+
+### 查看待处理订单
+```bash
+# 用户说："查看今天待发货的订单"
+commerce order list --status paid --limit 50
+```
+
+### 订单发货
+```bash
+# 步骤1：先获取订单信息，检查 shipping_mode_used
+commerce order get --id order_123
+
+# DYNAMIC 订单 — 使用买家选择的方案
+commerce order ship --id order_123 --auto
+
+# 任意模式 — 指定物流方案（先查 logistics rates query 获取 rate-id）
+commerce order ship --id order_123 --rate-id rate_abc123
+
+# 手动发货 — 只需提供运单号，carrier 可选
+commerce order ship --id order_123 --tracking DHL123456
+```
+
+### 取消订单
+```bash
+# 用户说："取消订单order_456，原因是客户要求"
+commerce order cancel \
+  --id order_456 \
+  --reason "客户要求取消" \
+  --yes
+```
+
+### 标记订单完成
+```bash
+# 用户说："标记订单order_789已送达"
+commerce order mark-delivered --id order_789
+```
+
+### 处理退款
+```bash
+# 用户说："订单order_123要退款150美元"
+commerce refund create \
+  --order-id order_123 \
+  --amount 150 \
+  --reason "商品有瑕疵"
+
+# 批准退款
+commerce refund approve --id refund_456
+```
+
+### 物流追踪
+```bash
+# 用户说："查询订单order_123的物流信息"
+# 返回物流轨迹（checkpoints）、预计送达时间、当前状态
+commerce order tracking --id order_123
+```
+
+**响应指导**：
+- **有 checkpoints**：展示当前状态、预计送达时间、轨迹列表
+- **checkpoints 为空**：告诉用户"物流信息同步中，快递公司通常需要几小时更新，稍后可以再查"
+- **可以**：展示返回的 tracking_url（用户自己决定是否点击）
+- **禁止**：主动建议用户"去快递官网查询"或"用小程序/APP查询"。平台提供物流追踪服务，应引导用户通过平台查询
+
+## 重要提示
+
+- 订单状态流转：pending → paid → shipped → delivered → completed
+- 取消和删除操作需要 `--yes` 确认
+- 发货后订单状态自动变为 shipped
+- 退款需要先创建，然后批准才会实际退款
+- 发货后**主动告知用户**"随时可以让我帮你查询物流状态"
+- 使用 `--help` 查看命令详细参数