Amazon Suggestion Miner

Amazon 搜索建议词挖掘工具

从种子词出发，利用 Amazon 搜索框自动补全 API 批量挖掘长尾关键词。

核心原理

Amazon 搜索框输入时，前端向 www.amazon.com/suggestions 发请求获取建议词。 这个 API 是 Amazon 自己的个性化推荐引擎，返回的数据是真实用户搜索热度的反映， 按搜索频次降序排列。

API 对比（已验证 2026-05）

使用流程

最终交付物为 Excel (xlsx) 文件，禁止生成 HTML 报告。 多模式运行时，各模式分别输出 xlsx，也可合并去重后输出一份总表 xlsx。

用户首次发来拓词需求时，必须先用 AskUserQuestion 让用户选择使用哪种模式（支持多选），并简要告知每种模式的方法：

AskUserQuestion 参数：

• question: "选择关键词扩展模式（可多选）"
• header: "扩展模式"
• multiSelect: true
• 4 个选项分别对应上表，description 字段填写对应说明

用户选择后，按所选模式依次执行脚本，合并去重后输出结果。如果用户同时选了多个模式，串行执行各模式，最终合并去重。

工作流程

模式1：批量扩展（建库主力）

给定种子词 + 变体前缀模板，批量扩展大量长尾词。

输入: seed="fan", prefixes=["fan for", "fan portable", "fan quiet", ...]
输出: 100-300条去重关键词

执行脚本：

python3 ~/.hermes/skills/productivity/amazon-suggestion-miner/scripts/suggestion_miner.py \
  --seed "fan" \
  --mode expand \
  --rounds 3 \
  --xlsx /root/keyword_suggestions_fan.xlsx

模式2：A-Z 字母扫描（穷举式覆盖）

在种子词后依次输入空格 + a/b/c.../z，记录每个字母组合下弹出的长尾词。共 26 个前缀，每个返回 ~10 条建议词，去重后通常 150-260 条。

输入: seed="wireless charger"
前缀: "wireless charger a", "wireless charger b", ..., "wireless charger z"
输出: 150-260条去重关键词

执行脚本：

python3 ~/.hermes/skills/productivity/amazon-suggestion-miner/scripts/suggestion_miner.py \
  --seed "wireless charger" \
  --mode az \
  --xlsx /root/keyword_az_wireless_charger.xlsx

模式3：逆向检索（两步联动）

模拟"将光标移到词根最前面，看系统推荐的前置修饰词"。分两步自动完成：

第一步 — A-Z 字母扫描：对种子词做 {seed} a ~ {seed} z 扫描，拿到后缀衍生词（如 "wireless charger adapter"、"wireless charger apple"）。

第二步 — 高频词逆向前置：从第一步结果中提取出现频率最高的 Top-N 单词（排除种子词本身），用 {高频词} {seed} 作为前缀再次请求建议词。

输入: seed="wireless charger"
Step 1: A-Z 扫描 → 260 条关键词
Step 2: 提取高频词 → ["adapter", "samsung", "car", "fast", "portable", ...] (Top-100)
        逆向检索 → "adapter wireless charger", "samsung wireless charger", ...
输出: 合并去重后 400-550 条关键词

执行脚本：

python3 ~/.hermes/skills/productivity/amazon-suggestion-miner/scripts/suggestion_miner.py \
  --seed "wireless charger" \
  --mode reverse \
  --top-n 30 \
  --xlsx /root/keyword_reverse_wireless_charger.xlsx

--top-n 控制逆向检索取多少个高频词（默认 100）。

模式4：深度递归扩展（单次查询 + 逐轮递归）

先用种子词做单次查询，拿到初始建议词；再对结果中的 Top-N 高频词逐一作为新前缀递归扩展，逐层深入挖掘。

R1: seed="fan" → 10条（单次查询）
R2: 取R1中Top-5高频词 → 每词10条 → 额外50条
R3: 取R2中Top-5高频词 → 每词10条 → 额外50条
去重合并 → ~110条

--depth 控制递归轮数（默认 2，即单次查询 + 1 轮递归），--top-n 控制每轮取多少高频词作为新前缀（默认 5）。

执行脚本：

python3 ~/.hermes/skills/productivity/amazon-suggestion-miner/scripts/suggestion_miner.py \
  --seed "fan" \
  --mode deep \
  --depth 3 \
  --top-n 5 \
  --xlsx /root/keyword_deep_fan.xlsx

变体前缀策略

扩展时自动生成以下前缀变体（可自定义）：

脚本默认生成10-13个前缀，每前缀返回10条，一轮即可拿到100-130条关键词。

输出格式

最终交付物为 Excel (xlsx) 文件。 脚本支持 JSON / CSV / SQLite 作为中间格式，但交付给用户的必须是 xlsx。禁止生成 HTML 报告。

Excel (xlsx) 输出 — 默认交付格式

python3 suggestion_miner.py --seed "fan" --mode expand --xlsx /root/suggestions_fan.xlsx

Sheet 结构：

样式特性： 表头冻结、自动列宽、边框、表头蓝底白字。

JSON 输出示例

{
  "seed": "fan",
  "mode": "expand",
  "total_keywords": 127,
  "total_widget_items": 15,
  "keywords": [
    {
      "keyword": "fan for bedroom",
      "source": "autocomplete",
      "prefix": "fan for",
      "rank": 1,
      "sugg_type": "KeywordSuggestion",
      "candidate_source": "local"
    }
  ],
  "widget_items": [
    {
      "keyword": "Clip",
      "full_keyword": "clip fan for bedroom",
      "image_url": "https://m.media-amazon.com/images/I/xxx.jpg",
      "search_url": "/s?k=clip+fan+for+bedroom"
    }
  ],
  "stats": {
    "rounds_executed": 3,
    "prefixes_tried": 15,
    "raw_suggestions": 150,
    "after_dedup": 127,
    "question_style": 0,
    "rufus_style_long": 5
  }
}

CSV 输出

keyword,source,prefix,rank,sugg_type,candidate_source
fan for bedroom,autocomplete,fan for,1,KeywordSuggestion,local
fan for bedroom quiet,autocomplete,fan for,2,KeywordSuggestion,local

SQLite 输出

自动写入 suggestion_keywords 表，可与 amazon-keyword-research 的 keywords 表关联：

CREATE TABLE IF NOT EXISTS suggestion_keywords (
    keyword TEXT,
    source TEXT,           -- 'autocomplete' / 'widget'
    prefix TEXT,
    rank INT,
    sugg_type TEXT,        -- 'KeywordSuggestion' / 'WidgetSuggestion'
    candidate_source TEXT, -- 'local' / 'lucene'
    seed TEXT,             -- 原始英文种子词
    mode TEXT,
    depth INT,
    market TEXT,           -- 站点代码: US/DE/JP/...
    translated_seed TEXT,  -- 翻译后实际使用的种子词
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (keyword, market)
);

多站点 + 多语言自动适配（v2.0 核心功能）

多站点支持

支持 23 个 Amazon 全球站点，通过 --market/--markets 参数指定：

# 单站点
--market DE

# 多站点批量
--markets US,DE,JP

# 全站点
--markets ALL

站点参数差异（已验证 2026-05）：

5 个站点 (UK/AU/BR/SG/TR) curl 直接调 API 返回 202 空，需浏览器辅助。

种子词自动翻译（--auto-translate / -T）

核心洞察：不同站点的用户搜索语言习惯完全不同，不能简单地用英文种子词去搜所有站点！

三层翻译优先级：

1. 内置词典（最精准，覆盖常见品类）——支持 / 分隔多候选词
2. Google Translate（自动补充，可能不准）
3. 英文原词保底（DE站英文比德文多18倍！）

python3 suggestion_miner.py \
  --seed "feather duster" \
  --mode expand --rounds 2 \
  --markets US,DE,JP \
  --auto-translate \
  --xlsx /root/suggestions_feather_duster_multi.xlsx \
  --db /root/keyword_research.db -v

实测数据（feather duster，2026-05）：

关键教训：

• ❌ Google Translate 的 羽毛掃き 在JP站返回 0 条——翻译词不是当地人搜的词
• ❌ 不能只依赖单一翻译——DE站英文 >> 德文，JP站日文 >> 英文，方向相反
• ✅ 多候选词并行策略是必须的——内置词典同义词 + Google翻译 + 英文原词

本地化修饰词模板

非英语站点的扩展前缀也用当地语言，不用英文修饰词：

手动指定翻译（--translations）

覆盖自动翻译，精确控制每个站点用哪个种子词：

--translations "DE:Staubwedel,JP:ハタキ"

⚠️ 限制与注意事项

1. 无需登录：API 不需要登录态，session-id 可随机生成
2. 无反爬：大部分站点不触发 503 或验证码，但建议间隔 0.3-0.5 秒
3. 前缀长度：3词以上前缀若不加 site-variant=desktop 参数，返回量锐减（可能仅1条原词）。必须传 site-variant=desktop，该参数触发 lucene 模糊匹配引擎，使多词前缀也能返回10条建议词（见下方"双引擎机制"）
4. Rufus 个人化问句：API 无法获取登录态下的个性化 Rufus 问句建议
5. Widget 限制：Widget 子分类词需要拼回完整关键词才能使用（如 "Clip" → "clip fan for bedroom"）
6. 5个反爬站点：UK/AU/BR/SG/TR 的 curl 直接调 API 返回 202/空，需浏览器辅助
7. 翻译风险：Google Translate 翻译的词可能是书面语而非搜索用语，务必看返回量验证
8. DE站英文优势：德国用户大量用英文搜索（尤其3C/家居品类），英文种子词在DE站效果往往比德文好
9. 数据时效：建议词反映近期搜索热度，建议每2-4周重新挖掘一次

双引擎机制（关键发现 2026-05）

Amazon Suggestions API 内部有两套匹配引擎：

实测对比：

结论：site-variant=desktop 是必须参数，否则多词并列前缀会严重丢词。API 调用时务必加上此参数。

与 amazon-keyword-research 的关系

推荐联动流程： 先用本工具扩展 200+ 关键词，再用 keyword-research 逐词爬搜索指标、评估机会。

已验证测试结果（2026-05-11）

单站点（US）

API 稳定性：100% 成功率，无 503/验证码，延迟 0.3-0.5s/请求

多站点 + 自动翻译（v2.0）

结论：多候选词 + 自动翻译策略是必须的，单翻译会严重遗漏