Zach Search Term Report Analyzer

前置建议

本公开版 Skill 是自包含的，不依赖私有工作区文件、内部知识库、店铺配置或团队数据源。

开始执行前，建议先读取本 Skill 自带材料：

• references/field_mapping.md — SP / SB / SD 字段映射
• references/decision_rules.md — 搜索词决策规则
• references/term_classification.md — 品牌词、竞品词、属性词、场景词分类口径
• references/output_template.md — 报告与 CSV 输出模板
• scripts/clean_search_term_report.py — 原始报表清洗与标准化脚本
• scripts/analyze_search_term_decisions.py — 单 ASIN 决策分析脚本
• scripts/fetch_listing_context.py — 可选的 Amazon 前台 Listing 上下文抓取脚本

定位

广告搜索词报告不只用来找否词。它同时承担三件事：

1. 找出持续消耗预算但转化弱的词
2. 找出 CVR、ACOS 或趋势表现更好的放量候选
3. 从用户真实搜索语言里提炼属性词、场景词和 Listing 反馈线索

本 Skill 输出的是分析建议和行动候选，不会替用户直接修改广告、预算、出价或否词设置。

输入参数

| 参数 | 必须 | 默认值 | 说明 | |------|------|--------|------| | 搜索词报告文件 | 是 | - | CSV / XLSX / XLSM / XLS，优先使用 Amazon Ads 官方导出文件 | | 品牌 | 否 | 报表字段或文件名识别 | 也可用 --brand 显式指定 | | ASIN | 否 | 自动识别单一候选 | 多个候选时必须让用户选择一个 | | 站点 | 否 | US | 用于可选 Listing 抓取 | | 报告类型 | 否 | 自动识别 | SP / SB / SD；识别失败时标记 UNKNOWN | | 目标 ACOS | 否 | 报表自身基准 | 用 --target-acos 0.20 显式传入更稳 | | Listing 上下文 | 否 | 默认尝试 live fetch | 可用 --listing-context-file 提供本地标题/卖点文本 |

执行流程

Step 1: 识别输入文件与分析对象

1. 读取用户上传或指定的搜索词报告。
2. 运行清洗脚本识别字段、报告类型、品牌候选和 ASIN 候选：

python3 skills/zach-search-term-report-analyzer/scripts/clean_search_term_report.py 

1. 如果识别到多个 ASIN，先列候选给用户选择，不要混合分析。
2. 如果品牌无法识别，允许用户用 --brand 显式传入；品牌只用于分组、文件命名和品牌词识别。

Step 2: 标准化字段

按 references/field_mapping.md 将原始字段统一为内部字段：

• date
• brand
• asin
• campaign_name
• ad_group_name
• targeting
• match_type
• search_term
• impressions
• clicks
• spend
• orders
• sales
• cvr
• acos
• roas

缺失字段按“有就用，没有就跳过”处理；但核心字段 date + search_term + clicks + spend 缺失时必须停止。

Step 3: 建立 ASIN 基准与时间窗

1. 默认以单个 ASIN 为分析单位。
2. 建立该 ASIN 近 30 天广告 CVR 基准：orders / clicks。
3. 分别聚合 7 / 14 / 30 天窗口的点击、花费、订单、CVR、ACOS 和趋势变化。
4. 如果用户提供 --target-acos，用它判断成本压力；否则使用该 ASIN 报表自身 ACOS 作参考。

Step 4: 抓取或读取 Listing 上下文

默认行为：脚本会尝试按 ASIN 和站点访问 Amazon 前台页面，提取 title / bullets / description / breadcrumb。

稳定测试或网络受限时使用：

--skip-live-listing-fetch
--listing-context-file skills/zach-search-term-report-analyzer/examples/listing-context-sample.md

Listing 上下文只用于增强“相关词、属性词、场景词、弱相关词”的判断；抓取失败不能阻断基础广告分析。

Step 5: 做搜索词决策分析

读取 references/decision_rules.md 和 references/term_classification.md，为每个 search term 输出：

• 主分类：brand_term / competitor_term / asin_term / core_category_term / attribute_term / scenario_term / irrelevant_term / uncertain_term
• 动作标签：scale_up / hold_test / reduce_bid / negative_candidate / observe / listing_feedback / manual_review
• 置信度：high / medium / low
• 解释：说明点击、花费、CVR、ACOS、趋势和 Listing 相关性如何共同支持该判断

Step 6: 输出报告与明细

默认输出到：

outputs/search-term-report-analyzer/{brand_or_unknown}/

脚本命令示例：

python3 skills/zach-search-term-report-analyzer/scripts/analyze_search_term_decisions.py \
   \
  --brand ExampleBrand \
  --asin B0PUBLIC01 \
  --target-acos 0.20 \
  --listing-context-file skills/zach-search-term-report-analyzer/examples/listing-context-sample.md \
  --skip-live-listing-fetch

输出文件清单

| 文件 | 格式 | 路径 | |------|------|------| | 主报告 | .md | outputs/search-term-report-analyzer/{brand}/{YYYY-MM-DD}_{brand}_{asin}_7-14-30天_搜索词报告分析.md | | 明细表 | .csv | outputs/search-term-report-analyzer/{brand}/{YYYY-MM-DD}_{brand}_{asin}_7-14-30天_搜索词分析明细.csv | | 异常清单 | .csv | outputs/search-term-report-analyzer/{brand}/{YYYY-MM-DD}_{brand}_{asin}_7-14-30天_异常清单.csv | | 运行摘要 | .json | outputs/search-term-report-analyzer/{brand}/{YYYY-MM-DD}_{brand}_{asin}_7-14-30天_run_summary.json |

风险与边界

• 本 Skill 不做：
• 不直接修改广告出价、预算、否词或广告结构
• 不上传用户报表、不沉淀真实销售数据
• 不依赖私有店铺配置或内部知识库
• 字段不足时不强行给出 CVR / ACOS 结论
• 需要人工复核：
• 多个 ASIN 混在同一份报告里
• 品牌词、竞品词或 ASIN 型搜索词策略不明确
• Listing 抓取失败且词义相关性高度依赖产品卖点
• 点击量低、花费低或 7 / 14 / 30 天信号互相冲突
• risk-level = medium：
• 本 Skill 会给出广告动作建议，但任何出价、预算、否词执行都需要用户确认后手动完成。

上游 / 下游

• 上游：
• 用户提供的 Amazon Ads search term report
• 可选 Listing 上下文文件
• 下游：
• 人工广告操作：复核否词候选、控 bid 候选、放量候选
• Listing 优化：把属性词、场景词、需求词反馈到标题、卖点、A+ 或素材

完成后

报告完成状态：

• DONE — 报告、明细、异常清单和摘要均已生成
• DONEWITHCONCERNS — 已生成，但存在需人工复核的高影响项
• BLOCKED — 核心字段缺失、文件不可读或 ASIN 无法确定
• NEEDS_CONTEXT — 需要用户补充品牌、ASIN、站点、目标 ACOS 或 Listing 上下文

告知用户：

1. 分析对象：品牌、ASIN、站点、报告类型
2. 结果摘要：否词候选、控成本候选、放量候选、Listing 反馈词数量
3. 文件路径：主报告、明细表、异常清单和运行摘要

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zach22-1999
• Source: zach22-1999/amazon-skills
• License: MIT

Install and usage instructions live in the source repository linked above.