@optima-chat/optima-agent 0.8.21 → 0.8.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -12,7 +12,7 @@ Shopify 集成模块，用于连接和管理用户的 Shopify 店铺。
|
|
|
12
12
|
## 典型场景
|
|
13
13
|
|
|
14
14
|
当用户说：
|
|
15
|
-
- "连接我的 Shopify 店铺" →
|
|
15
|
+
- "连接我的 Shopify 店铺" → 使用下方「连接 Shopify 店铺流程（AI Shell）」
|
|
16
16
|
- "查看我连接了哪些 Shopify 店铺" → `shopify auth stores`
|
|
17
17
|
- "看看 Shopify 上有哪些商品" → `shopify product list --store <storeId>`
|
|
18
18
|
- "把 Shopify 商品同步过来" → `shopify product sync --store <storeId>`
|
|
@@ -27,7 +27,7 @@ Shopify 集成模块，用于连接和管理用户的 Shopify 店铺。
|
|
|
27
27
|
|
|
28
28
|
| 用户需求 | 推荐命令 | 关键注意点 |
|
|
29
29
|
|---------|---------|-----------|
|
|
30
|
-
| 连接 Shopify 店铺 |
|
|
30
|
+
| 连接 Shopify 店铺 | 见下方 AI Shell 连接流程 | 两步式：获取 URL → 轮询状态 |
|
|
31
31
|
| 查看已连接店铺 | `shopify auth stores` | 显示所有已连接店铺 |
|
|
32
32
|
| 断开 Shopify 店铺 | `shopify auth stores --disconnect <storeId>` | 不可逆操作，需确认 |
|
|
33
33
|
| 浏览 Shopify 商品 | `shopify product list --store <id>` | 可用 --status 过滤 |
|
|
@@ -55,24 +55,81 @@ shopify auth stores
|
|
|
55
55
|
|
|
56
56
|
如果用户只连接了一个店铺，可以从输出中直接取 storeId。
|
|
57
57
|
|
|
58
|
-
## 连接 Shopify
|
|
58
|
+
## 连接 Shopify 店铺流程（AI Shell）
|
|
59
|
+
|
|
60
|
+
**重要**：在 AI Shell 环境中，**必须使用两步式流程**（`--url-only` + `auth check`），不要使用默认的 `auth login`（会阻塞等待浏览器授权）。
|
|
61
|
+
|
|
62
|
+
### 步骤 1：获取授权 URL
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
shopify auth login --shop mystore.myshopify.com --url-only
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
返回 JSON 包含 `installUrl` 和 `state`。
|
|
69
|
+
|
|
70
|
+
### 步骤 2：展示链接给用户
|
|
71
|
+
|
|
72
|
+
将 `installUrl` 作为**可点击的 Markdown 链接**展示给用户，例如：
|
|
73
|
+
|
|
74
|
+
> 请点击以下链接授权您的 Shopify 店铺：
|
|
75
|
+
> [授权 mystore.myshopify.com](https://mystore.myshopify.com/admin/oauth/authorize?...)
|
|
76
|
+
> 我会自动检测授权状态，请在浏览器中完成授权。
|
|
77
|
+
|
|
78
|
+
### 步骤 3：自动轮询授权状态
|
|
79
|
+
|
|
80
|
+
展示链接后，**立即开始轮询**，不需要等待用户回复：
|
|
59
81
|
|
|
60
82
|
```bash
|
|
61
|
-
#
|
|
62
|
-
shopify auth
|
|
83
|
+
# 等待 15 秒后检查
|
|
84
|
+
sleep 15 && shopify auth check --state <state值>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
根据返回结果：
|
|
88
|
+
- `completed: true` → 授权成功，展示店铺信息
|
|
89
|
+
- `completed: false, expired: false` → 尚未完成，继续等 15 秒再查
|
|
90
|
+
- `completed: false, expired: true` → 已过期，提示用户重新连接
|
|
91
|
+
|
|
92
|
+
**轮询规则**：
|
|
93
|
+
- 每次间隔 **15 秒**
|
|
94
|
+
- 最多轮询 **20 次**（5 分钟）
|
|
95
|
+
- 每 3-4 次轮询时告知用户："⏳ 仍在等待授权..."
|
|
96
|
+
- 超时后告知用户："授权超时，请重试"
|
|
97
|
+
|
|
98
|
+
### 完整示例对话
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
用户：连接我的 Shopify 店铺 cool-gadgets.myshopify.com
|
|
102
|
+
|
|
103
|
+
AI：[执行 Bash: shopify auth login --shop cool-gadgets.myshopify.com --url-only]
|
|
104
|
+
→ 获取到 installUrl 和 state
|
|
105
|
+
|
|
106
|
+
请点击以下链接授权您的 Shopify 店铺：
|
|
107
|
+
[授权 cool-gadgets.myshopify.com](https://cool-gadgets.myshopify.com/admin/oauth/authorize?...)
|
|
108
|
+
我会自动检测授权状态。
|
|
109
|
+
|
|
110
|
+
[执行 Bash: sleep 15 && shopify auth check --state abc123]
|
|
111
|
+
→ completed: false
|
|
112
|
+
|
|
113
|
+
[执行 Bash: sleep 15 && shopify auth check --state abc123]
|
|
114
|
+
→ completed: false
|
|
115
|
+
|
|
116
|
+
⏳ 仍在等待授权...
|
|
63
117
|
|
|
64
|
-
|
|
65
|
-
|
|
118
|
+
[执行 Bash: sleep 15 && shopify auth check --state abc123]
|
|
119
|
+
→ completed: true, store: { shopName: "Cool Gadgets", ... }
|
|
66
120
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
121
|
+
✅ 已成功连接 Shopify 店铺！
|
|
122
|
+
- 店铺：Cool Gadgets
|
|
123
|
+
- 域名：cool-gadgets.myshopify.com
|
|
124
|
+
- 邮箱：owner@example.com
|
|
70
125
|
```
|
|
71
126
|
|
|
72
127
|
## 命令参考
|
|
73
128
|
|
|
74
129
|
### 认证和店铺管理
|
|
75
|
-
- `shopify auth login --shop <domain>` - 连接 Shopify
|
|
130
|
+
- `shopify auth login --shop <domain>` - 连接 Shopify 店铺（有浏览器环境）
|
|
131
|
+
- `shopify auth login --shop <domain> --url-only` - 获取授权 URL（AI Shell/无头环境）
|
|
132
|
+
- `shopify auth check --state <state>` - 检查 OAuth 授权状态（单次检查）
|
|
76
133
|
- `shopify auth status` - 查看认证状态
|
|
77
134
|
- `shopify auth stores` - 列出已连接店铺
|
|
78
135
|
- `shopify auth stores --info <storeId>` - 查看店铺实时信息
|
|
@@ -220,6 +277,6 @@ shopify analytics query --store abc123 \
|
|
|
220
277
|
- 所有命令都需要 `--store <storeId>` 参数，先用 `shopify auth stores` 获取
|
|
221
278
|
- 商品/订单/库存同步是从 **Shopify → Optima** 方向
|
|
222
279
|
- 折扣码在 **Shopify 平台**上创建和管理
|
|
223
|
-
- 连接店铺需要浏览器交互（OAuth
|
|
280
|
+
- 连接店铺需要浏览器交互（OAuth 授权），在 AI Shell 中使用 `--url-only` + `auth check` 两步式流程
|
|
224
281
|
- 断开店铺是软删除，不会影响 Shopify 上的数据
|
|
225
282
|
- 使用 `--help` 查看命令详细参数
|
package/package.json
CHANGED