@optima-chat/optima-agent 0.7.6 → 0.7.7

package/.claude/settings.local.json

@@ -104,7 +104,9 @@
       "Bash(npx @optima-chat/ads-cli:*)",
       "Bash(head:*)",
       "Bash(git pull:*)",
-      "Bash(pnpm build:*)"
+      "Bash(pnpm build:*)",
+      "Skill(read-code)",
+      "Bash(npm run cli:*)"
     ],
     "deny": [],
     "ask": []

package/.claude/skills/tiktok/SKILL.md

@@ -1,63 +1,116 @@
 ---
 name: tiktok
-description: TikTok influencer marketing and trend discovery. Use when user needs to find TikTok creators (TikTok网红/达人/创作者), discover viral products (爆款/热销/带货), analyze trending videos (热门视频/趋势), research hashtags (话题/标签/#), or competitive analysis (竞品/对手分析).
+description: TikTok influencer marketing, trend discovery, and TikTok Shop product research. Use when user needs to find TikTok creators (TikTok网红/达人/创作者), discover viral products (爆款/热销/带货), search TikTok Shop products (TikTok小店商品/搜索产品/TikTok Shop), analyze trending videos (热门视频/趋势), research hashtags (话题/标签/#), or competitive analysis (竞品/对手分析).
 ---
 
-# TikTok - Influencer Marketing & Trend Discovery
+# TikTok - Influencer Marketing, Trend Discovery & Shop Research
+
+## 📋 前置要求
+
+使用本 skill 需要全局安装 optima-scout CLI：
+
+```bash
+npm install -g @optima-chat/scout-cli@latest
+```
+
+所有命令使用 `scout tiktok` 前缀。验证安装：`scout tiktok --help`
+
+---
+
+## ⚠️ 核心方法论：数据交叉验证
+
+TikTok 选品的**关键**是交叉验证：
+
+- 📹 **视频热度** (`trending`, `search-videos`) = 内容端的热度
+- 💰 **销量数据** (`shop-search`, `shop-product`) = 交易端的验证
+
+**单一数据源的风险：**
+- ❌ 只看视频热度 → 可能是纯娱乐内容，不转化
+- ❌ 只看销量数据 → 不知道怎么做内容，盲目跟风
+
+**正确做法：**
+- ✅ **视频火 + 销量高** = 强信号（立即行动）
+- ✅ **视频火 + 销量低** = 内容机会（抢先入场）
+- ✅ **视频少 + 销量高** = 自然流量好（产品过硬）
+
+**建议工作流：**
+```
+trending/search-videos 发现 → shop-search 验证 → shop-product 深挖 → Amazon 对标 → 1688 采购
+```
+
+---
+
+## 快速选择：我该用哪个命令？
+
+| 你的目标 | 最佳命令 | 补充命令 | 组合逻辑 |
+|---------|---------|---------|---------|
+| **发现爆款产品** | `shop-search` 按销量排序 | `trending --has-product` | 销量+热度双验证 |
+| **找内容灵感** | `trending` | `video-insights` | 看趋势视频的文案和 hook |
+| **验证产品需求** | `search-videos "产品" --has-product` | `shop-search "产品"` | 视频数量=热度，销量=真实需求 |
+| **竞品分析** | `search-videos "品牌"` | `shop-search "品牌"` | 内容策略+价格策略 |
+| **网红合作** | `creators` | `creator-products` | 找人+看历史推广 |
+| **学习爆款套路** | `video-insights <url>` | `shop-product <id>` | 内容拆解+产品定位 |
+| **研究定价策略** | `shop-product <id>` | `shop-search "同类产品"` | 单品深挖+横向对比 |
+
+---
 
 ## 典型场景
 
 当用户说：
 - "帮我找TikTok网红" / "找美妆博主" → `scout tiktok creators`
 - "TikTok上什么产品火" / "最近有什么爆款" → `scout tiktok trending --has-product`
+- "搜索TikTok Shop的XX产品" / "TikTok小店有什么XX" → `scout tiktok shop-search "XX"`
+- "这个TikTok Shop产品详情" / "产品ID xxx 的信息" → `scout tiktok shop-product <productId>`
 - "搜索XX相关的视频" → `scout tiktok search-videos "XX"`
 - "这个视频数据怎么样" + URL → `scout tiktok video-insights <url>`
 - "TikTok热门话题" / "有什么热门标签" → `scout tiktok hashtags`
 - "看看XX网红推广什么产品" → `scout tiktok creator-products @username`
 
-### 场景决策表
-
-| 用户需求 | 推荐命令 | 关键参数 |
-|---------|---------|---------|
-| 找网红合作 | `tiktok creators` | `--follower-count` 筛选粉丝规模，`--sort engagement_rate` 按互动率排序 |
-| 发现爆款产品 | `tiktok trending --has-product` | `--region` 指定市场，`--time-period 7d` 近期趋势 |
-| 研究产品热度 | `tiktok search-videos "产品名" --has-product` | 找带货视频，验证商业化程度 |
-| 分析爆款视频 | `tiktok video-insights <url>` | 获取字幕和评论，分析成功要素 |
-| 内容策略研究 | `tiktok hashtags` | 找热门话题，结合搜索视频看内容格式 |
-| 竞品分析 | `tiktok search-videos "品牌名"` | 找竞品推广视频，分析营销策略 |
+---
 
 ## 核心命令
 
-### 1. 查找创作者 - `scout tiktok creators`
+### 📦 第一层：产品发现（3种入口）
 
-**用途**：找网红合作，按粉丝数和互动率筛选
+#### 1. TikTok Shop 产品搜索 - `scout tiktok shop-search` ⭐ NEW
 
-```bash
-# 找中等规模高互动网红（最适合合作）
-scout tiktok creators --follower-count "100K-1M" --sort engagement_rate --limit 20
+**用途**：直接搜索 TikTok Shop 的在售商品，获取**真实销量数据**
 
-# 找大V网红
-scout tiktok creators --follower-count "1M-10M" --country US --limit 10
+```bash
+# 搜索咖啡相关产品
+scout tiktok shop-search "coffee" --limit 20
 
-# 按地区和受众筛选
-scout tiktok creators --country GB --audience-country US --limit 20
+# 文本格式输出（更易读）
+scout tiktok shop-search "coffee maker" --limit 10 --format text
 ```
 
 **返回数据**：
-- `username`, `displayName` - 账号信息
-- `followers`, `totalVideos`, `totalLikes` - 规模指标
-- `engagementRate` - **最重要**，衡量粉丝活跃度
-- `avgViews` - 平均播放量
-- `verified` - 认证状态
-- `profileUrl` - 主页链接
+- `product_id` - 产品ID（用于查询详情）
+- `title` - 产品标题
+- `product_price_info` - 价格信息（现价、原价、折扣）
+- `sold_info.sold_count` - **实际销量**（关键指标）
+- `rate_info` - 评分和评论数
+- `seller_info` - 卖家信息（shop_name, seller_id）
+- `seo_url.canonical_url` - 产品链接
 
 **关键指标**：
-- **互动率 >5%** = 优质网红（粉丝活跃）
-- **互动率 2-5%** = 正常水平
-- **互动率 <2%** = 粉丝质量差或僵尸粉
-- **avgViews / followers > 1** = 内容质量好，算法推荐多
-
-### 2. 热门视频 - `scout tiktok trending`
+- **sold_count** - 销量是验证需求的硬指标（参考）
+  - `>5000` = 高销量产品
+  - `1000-5000` = 中等销量
+  - `<1000` = 低销量或新品
+  - ⚠️ 注意：实际销量基准因品类、价格、地区差异很大
+    - 低价产品（<$10）销量基准通常更高
+    - 高价产品（>$50）销量基准较低
+- **rating + review_count** - 评分高但评论少 = 刷单风险
+- **discount_format** - 折扣力度，了解价格策略
+- **shop_name** - 同一卖家多个爆款 = 供应链可靠
+
+**与视频搜索的区别**：
+- `shop-search` = 直接找 TikTok Shop 的**在售商品**，有价格和销量
+- `search-videos` = 找推广**视频**，衡量热度和内容趋势
+- **组合使用**：先 `shop-search` 找高销量产品 → 再 `search-videos` 看推广视频学习内容
+
+#### 2. 热门视频 - `scout tiktok trending`
 
 **用途**：发现正在火的产品和内容
 
@@ -81,7 +134,10 @@ scout tiktok trending --region GB --time-period 24h --limit 30
 - **likes/views >5%** = 内容质量好
 - **有 productUrl** = 已商业化，市场验证
 
-### 3. 搜索视频 - `scout tiktok search-videos`
+**💡 交叉验证技巧**：
+从 trending 发现热门产品 → 用 `shop-search` 搜索同款 → 对比销量验证真实需求
+
+#### 3. 搜索视频 - `scout tiktok search-videos`
 
 **用途**：研究特定产品/话题的视频
 
@@ -98,7 +154,11 @@ scout tiktok search-videos "coffee maker" --has-product --limit 20
 - 如果搜到很多带货视频 = 竞争激烈
 - 如果只有几个带货视频 = 机会窗口
 
-### 4. 视频深度分析 - `scout tiktok video-insights`
+---
+
+### 🔍 第二层：深度分析（3种工具）
+
+#### 4. 视频深度分析 - `scout tiktok video-insights`
 
 **用途**：分析爆款视频的成功要素
 
@@ -117,25 +177,45 @@ scout tiktok video-insights "https://tiktok.com/@user/video/123456789"
 3. **Likes/Views 比例** - >5% 是优秀内容
 4. **Shares** - 高分享 = 传播性强
 
-### 5. 热门话题 - `scout tiktok hashtags`
+#### 5. TikTok Shop 产品详情 - `scout tiktok shop-product` ⭐ NEW
 
-**用途**：找热门话题，优化内容策略
+**用途**：获取产品的完整信息
 
 ```bash
-scout tiktok hashtags --region US --limit 30
+scout tiktok shop-product "1729991116834247323"
+
+# JSON 格式（程序处理）
+scout tiktok shop-product "1729991116834247323" --format json
 ```
 
 **返回数据**：
-- `name` - 话题名称
-- `views` - 浏览量（>10B = 超级热门）
-- `trending` - 是否正在趋势中
+- 基础信息（标题、价格、销量、评分）
+- 产品规格（specifications）
+- 运费信息（shipping_info）
+- 卖家详情（seller_id, shop_name）
+- 产品描述和图片
+
+**使用场景**：
+1. **选品决策** - 从搜索结果中选出高潜力产品，查看完整信息
+2. **竞品分析** - 研究热销产品的定价、规格、运费策略
+3. **供应商对接** - 拿到详细规格，去 1688 找相似供应商
+
+**💡 深度分析技巧**：
+```bash
+# 1. 从 shop-search 找到高销量产品
+scout tiktok shop-search "coffee mug" --limit 20
 
-**使用建议**：
-- 浏览量 >10B = 主流话题，竞争激烈
-- 浏览量 1-10B = 细分话题，精准流量
-- `trending: true` = 正在爆发，时效性强
+# 2. 查看详情（假设 product_id = 123456）
+scout tiktok shop-product "123456"
+
+# 3. 搜索推广视频，学习内容角度
+scout tiktok search-videos "coffee mug" --has-product
 
-### 6. 创作者产品提取 - `scout tiktok creator-products`
+# 4. 分析最火的视频
+scout tiktok video-insights <最火视频的URL>
+```
+
+#### 6. 创作者产品提取 - `scout tiktok creator-products`
 
 **用途**：看某个网红推广什么产品
 
@@ -152,9 +232,162 @@ scout tiktok creator-products @username --sort popular --limit 30
 2. **竞品分析** - 看竞品找了哪些网红
 3. **产品验证** - 如果多个网红都推同一产品 = 供应商可靠或产品好卖
 
+---
+
+### 🛠️ 第三层：支撑工具
+
+#### 7. 查找创作者 - `scout tiktok creators`
+
+**用途**：找网红合作，按粉丝数和互动率筛选
+
+```bash
+# 找中等规模高互动网红（最适合合作）
+scout tiktok creators --follower-count "100K-1M" --sort engagement_rate --limit 20
+
+# 找大V网红
+scout tiktok creators --follower-count "1M-10M" --country US --limit 10
+
+# 按地区和受众筛选
+scout tiktok creators --country GB --audience-country US --limit 20
+```
+
+**返回数据**：
+- `username`, `displayName` - 账号信息
+- `followers`, `totalVideos`, `totalLikes` - 规模指标
+- `engagementRate` - **最重要**，衡量粉丝活跃度
+- `avgViews` - 平均播放量
+- `verified` - 认证状态
+- `profileUrl` - 主页链接
+
+**关键指标**：
+- **互动率 >5%** = 优质网红（粉丝活跃）
+- **互动率 2-5%** = 正常水平
+- **互动率 <2%** = 粉丝质量差或僵尸粉
+- **avgViews / followers > 1** = 内容质量好，算法推荐多
+
+#### 8. 热门话题 - `scout tiktok hashtags`
+
+**用途**：找热门话题，优化内容策略
+
+```bash
+scout tiktok hashtags --region US --limit 30
+```
+
+**返回数据**：
+- `name` - 话题名称
+- `views` - 浏览量（>10B = 超级热门）
+- `trending` - 是否正在趋势中
+
+**使用建议**：
+- 浏览量 >10B = 主流话题，竞争激烈
+- 浏览量 1-10B = 细分话题，精准流量
+- `trending: true` = 正在爆发，时效性强
+
+---
+
+## 数据交叉验证（关键方法论）
+
+### 信号强度判断
+
+#### 🔥 强信号（立即行动）
+- ✅ `shop-search` 销量 >5000
+- ✅ `trending` 有 3+ 个视频推该产品
+- ✅ `search-videos` 找到 10+ 个带货视频
+- ✅ 评论区高频询问购买链接
+
+#### ⚡ 中等信号（值得测试）
+- ⚠️ 销量 1000-5000
+- ⚠️ trending 有 1-2 个视频
+- ⚠️ 视频数量 5-10 个
+
+#### ❄️ 弱信号（观望）
+- ⚠️ 销量 <1000
+- ⚠️ trending 没有
+- ⚠️ 只有 1-2 个带货视频
+
+### 典型验证场景
+
+**场景1：trending 发现爆款视频**
+```bash
+# Step 1: 看到热门视频推某产品
+scout tiktok trending --region US --has-product
+
+# Step 2: 提取产品关键词，验证 TikTok Shop 销量
+scout tiktok shop-search "提取的产品名"
+
+# Step 3: 判断
+# - 如果 sold_count >5000 → 强信号，市场验证
+# - 如果 sold_count <500 → 可能是内容火但不好卖，风险
+```
+
+**场景2：shop-search 发现高销量产品**
+```bash
+# Step 1: 找高销量产品
+scout tiktok shop-search "coffee" --limit 20
+# 假设发现某款卖了 10000 件
+
+# Step 2: 提取 product_id，看详情
+scout tiktok shop-product <product_id>
+# 了解定价、规格
+
+# Step 3: 搜索推广视频，学习内容角度
+scout tiktok search-videos "产品标题" --has-product
+# 如果视频少 → 可能是靠自然流量，内容机会
+# 如果视频多 → 竞争激烈，需要差异化
+```
+
+**场景3：双向验证（最可靠）**
+```bash
+# 同时查询视频热度和销量数据
+scout tiktok trending --region US --has-product --limit 20
+scout tiktok shop-search "同一产品关键词" --limit 20
+
+# 交叉对比：
+# 视频热 + 销量高 = 🔥 强信号
+# 视频热 + 销量低 = 💡 内容机会（可能产品还未饱和）
+# 视频少 + 销量高 = 💎 产品硬（自然流量强）
+```
+
+---
+
 ## 工作流程
 
-### 流程1：发现爆款产品 → 验证 → 采购
+### 流程1：TikTok Shop 选品 → Amazon 验证 → 采购
+
+```bash
+# 1. 搜索 TikTok Shop 的热销产品
+scout tiktok shop-search "coffee mug" --limit 20
+# 关注 sold_count >1000 + rating >4.5 的产品
+
+# 2. 查看高销量产品的详细信息
+scout tiktok shop-product <product_id>
+# 了解规格、定价策略、运费
+
+# 3. 搜索相关视频，看内容趋势
+scout tiktok search-videos "coffee mug" --has-product --limit 20
+# 验证有多少视频在推广，学习内容角度
+
+# 4. 分析最火的推广视频
+scout tiktok video-insights <最火视频URL>
+# 提取 Hook、卖点、评论反馈
+
+# 5. Amazon 市场验证
+scout search "coffee mug" --limit 10
+# 确认市场规模和竞争
+
+# 6. 找 1688 供应商（如果是适合代发的产品）
+scout supplier-search "咖啡杯" --limit 10
+# 计算利润空间
+# 注意：海外品牌或专利产品可能找不到1688货源
+# 可以使用图片搜索或联系原厂代理
+```
+
+**优势**：
+- TikTok Shop 数据是**真实销量**，比视频热度更可靠
+- 可以直接看到定价策略和折扣力度
+- 结合视频推广数据，全面评估产品潜力
+
+### 流程2：发现爆款产品 → 验证 → 采购
 
 ```bash
 # 1. 发现趋势产品
@@ -164,16 +397,24 @@ scout tiktok trending --region US --has-product --time-period 7d --limit 20
 scout tiktok video-insights "https://tiktok.com/video/xxx"
 # 看评论是否有强购买意向，transcript 看卖点
 
-# 3. 验证 Amazon 市场（切换到 scout skill）
+# 3. 验证 TikTok Shop 销量
+scout tiktok shop-search "从视频提取的产品关键词"
+# 如果销量高 → 强信号
+
+# 4. 查看产品详情
+scout tiktok shop-product <product_id>
+
+# 5. 验证 Amazon 市场（切换到 scout skill）
 scout search "product name" --limit 10
 # 看市场规模、竞争、价格区间
 
-# 4. 找 1688 供应商（使用 scout 的 supplier-search 命令）
+# 6. 找 1688 供应商（如果是适合代发的产品）
 scout supplier-search "产品关键词" --limit 10
 # 计算利润空间
+# 注意：海外品牌或专利产品可能找不到1688货源
 ```
 
-### 流程2：网红营销选号
+### 流程3：网红营销选号
 
 ```bash
 # 1. 找目标粉丝规模的网红
@@ -189,7 +430,7 @@ scout tiktok video-insights "https://tiktok.com/video/xxx"
 # 4. 建立候选名单，联系合作
 ```
 
-### 流程3：竞品分析
+### 流程4：竞品分析
 
 ```bash
 # 1. 搜索竞品品牌名
@@ -198,13 +439,23 @@ scout tiktok search-videos "competitor brand" --limit 30
 # 2. 找到他们的推广视频，分析内容策略
 scout tiktok video-insights "竞品视频URL"
 
-# 3. 提取他们合作的网红
+# 3. 搜索竞品在 TikTok Shop 的产品
+scout tiktok shop-search "competitor brand" --limit 20
+# 分析定价策略、销量、评分
+
+# 4. 查看竞品产品详情
+scout tiktok shop-product <competitor_product_id>
+# 研究规格、运费、卖点
+
+# 5. 提取他们合作的网红
 # 从搜索结果中记录 creator usernames
 
-# 4. 分析他们的网红选择策略
+# 6. 分析他们的网红选择策略
 scout tiktok creator-products @competitor_influencer
 ```
 
+---
+
 ## 数据解读关键
 
 ### 网红质量判断
@@ -236,19 +487,90 @@ scout tiktok creator-products @competitor_influencer
 - "I need this" / "Ordering now" = 已转化
 - "@朋友" 标记 = 传播潜力
 
-### 产品趋势判断
+### 产品趋势判断（升级版）
 
 **强趋势信号**：
-- ✅ trending 中有 3+ 个视频推同一产品
-- ✅ 搜索该产品，有 10+ 个带货视频
+- ✅ `shop-search` 销量 >5000
+- ✅ `trending` 中有 3+ 个视频推同一产品
+- ✅ `search-videos` 搜到 10+ 个带货视频
 - ✅ 评论区高频询问购买链接
 - ✅ Amazon 有对应产品且评论数 >100
 
 **弱信号/风险**：
+- ⚠️ 视频多但 TikTok Shop 销量低（内容娱乐向，不好转化）
+- ⚠️ 销量高但视频少（可能是老品，趋势已过）
 - ⚠️ 只有 1-2 个视频，可能是偶然
 - ⚠️ 评论区负面反馈多
 - ⚠️ Amazon 没有对应产品（难转化）
-- ⚠️ 视频播放高但无产品链接（纯内容向，不好变现）
+
+### TikTok Shop 数据解读
+
+**销量区间：**
+- `>10000` = 超级爆款，但竞争激烈
+- `5000-10000` = 热销产品，市场验证充分
+- `1000-5000` = 稳定需求，适合跟进
+- `500-1000` = 新品或小众需求
+- `<500` = 测试期或弱需求
+
+**评分与评论：**
+- `评分 >4.5 + 评论 >100` = 产品质量好
+- `评分 >4.5 + 评论 <50` = 可能刷单
+- `评分 <4.0` = 产品问题，慎重
+
+**折扣分析：**
+- 折扣 >50% = 定价策略激进，或清库存
+- 折扣 20-50% = 正常促销
+- 无折扣 = 产品竞争力强或新品
+
+---
+
+## 常见陷阱与避坑指南
+
+### 陷阱1：视频热度与销量不匹配
+**两种场景：**
+
+**场景A - 视频火但不转化**
+- **表现**：trending 视频播放百万，但 shop-search 销量很低
+- **原因**：纯娱乐内容，用户只是看热闹，没有购买意图
+- **避坑**：必须用 `shop-search` 验证销量，不能只看视频热度
+
+**场景B - 趋势已过**
+- **表现**：TikTok Shop 销量高，但 trending 和 search-videos 找不到新视频
+- **原因**：产品已过热度顶峰，现在入场可能晚了
+- **避坑**：优先选"视频热度上升 + 销量增长"的产品
+
+**核心原则**：视频热度和销量数据必须**双向验证**，单一数据源都有风险
+
+### 陷阱2：刷单产品
+**表现**：TikTok Shop 销量很高，但评论数量少，评分异常高
+**原因**：卖家刷单，虚假繁荣
+
+**避坑检查清单：**
+- ✅ 评分 >4.5 但评论 <10 条 = 高度可疑
+- ✅ 评论内容过于一致或模板化 = 可能刷单
+- ✅ 评论日期集中在短期内 = 异常信号
+- ✅ 结合多个数据源验证：
+  - 查看 trending 视频评论区的真实反馈
+  - 在 Amazon 搜索同款产品对比评论
+  - 观察店铺其他产品的评论分布
+
+### 陷阱3：区域和货源限制
+**两种情况：**
+
+**情况A - 区域不匹配**
+- **表现**：trending 发现美国热门产品，但 TikTok Shop 搜不到
+- **原因**：TikTok Shop 区域限制，某些产品只在特定市场
+- **避坑**：用 `--region` 参数保持一致，或选择多区域可用的产品
+
+**情况B - 找不到供应商**
+- **表现**：TikTok Shop 找到好产品，但 1688 找不到货源
+- **原因**：海外品牌、专利产品、或小众产品
+- **避坑**：
+  - 使用图片反向搜索（Google Images、淘宝拍图）
+  - 联系产品原厂或授权代理
+  - 评估是否值得联系海外供应商直接合作
+
+---
 
 ## 重要提醒
 
@@ -260,3 +582,4 @@ scout tiktok creator-products @competitor_influencer
 3. **--has-product 筛选**：找产品机会必须加这个参数，否则很多纯内容向视频
 4. **Engagement Rate > Follower Count**：小网红高互动比大V低互动效果好
 5. **跨 Skill 联动**：TikTok 发现趋势 → scout 验证市场 → scout supplier-search 找供应商，这是完整链路
+6. **TikTok Shop 数据最可靠**：销量数据 > 视频热度，真实交易数据是最强验证

package/package.json

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