@optima-chat/optima-agent 0.8.38 → 0.8.39

package/.claude/settings.local.json

@@ -145,7 +145,8 @@
       "Bash(aws ecs:*)",
       "Bash(aws ecr:*)",
       "Bash(gh search:*)",
-      "Bash(npx tsc:*)"
+      "Bash(npx tsc:*)",
+      "Bash(find /Users/verypro/optima-agent -path */node_modules -prune -o -type f \\\\\\(-name *comfy* -o -name *gen* \\\\\\) -print)"
     ],
     "deny": [],
     "ask": []

package/.claude/skills/logistics/SKILL.md

@@ -151,6 +151,30 @@ logistics address validate --address '<JSON Address>'
 
 所有命令支持 `--pretty` 参数输出人类可读格式。
 
+### JD 走货限制知识
+
+**货物类型限制**（不同专线支持不同 cargo type）：
+- 普货线：仅接 general
+- 带电线：接 battery + general
+- 服装线：接 clothing + general
+- 化妆品线：接 cosmetic
+- 系统会自动根据产品 cargo_type 过滤不可用专线
+
+**品牌限制**：部分国际品牌在 JD 禁运列表中，系统自动检查
+
+**PGA 管控**：部分商品（食品、药品等）受 PGA 管控，系统做关键词初筛
+
+**偏远邮编**：US 部分邮编为偏远无服务区域，JD 不提供服务
+
+### AI 发货决策树
+
+```
+卖家说"发货" → 查 getRates
+  ├── 有可用方案 → AskUserQuestion 展示方案让卖家选择
+  ├── JD 无方案但有 EasyShip → 告知原因，建议使用其他物流或手动发货
+  └── 全部无方案 → 告知原因 + 建议手动发货
+```
+
 ## 不确定用什么命令？
 
 运行 `logistics --help` 查看所有子命令。

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

@@ -45,10 +45,28 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 
 | shipping_mode_used | 含义 | 发货方式 |
 |--------------------|------|----------|
-| `easyship` | 买家选择了动态运费快递 | 可选自动发货 或 手动发货 |
-| `fixed` | 买家使用固定运费 | 只能手动发货 |
-| `free` | 全球免运费 | 只能手动发货 |
-| 空/null | 历史订单 | 只能手动发货 |
+| `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>`：手动发货
 
 #### 发货决策规则（必须严格遵守）
 
@@ -60,30 +78,35 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 
 **步骤3**：根据字段值决定下一步操作：
 
-- **如果 `shipping_mode_used = "easyship"`**：
+- **如果 `shipping_mode_used = "easyship"`（DYNAMIC 订单）**：
   1. **必须**使用 AskUserQuestion 工具询问用户
-  2. 提供两个选项让用户选择
+  2. 提供三个选项：使用买家方案（--auto）、选择其他方案（--rate-id）、手动发货（--tracking）
   3. **禁止**直接询问运单号
   4. 等待用户选择后再执行对应命令
 
 - **如果 `shipping_mode_used = "fixed"` 或 `"free"` 或字段为空**：
-  1. 询问用户提供运单号。快递公司名称为**可选**，如果用户未提供，后端会根据运单号自动检测
-  2. 用户提供运单号后即可执行发货命令，无需等待用户补充 carrier
-  3. **即使用户提供了快递公司名称，发货时也统一不传 carrier**，让后端根据运单号自动检测并存储准确的快递公司名称（人类可读，如 "SF Express"、"UPS"）。发货成功后对比响应中的 carrier 与用户所说的：
+  1. **必须**使用 AskUserQuestion 工具询问用户
+  2. 提供两个选项：使用系统物流（--rate-id）、手动发货（--tracking）
+  3. 如果用户选择系统物流，先 `logistics rates query` 查报价，再用 AskUserQuestion 展示可用方案
+  4. 如果用户选择手动发货：询问运单号，快递公司名称为**可选**
+  5. **即使用户提供了快递公司名称，发货时也统一不传 carrier**，让后端根据运单号自动检测并存储准确的快递公司名称（人类可读，如 "SF Express"、"UPS"）。发货成功后对比响应中的 carrier 与用户所说的：
      - 一致 → 正常告知
      - 不一致 → 告知用户："您提供的是 XX，系统根据运单号识别为 YY，已按识别结果记录。如有误请告知。"
 
-#### Easyship 自动发货
+#### 系统物流发货
 
-**适用场景**：`shipping_mode_used = "easyship"` 且用户选择使用 Easyship
+**适用场景**：任意 shipping_mode_used，用户选择使用系统物流
 
 **命令**：
 ```bash
-# 使用买家选择的快递（推荐）
+# DYNAMIC 订单 — 使用买家选择的快递（推荐）
 commerce order ship --id <order-id> --auto
 
-# 或指定其他 Easyship 支持的快递
+# 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>
 ```
 
 **返回结果包含**：
@@ -95,7 +118,7 @@ commerce order ship --id <order-id> --auto --courier-id <courier-id>
 
 **运单标签处理（重要）**：
 
-运单标签是用户必须打印并贴在包裹上的快递单。Easyship 生成标签需要几秒到几分钟。
+运单标签是用户必须打印并贴在包裹上的快递单。物流服务生成标签需要几秒到几分钟。
 
 **发货后根据 label_state 处理**：
 
@@ -103,11 +126,11 @@ commerce order ship --id <order-id> --auto --courier-id <courier-id>
 |-------------|------|----------|
 | `generated` / `printed` | 标签已生成 | 提供 `label_url` 让用户下载打印 |
 | `pending` / `generating` | 标签生成中 | 告知用户「标签正在生成，稍后可以让我帮你查询」 |
-| `failed` / `technical_failed` | 生成失败 | 告知用户需要检查 EasyShip 后台或重新发货 |
+| `failed` / `technical_failed` | 生成失败 | 告知用户需要检查物流服务后台或重新发货 |
 
 **查询标签状态**：
 
-如果发货时 label_state 为 pending/generating，稍后使用 `order refresh-label` 从 Easyship 同步最新状态：
+如果发货时 label_state 为 pending/generating，稍后使用 `order refresh-label` 同步最新状态：
 ```bash
 commerce order refresh-label --id <order-id>
 ```
@@ -166,64 +189,68 @@ commerce order mark-delivered --id <order-id>
 
 #### 发货场景示例对话
 
-**场景1：Easyship 订单**
+**场景1：DYNAMIC 订单（买家已选物流方案）**
 ```
 用户：订单 order_abc 发货
 
 助手：[执行 Bash: commerce order get --id order_abc]
-      [发现 shipping_mode_used = "easyship"]
+      [发现 shipping_mode_used = "easyship"，有 selected_courier_id]
       [使用 AskUserQuestion 工具]
 
 AskUserQuestion:
-  question: "该订单使用 Easyship 运费模式，请选择发货方式"
+  question: "该订单买家已选择物流方案，请选择发货方式"
   options:
-    - label: "Easyship 自动发货（推荐）"
-      description: "自动生成运单号和标签，使用买家选择的快递"
+    - label: "使用买家选择的物流方案（推荐）"
+      description: "自动生成运单号和标签，使用买家 checkout 时选的快递"
+    - label: "选择其他系统物流方案"
+      description: "查询可用物流方案，选择后创建运单"
     - label: "手动填写运单号"
-      description: "使用其他快递公司，需要提供运单号"
+      description: "自己处理物流，需要提供运单号"
 
-用户：[选择 Easyship 自动发货]
+用户：[选择使用买家方案]
 
 助手：[执行 Bash: commerce order ship --id order_abc --auto]
       [检查返回结果中的 label_state]
-
-      [情况A：label_state = "generated"，有 label_url]
-      发货成功！运单号 ES123456789，快递公司 FedEx。
-      运单标签已生成，请下载打印后贴在包裹上：https://...
-      物流信息同步中，稍后可以让我帮你查询物流状态。
-
-      [情况B：label_state = "pending" 或 "generating"]
       发货成功！运单号 ES123456789，快递公司 FedEx。
-      运单标签正在生成中，稍后可以让我帮你查询标签和物流状态。
-
-用户：标签好了吗
-
-助手：[执行 Bash: commerce order refresh-label --id order_abc]
-      [检查返回结果中的 label_state 和 label_url]
-
-      [情况A：label_state = "generated"，有 label_url]
       运单标签已生成，请下载打印后贴在包裹上：https://...
-
-      [情况B：label_state 仍为 "pending" 或 "generating"]
-      运单标签仍在生成中，请稍后再试。
 ```
 
-**场景2：固定运费/免运费订单（手动发货）**
+**场景2：FREE/FIXED 订单（使用系统物流）**
 ```
 用户：订单 order_xyz 发货
 
 助手：[执行 Bash: commerce order get --id order_xyz]
-      [发现 shipping_mode_used = "fixed" 或 "free"]
-      请提供运单号（快递公司可选，系统会自动识别）。
+      [发现 shipping_mode_used = "fixed"，无 selected_courier_id]
+      [使用 AskUserQuestion 工具]
 
-用户：单号 SF123456
+AskUserQuestion:
+  question: "该订单使用固定运费模式，请选择发货方式"
+  options:
+    - label: "使用系统物流"
+      description: "查询可用物流方案，选择后自动创建运单和标签"
+    - label: "手动填写运单号"
+      description: "自己处理物流，需要提供运单号"
 
-助手：[执行 Bash: commerce order ship --id order_xyz --tracking SF123456]
-      发货成功！运单号 SF123456，快递公司顺丰速运（自动识别）。
-      随时可以让我帮你查询物流状态。
+用户：[选择系统物流]
+
+助手：[执行 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：用户直接提供运单号发货**
+**场景3：手动发货（用户直接提供运单号）**
 ```
 用户：订单 order_abc 发货，单号 YT9876543210
 
@@ -365,16 +392,14 @@ commerce order list --status paid --limit 50
 # 步骤1：先获取订单信息，检查 shipping_mode_used
 commerce order get --id order_123
 
-# 步骤2a：如果 shipping_mode_used = "easyship"，询问用户选择后
-# 用户选择 Easyship 自动发货
+# DYNAMIC 订单 — 使用买家选择的方案
 commerce order ship --id order_123 --auto
 
-# 步骤2b：如果用户选择手动发货，或 shipping_mode_used = "fixed"/"free"
-# 只需提供运单号，carrier 可选
-commerce order ship --id order_123 --tracking DHL123456
+# 任意模式 — 指定物流方案（先查 logistics rates query 获取 rate-id）
+commerce order ship --id order_123 --rate-id rate_abc123
 
-# 或同时指定 carrier
-commerce order ship --id order_123 --tracking DHL123456 --carrier DHL
+# 手动发货 — 只需提供运单号，carrier 可选
+commerce order ship --id order_123 --tracking DHL123456
 ```
 
 ### 取消订单

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

@@ -335,6 +335,19 @@ commerce product add-images --id prod_123 --media-id media_red,media_blue
 commerce product get --id prod_123
 ```
 
+### 物流属性引导（物理产品）
+
+创建 `requires_shipping: true` 的物理产品时：
+
+1. **重量**：引导卖家填写准确重量（影响所有物流报价准确性）
+2. **cargo_type**：根据产品标题/描述自动推断（默认 general），向卖家确认
+   - 推断方式："根据产品信息，我推断这是普通商品，对吗？"（不要直接问"含电池吗？"）
+   - 可选值：general（普货）、battery（带电）、liquid（液体）、cosmetic（化妆品）、clothing（服装）、powder（粉末）、wood（木制品）
+   - 这是通用物流属性，不需要提及任何具体物流商
+3. **brand**：引导填写品牌（可选，用于物流限制检查）
+4. 用户可跳过，但告知"会影响物流方案选择和报价准确性"
+5. 数字产品跳过整个物流属性流程
+
 ## 重要提示
 
 - **国际化策略** - 平台默认语言是英文（en-US）。当用户同时提供中英文内容时，用英文创建商品，中文通过 `i18n` skill 添加翻译。当用户要求"国际化"时，确保英文在主表，其他语言通过 i18n 添加。详见 i18n skill。

package/dist/src/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/system-prompt.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,IAAI,MAAM,CAkKxC"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/system-prompt.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,IAAI,MAAM,CA6KxC"}

package/dist/src/system-prompt.js

@@ -74,6 +74,17 @@ export function getSystemPrompt() {
   4. 3 次均失败后，告知用户："认证已过期，请刷新页面后重试"，**停止重试**
 - 不要尝试通过 login/logout 修复认证问题
 
+## 额度不足处理
+
+当工具返回 \`INSUFFICIENT_CREDITS\` 错误时：
+- 告知用户当前积分不足，无法完成本次操作
+- 引导用户查看用量明细：[查看用量明细](action://usage)
+- 告知用户可以**购买积分**或**升级计划**来获取更多额度
+- **不要重试**，等用户充值后再操作
+
+**回复示例**：
+- "积分不足，无法生成图片。您可以 [查看用量明细](action://usage) 了解当前额度，通过购买积分或升级计划来继续使用。"
+
 ## 链接处理规则
 
 当用户发送电商平台链接时，**不要用 WebFetch 访问**（会被反爬拦截），先用 Skill 工具加载对应技能，再按技能中的 URL 解析规则执行命令：

package/dist/src/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/system-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,OAAO,GAAG,GAAG,CAAC,kBAAkB,CAAC,OAAO,EAAE;QAC9C,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,SAAS;QACd,OAAO,EAAE,MAAM;KAChB,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,GAAG,CAAC,kBAAkB,CAAC,OAAO,EAAE;QAC9C,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;KAClB,CAAC,CAAC;IAEH,OAAO;;;;;;;;;aASI,OAAO,IAAI,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2I9B,CAAC;AACF,CAAC"}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/system-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,OAAO,GAAG,GAAG,CAAC,kBAAkB,CAAC,OAAO,EAAE;QAC9C,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,SAAS;QACd,OAAO,EAAE,MAAM;KAChB,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,GAAG,CAAC,kBAAkB,CAAC,OAAO,EAAE;QAC9C,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,SAAS;KAClB,CAAC,CAAC;IAEH,OAAO;;;;;;;;;aASI,OAAO,IAAI,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJ9B,CAAC;AACF,CAAC"}

package/package.json

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