@optima-chat/optima-agent 0.9.13 → 0.9.15

package/.claude/skills/shopify/SKILL.md

@@ -1,282 +1,282 @@
----
-name: shopify
-description: Shopify store integration for Optima Commerce. Connect Shopify stores, sync products/orders/inventory/customers, manage collections, discounts, draft orders, refunds, webhooks, markets, and analytics. Use when user mentions Shopify, wants to connect a Shopify store, or manage Shopify-related operations.
----
-
-# Shopify CLI - Shopify 店铺集成管理
-
-Shopify 集成模块，用于连接和管理用户的 Shopify 店铺。
-
-**重要**：这里管理的是用户在 Shopify 平台上的店铺，不是 Optima 自有店铺。用户可以将 Shopify 店铺连接到 Optima，实现跨平台管理。
-
-## 典型场景
-
-当用户说：
-- "连接我的 Shopify 店铺" → 使用下方「连接 Shopify 店铺流程（AI Shell）」
-- "查看我连接了哪些 Shopify 店铺" → `shopify auth stores`
-- "看看 Shopify 上有哪些商品" → `shopify product list --store <storeId>`
-- "把 Shopify 商品同步过来" → `shopify product sync --store <storeId>`
-- "查看 Shopify 订单" → `shopify order list --store <storeId>`
-- "Shopify 订单发货" → `shopify order fulfill --store <storeId> --order <orderId> --tracking <号码>`
-- "查看 Shopify 库存" → `shopify inventory list --store <storeId>`
-- "同步 Shopify 库存" → `shopify inventory sync --store <storeId>`
-- "创建 Shopify 折扣码" → `shopify discount create --store <storeId> --code SAVE10 --percentage 10`
-- "查看 Shopify 销售数据" → `shopify analytics report --store <storeId>`
-
-### 场景决策表
-
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 连接 Shopify 店铺 | 见下方 AI Shell 连接流程 | 两步式：获取 URL → 轮询状态 |
-| 查看已连接店铺 | `shopify auth stores` | 显示所有已连接店铺 |
-| 断开 Shopify 店铺 | `shopify auth stores --disconnect <storeId>` | 不可逆操作，需确认 |
-| 浏览 Shopify 商品 | `shopify product list --store <id>` | 可用 --status 过滤 |
-| 同步商品到 Optima | `shopify product sync --store <id>` | 从 Shopify 同步到 Optima |
-| 查看 Shopify 订单 | `shopify order list --store <id>` | 可用 --status 过滤 |
-| Shopify 订单发货 | `shopify order fulfill --store <id> --order <oid>` | 需要 tracking 号 |
-| 库存对比 | `shopify inventory compare --store <id>` | 对比 Shopify 和 Optima 库存差异 |
-| 客户同步 | `shopify customer sync --store <id>` | 同步客户数据到 Optima |
-| 创建折扣码 | `shopify discount create --store <id>` | 支持百分比和固定金额 |
-| 销售报表 | `shopify analytics report --store <id>` | ShopifyQL 数据分析 |
-
-## 使用前提
-
-1. 用户必须先登录 Optima（`optima auth login`）
-2. 然后连接 Shopify 店铺（`shopify auth login --shop <domain>`）
-3. 连接后通过 `--store <storeId>` 指定操作哪个店铺
-
-### 获取 storeId
-
-所有操作都需要 `--store <storeId>` 参数，先用 `shopify auth stores` 获取：
-
-```bash
-shopify auth stores
-```
-
-如果用户只连接了一个店铺，可以从输出中直接取 storeId。
-
-## 连接 Shopify 店铺流程（AI Shell）
-
-**重要**：在 AI Shell 环境中，**必须使用两步式流程**（`--url-only` + `auth check`），不要使用默认的 `auth login`（会阻塞等待浏览器授权）。
-
-### 步骤 1：获取授权 URL
-
-```bash
-shopify auth login --shop mystore.myshopify.com --url-only
-```
-
-返回 JSON 包含 `installUrl` 和 `state`。
-
-### 步骤 2：展示链接给用户
-
-将 `installUrl` 作为**可点击的 Markdown 链接**展示给用户，例如：
-
-> 请点击以下链接授权您的 Shopify 店铺：
-> [授权 mystore.myshopify.com](https://mystore.myshopify.com/admin/oauth/authorize?...)
-> 我会自动检测授权状态，请在浏览器中完成授权。
-
-### 步骤 3：自动轮询授权状态
-
-展示链接后，**立即开始轮询**，不需要等待用户回复：
-
-```bash
-# 等待 15 秒后检查
-sleep 15 && shopify auth check --state <state值>
-```
-
-根据返回结果：
-- `completed: true` → 授权成功，展示店铺信息
-- `completed: false, expired: false` → 尚未完成，继续等 15 秒再查
-- `completed: false, expired: true` → 已过期，提示用户重新连接
-
-**轮询规则**：
-- 每次间隔 **15 秒**
-- 最多轮询 **20 次**（5 分钟）
-- 每 3-4 次轮询时告知用户："⏳ 仍在等待授权..."
-- 超时后告知用户："授权超时，请重试"
-
-### 完整示例对话
-
-```
-用户：连接我的 Shopify 店铺 cool-gadgets.myshopify.com
-
-AI：[执行 Bash: shopify auth login --shop cool-gadgets.myshopify.com --url-only]
-    → 获取到 installUrl 和 state
-
-    请点击以下链接授权您的 Shopify 店铺：
-    [授权 cool-gadgets.myshopify.com](https://cool-gadgets.myshopify.com/admin/oauth/authorize?...)
-    我会自动检测授权状态。
-
-    [执行 Bash: sleep 15 && shopify auth check --state abc123]
-    → completed: false
-
-    [执行 Bash: sleep 15 && shopify auth check --state abc123]
-    → completed: false
-
-    ⏳ 仍在等待授权...
-
-    [执行 Bash: sleep 15 && shopify auth check --state abc123]
-    → completed: true, store: { shopName: "Cool Gadgets", ... }
-
-    ✅ 已成功连接 Shopify 店铺！
-    - 店铺：Cool Gadgets
-    - 域名：cool-gadgets.myshopify.com
-    - 邮箱：owner@example.com
-```
-
-## 命令参考
-
-### 认证和店铺管理
-- `shopify auth login --shop <domain>` - 连接 Shopify 店铺（有浏览器环境）
-- `shopify auth login --shop <domain> --url-only` - 获取授权 URL（AI Shell/无头环境）
-- `shopify auth check --state <state>` - 检查 OAuth 授权状态（单次检查）
-- `shopify auth status` - 查看认证状态
-- `shopify auth stores` - 列出已连接店铺
-- `shopify auth stores --info <storeId>` - 查看店铺实时信息
-- `shopify auth stores --disconnect <storeId>` - 断开店铺连接
-
-### 商品管理
-- `shopify product list --store <id>` - 商品列表
-- `shopify product get --store <id> --product <pid>` - 商品详情
-- `shopify product search --store <id> --query <关键词>` - 搜索商品
-- `shopify product sync --store <id>` - 同步商品到 Optima
-- `shopify product publish --store <id> --product <pid>` - 发布商品到销售渠道
-- `shopify product mapping --store <id>` - 查看 Shopify↔Optima 商品映射
-
-### 订单管理
-- `shopify order list --store <id>` - 订单列表
-- `shopify order get --store <id> --order <oid>` - 订单详情
-- `shopify order fulfill --store <id> --order <oid> --tracking <号码>` - 订单发货
-- `shopify order sync --store <id>` - 同步订单到 Optima
-
-### 库存管理
-- `shopify inventory list --store <id>` - 库存列表
-- `shopify inventory get --store <id> --product <pid>` - 查看商品库存
-- `shopify inventory adjust --store <id> --item <itemId> --delta <数量>` - 调整库存
-- `shopify inventory sync --store <id>` - 同步库存
-- `shopify inventory compare --store <id>` - 对比 Shopify/Optima 库存差异
-- `shopify inventory locations --store <id>` - 查看库存位置
-
-### 位置管理
-- `shopify location list --store <id>` - 仓库/位置列表
-- `shopify location get --store <id> --location <lid>` - 位置详情
-
-### 集合管理
-- `shopify collection list --store <id>` - 集合列表
-- `shopify collection get --store <id> --collection <cid>` - 集合详情
-- `shopify collection create --store <id> --title <名称>` - 创建集合
-- `shopify collection add --store <id> --collection <cid> --products <pid1,pid2>` - 添加商品到集合
-
-### 客户管理
-- `shopify customer list --store <id>` - 客户列表
-- `shopify customer get --store <id> --customer <cid>` - 客户详情
-- `shopify customer sync --store <id>` - 同步客户到 Optima
-
-### 折扣管理
-- `shopify discount list --store <id>` - 折扣列表
-- `shopify discount get --store <id> --discount <did>` - 折扣详情
-- `shopify discount create --store <id>` - 创建折扣码
-- `shopify discount delete --store <id> --discount <did>` - 删除折扣
-
-### 草稿订单
-- `shopify draft-order list --store <id>` - 草稿订单列表
-- `shopify draft-order get --store <id> --draft-order <did>` - 草稿订单详情
-- `shopify draft-order create --store <id>` - 创建草稿订单
-- `shopify draft-order complete --store <id> --draft-order <did>` - 完成草稿订单
-- `shopify draft-order delete --store <id> --draft-order <did>` - 删除草稿订单
-
-### 退款管理
-- `shopify refund list --store <id> --order <oid>` - 退款列表
-- `shopify refund create --store <id> --order <oid>` - 创建退款
-
-### 市场管理
-- `shopify market list --store <id>` - 市场列表
-- `shopify market get --store <id> --market <mid>` - 市场详情
-
-### 数据分析
-- `shopify analytics report --store <id>` - 销售报表
-- `shopify analytics query --store <id> --query <ShopifyQL>` - 自定义 ShopifyQL 查询
-
-### Webhook 管理
-- `shopify webhook list --store <id>` - 已订阅的 webhook
-- `shopify webhook subscribe --store <id> --topic <topic>` - 订阅 webhook
-- `shopify webhook unsubscribe --store <id> --subscription <sid>` - 取消订阅
-
-## 详细示例
-
-### 连接店铺并查看商品
-```bash
-# 连接 Shopify 店铺
-shopify auth login --shop my-cool-store.myshopify.com
-
-# 查看已连接店铺，获取 storeId
-shopify auth stores
-
-# 查看商品列表
-shopify product list --store abc123
-
-# 搜索特定商品
-shopify product search --store abc123 --query "T-shirt"
-```
-
-### 同步商品和库存
-```bash
-# 将 Shopify 商品同步到 Optima Commerce
-shopify product sync --store abc123
-
-# 查看商品映射关系
-shopify product mapping --store abc123
-
-# 对比两个平台的库存差异
-shopify inventory compare --store abc123
-
-# 同步库存
-shopify inventory sync --store abc123
-```
-
-### 订单发货
-```bash
-# 查看待发货订单
-shopify order list --store abc123 --status unfulfilled
-
-# 查看订单详情
-shopify order get --store abc123 --order order_456
-
-# 发货（提供 tracking 号码）
-shopify order fulfill --store abc123 --order order_456 \
-  --tracking SF1234567890
-```
-
-### 创建折扣码
-```bash
-# 创建 10% 折扣码
-shopify discount create --store abc123 \
-  --code SAVE10 \
-  --percentage 10 \
-  --title "新年促销 10% off"
-
-# 创建固定金额折扣
-shopify discount create --store abc123 \
-  --code FLAT20 \
-  --amount 20 \
-  --title "满减优惠 $20 off"
-```
-
-### 销售数据分析
-```bash
-# 生成销售报表
-shopify analytics report --store abc123
-
-# 自定义 ShopifyQL 查询
-shopify analytics query --store abc123 \
-  --query "FROM orders SHOW sum(total_price) GROUP BY day SINCE -30d"
-```
-
-## 重要提示
-
-- 所有命令都需要 `--store <storeId>` 参数，先用 `shopify auth stores` 获取
-- 商品/订单/库存同步是从 **Shopify → Optima** 方向
-- 折扣码在 **Shopify 平台**上创建和管理
-- 连接店铺需要浏览器交互（OAuth 授权），在 AI Shell 中使用 `--url-only` + `auth check` 两步式流程
-- 断开店铺是软删除，不会影响 Shopify 上的数据
-- 使用 `--help` 查看命令详细参数
+---
+name: shopify
+description: Shopify store integration for Optima Commerce. Connect Shopify stores, sync products/orders/inventory/customers, manage collections, discounts, draft orders, refunds, webhooks, markets, and analytics. Use when user mentions Shopify, wants to connect a Shopify store, or manage Shopify-related operations.
+---
+
+# Shopify CLI - Shopify 店铺集成管理
+
+Shopify 集成模块，用于连接和管理用户的 Shopify 店铺。
+
+**重要**：这里管理的是用户在 Shopify 平台上的店铺，不是 Optima 自有店铺。用户可以将 Shopify 店铺连接到 Optima，实现跨平台管理。
+
+## 典型场景
+
+当用户说：
+- "连接我的 Shopify 店铺" → 使用下方「连接 Shopify 店铺流程（AI Shell）」
+- "查看我连接了哪些 Shopify 店铺" → `shopify auth stores`
+- "看看 Shopify 上有哪些商品" → `shopify product list --store <storeId>`
+- "把 Shopify 商品同步过来" → `shopify product sync --store <storeId>`
+- "查看 Shopify 订单" → `shopify order list --store <storeId>`
+- "Shopify 订单发货" → `shopify order fulfill --store <storeId> --order <orderId> --tracking <号码>`
+- "查看 Shopify 库存" → `shopify inventory list --store <storeId>`
+- "同步 Shopify 库存" → `shopify inventory sync --store <storeId>`
+- "创建 Shopify 折扣码" → `shopify discount create --store <storeId> --code SAVE10 --percentage 10`
+- "查看 Shopify 销售数据" → `shopify analytics report --store <storeId>`
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 连接 Shopify 店铺 | 见下方 AI Shell 连接流程 | 两步式：获取 URL → 轮询状态 |
+| 查看已连接店铺 | `shopify auth stores` | 显示所有已连接店铺 |
+| 断开 Shopify 店铺 | `shopify auth stores --disconnect <storeId>` | 不可逆操作，需确认 |
+| 浏览 Shopify 商品 | `shopify product list --store <id>` | 可用 --status 过滤 |
+| 同步商品到 Optima | `shopify product sync --store <id>` | 从 Shopify 同步到 Optima |
+| 查看 Shopify 订单 | `shopify order list --store <id>` | 可用 --status 过滤 |
+| Shopify 订单发货 | `shopify order fulfill --store <id> --order <oid>` | 需要 tracking 号 |
+| 库存对比 | `shopify inventory compare --store <id>` | 对比 Shopify 和 Optima 库存差异 |
+| 客户同步 | `shopify customer sync --store <id>` | 同步客户数据到 Optima |
+| 创建折扣码 | `shopify discount create --store <id>` | 支持百分比和固定金额 |
+| 销售报表 | `shopify analytics report --store <id>` | ShopifyQL 数据分析 |
+
+## 使用前提
+
+1. 用户必须先登录 Optima（`optima auth login`）
+2. 然后连接 Shopify 店铺（`shopify auth login --shop <domain>`）
+3. 连接后通过 `--store <storeId>` 指定操作哪个店铺
+
+### 获取 storeId
+
+所有操作都需要 `--store <storeId>` 参数，先用 `shopify auth stores` 获取：
+
+```bash
+shopify auth stores
+```
+
+如果用户只连接了一个店铺，可以从输出中直接取 storeId。
+
+## 连接 Shopify 店铺流程（AI Shell）
+
+**重要**：在 AI Shell 环境中，**必须使用两步式流程**（`--url-only` + `auth check`），不要使用默认的 `auth login`（会阻塞等待浏览器授权）。
+
+### 步骤 1：获取授权 URL
+
+```bash
+shopify auth login --shop mystore.myshopify.com --url-only
+```
+
+返回 JSON 包含 `installUrl` 和 `state`。
+
+### 步骤 2：展示链接给用户
+
+将 `installUrl` 作为**可点击的 Markdown 链接**展示给用户，例如：
+
+> 请点击以下链接授权您的 Shopify 店铺：
+> [授权 mystore.myshopify.com](https://mystore.myshopify.com/admin/oauth/authorize?...)
+> 我会自动检测授权状态，请在浏览器中完成授权。
+
+### 步骤 3：自动轮询授权状态
+
+展示链接后，**立即开始轮询**，不需要等待用户回复：
+
+```bash
+# 等待 15 秒后检查
+sleep 15 && shopify auth check --state <state值>
+```
+
+根据返回结果：
+- `completed: true` → 授权成功，展示店铺信息
+- `completed: false, expired: false` → 尚未完成，继续等 15 秒再查
+- `completed: false, expired: true` → 已过期，提示用户重新连接
+
+**轮询规则**：
+- 每次间隔 **15 秒**
+- 最多轮询 **20 次**（5 分钟）
+- 每 3-4 次轮询时告知用户："⏳ 仍在等待授权..."
+- 超时后告知用户："授权超时，请重试"
+
+### 完整示例对话
+
+```
+用户：连接我的 Shopify 店铺 cool-gadgets.myshopify.com
+
+AI：[执行 Bash: shopify auth login --shop cool-gadgets.myshopify.com --url-only]
+    → 获取到 installUrl 和 state
+
+    请点击以下链接授权您的 Shopify 店铺：
+    [授权 cool-gadgets.myshopify.com](https://cool-gadgets.myshopify.com/admin/oauth/authorize?...)
+    我会自动检测授权状态。
+
+    [执行 Bash: sleep 15 && shopify auth check --state abc123]
+    → completed: false
+
+    [执行 Bash: sleep 15 && shopify auth check --state abc123]
+    → completed: false
+
+    ⏳ 仍在等待授权...
+
+    [执行 Bash: sleep 15 && shopify auth check --state abc123]
+    → completed: true, store: { shopName: "Cool Gadgets", ... }
+
+    ✅ 已成功连接 Shopify 店铺！
+    - 店铺：Cool Gadgets
+    - 域名：cool-gadgets.myshopify.com
+    - 邮箱：owner@example.com
+```
+
+## 命令参考
+
+### 认证和店铺管理
+- `shopify auth login --shop <domain>` - 连接 Shopify 店铺（有浏览器环境）
+- `shopify auth login --shop <domain> --url-only` - 获取授权 URL（AI Shell/无头环境）
+- `shopify auth check --state <state>` - 检查 OAuth 授权状态（单次检查）
+- `shopify auth status` - 查看认证状态
+- `shopify auth stores` - 列出已连接店铺
+- `shopify auth stores --info <storeId>` - 查看店铺实时信息
+- `shopify auth stores --disconnect <storeId>` - 断开店铺连接
+
+### 商品管理
+- `shopify product list --store <id>` - 商品列表
+- `shopify product get --store <id> --product <pid>` - 商品详情
+- `shopify product search --store <id> --query <关键词>` - 搜索商品
+- `shopify product sync --store <id>` - 同步商品到 Optima
+- `shopify product publish --store <id> --product <pid>` - 发布商品到销售渠道
+- `shopify product mapping --store <id>` - 查看 Shopify↔Optima 商品映射
+
+### 订单管理
+- `shopify order list --store <id>` - 订单列表
+- `shopify order get --store <id> --order <oid>` - 订单详情
+- `shopify order fulfill --store <id> --order <oid> --tracking <号码>` - 订单发货
+- `shopify order sync --store <id>` - 同步订单到 Optima
+
+### 库存管理
+- `shopify inventory list --store <id>` - 库存列表
+- `shopify inventory get --store <id> --product <pid>` - 查看商品库存
+- `shopify inventory adjust --store <id> --item <itemId> --delta <数量>` - 调整库存
+- `shopify inventory sync --store <id>` - 同步库存
+- `shopify inventory compare --store <id>` - 对比 Shopify/Optima 库存差异
+- `shopify inventory locations --store <id>` - 查看库存位置
+
+### 位置管理
+- `shopify location list --store <id>` - 仓库/位置列表
+- `shopify location get --store <id> --location <lid>` - 位置详情
+
+### 集合管理
+- `shopify collection list --store <id>` - 集合列表
+- `shopify collection get --store <id> --collection <cid>` - 集合详情
+- `shopify collection create --store <id> --title <名称>` - 创建集合
+- `shopify collection add --store <id> --collection <cid> --products <pid1,pid2>` - 添加商品到集合
+
+### 客户管理
+- `shopify customer list --store <id>` - 客户列表
+- `shopify customer get --store <id> --customer <cid>` - 客户详情
+- `shopify customer sync --store <id>` - 同步客户到 Optima
+
+### 折扣管理
+- `shopify discount list --store <id>` - 折扣列表
+- `shopify discount get --store <id> --discount <did>` - 折扣详情
+- `shopify discount create --store <id>` - 创建折扣码
+- `shopify discount delete --store <id> --discount <did>` - 删除折扣
+
+### 草稿订单
+- `shopify draft-order list --store <id>` - 草稿订单列表
+- `shopify draft-order get --store <id> --draft-order <did>` - 草稿订单详情
+- `shopify draft-order create --store <id>` - 创建草稿订单
+- `shopify draft-order complete --store <id> --draft-order <did>` - 完成草稿订单
+- `shopify draft-order delete --store <id> --draft-order <did>` - 删除草稿订单
+
+### 退款管理
+- `shopify refund list --store <id> --order <oid>` - 退款列表
+- `shopify refund create --store <id> --order <oid>` - 创建退款
+
+### 市场管理
+- `shopify market list --store <id>` - 市场列表
+- `shopify market get --store <id> --market <mid>` - 市场详情
+
+### 数据分析
+- `shopify analytics report --store <id>` - 销售报表
+- `shopify analytics query --store <id> --query <ShopifyQL>` - 自定义 ShopifyQL 查询
+
+### Webhook 管理
+- `shopify webhook list --store <id>` - 已订阅的 webhook
+- `shopify webhook subscribe --store <id> --topic <topic>` - 订阅 webhook
+- `shopify webhook unsubscribe --store <id> --subscription <sid>` - 取消订阅
+
+## 详细示例
+
+### 连接店铺并查看商品
+```bash
+# 连接 Shopify 店铺
+shopify auth login --shop my-cool-store.myshopify.com
+
+# 查看已连接店铺，获取 storeId
+shopify auth stores
+
+# 查看商品列表
+shopify product list --store abc123
+
+# 搜索特定商品
+shopify product search --store abc123 --query "T-shirt"
+```
+
+### 同步商品和库存
+```bash
+# 将 Shopify 商品同步到 Optima Commerce
+shopify product sync --store abc123
+
+# 查看商品映射关系
+shopify product mapping --store abc123
+
+# 对比两个平台的库存差异
+shopify inventory compare --store abc123
+
+# 同步库存
+shopify inventory sync --store abc123
+```
+
+### 订单发货
+```bash
+# 查看待发货订单
+shopify order list --store abc123 --status unfulfilled
+
+# 查看订单详情
+shopify order get --store abc123 --order order_456
+
+# 发货（提供 tracking 号码）
+shopify order fulfill --store abc123 --order order_456 \
+  --tracking SF1234567890
+```
+
+### 创建折扣码
+```bash
+# 创建 10% 折扣码
+shopify discount create --store abc123 \
+  --code SAVE10 \
+  --percentage 10 \
+  --title "新年促销 10% off"
+
+# 创建固定金额折扣
+shopify discount create --store abc123 \
+  --code FLAT20 \
+  --amount 20 \
+  --title "满减优惠 $20 off"
+```
+
+### 销售数据分析
+```bash
+# 生成销售报表
+shopify analytics report --store abc123
+
+# 自定义 ShopifyQL 查询
+shopify analytics query --store abc123 \
+  --query "FROM orders SHOW sum(total_price) GROUP BY day SINCE -30d"
+```
+
+## 重要提示
+
+- 所有命令都需要 `--store <storeId>` 参数，先用 `shopify auth stores` 获取
+- 商品/订单/库存同步是从 **Shopify → Optima** 方向
+- 折扣码在 **Shopify 平台**上创建和管理
+- 连接店铺需要浏览器交互（OAuth 授权），在 AI Shell 中使用 `--url-only` + `auth check` 两步式流程
+- 断开店铺是软删除，不会影响 Shopify 上的数据
+- 使用 `--help` 查看命令详细参数