# Scout CLI 命令完整参考

本文档提供所有 scout CLI 命令的详细参数、返回字段、用法示例和实用提示。

> ⚠️ **下列各节写的「返回字段」指的是缓存 JSON 文件里的内容，不是 stdout。** 这些命令在 `json` 模式下 stdout 只输出一个很小的摘要对象（一个计数或少量标识字段 + `cache_file` 路径），**真正的字段在 `cache_file` 指向的文件里**——要拿字段就去读 `cache_file`，别指望直接 parse stdout：
>
> | 节 | 命令 | stdout 摘要里实际有什么 |
> |---|---|---|
> | §1 | `search` | `total_results` + `credits_remaining` + `cache_file`（`credits_remaining` **只有这一个命令有**） |
> | §2 | `product` | `asin` + 截断到 80 字的 `title` + `cache_file`（无计数） |
> | §3 | `reviews` | `total_reviews` + `cache_file` |
> | §4 | `keepa product` | `tokensLeft` + `cache_file`（keepa 系是 `tokensLeft`，不是 `credits_remaining`） |
> | §5 | `keepa search` | `total_asins` + `cache_file` |
> | §9 | `keepa deals` | `command` + `total_deals` + `cache_file` |
>
> 依据：`cli/src/commands/search.ts:31-35`、`product.ts:29-35`、`reviews.ts:37-40`、`keepa.ts:42-45` / `114-117` / `338-342`。
>
> 🔴 **§11 `supplier-search` 与 §12 `supplier-search-image` 是例外，不适用上面这条。** 这两个命令的 json 模式**故意**把 `url` / `shopUrl` 等字段内联进 stdout（`supplier-search.ts:50-71` 的 `buildSupplierJsonSummary`，§12 在 `supplier-search-image.ts:118` 复用它），就是为了让 agent 直接拿到可点击的来源链接。汇报供应商结果时**必须**按 `SKILL.md` 的要求从 `summary.suppliers[].url` / `.shopUrl` 取链接，**不要**改去读缓存文件、更不许自行拼接 1688 链接。

---

## 1. scout search

搜索 Amazon 商品列表。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<query>` | string | 是 | - | 搜索关键词 |
| `-l, --limit` | number | 否 | 不限制 | 返回条数**上限**，正整数。只截断、不补足——上游给不够时**不会**多翻页去凑，所以 `--limit 50` 经常拿到少于 50 条（实测一页 20~65 条不等）。不传即返回上游给的全部 |
| `-d, --domain` | string | 否 | amazon.com | 目标站点全域名（`amazon.com`、`amazon.co.uk`） |
| `-f, --format` | string | 否 | json | 输出格式：`json` 或 `text` |

### 返回字段

- `asin` — 商品唯一标识
- `title` — 商品标题
- `price` — 当前价格
- `rating` — 平均评分
- `ratings_total` — 总评论数
- `recent_sales` — 近期销量描述（如 "10K+ bought"）

### 典型用法

```bash
scout search "titanium cup"
scout search "wireless earbuds" --domain amazon.co.uk
```

### 分析要点

- **价格分布**：观察搜索结果的价格区间，识别主流价格带和高溢价空间
- **recent_sales**：关注 "10K+ bought" 等标签，快速判断市场热度
- **ratings_total**：评论总数反映市场成熟度——数千条评论=成熟红海，几十条=新兴机会
- **average rating**：低于 4.0 星的品类存在产品改进空间

### 多关键词策略

用 2-3 组同义词搜索同一品类，不同关键词会揭示不同的市场细分：

```bash
scout search "titanium cup"
scout search "titanium mug"
scout search "titanium tumbler"
```

不同关键词可能覆盖不同的用户群体和使用场景，合并分析能获得更完整的市场画像。

---

## 2. scout product

获取单个商品的详细信息。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<asin>` | string | 是 | - | 商品 ASIN |
| `-d, --domain` | string | 否 | amazon.com | 目标站点全域名（`amazon.com`、`amazon.de`） |
| `-f, --format` | string | 否 | json | 输出格式：`json` 或 `text` |

### 返回字段

- `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 |
| `-p, --pages` | number | 否 | 3 | 抓取页数，范围 1-10（每页约 10 条评论） |
| `-s, --sort` | string | 否 | recent | 排序方式：`recent`（最新）或 `helpful`（最有帮助） |
| `--star` | string | 否 | - | 星级筛选：`one_star`、`two_star`、`three_star`、`four_star`、`five_star` |
| `--all-stars` | flag | 否 | - | 分别抓取每个星级的评论（覆盖 `--star`） |
| `--verified` | flag | 否 | - | 仅抓取已验证购买的评论 |
| `-d, --domain` | string | 否 | com | **域名后缀码**，不是全域名：`com`、`de`、`co.uk`、`co.jp` 等 |
| `-f, --format` | string | 否 | json | 输出格式：`json` 或 `text` |

> ⚠️ **`--domain` 与 `scout search` / `scout product` / `scout keepa *` 不同**：那几个命令收的是全域名（`amazon.com`、`amazon.de`），本命令收的是后缀码（`com`、`de`）。该值原样透传给上游抓取器的 `domainCode`，scout 侧不校验、也不会把 `amazon.com` 纠正成 `com`。

### 返回字段

> 字段指的是缓存 JSON 的内容（stdout 只输出摘要 + 缓存路径，见 SKILL.md「CLI 自动缓存」）。

**评论列表（每条）：**
- `id` — 评论 ID
- `title` — 评论标题
- `body` — 评论正文
- `rating` — 评分（1-5）
- `date` — 评论日期
- `verified_purchase` — 是否已验证购买
- `helpful_votes` — 有帮助投票数
- `vine_program` — 是否 Vine 计划评论
- `user_name` — 评论者昵称
- `images` — 评论附图
- `variation` — 对应的商品变体（无则为 `null`）

**商品概况（`summary`）：**
- `product_title` — 商品标题
- `product_rating` — 平均评分。⚠️ 类型是 **`string` 不是 number**（`backend/src/types/reviews.ts:76`），拿去做数值比较/排序前先转数
- `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

# 抓德国站评论——注意是后缀码 de，不是 amazon.de
scout reviews B09V3KXJPB -d de --star one_star

# 默认 json 时 stdout 只有条数 + 缓存路径；要在终端直接看评论正文用 text
scout reviews B09V3KXJPB --star one_star --pages 3 --format text
```

### 费用说明

- 每页约 **$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 历史数据查询——**核心命令**，提供价格、排名、销量等完整历史趋势。

> 以下 §4–§10 所有 `scout keepa` 子命令都有这两个通用选项，各节表格不再重复列出：`-d, --domain`（默认 `amazon.com`，收**全域名**）、`-f, --format`（默认 `json`；`keepa graph` 除外，它直接输出 PNG 文件）。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<asin>` | string | 是 | - | 商品 ASIN（支持逗号分隔批量查询，最多 100 个） |
| `-s, --stats` | number | 否 | 90 | 统计周期天数 |
| `--days` | number | 否 | - | 历史数据天数 |
| `--buybox` | flag | 否 | - | 包含 BuyBox 数据 |
| `--rating` | flag | 否 | - | 包含评分历史数据 |
| `--offers` | number | 否 | - | 抓取的 offer 数量（上游建议 20-100，scout 侧不校验） |

### 关键返回字段

| 字段路径 | 含义 | 说明 |
|----------|------|------|
| `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 |
| `-p, --page` | number | 否 | 0 | 页码（从 0 开始） |
| `--per-page` | number | 否 | 50 | 每页返回数量 |

### 常用筛选字段

`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 |
| `-r, --range` | number | 否 | 0 | 统计天数，只接受 `0` / `30` / `90` / `180`（`0` = 当前榜） |

### 典型用法

```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 = 所有根类目） |
| `--parents` | flag | 否 | - | 一并返回父类目 |

### 典型用法

```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 | 否 | - | 标题关键词搜索 |
| `--min-rating` | number | 否 | - | 最低评分（0-50，即 4.5 星写 45） |

### 返回字段

- `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, --output` | string | 否 | keepa-graph.png | 输出文件路径 |
| `-w, --width` | number | 否 | - | 图片宽度（像素） |
| `--height` | number | 否 | - | 图片高度（像素） |

### 返回

Keepa 价格走势 PNG 图片。

### 典型用法

```bash
scout keepa graph B09V3KXJPB -o price-chart.png
```

---

## 11. scout supplier-search

通过关键词搜索 1688 供应商。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<keyword>` | string | 是 | - | 搜索关键词（中文） |
| `-l, --limit` | number | 否 | 20 | 返回结果数量，范围 1-100 |
| `-f, --format` | string | 否 | text | 输出格式：`text` 或 `json` |

### 返回字段

- 产品信息（标题、图片）
- `url` — 1688 商品详情页链接（向用户透出来源时使用，只用此真实返回值）
- `shopUrl` — 供应商店铺链接
- `supplier.name` — 店铺名
- 价格梯度（如 "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 供应商（以图搜货）。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<image>` | string | 是 | - | **图片 URL 或本地文件路径**（两者都支持，自动识别：以 `http://` / `https://` 开头当 URL，否则当本地路径） |
| `-l, --limit` | number | 否 | 20 | 返回结果数量，范围 1-100 |
| `-f, --format` | string | 否 | text | 输出格式：`text` 或 `json` |

**本地文件方式的约束**（CLI 会自动读取并上传，无需你自己找图床或生成公网链接）：

| 项 | 限制 |
|---|---|
| 格式 | `.jpg` / `.jpeg` / `.png` / `.gif` / `.webp` / `.bmp` |
| 大小 | 100 字节 ~ 10MB（超 480KB 时后端会自动等比缩放 + 降质压缩） |
| 路径 | 绝对路径或相对路径均可；工作目录 / `/tmp` / `/var` 之外的路径不允许含 `..` |

### 返回字段

同 `scout supplier-search`。

### 典型用法

```bash
# 用户在对话里传的图片 —— 直接给本地路径，不要去找公网链接
scout supplier-search-image /home/aiuser/attachments/pasted-file-xxxx.png

# 用 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、直接链接等）
- === 用户在对话里上传的图片，**直接把本地路径传给本命令**（如 `/home/aiuser/attachments/xxx.png`）。CLI 会自己读文件、上传、拿到可供上游抓取的链接。**不要**再去调 `/api/user/files/share`、找图床、或想办法生成公网 URL —— 那是多余的一步，且 cn-prod 上该端点因缺配置不可用（optima-gateway#1812）。===
- 非阿里系图片会自动转换格式
- 图片无法访问时会返回友好的错误提示
- **图搜优先、词搜兜底**：以图搜图结果更贴近原图、准确度更高，是主结果。**默认只跑 `supplier-search-image`**；仅当它返回 **< 5 条**（或为空 / 图片无法识别）时，才补调 `supplier-search` 关键词搜索兜底。
- **报错先换图重试、成功即作废兜底**：本命令报错（尤其「图片转换失败」）时不要直接转关键词搜索，先**换一张图**重跑本命令。**同一张图重试无效** —— 这类失败是上游取图阶段的确定性超时（后端已自动重试 3 次），同图重发只会同样失败。**换图后成功且 ≥ 5 条时，此前因失败而计划的 `supplier-search` 兜底一律作废、不要再跑** —— 兜底条件按**最后一次**图搜的结果判定，不按中途失败判定。
- 兜底的关键词结果**排在图搜结果之后**，并注明「关键词补充（准确度可能较低）」；与图搜重复的同一 offer（按链接 / offerId）只保留图搜那条。

---

## 13. scout shein-search

搜索 Shein 平台同品类商品。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<keyword>` | string | 是 | - | 搜索关键词 |
| `-l, --limit` | number | 否 | 20 | 返回结果数量，上限 100 |
| `--country` | string | 否 | US | 国家，如 `US` / `CA` / `UK`（scout 侧不校验，透传上游） |
| `-c, --currency` | string | 否 | USD | 币种，如 `USD` / `EUR` / `GBP`（同上，不校验） |
| `--language` | string | 否 | en | 语言，如 `en` / `es` / `fr`（同上，不校验） |
| `-f, --format` | string | 否 | text | 输出格式：`text` 或 `json` |

### 用途

查看 Shein 同品类的低价竞争天花板，评估来自快时尚平台的价格压力。

### 典型用法

```bash
scout shein-search "titanium cup" --limit 20
```

---

## 14. scout temu-search

搜索 Temu 平台同品类商品。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<keyword>` | string | 是 | - | 搜索关键词 |
| `-l, --limit` | number | 否 | 20 | 返回结果数量，上限 200 |
| `-c, --currency` | string | 否 | USD | 币种，后端只接受 `USD`，传其它值会 400 |
| `-f, --format` | string | 否 | text | 输出格式：`text` 或 `json` |

### 用途

查看 Temu 同品类的低价竞争态势，了解极致性价比市场的价格底线。

### 典型用法

```bash
scout temu-search "titanium cup" --limit 20
```

---

## 15. scout sp keywords

反查 ASIN 的流量关键词（卖家精灵 SellerSprite 数据）。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<asin>` | string | 是 | - | 商品 ASIN |
| `--marketplace` | string | 否 | US | 站点（US/UK/DE/FR/IT/ES/CA/JP） |

### 返回字段

- `keyword` — 关键词
- `searches` — 月搜索量
- `bid` — PPC 建议竞价
- `bidMin` — PPC 最低竞价
- `bidMax` — PPC 最高竞价
- `badges` — 流量标签（如 `["naturalSearching", "ads"]` 表示同时有自然和广告流量）
- `rankPosition` — 自然排名（page + position）
- `adPosition` — 广告排名（page + position）
- `purchases` — 月购买量
- `purchaseRate` — 转化率

### 典型用法

```bash
# 反查竞品流量关键词
scout sp keywords B0D2XRXNGY

# 查看竞品在英国站的流量词
scout sp keywords B0D2XRXNGY --marketplace UK
```

### 分析要点

- **badges 含 "ads"**：竞品在该关键词投了广告，可统计广告词数量估算广告预算
- **rankPosition vs adPosition**：对比自然排名和广告排名，判断竞品的流量获取策略
- **bid/bidMin/bidMax**：真实 PPC 竞价数据，用于 FAN 模型精算广告成本

### 实测数据样例

```
earbuds: 搜索量 501,168 | 竞价 $2.11 ($1.32-$2.84) | 自然排名 P3#78 | 广告排名 P1#13
```

---

## 16. scout sp keywords-mine

关键词挖掘——获取关键词的精确搜索量、PPC 竞价、转化率等数据（卖家精灵数据）。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<keyword>` | string | 是 | - | 搜索关键词 |
| `--marketplace` | string | 否 | US | 站点 |

### 返回字段

- `keyword` — 关键词（含衍生词和长尾词）
- `searches` — 精确月搜索量
- `purchases` — 月购买量
- `purchaseRate` — 转化率
- `bid` — PPC 建议竞价
- `bidMin` — PPC 最低竞价
- `bidMax` — PPC 最高竞价
- `adProducts` — 广告产品数
- `supplyDemandRatio` — 供需比
- `monopolyClickRate` — 垄断点击率
- `avgPrice` — 搜索结果均价

### 典型用法

```bash
# 挖掘关键词数据
scout sp keywords-mine "open ear earbuds"

# 验证市场需求
scout sp keywords-mine "titanium cup"
```

### 分析要点

- **searches**：精确月搜索量，比 BSR drops 估算更直接，可直接用于 SPAN 市场规模评分
- **purchases / purchaseRate**：真实购买量和转化率，验证需求是否真实
- **bid/bidMin/bidMax**：真实 PPC 竞价，用于 FAN 模型替代 ACoS 估算
- **supplyDemandRatio**：供需比越高表示供给越饱和，低于 1 表示供不应求
- **monopolyClickRate**：高垄断点击率（>50%）说明头部品牌吃掉大部分流量

### 实测数据样例

```
airpods: 搜索量 2,883,637 | 竞价 $1.64 | 转化率 2.52% | 广告产品 52 | 供需比 185.75 | 垄断点击率 72.39%
```

---

## 17. scout sp keywords-order

反查 ASIN 的出单关键词——哪些关键词真正带来了转化（卖家精灵数据）。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<asin>` | string | 是 | - | 商品 ASIN |
| `--reverse-type` | string | 否 | M | 时间维度：`M`=月, `W`=周 |
| `--date` | string | 否 | 当前月 | 日期：月维度 `yyyyMM`（如 202604），周维度 `yyyyMMdd` |
| `--marketplace` | string | 否 | US | 站点 |

### 返回字段

- `keyword` — 出单关键词
- `searches` — 月搜索量
- `monopolyClickRate` — 垄断点击率
- `conversionShare` — 转化份额（该关键词贡献的转化占比）
- `conversionType` — 转化类型（如"优质词"）
- `searchGrowth` — 搜索量增长率

### 典型用法

```bash
# 查看竞品当月出单词
scout sp keywords-order B0D2XRXNGY

# 查看竞品上月出单词
scout sp keywords-order B0D2XRXNGY --date 202604

# 按周查看
scout sp keywords-order B0D2XRXNGY --reverse-type W --date 20260420
```

### 分析要点

- **区分流量词和出单词**：流量词（`scout sp keywords`）不一定带来转化，出单词才是真正的转化路径
- **conversionShare**：转化份额高的关键词是竞品的核心出单词，值得重点关注
- **conversionType**：优质词表示关键词质量高，竞争价值大

### 实测数据样例

```
open ear earbuds: 搜索量 141,637 | 垄断点击率 18.72% | 转化份额 14.14% | 转化类型=优质词
```

---

## 18. scout sp market

类目市场分析——获取类目级别的市场规模、竞争、盈利等数据（卖家精灵数据）。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<nodeIdPath>` | string | 是 | - | 类目路径（如 `172282:24046923011:172541:12097478011`），通过 `scout sp category` 获取 |
| `--marketplace` | string | 否 | US | 站点 |

### 返回字段

- 类目规模（总销量、总销额）
- 均价
- 利润数据
- FBA 占比
- 退货率
- 卖家数量
- 需求趋势

### 典型用法

```bash
# 先查类目路径
scout sp category "Headphones"
# 再查市场数据
scout sp market "172282:24046923011:172541:12097478011"
```

### 分析要点

- 提供类目级宏观视角，适合 SPAN 评分的市场吸引力评估
- 退货率和 FBA 占比可直接用于 FAN 财务模型

---

## 19. scout sp brands

类目品牌集中度分析——量化品牌垄断程度（卖家精灵数据）。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<nodeIdPath>` | string | 是 | - | 类目路径（通过 `scout sp category` 获取） |
| `--marketplace` | string | 否 | US | 站点 |

### 返回字段

- 品牌名称
- ASIN 数量
- 销量份额（%）
- 销额份额（%）
- 新品数量

### 典型用法

```bash
scout sp brands "172282:24046923011:172541:12097478011"
```

### 分析要点

- **CR3/CR5**：前 3/5 名品牌的合计份额，直接用于 SPAN 竞争地位评分的进入壁垒维度
- **销量份额 vs 销额份额**：份额差异大说明存在高溢价品牌，可能有品牌溢价空间
- **新品数量**：头部品牌新品多=品类活跃，新品少=品类成熟

### 实测数据样例

```
Apple: 3 ASIN, 销量份额 17.67%, 销额份额 35.48%
HAOYUYAN: 8 ASIN, 销量份额 13.83%（5 个新品）
Soundcore: 6 ASIN, 排名第 3
```

---

## 20. scout sp category

关键词类目查询——获取关键词对应的 Amazon 类目树和 nodeIdPath（卖家精灵数据）。

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `<keyword>` | string | 是 | - | 搜索关键词 |
| `--marketplace` | string | 否 | US | 站点 |

### 返回字段

- 类目树结构
- `nodeIdPath` — 类目路径（传给 `scout sp market` / `scout sp brands` 使用）
- 类目名称

### 典型用法

```bash
# 查询关键词对应的类目
scout sp category "Headphones"
scout sp category "titanium cup"
```

### 使用场景

`scout sp category` 是 `scout sp market` 和 `scout sp brands` 的前置命令。典型工作流：

```bash
# 1. 查类目路径
scout sp category "open ear earbuds"
# 2. 用返回的 nodeIdPath 查市场数据
scout sp market "172282:24046923011:172541:12097478011"
# 3. 用同一 nodeIdPath 查品牌集中度
scout sp brands "172282:24046923011:172541:12097478011"
```

---

## 21-32. 其他 scout sp 命令

以下命令参数模式与上述 #15-#20 一致，不再逐一展开。

### 关键词/流量类

| 命令 | 用途 | 关键返回字段 |
|------|------|------------|
| `scout sp keywords-research <keyword>` | 关键词市场分析 | searches, purchases, purchaseRate, growth, brands, categories, bid |
| `scout sp keywords-trends <keyword>` | 关键词历史趋势（2017-至今） | 每月 search/purchases/purchaseRate/growth |
| `scout sp traffic-stats <ASIN>` | 流量关键词概览统计 | keywords 总数, ranks, ads 数 |
| `scout sp traffic-source <ASIN>` | 流量来源结构 | 各来源类型的关键词数和占比 |
| `scout sp traffic-listing <ASIN>` | 免费/付费流量分布 | 各流量类型的数量 |
| `scout sp traffic-related <ASIN>` | 关联商品列表 | 关联 ASIN、关联类型、关联强度 |
| `scout sp traffic-extend <ASIN>` | 批量关键词拓展 | 扩展关键词列表（含搜索量、竞价） |

### 产品类

| 命令 | 用途 | 关键返回字段 |
|------|------|------------|
| `scout sp predict <ASIN>` | 销量预测（14 个月） | 日/月销量、销售额预测 |
| `scout sp competitors <ASIN>` | 竞品查询 | 销量/销额/BSR/价格/利润/评分/FBA 类型 |
| `scout sp coupon <ASIN>` | 优惠趋势 | 原价/优惠类型/优惠金额/最终成交价 |

### 市场类（先通过 `scout sp category` 获取 nodeIdPath）

| 命令 | 用途 | 关键返回字段 |
|------|------|------------|
| `scout sp market-stats <nodeIdPath>` | 类目统计 | 与 market 类似，更侧重统计指标 |
| `scout sp sellers <nodeIdPath>` | 卖家集中度 | 头部卖家名称/销量份额/销额份额 |
| `scout sp demand <nodeIdPath>` | 需求趋势 | 页面浏览量/商品数/退货率趋势 |
| `scout sp prices <nodeIdPath>` | 价格分布 | 各价格区间的商品数/销量/销额 |
| `scout sp ratings <nodeIdPath>` | 评分数分布 | 各评分数区间（进入难度） |
| `scout sp rating-values <nodeIdPath>` | 评分值分布 | 各评分值区间（市场成熟度） |
| `scout sp listing-dates <nodeIdPath>` | 上架时间分布 | 各时间区间商品数（新品接受度） |
| `scout sp listing-trends <nodeIdPath>` | 上架趋势 | 按绝对上架时间统计 |
| `scout sp seller-countries <nodeIdPath>` | 卖家所属地分布 | 各国家卖家数/销量占比 |
| `scout sp seller-types <nodeIdPath>` | 发货类型分布 | FBA/FBM/Amazon 自营占比 |
| `scout sp ebc <nodeIdPath>` | A+视频分布 | 有/无 A+和视频的商品占比 |
| `scout sp products <nodeIdPath>` | 商品集中度 | 头部商品排名/销量/销额集中度 |

### 其他

| 命令 | 用途 | 关键返回字段 |
|------|------|------------|
| `scout sp google-trend <keyword>` | 谷歌搜索趋势 | 按月/周的搜索热度指数 |
| `scout sp aba-weekly <keyword>` | ABA 周数据选品 | 热门/异动/增长/潜力关键词 |
| `scout sp aba-monthly <keyword>` | ABA 月数据选品 | 同上（月维度） |
| `scout sp aba-trend <keyword>` | ABA 关键词趋势 | ABA 排名和搜索量历史 |

所有 `scout sp` 命令通用选项：`-m, --marketplace <code>`（默认 US）、`-f, --format <format>`（json/text）。