@optima-chat/optima-agent 0.7.1 → 0.7.3

package/.claude/settings.local.json

@@ -99,7 +99,9 @@
       "Bash(git checkout:*)",
       "Bash(npm test:*)",
       "Bash(git tag:*)",
-      "Bash(/private/tmp/claude/-Users-verypro-optima-agent/68a9ac2c-def2-44e1-b42b-e53bd9022ab6/scratchpad/test-canUseTool.sh)"
+      "Bash(/private/tmp/claude/-Users-verypro-optima-agent/68a9ac2c-def2-44e1-b42b-e53bd9022ab6/scratchpad/test-canUseTool.sh)",
+      "Bash(optima --help:*)",
+      "Bash(npx @optima-chat/ads-cli:*)"
     ],
     "deny": [],
     "ask": []

package/.claude/skills/ads/SKILL.md

@@ -1,94 +1,243 @@
 ---
 name: ads
-description: Google Ads 广告投放管理。创建广告系列、广告组、关键词，查看广告效果数据。当用户需要投放广告、管理 Google Ads、分析广告效果时使用此技能。
+description: Google Ads 广告投放管理。创建广告系列、广告组、关键词、广告，查看广告效果数据。当用户需要投放广告、管理 Google Ads、分析广告效果时使用此技能。
 ---
 
-# Google Ads CLI 使用指南
+# Google Ads CLI - 广告投放管理
 
-## 核心命令
+CLI 命令: `google-ads`（或 `ads`）
 
-### 账号管理
+## 首次使用
 
 ```bash
-# 创建账号
-google-ads account create --email your@gmail.com --name "公司名称"
-
-# 验证账号
+# 检查用户是否已授权 Google Ads 账号
 google-ads account check
-
-# 查看配置
-google-ads config show
 ```
 
-### 广告系列
+**返回状态**：
+- `status: "active"` → 已授权，可以开始使用
+- `status: "not_linked"` → 用户尚未授权 Google Ads，需引导用户在 Optima 平台完成 Google Ads 账号授权
+
+## 典型场景
+
+### 场景1：从零开始投放广告
+
+**用户说**："我想投放 Google 广告推广我的产品"
+
+**流程**: 创建广告系列 → 创建广告组 → 添加关键词 → 创建广告 → 启用
 
 ```bash
-# 列出广告系列
-google-ads campaign list
+# 1. 创建广告系列（每日预算 $50，默认 PAUSED）
+google-ads campaign create -n "产品推广" -b 50
+
+# 2. 创建广告组（CPC 出价 $2）
+google-ads ad-group create --campaign-id <campaign-id> -n "核心关键词组" --cpc-bid 2
 
-# 创建广告系列
-google-ads campaign create -n "广告系列名称" -b 50
+# 3. 添加关键词
+google-ads keyword add --ad-group-id <ad-group-id> -k "产品名称,品牌词,行业词"
 
-# 查看广告系列详情
-google-ads campaign get <campaign-id>
+# 4. 创建广告
+google-ads ad create \
+  --ad-group-id <ad-group-id> \
+  --headlines "优质产品,限时优惠,免费配送" \
+  --descriptions "高品质产品限时优惠中,立即下单享受专属折扣" \
+  --final-url "https://shop.example.com"
 
-# 暂停/启用广告系列
-google-ads campaign pause <campaign-id>
-google-ads campaign enable <campaign-id>
+# 5. 确认无误后启用
+google-ads campaign update --campaign-id <campaign-id> --status ENABLED
 ```
 
-### 广告组
+### 场景2：查看广告效果
+
+**用户说**："看看我的广告效果怎么样"
 
 ```bash
-# 列出广告组
-google-ads adgroup list --campaign-id <campaign-id>
+# 快速查看所有广告系列状态
+google-ads campaign list
 
-# 创建广告组
-google-ads adgroup create --campaign-id <campaign-id> -n "广告组名称"
+# 查看详细效果数据（GAQL 查询）
+google-ads query -q "
+  SELECT
+    campaign.name,
+    metrics.impressions,
+    metrics.clicks,
+    metrics.ctr,
+    metrics.average_cpc,
+    metrics.cost_micros,
+    metrics.conversions
+  FROM campaign
+  WHERE segments.date DURING LAST_7_DAYS
+  ORDER BY metrics.cost_micros DESC
+"
 ```
 
-### 关键词
+### 场景3：暂停/启用广告
+
+**用户说**："暂停那个效果不好的广告系列"
 
 ```bash
-# 列出关键词
-google-ads keyword list
+# 先查看列表确认 ID
+google-ads campaign list
+
+# 暂停广告系列
+google-ads campaign update --campaign-id <id> --status PAUSED
 
-# 添加关键词
-google-ads keyword add --adgroup-id <adgroup-id> -k "关键词1,关键词2"
+# 重新启用
+google-ads campaign update --campaign-id <id> --status ENABLED
 ```
 
-### 效果分析
+### 场景4：调整预算和出价
+
+**用户说**："把预算提高到 100 美元"
 
 ```bash
-# GAQL 查询
-google-ads query -q "SELECT campaign.id, campaign.name, metrics.impressions FROM campaign" --pretty
+# 更新广告系列预算
+google-ads campaign update --campaign-id <id> --budget 100
 
-# 查看效果报告
-google-ads report --campaign-id <campaign-id> --days 7
+# 更新广告组 CPC 出价
+google-ads ad-group update --ad-group-id <id> --cpc-bid 3
 ```
 
-## 典型流程
+### 场景5：添加新关键词
 
-### 创建新广告
+**用户说**："给广告添加一些新关键词"
 
 ```bash
-# 1. 创建广告系列
-google-ads campaign create -n "产品推广" -b 100
-# 获得 campaign_id
+# 先确认广告组 ID
+google-ads ad-group list
 
-# 2. 创建广告组
-google-ads adgroup create --campaign-id <campaign-id> -n "核心关键词组"
-# 获得 adgroup_id
+# 添加关键词（默认广泛匹配）
+google-ads keyword add --ad-group-id <id> -k "新关键词1,新关键词2"
 
-# 3. 添加关键词
-google-ads keyword add --adgroup-id <adgroup-id> -k "产品名称,品牌词,行业词"
+# 添加精确匹配关键词
+google-ads keyword add --ad-group-id <id> -k "精确词" --match-type EXACT
 
-# 4. 验证
-google-ads campaign list
+# 添加词组匹配关键词
+google-ads keyword add --ad-group-id <id> -k "词组匹配" --match-type PHRASE
 ```
 
-## 注意事项
+## 场景决策表
 
-- 所有命令默认 JSON 输出
-- 预算单位为美元
-- 新账号需要先设置账单信息才能投放广告
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 新建广告投放 | 完整流程（场景1） | 按顺序：系列→组→关键词→广告 |
+| 查看效果 | `campaign list` 或 GAQL | GAQL 获取详细指标 |
+| 暂停/启用 | `campaign update --status` | PAUSED 或 ENABLED |
+| 调整预算 | `campaign update --budget` | 单位美元 |
+| 调整出价 | `ad-group update --cpc-bid` | 单位美元 |
+| 添加关键词 | `keyword add` | 注意匹配类型 |
+| 删除广告 | `campaign delete` / `ad delete` | 不可恢复，建议先暂停 |
+
+## 自然语言映射
+
+当用户说：
+- "投放广告" / "创建广告" → 引导完整流程（场景1）
+- "广告效果" / "看看数据" → `campaign list` + GAQL
+- "暂停广告" → `campaign update --status PAUSED`
+- "启用广告" → `campaign update --status ENABLED`
+- "调整预算到 XX" → `campaign update --budget XX`
+- "添加关键词 XX" → `keyword add -k "XX"`
+- "删除广告" → 先确认，再执行删除
+
+## 关键概念
+
+### 广告层级结构
+
+```
+Account（账号）
+└── Campaign（广告系列）- 设置预算
+    └── Ad Group（广告组）- 设置出价
+        ├── Keywords（关键词）- 触发条件
+        └── Ads（广告）- 展示内容
+```
+
+### 状态说明
+
+| 状态 | 含义 |
+|------|------|
+| `ENABLED` | 正常投放中 |
+| `PAUSED` | 已暂停 |
+| `REMOVED` | 已删除 |
+
+### 关键词匹配类型
+
+| 类型 | 说明 |
+|------|------|
+| `BROAD` | 广泛匹配（默认） |
+| `PHRASE` | 词组匹配 |
+| `EXACT` | 精确匹配 |
+
+### RSA 广告要求
+
+- **标题**: 至少 3 个，最多 15 个（每个 ≤30 字符）
+- **描述**: 至少 2 个，最多 4 个（每个 ≤90 字符）
+
+## 常见问题
+
+### 广告创建后没有展示
+
+1. 检查状态是否 PAUSED → 启用它
+2. 账号是否设置账单信息 → 去 Google Ads 后台设置
+3. 关键词是否有搜索量 → 添加更多关键词
+
+### 不知道广告效果好不好
+
+用 GAQL 查询关键指标：
+```bash
+google-ads query -q "
+  SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.ctr, metrics.conversions, metrics.cost_micros
+  FROM campaign WHERE segments.date DURING LAST_7_DAYS
+"
+```
+
+**指标参考**：
+- CTR > 2% = 良好
+- CPC 看行业，一般 $0.5-2
+
+### 关键词出价设多少
+
+- 新广告先设 $1-2，观察效果
+- 效果好提高出价，效果差降低或暂停
+
+## 命令参考
+
+### 账号
+- `google-ads account check` - 检查 Google Ads 账号授权状态
+
+### 广告系列
+- `google-ads campaign list [--status ENABLED|PAUSED]` - 列出
+- `google-ads campaign info <id>` - 详情
+- `google-ads campaign create -n "名称" -b 预算` - 创建
+- `google-ads campaign update --campaign-id <id> [--status|--budget|--name]` - 更新
+- `google-ads campaign delete --campaign-id <id>` - 删除
+
+### 广告组
+- `google-ads ad-group list [--campaign-id <id>]` - 列出
+- `google-ads ad-group info <id>` - 详情
+- `google-ads ad-group create --campaign-id <id> -n "名称" [--cpc-bid 出价]` - 创建
+- `google-ads ad-group update --ad-group-id <id> [--status|--cpc-bid|--name]` - 更新
+- `google-ads ad-group delete --ad-group-id <id>` - 删除
+
+### 关键词
+- `google-ads keyword list [--campaign-id <id>]` - 列出
+- `google-ads keyword add --ad-group-id <id> -k "词1,词2" [--match-type BROAD|PHRASE|EXACT]` - 添加
+- `google-ads keyword update --keyword-id <id> --status` - 更新
+- `google-ads keyword delete --keyword-id <id>` - 删除
+
+### 广告
+- `google-ads ad list [--ad-group-id <id>]` - 列出
+- `google-ads ad info <id>` - 详情
+- `google-ads ad create --ad-group-id <id> --headlines "..." --descriptions "..." --final-url "..."` - 创建
+- `google-ads ad update --ad-id <id> --status` - 更新
+- `google-ads ad delete --ad-id <id>` - 删除
+
+### GAQL 查询
+- `google-ads query -q "SELECT ... FROM ..."` - 执行查询
+- `google-ads query -f query.gaql` - 从文件读取
+
+## 重要提示
+
+- **所有命令默认 JSON 输出**
+- **预算和出价单位**：美元
+- **新广告默认 PAUSED**：创建后需手动启用
+- **删除不可恢复**：建议先暂停

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

@@ -45,6 +45,7 @@ description: Order fulfillment and shipping management. Process orders, ship pac
 |--------------------|------|----------|
 | `easyship` | 买家选择了 Easyship 快递 | 可选 Easyship 自动发货 或 手动发货 |
 | `fixed` | 买家使用固定运费 | 只能手动发货 |
+| `free` | 全球免运费 | 只能手动发货 |
 | 空/null | 历史订单 | 只能手动发货 |
 
 #### 发货决策规则（必须严格遵守）
@@ -63,7 +64,7 @@ description: Order fulfillment and shipping management. Process orders, ship pac
   3. **禁止**直接询问运单号
   4. 等待用户选择后再执行对应命令
 
-- **如果 `shipping_mode_used = "fixed"` 或字段为空**：
+- **如果 `shipping_mode_used = "fixed"` 或 `"free"` 或字段为空**：
   1. 直接询问用户提供运单号和快递公司名称
   2. 收集信息后执行手动发货命令
 
@@ -112,7 +113,7 @@ commerce easyship couriers
 #### 手动发货
 
 **适用场景**：
-- `shipping_mode_used = "fixed"` 或为空
+- `shipping_mode_used = "fixed"` 或 `"free"` 或为空
 - 或用户选择不使用 Easyship
 
 **命令**：
@@ -320,7 +321,7 @@ commerce order get --id order_123
 # 用户选择 Easyship 自动发货
 commerce order ship --id order_123 --easyship
 
-# 步骤2b：如果用户选择手动发货，或 shipping_mode_used = "fixed"
+# 步骤2b：如果用户选择手动发货，或 shipping_mode_used = "fixed"/"free"
 commerce order ship \
   --id order_123 \
   --tracking DHL123456 \

package/.claude/skills/shipping/SKILL.md

@@ -15,6 +15,7 @@ description: "运费配置和物流管理。使用场景：查看/设置运费
 | "查看运费区域" / "固定运费" | `commerce shipping-zone list` |
 | "添加运费区域" | `commerce shipping-zone create` |
 | "设置默认运费" / "兜底运费" / "其他地区运费" | `commerce shipping-zone create --is-default` |
+| "全球免运费" / "免邮" / "包邮" | `commerce shipping update-mode --mode free` |
 | "Easyship快递" / "可用快递" | `commerce easyship couriers` |
 | "查看发货地址" | `commerce easyship get-origin` |
 | "更新发货地址" | `commerce merchant update --origin-*`（见 merchant skill） |
@@ -40,14 +41,21 @@ commerce shipping get-mode
 ### 修改模式
 ```bash
 commerce shipping update-mode --mode <模式>
+
+# 设置免运费模式（可配置配送天数）
+commerce shipping update-mode --mode free --free-days-min 5 --free-days-max 10
 ```
 
 | 模式 | 说明 |
 |------|------|
-| `auto` | 自动选择（Easyship 实时报价 + 固定运费，取较优） |
+| `free` | **全球免运费**（新商户默认），可配置配送天数 |
 | `fixed_only` | 仅使用固定运费区域 |
 | `easyship_only` | 仅使用 Easyship 实时报价 |
 
+**免运费模式参数**：
+- `--free-days-min` - 最小配送天数（默认 7）
+- `--free-days-max` - 最大配送天数（默认 14）
+
 ---
 
 ## 运费计算

package/package.json

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