Zach search term report analyzer

Amazon 搜索词报告分析（v2）

工作方式

v2 将确定性计算与语义判断分开：

搜索词报告
  → Stage A：清洗、7/14/30 天聚合、词根聚类、硬标签
  → Stage B：AI 助手或人工完成词根语义分类
  → Stage C：严格校验、词根决策继承、六类结果渲染

词根继承用于处理低样本长尾词：当单个搜索词样本不足、但所属词根样本足够时，该词继承词根级判断；词与词根样本都不足时进入低量长尾池 pool，汇总监控但不伪装成待判定。

需要的输入

参数	必须	默认值	说明
搜索词报告	是	—	CSV / XLSX / XLSM / XLS
ASIN	是	—	一次只分析一个 ASIN
品牌	是	—	用于品牌词硬标签与输出命名
目标 ACOS	是	—	使用小数，例如 0.20
站点	否	US	用于可选的 Listing 上下文抓取
报告类型	否	自动识别	SP / SB / SD
时间窗	否	7,14,30	用逗号分隔
Listing 上下文	否	空	可传入本地 Markdown / 文本快照

如果报告包含多个 ASIN，先从清洗元数据中列出候选，再让用户选定一个；不要混合分析。目标 ACOS、品牌或 ASIN 缺失时必须补齐，不能用隐藏默认值代替。

本地参考

• references/architecture.md — v2 管线、数据契约与决策顺序
• references/field_mapping.md — SP / SB / SD 字段映射
• references/decision_rules.md — 决策规则的运营解释
• references/term_classification.md — Stage B 分类枚举与 JSON schema
• references/output_template.md — 六类输出与完成信号
• scripts/prepare_search_term_analysis.py — Stage A
• scripts/finalize_search_term_report.py — Stage C
• scripts/clean_search_term_report.py — 清洗底层
• scripts/fetch_listing_context.py — 可选 Listing 上下文抓取

Stage A：准备分析工作簿

python3 skills/zach-search-term-report-analyzer/scripts/prepare_search_term_analysis.py \
  <input_file> \
  --asin B0XXXXXXXX \
  --brand ExampleBrand \
  --site US \
  --target-acos 0.20 \
  --windows 7,14,30 \
  --listing-context-file <optional-listing-context.md> \
  --output-dir outputs/search-term-report-analyzer/ExampleBrand/intermediate/

--listing-context-file 与 --report-type 均为可选参数，不使用时删除对应命令行。

Stage A 只做可复现计算：

• 标准化字段、搜索词和数值格式
• 识别无法解析的非空数值，禁止静默清零
• 按 7/14/30 天窗口聚合并重新计算 CTR、CVR、ACOS、ROAS
• 聚类搜索词词根
• 标记确定性的 asin_term 与 brand_term

它会在中间目录生成：

• workbook.json：term、root、窗口指标和分类请求
• roots_for_review.md：按花费排序的待分类词根表

Stage B：完成词根分类

读取 roots_for_review.md、workbook.json 中的 Listing 上下文和 references/term_classification.md，为 classification_request.roots_to_classify 中每一个词根填写：

• category
• relevance
• 一句话 note
• 可选的 needs_listing_check

输出 root_classifications.json。示意结构：

{
  "asin": "B0XXXXXXXX",
  "classified_by": "ai_assistant",
  "listing_context_source": "workbook.meta.listing_context",
  "roots": {
    "portable karaoke": {
      "category": "core_category_term",
      "relevance": "high",
      "note": "与目标商品的核心用途直接一致",
      "needs_listing_check": false
    }
  },
  "term_overrides": {}
}

分类纪律：

1. 禁止使用 uncertain_term，必须给出 category 和 relevance。
2. 所有待分类词根必须覆盖，缺一个 Stage C 都会失败。
3. needs_listing_check 只用于少数确实依赖页面能力才能判断的词根。
4. 只有成员词明显偏离词根语义时才写 term_overrides。
5. 否词判断必须同时考虑相关性、样本量和 Listing 承接，不因一次点击机械否定。

Stage C：生成正式结果

python3 skills/zach-search-term-report-analyzer/scripts/finalize_search_term_report.py \
  outputs/search-term-report-analyzer/ExampleBrand/intermediate/workbook.json \
  --classifications outputs/search-term-report-analyzer/ExampleBrand/intermediate/root_classifications.json \
  --output-dir outputs/search-term-report-analyzer/ExampleBrand/

Stage C 启动时会严格校验分类覆盖率和枚举值。校验通过后，每个搜索词得到一个主决策、一个决策依据层级 basis、置信度和原因。

输出

输出目录建议为 outputs/search-term-report-analyzer/{brand}/：

文件	用途
..._搜索词报告分析.md	主报告
..._搜索词分析明细.csv	全词明细
..._否词清单.csv	exact 否词候选与 root 级 phrase 建议
..._搜索词分析操作台.html	可筛选、排序、勾选和导出 CSV 的交互工作台
..._搜索词分析汇报.html	KPI、决策分布和花费去向静态汇报页
..._run_summary.json	验收指标与文件清单

两个 HTML 都是自包含单文件，数据内联，无 CDN、Webfont、外链图片或运行时 fetch，可直接用浏览器打开。

验收

读取 run_summary.json 并核对：

1. pending_ratio_terms 与 pending_ratio_spend 均不高于 0.10；超标必须解释。
2. pool 的词数、点击、花费和订单在报告中单独披露，且不计入 pending。
3. 六类正式输出全部存在，两个 HTML 不包含“payload 未注入”提示。
4. 决策分布、花费去向、主报告和 CSV 相互一致。
5. 报告区分数据事实与分析推断，并标注来源文件和时间范围。

风险与边界

• 本 skill 只输出建议，不自动修改广告预算、bid、匹配类型或否词。
• 字段不足时不强行生成 ACOS / CVR 结论；SB / SD 缺少订单或销售字段时，只做可由现有字段支持的判断并声明限制。
• ASIN 串号、产品混杂、分类覆盖不全、核心字段缺失或 pending 超标时，必须升级人工复核。
• 任何真实广告修改都应在用户确认后通过对应广告平台执行。

旧版兼容入口

scripts/analyze_search_term_decisions.py 暂时保留，供已有自动化过渡使用，但已弃用。新任务只使用 Stage A → Stage B → Stage C；旧入口将在后续大版本移除。