/zach-search-term-analyzer

name: zach-search-term-analyzer
description: |
  分析 Amazon Brand Analytics 热门搜索词报告（Top Search Terms）。场景化框架：自家 ASIN 在/不在该词点击 TOP3 走完全不同的业务判断（存量经营 vs 市场进入），确定性脚本输出场景状态、市场结构象限与成交系数，直接对接广告分池和 Listing 关键词布局。
  使用时机：拿到 Brand Analytics Top Search Terms（热门搜索词）报告后，做关键词策略、市场进入判断或自家词份额监控。
  触发词：/zach-search-term-analyzer
triggers:
  - "/zach-search-term-analyzer"
benefits-from: [zach-product-research]
user-invocable: true
allowed-tools: [Read, Glob, Bash, Write, Edit, Grep]
risk-level: low

Amazon Brand Analytics 搜索词分析（v3 场景化框架）

分析 Brand Analytics Top Search Terms（热门搜索词）报告（任何类目），按"自家 ASIN 在/不在点击 TOP3"做场景路由，输出市场结构判断与实操建议。

---

数据来源（⚠️ 重要区分）

本工具分析的是 **Brand Analytics → Top Search Terms（热门搜索词）** 报告，**不是** PPC 搜索词报告；如果文件字段不包含下方必需字段，先停下确认报告类型。

| | Brand Analytics Top Search Terms | PPC 搜索词报告 | |---|---|---| | 来源 | Seller Central → Brand Analytics | 广告后台 → SP/SB Campaign | | 数据范围 | 全平台搜索词（与你的产品无关也能查） | 仅与你的广告触发相关的搜索词 | | 核心指标 | 搜索频率排名、点击份额、转化份额 | Impressions、Clicks、Spend、Sales、ACOS | | 适用场景 | 市场分析、选品定位、Listing 关键词策略、自家词份额监控 | 广告优化、出价调整、否定词管理 |

> ⚠️ 使用 Brand Analytics 需要完成品牌备案（Brand Registry）。PPC 搜索词报告请用 `zach-search-term-report-analyzer`。

报告口径速查（判读前必读）

| 口径 | 内容 | |---|---| | Search Frequency Rank | 全平台**相对排名**不是搜索量；#1 与 #2 可差数量级；跨类目/跨站点不可比 | | TOP3 商品 | 该词下**被点击最多**的 3 个 ASIN（含广告位点击）——是"点击王"不是"转化王"，转化最高的 ASIN 可能不在表里 | | 点击份额 / 转化份额 | **独立指标**：买家可点 A 买 B，所以 TOP3 转化份额为 0/缺失是常见真实现象（转化分散到长尾或被脱敏），不是数据错误 | | 成交系数 | 转化份额 ÷ 点击份额 = 该 ASIN 转化率 ÷ 该词平均转化率；≥1 = Closer，<1 = 流量磁铁 | | 粒度与滞后 | 日/周/月/季可选，实战以**周报**为主；数据滞后约 T+3~T+7；低频词被脱敏不显示 | | 定位边界 | ABA 代表热度流量，不必然代表市场需求全貌 |

---

数据诚信规则（⭐ 最高优先级）

1. **绝不捏造数据**：所有分析数据来自用户提供的报告原始文件，没有数据就说"暂无" 2. **缺失≠零**：转化份额缺失/全 0 的词单列 B0"数据不足"，不参与象限判定，不得判为"转化差" 3. **区分事实与推断**：数据结论标「📊 数据事实」，策略建议标「💡 分析推断」 4. **排名≠搜索量**：搜索频率排名只表示相对位置 5. **时效性**：建议用最近 3-6 个月数据；强季节性产品参考上个旺季同期，且不同时段分开分析

---

场景框架（v3 核心）

场景路由

自家 ASIN ∈ 该词点击 TOP3 ？
├─ 是 → 场景 A：存量经营（看自家行 + 同词竞品行）
├─ 否 → 场景 B：市场进入（看 TOP3 合计的市场结构）
└─ 未提供自家 ASIN → 全部场景 B，报告显著标注"仅市场视角"

场景 A：自家在 TOP3（防守/收割视角）

| 状态 | 判定（默认阈值） | 动作 | |---|---|---| | A1 收割词 | 自家成交系数 ≥ 1.0 | 防守+放量：加预算、防御性投放、盯竞品进入 | | A2 漏水词 | 自家点击份额 − 转化份额 > 4pt | 先修详情页再抬价：价格/评价/主图/A+，用 SQP 定位漏斗卡点 | | A4 份额预警 | 曾在 TOP3、最新一期掉出（或点击份额连续下滑） | 排查排名/价格/断货/新竞品 | | A5 平衡词 | 介于两者之间 | 维持现状，周度跟踪 |

附加信号：同词 TOP3 内竞品成交系数 <1 → **截流机会**（SP/SD 定向+压价）。

场景 B：自家不在 TOP3（进攻/进入视角）

两轴：**点击集中度** = SUM(TOP3 点击份额)；**头部满足度** = SUM(转化份额) ÷ SUM(点击份额)：

| 象限 | 判定（默认阈值） | 结构解读 | 动作 | |---|---|---|---| | B1 机会词 | 集中度 <50% 且 满足度 <1.0 | 点击分散且头部接不住需求，转化流向 TOP3 之外 | **优先级最高**：产品能接住意图则优先投放+进 Listing；先核对 TOP3 属性一致性 | | B2 常规竞争词 | 集中度 <50% 且 满足度 ≥1.0 | 蛋糕未整合、头部转化健康 | 可进：常规差异化+正常出价测试 | | B3 头部满足词 | 集中度 ≥50% 且 满足度 ≥1.0 | 头部垄断且高效满足市场 | 避其锋芒：不正面竞价，找相邻长尾切入 | | B4 伏击词 | 集中度 ≥50% 且 满足度 <1.0 | 头部霸点击但买家买了别家 | 伏击：竞品定向+压价，用转化力偷单，不打点击战 | | B0 数据不足 | 转化数据缺失/分散/脱敏 | 无法判定头部满足度 | 不判定；转 SQP/广告数据验证 |

附加信号：**垄断红线**（点击或转化集中度 ≥70%）；**蓝海信号**（SFR ≥20万 且 TOP3 份额 ≥60%，未开发利基）。

SFR 五级分层（预算量级标签，不参与象限判定）

T1 核心大词（≤1万，排名用）｜T2 次核心（1-2万）｜T3 中量词（2-5万）｜T4 中长尾（5-10万，ROI 导向）｜T5 长尾（>10万，追 ACOS）

> 全部阈值为多源实战经验默认值，可通过脚本参数按类目校准；判定标准与出处见 `references/关键词分类逻辑说明.md`。

---

执行步骤

1. **识别 CSV 文件** - 查找当前目录或指定目录下的搜索词报告 2. **确定自家 ASIN 清单（场景路由）** - 让用户提供自家 ASIN 清单；拿不到时明确告知"全部按场景 B 市场视角分析"再继续，不要静默跳过 3. **运行唯一分析引擎** - 使用脚本执行完整分析，禁止临时手写替代：

   python3 skills/zach-search-term-analyzer/scripts/analyze_search_terms.py <报告目录> \
     --own-asins "B0XXXXXXXX,B0YYYYYYYY"   # 或 --own-asins-file <清单文件>

• 跨品类可加 `--category-lexicon <品类词表.json>`（`audience_words / scene_words / attribute_words` 三个可选字符串数组）
• 类目校准阈值：`--click-conc-concentrated`、`--monopoly-redline`、`--coefficient-threshold`、`--own-gap-points`、`--sfr-tiers` 等

4. **（可选）语义注解 pass** - 脚本的关键词标签只是词面词典初筛；AI 助手可对 TOP 200 搜索词补充买家意图注解（谁在买/什么场景/什么任务），注解只做增量补充，不筛除、不重排、不改动脚本的量化分类 5. **解读报告** - 按场景框架给出投放分池与 Listing 布局建议；⚠️ 否定词不由本报告自动生成——否词决策由自家 PPC 搜索词报告驱动

输出文件

**analysis_reports/** 目录：

| 文件 | 内容 | |---|---| | `01_品牌竞争分析.csv/.md` | 品牌 TOP3 位置上榜频次（⚠️ 非市场销售份额） | | `02_类别趋势分析.csv/.md` | 类别分布与跨类目机会 | | `03_搜索词热度分析.csv/.md` ⭐⭐ | 场景化分类核心产物：场景/状态/集中度/满足度/红线/蓝海/自家份额 | | `04_词频统计分析.xlsx/.md` ⭐ | 单词+双词短语（去重计数；短语只取真实相邻组合） | | `05_竞争格局分析.csv/.md` | 点击 TOP3 商品层（自家 ★ 标记） | | `06_成交系数分析.csv/.md` | per-ASIN 成交系数：自家自诊+截流目标+逆向学习对象 | | `07_时间序列分析.csv/.md` | 分期概览+核心词趋势（多期时含 `核心关键词趋势.csv/.png`） |

报告格式要求

• CSV 文件（UTF-8 编码），支持多期报告；同一（搜索词, 报告日期）跨文件重复自动去重；份额字段兼容数值与 `12.34%` 字符串
• **必需字段**：搜索频率排名、搜索词、报告日期、点击量最高的商品 #1/#2/#3（ASIN/点击份额/转化份额）；品牌/类别字段缺失时对应维度出空占位报告（部分 ERP 导出如领星不含品牌字段）

实操建议示例

🧭 场景 A（自家 ASIN 已提供）：
🛡️ wireless speaker waterproof（A1收割词，自家系数1.3）→ 加预算防守
🔧 bluetooth speaker（A2漏水词，点击12.8% vs 转化6.1%）→ 先修详情页再抬价
🎯 同词竞品 B0XXXXXXXX 系数 0.4 → SP 商品定向截流

🧭 场景 B（市场进入）：
🌊 speaker with lights（B1机会词，集中度28%、满足度0.6）→ 属性一致则优先投放+进标题
🥷 party speaker（B4伏击词，集中度61%、满足度0.5）→ 竞品定向偷单，不打点击战
⛔ jbl speaker（B3头部满足词+垄断红线）→ 避其锋芒找长尾
❓ karaoke machine kids（B0数据不足）→ 转 SQP/广告数据验证

本地参考

• `references/关键词分类逻辑说明.md` — 场景框架完整判定标准、阈值依据与来源
• `references/字段说明.md` — 报告字段口径与陷阱
• `references/分析角度和方法.md` — 7 维度分析方法与实操应用
• `scripts/analyze_search_terms.py` — 唯一分析引擎（v3.0）

依赖环境

• Python 3.8+；依赖检查：

  python3 -c "import pandas, numpy, matplotlib, seaborn, openpyxl"

• 缺失时：`pip3 install -r skills/zach-search-term-analyzer/scripts/requirements.txt`

风险与边界

• **risk-level: low** — 纯本地分析，不涉及任何账号操作或数据写入；自家 ASIN 清单只用于本地路由计算
• 本报告的所有判断都是**先验**：B1 的"外流可接"、A2 的"漏水原因"，最终以 SQP（自家漏斗份额）与 PPC 数据（实际 CVR/ACOS）验证

完成后

报告完成状态：DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT