@optima-chat/optima-agent 0.9.19 → 0.9.21

package/.claude/skills/scout/references/commands.md

@@ -0,0 +1,534 @@
+# Scout CLI 命令完整参考
+
+本文档提供所有 scout CLI 命令的详细参数、返回字段、用法示例和实用提示。
+
+---
+
+## 1. scout search
+
+搜索 Amazon 商品列表。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<query>` | string | 是 | - | 搜索关键词 |
+| `--limit` | number | 否 | 10 | 返回结果数量，范围 1-50 |
+| `--domain` | string | 否 | amazon.com | 目标站点域名 |
+
+### 返回字段
+
+- `ASIN` — 商品唯一标识
+- `title` — 商品标题
+- `price` — 当前价格
+- `rating` — 平均评分
+- `ratings_total` — 总评论数
+- `recent_sales` — 近期销量描述（如 "10K+ bought"）
+
+### 典型用法
+
+```bash
+scout search "titanium cup" --limit 20
+scout search "wireless earbuds" --limit 50 --domain amazon.co.uk
+```
+
+### 分析要点
+
+- **价格分布**：观察搜索结果的价格区间，识别主流价格带和高溢价空间
+- **recent_sales**：关注 "10K+ bought" 等标签，快速判断市场热度
+- **ratings_total**：评论总数反映市场成熟度——数千条评论=成熟红海，几十条=新兴机会
+- **average rating**：低于 4.0 星的品类存在产品改进空间
+
+### 多关键词策略
+
+用 2-3 组同义词搜索同一品类，不同关键词会揭示不同的市场细分：
+
+```bash
+scout search "titanium cup" --limit 20
+scout search "titanium mug" --limit 20
+scout search "titanium tumbler" --limit 20
+```
+
+不同关键词可能覆盖不同的用户群体和使用场景，合并分析能获得更完整的市场画像。
+
+---
+
+## 2. scout product
+
+获取单个商品的详细信息。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<asin>` | string | 是 | - | 商品 ASIN |
+| `--domain` | string | 否 | amazon.com | 目标站点域名 |
+
+### 返回字段
+
+- `pricing` — 价格信息（当前价、原价、折扣等）
+- `sales` — 销售数据
+- `reviews` — 评论概况
+- `specifications` — 产品规格（**可能包含 BSR 排名**）
+- `rating_breakdown` — 评分分布（五星到一星各占比例）
+- `BSR` — Best Sellers Rank（在 specifications 中查找）
+- `feature_bullets` — 卖点要点列表
+- `images` — 商品图片列表
+- `description` — 商品描述
+- `categories` — 所属类目
+- `top_reviews` — 精选评论（8-13 条）
+
+### 典型用法
+
+```bash
+scout product B09V3KXJPB
+scout product B09V3KXJPB --domain amazon.de
+```
+
+### 关键数据提取
+
+- **BSR**：在 `specifications` 字段中查找，可能包含多个类目的排名
+- **rating_breakdown**：重点关注五星和一星比例——五星高=产品满意度好，一星高=存在严重问题
+- **top_reviews**：返回 8-13 条精选评论，适合快速扫描用户反馈
+- **feature_bullets**：提炼竞品的核心卖点，为差异化定位提供参考
+- **images count**：7 张为标准配置，少于 7 张说明 listing 优化不足，存在超越机会
+- **A+ Content**：有无 A+ 内容反映卖家的运营投入程度
+
+### 实用提示
+
+> Images count - 7 is standard, fewer = poor optimization
+
+> Specifications - May include BSR in multiple categories
+
+---
+
+## 3. scout reviews
+
+批量抓取商品评论，用于深度痛点分析。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<asin>` | string | 是 | - | 商品 ASIN |
+| `--pages` | number | 否 | 3 | 抓取页数，范围 1-10（每页约 10 条评论） |
+| `--sort` | string | 否 | - | 排序方式：`recent`（最新）或 `helpful`（最有帮助） |
+| `--star` | string | 否 | - | 星级筛选：`one_star`、`two_star`、`three_star`、`four_star`、`five_star` |
+| `--all-stars` | flag | 否 | - | 分别抓取每个星级的评论 |
+| `--verified` | flag | 否 | - | 仅抓取已验证购买的评论 |
+| `--domain` | string | 否 | amazon.com | 目标站点域名 |
+| `--format` | string | 否 | text | 输出格式：`json` 或 `text` |
+
+### 返回字段
+
+**评论列表（每条）：**
+- `id` — 评论 ID
+- `title` — 评论标题
+- `body` — 评论正文
+- `rating` — 评分（1-5）
+- `date` — 评论日期
+- `verified` — 是否已验证购买
+- `helpful_votes` — 有帮助投票数
+- `images` — 评论附图
+
+**商品概况：**
+- `title` — 商品标题
+- `rating` — 平均评分
+- `total_ratings` — 总评论数
+- `rating_breakdown` — 评分分布
+
+### scout product vs scout reviews 对比
+
+| | scout product | scout reviews |
+|---|---|---|
+| 评论数量 | 8-13 条 top_reviews | 30-500 条 |
+| 适用场景 | 快速扫描 | 深度痛点分析 |
+| 可筛选 | 否 | 支持星级、排序、已验证 |
+
+### 典型用法
+
+```bash
+# 差评聚类分析——找产品痛点
+scout reviews B09V3KXJPB --star one_star --pages 5
+
+# 高影响评论——看用户最关心什么
+scout reviews B09V3KXJPB --sort helpful --pages 3
+
+# 全面分析——覆盖所有星级（约 250 条）
+scout reviews B09V3KXJPB --all-stars --pages 5
+
+# 只看真实购买者的评价
+scout reviews B09V3KXJPB --verified
+
+# JSON 格式输出，便于程序处理
+scout reviews B09V3KXJPB --star one_star --pages 3 --format json
+```
+
+### 费用说明
+
+- 每页约 **$0.0075** Apify credits
+- `--all-stars --pages 10`（约 500 条评论）大约 **$0.38**
+
+### 竞品评论对比策略
+
+分别抓取两个竞品的差评，对比痛点差异，寻找差异化机会：
+
+```bash
+scout reviews B09V3KXJPB --star one_star --pages 5
+scout reviews B0D4J2QLCR --star one_star --pages 5
+```
+
+---
+
+## 4. scout keepa product
+
+Keepa 历史数据查询——**核心命令**，提供价格、排名、销量等完整历史趋势。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<asin>` | string | 是 | - | 商品 ASIN（支持逗号分隔批量查询，最多 100 个） |
+| `--stats` | number | 否 | 90 | 统计周期天数 |
+| `--buybox` | flag | 否 | - | 包含 BuyBox 数据 |
+| `--rating` | flag | 否 | - | 包含评分历史数据 |
+| `--domain` | string | 否 | amazon.com | 目标站点域名 |
+
+### 关键返回字段
+
+| 字段路径 | 含义 | 说明 |
+|----------|------|------|
+| `stats.current[3]` | 当前 BSR 排名 | 越小越好 |
+| `stats.salesRankDrops30` | 30 天 BSR 下降次数 | **约等于 30 天出单次数** |
+| `stats.salesRankDrops90` | 90 天 BSR 下降次数 | **约等于 90 天出单次数** |
+| `stats.outOfStockPercentage30` | 30 天断货率 | 高断货率=供应链问题或需求旺盛 |
+| `csv[0]` | Amazon 自营价格历史 | - |
+| `csv[1]` | 第三方新品价格历史 | - |
+| `csv[3]` | BSR 排名历史 | 观察趋势走向 |
+| `csv[11]` | 在售卖家数量历史（COUNT_NEW） | 卖家增多=竞争加剧 |
+| `csv[16]` | 评分历史 | - |
+| `csv[17]` | 评论数历史 | 增长速度反映市场活跃度 |
+
+### 单位换算
+
+- **价格**：单位为美分，除以 100 得美元（如 2999 = $29.99）
+- **评分**：乘以 10 存储（如 45 = 4.5 星）
+
+### 典型用法
+
+```bash
+# 默认查询（90天统计）
+scout keepa product B09V3KXJPB
+
+# 长周期分析（180天）
+scout keepa product B09V3KXJPB --stats 180
+
+# 含 BuyBox 和评分数据
+scout keepa product B09V3KXJPB --buybox --rating
+
+# 批量查询多个 ASIN
+scout keepa product B09V3KXJPB,B0D4J2QLCR
+
+# 指定其他站点
+scout keepa product B09V3KXJPB --domain amazon.de
+```
+
+---
+
+## 5. scout keepa search
+
+Keepa Product Finder——按条件筛选商品，发现市场机会。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<selection>` | JSON string | 是 | - | 筛选条件 JSON |
+| `--per-page` | number | 否 | 10 | 每页返回数量 |
+
+### 常用筛选字段
+
+`selection` 支持数百个筛选条件，以下为最常用的：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `salesRankRange` | [min, max] | BSR 排名范围 |
+| `avg90_COUNT_REVIEWS_lte` | number | 90 天平均评论数上限 |
+| `currentRange` | [min, max] | 当前价格范围，**单位为美分**（$20-50 = [2000, 5000]） |
+| `brand` | string | 品牌名 |
+
+### 典型用法
+
+```bash
+# 找低竞争新机会：BSR 前 10000，评论少于 500，价格 $20-50
+scout keepa search '{"salesRankRange":[1,10000],"avg90_COUNT_REVIEWS_lte":500,"currentRange":[2000,5000]}'
+
+# 找特定品牌的热销商品
+scout keepa search '{"brand":"Apple","salesRankRange":[1,50000]}' --per-page 10
+```
+
+### 实用提示
+
+- **价格单位是美分**：$20 写成 2000，$50 写成 5000，切勿搞混
+- 组合多个条件可以快速缩小范围，找到低竞争高需求的利基市场
+
+---
+
+## 6. scout keepa bestsellers
+
+查询指定类目的畅销商品排行。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<categoryId>` | number | 是 | - | 类目 ID |
+| `--range` | number | 否 | - | 统计天数 |
+
+### 典型用法
+
+```bash
+# 查看 Electronics 类目畅销榜
+scout keepa bestsellers 172282
+
+# 查看 90 天畅销排行
+scout keepa bestsellers 172282 --range 90
+```
+
+### 实用提示
+
+- 先用 `scout keepa category 0` 获取所有根类目 ID，再查具体类目的畅销榜
+- 结合 `scout keepa product` 进一步分析畅销商品的历史数据
+
+---
+
+## 7. scout keepa category
+
+查询 Amazon 类目结构。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<id>` | number | 是 | - | 类目 ID（0 = 所有根类目） |
+
+### 典型用法
+
+```bash
+# 获取所有根类目列表
+scout keepa category 0
+
+# 查看 Electronics 的子类目
+scout keepa category 172282
+```
+
+---
+
+## 8. scout keepa seller
+
+查询卖家信息及店铺商品列表。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<sellerId>` | string | 是 | - | 卖家 ID |
+| `--storefront` | flag | 否 | - | 包含店铺全部 ASIN 列表 |
+
+### 返回字段
+
+- 卖家名称
+- 卖家评分
+- 店铺 ASIN 总数
+- （加 `--storefront` 时）完整 ASIN 列表
+
+### 典型用法
+
+```bash
+# 查看 Amazon.com 自营信息
+scout keepa seller ATVPDKIKX0DER
+
+# 查看第三方卖家并获取全部店铺商品
+scout keepa seller A2R2RITDJNW1Q6 --storefront
+```
+
+---
+
+## 9. scout keepa deals
+
+查询近期降价商品。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--category` | number | 否 | - | 品类 ID 筛选 |
+| `--title` | string | 否 | - | 标题关键词搜索 |
+
+### 返回字段
+
+- `ASIN` — 商品标识
+- 标题
+- 当前价格
+- 降幅
+
+### 典型用法
+
+```bash
+# 默认查看 BuyBox 降价商品
+scout keepa deals
+
+# 查看 Electronics 类目降价
+scout keepa deals --category 172282
+
+# 按标题搜索降价商品
+scout keepa deals --title "wireless earbuds"
+```
+
+---
+
+## 10. scout keepa graph
+
+生成 Keepa 价格走势图片。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<asin>` | string | 是 | - | 商品 ASIN |
+| `-o` | string | 否 | - | 输出文件路径 |
+
+### 返回
+
+Keepa 价格走势 PNG 图片。
+
+### 典型用法
+
+```bash
+scout keepa graph B09V3KXJPB -o price-chart.png
+```
+
+---
+
+## 11. scout supplier-search
+
+通过关键词搜索 1688 供应商。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<keyword>` | string | 是 | - | 搜索关键词（中文） |
+| `--limit` | number | 否 | 20 | 返回结果数量，范围 1-100 |
+| `--format` | string | 否 | text | 输出格式：`text` 或 `json` |
+
+### 返回字段
+
+- 产品信息（标题、图片）
+- 价格梯度（如 "2~49台: ¥599, ≥100台: ¥429"）
+- MOQ（最小起订量）
+- 供应商位置
+- 供应商经营年限
+- 供应商类型
+- 标签
+
+### 典型用法
+
+```bash
+scout supplier-search "钛合金杯子" --limit 30
+scout supplier-search "无线耳机" --format json
+```
+
+### 关键分析维度
+
+- **MOQ 限制**：最小起订量直接影响启动资金需求
+- **供应商类型**：`生产加工` = 工厂（价格更优），`经销批发` = 贸易商（灵活度更高）
+- **经营年限**：8 年以上为成熟供应商，合作风险较低
+- **回头率**：越高越好，30-50% 为正常水平，反映客户满意度
+
+---
+
+## 12. scout supplier-search-image
+
+通过图片搜索 1688 供应商（以图搜货）。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<imageUrl>` | string | 是 | - | 图片 URL |
+| `--limit` | number | 否 | 20 | 返回结果数量，范围 1-100 |
+| `--format` | string | 否 | text | 输出格式：`text` 或 `json` |
+
+### 返回字段
+
+同 `scout supplier-search`。
+
+### 典型用法
+
+```bash
+# 用 Amazon 商品图片找源头供应商
+scout supplier-search-image "https://m.media-amazon.com/images/I/xxxx.jpg" --limit 30
+
+# 用任意平台图片搜索
+scout supplier-search-image "https://example.com/product.jpg"
+```
+
+### 使用场景
+
+- **找同款**：看到某个产品想找同款供应商
+- **看图找货**：只有产品图片，不知道中文关键词怎么搜
+- **Amazon 产品在 1688 找源头**：直接用 Amazon listing 图片反向搜索
+
+### 重要提示
+
+- 支持任何平台的图片 URL（Amazon、Alibaba、直接链接等）
+- 非阿里系图片会自动转换格式
+- 图片无法访问时会返回友好的错误提示
+- **最佳实践**：同时用图片搜索和关键词搜索（`supplier-search`）对比结果，覆盖更全面
+
+---
+
+## 13. scout shein-search
+
+搜索 Shein 平台同品类商品。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<keyword>` | string | 是 | - | 搜索关键词 |
+| `--limit` | number | 否 | - | 返回结果数量 |
+
+### 用途
+
+查看 Shein 同品类的低价竞争天花板，评估来自快时尚平台的价格压力。
+
+### 典型用法
+
+```bash
+scout shein-search "titanium cup" --limit 20
+```
+
+---
+
+## 14. scout temu-search
+
+搜索 Temu 平台同品类商品。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `<keyword>` | string | 是 | - | 搜索关键词 |
+| `--limit` | number | 否 | - | 返回结果数量（最低 20） |
+
+### 用途
+
+查看 Temu 同品类的低价竞争态势，了解极致性价比市场的价格底线。
+
+### 典型用法
+
+```bash
+scout temu-search "titanium cup" --limit 20
+```