tomevault-io 前置建议
本公开版 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 上下文抓取脚本
定位
广告搜索词报告不只用来找否词。它同时承担三件事：
- 找出持续消耗预算但转化弱的词
- 找出 CVR、ACOS 或趋势表现更好的放量候选
- 从用户真实搜索语言里提炼属性词、场景词和 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: 识别输入文件与分析对象
- 读取用户上传或指定的搜索词报告。
- 运行清洗脚本识别字段、报告类型、品牌候选和 ASIN 候选：
python3 skills/zach-search-term-report-analyzer/scripts/clean_search_term_report.py <input_file>
- 如果识别到多个 ASIN，先列候选给用户选择，不要混合分析。
- 如果品牌无法识别，允许用户用
--brand显式传入；品牌只用于分组、文件命名和品牌词识别。
Step 2: 标准化字段
按 references/field_mapping.md 将原始字段统一为内部字段：
datebrandasincampaign_namead_group_nametargetingmatch_typesearch_termimpressionsclicksspendorderssalescvracosroas
缺失字段按“有就用，没有就跳过”处理；但核心字段 date + search_term + clicks + spend 缺失时必须停止。
Step 3: 建立 ASIN 基准与时间窗
- 默认以单个 ASIN 为分析单位。
- 建立该 ASIN 近 30 天广告 CVR 基准：
orders / clicks。 - 分别聚合 7 / 14 / 30 天窗口的点击、花费、订单、CVR、ACOS 和趋势变化。
- 如果用户提供
--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 \
<input_file> \
--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 — 报告、明细、异常清单和摘要均已生成
- DONE_WITH_CONCERNS — 已生成，但存在需人工复核的高影响项
- BLOCKED — 核心字段缺失、文件不可读或 ASIN 无法确定
- NEEDS_CONTEXT — 需要用户补充品牌、ASIN、站点、目标 ACOS 或 Listing 上下文
告知用户：
- 分析对象：品牌、ASIN、站点、报告类型
- 结果摘要：否词候选、控成本候选、放量候选、Listing 反馈词数量
- 文件路径：主报告、明细表、异常清单和运行摘要
Source: zach22-1999/amazon-skills — distributed by TomeVault.