zach-search-term-report-analyzer

Name: zach-search-term-report-analyzer
Author: zach22-1999

123stars32forks

How to install zach-search-term-report-analyzer?

zach22-1999/amazon-skills/zach-search-term-report-analyzer

$npx -y skills add zach22-1999/amazon-skills --skill zach-search-term-report-analyzer

Installs into the current project.

Summary

分析 Amazon Ads SP / SB / SD 搜索词报告。确定性脚本负责清洗、时间窗聚合、词根聚类和决策计算，AI 助手或人工负责词根级语义分类；通过词根继承减少长尾词的待判定比例，输出 Markdown、CSV、HTML 和 JSON 六类结果。使用时机：判断搜索词是否应该否定、控成本、继续测试或放量，分析 7/14/30 天 CVR 与 ACOS 变化，或者提炼可反馈给 Listing 的属性词和场景词。触发词：/zach-search-term-report-analyzer

Files · 1

View on GitHub

SKILL.md

1	# Amazon 搜索词报告分析（v2）
2
3	## 工作方式
4
5	v2 将确定性计算与语义判断分开：
6
7	```text
8	搜索词报告
9	→ Stage A：清洗、7/14/30 天聚合、词根聚类、硬标签
10	→ Stage B：AI 助手或人工完成词根语义分类
11	→ Stage C：严格校验、词根决策继承、六类结果渲染
12	```
13
14	词根继承用于处理低样本长尾词：当单个搜索词样本不足、但所属词根样本足够时，该词继承词根级判断；词与词根样本都不足时进入低量长尾池 `pool`，汇总监控但不伪装成待判定。
15
16	## 需要的输入
17
18	\| 参数 \| 必须 \| 默认值 \| 说明 \|
19	\|------\|------\|--------\|------\|
20	\| 搜索词报告 \| 是 \| — \| CSV / XLSX / XLSM / XLS \|
21	\| ASIN \| 是 \| — \| 一次只分析一个 ASIN \|
22	\| 品牌 \| 是 \| — \| 用于品牌词硬标签与输出命名 \|
23	\| 目标 ACOS \| 是 \| — \| 使用小数，例如 `0.20` \|
24	\| 站点 \| 否 \| US \| 用于可选的 Listing 上下文抓取 \|
25	\| 报告类型 \| 否 \| 自动识别 \| SP / SB / SD \|
26	\| 时间窗 \| 否 \| 7,14,30 \| 用逗号分隔 \|
27	\| Listing 上下文 \| 否 \| 空 \| 可传入本地 Markdown / 文本快照 \|
28
29	如果报告包含多个 ASIN，先从清洗元数据中列出候选，再让用户选定一个；不要混合分析。目标 ACOS、品牌或 ASIN 缺失时必须补齐，不能用隐藏默认值代替。
30
31	## 本地参考
32
33	- `references/architecture.md` — v2 管线、数据契约与决策顺序
34	- `references/field_mapping.md` — SP / SB / SD 字段映射
35	- `references/decision_rules.md` — 决策规则的运营解释
36	- `references/term_classification.md` — Stage B 分类枚举与 JSON schema
37	- `references/output_template.md` — 六类输出与完成信号
38	- `scripts/prepare_search_term_analysis.py` — Stage A
39	- `scripts/finalize_search_term_report.py` — Stage C
40	- `scripts/clean_search_term_report.py` — 清洗底层
41	- `scripts/fetch_listing_context.py` — 可选 Listing 上下文抓取
42
43	## Stage A：准备分析工作簿
44
45	```bash
46	python3 skills/zach-search-term-report-analyzer/scripts/prepare_search_term_analysis.py \
47	<input_file> \
48	--asin B0XXXXXXXX \
49	--brand ExampleBrand \
50	--site US \
51	--target-acos 0.20 \
52	--windows 7,14,30 \
53	--listing-context-file <optional-listing-context.md> \
54	--output-dir outputs/search-term-report-analyzer/ExampleBrand/intermediate/
55	```
56
57	`--listing-context-file` 与 `--report-type` 均为可选参数，不使用时删除对应命令行。
58
59	Stage A 只做可复现计算：
60
61	- 标准化字段、搜索词和数值格式
62	- 识别无法解析的非空数值，禁止静默清零
63	- 按 7/14/30 天窗口聚合并重新计算 CTR、CVR、ACOS、ROAS
64	- 聚类搜索词词根
65	- 标记确定性的 `asin_term` 与 `brand_term`
66
67	它会在中间目录生成：
68
69	- `workbook.json`：term、root、窗口指标和分类请求
70	- `roots_for_review.md`：按花费排序的待分类词根表
71
72	## Stage B：完成词根分类
73
74	读取 `roots_for_review.md`、`workbook.json` 中的 Listing 上下文和 `references/term_classification.md`，为 `classification_request.roots_to_classify` 中每一个词根填写：
75
76	- `category`
77	- `relevance`
78	- 一句话 `note`
79	- 可选的 `needs_listing_check`
80
81	输出 `root_classifications.json`。示意结构：
82
83	```json
84	{
85	"asin": "B0XXXXXXXX",
86	"classified_by": "ai_assistant",
87	"listing_context_source": "workbook.meta.listing_context",
88	"roots": {
89	"portable karaoke": {
90	"category": "core_category_term",
91	"relevance": "high",
92	"note": "与目标商品的核心用途直接一致",
93	"needs_listing_check": false
94	}
95	},
96	"term_overrides": {}
97	}
98	```
99
100	分类纪律：
101
102	1. 禁止使用 `uncertain_term`，必须给出 category 和 relevance。
103	2. 所有待分类词根必须覆盖，缺一个 Stage C 都会失败。
104	3. `needs_listing_check` 只用于少数确实依赖页面能力才能判断的词根。
105	4. 只有成员词明显偏离词根语义时才写 `term_overrides`。
106	5. 否词判断必须同时考虑相关性、样本量和 Listing 承接，不因一次点击机械否定。
107
108	## Stage C：生成正式结果
109
110	```bash
111	python3 skills/zach-search-term-report-analyzer/scripts/finalize_search_term_report.py \
112	outputs/search-term-report-analyzer/ExampleBrand/intermediate/workbook.json \
113	--classifications outputs/search-term-report-analyzer/ExampleBrand/intermediate/root_classifications.json \
114	--output-dir outputs/search-term-report-analyzer/ExampleBrand/
115	```
116
117	Stage C 启动时会严格校验分类覆盖率和枚举值。校验通过后，每个搜索词得到一个主决策、一个决策依据层级 `basis`、置信度和原因。
118
119	## 输出
120
121	输出目录建议为 `outputs/search-term-report-analyzer/{brand}/`：
122
123	\| 文件 \| 用途 \|
124	\|------\|------\|
125	\| `..._搜索词报告分析.md` \| 主报告 \|
126	\| `..._搜索词分析明细.csv` \| 全词明细 \|
127	\| `..._否词清单.csv` \| exact 否词候选与 root 级 phrase 建议 \|
128	\| `..._搜索词分析操作台.html` \| 可筛选、排序、勾选和导出 CSV 的交互工作台 \|
129	\| `..._搜索词分析汇报.html` \| KPI、决策分布和花费去向静态汇报页 \|
130	\| `..._run_summary.json` \| 验收指标与文件清单 \|
131
132	两个 HTML 都是自包含单文件，数据内联，无 CDN、Webfont、外链图片或运行时 `fetch`，可直接用浏览器打开。
133
134	## 验收
135
136	读取 `run_summary.json` 并核对：
137
138	1. `pending_ratio_terms` 与 `pending_ratio_spend` 均不高于 `0.10`；超标必须解释。
139	2. `pool` 的词数、点击、花费和订单在报告中单独披露，且不计入 pending。
140	3. 六类正式输出全部存在，两个 HTML 不包含“payload 未注入”提示。
141	4. 决策分布、花费去向、主报告和 CSV 相互一致。
142	5. 报告区分数据事实与分析推断，并标注来源文件和时间范围。
143
144	## 风险与边界
145
146	- 本 skill 只输出建议，不自动修改广告预算、bid、匹配类型或否词。
147	- 字段不足时不强行生成 ACOS / CVR 结论；SB / SD 缺少订单或销售字段时，只做可由现有字段支持的判断并声明限制。
148	- ASIN 串号、产品混杂、分类覆盖不全、核心字段缺失或 pending 超标时，必须升级人工复核。
149	- 任何真实广告修改都应在用户确认后通过对应广告平台执行。
150
151	## 旧版兼容入口
152
153	`scripts/analyze_search_term_decisions.py` 暂时保留，供已有自动化过渡使用，但已弃用。新任务只使用 Stage A → Stage B → Stage C；旧入口将在后续大版本移除。

People who liked this also viewed

6 picks

Type

zach-search-term-report-analyzer

123stars32forks

View on GitHub

How to install zach-search-term-report-analyzer?

zach22-1999/amazon-skills/zach-search-term-report-analyzer

$npx -y skills add zach22-1999/amazon-skills --skill zach-search-term-report-analyzer

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Amazon 搜索词报告分析（v2）
2
3	## 工作方式
4
5	v2 将确定性计算与语义判断分开：
6
7	```text
8	搜索词报告
9	→ Stage A：清洗、7/14/30 天聚合、词根聚类、硬标签
10	→ Stage B：AI 助手或人工完成词根语义分类
11	→ Stage C：严格校验、词根决策继承、六类结果渲染
12	```
13
14	词根继承用于处理低样本长尾词：当单个搜索词样本不足、但所属词根样本足够时，该词继承词根级判断；词与词根样本都不足时进入低量长尾池 `pool`，汇总监控但不伪装成待判定。
15
16	## 需要的输入
17
18	\| 参数 \| 必须 \| 默认值 \| 说明 \|
19	\|------\|------\|--------\|------\|
20	\| 搜索词报告 \| 是 \| — \| CSV / XLSX / XLSM / XLS \|
21	\| ASIN \| 是 \| — \| 一次只分析一个 ASIN \|
22	\| 品牌 \| 是 \| — \| 用于品牌词硬标签与输出命名 \|
23	\| 目标 ACOS \| 是 \| — \| 使用小数，例如 `0.20` \|
24	\| 站点 \| 否 \| US \| 用于可选的 Listing 上下文抓取 \|
25	\| 报告类型 \| 否 \| 自动识别 \| SP / SB / SD \|
26	\| 时间窗 \| 否 \| 7,14,30 \| 用逗号分隔 \|
27	\| Listing 上下文 \| 否 \| 空 \| 可传入本地 Markdown / 文本快照 \|
28
29	如果报告包含多个 ASIN，先从清洗元数据中列出候选，再让用户选定一个；不要混合分析。目标 ACOS、品牌或 ASIN 缺失时必须补齐，不能用隐藏默认值代替。
30
31	## 本地参考
32
33	- `references/architecture.md` — v2 管线、数据契约与决策顺序
34	- `references/field_mapping.md` — SP / SB / SD 字段映射
35	- `references/decision_rules.md` — 决策规则的运营解释
36	- `references/term_classification.md` — Stage B 分类枚举与 JSON schema
37	- `references/output_template.md` — 六类输出与完成信号
38	- `scripts/prepare_search_term_analysis.py` — Stage A
39	- `scripts/finalize_search_term_report.py` — Stage C
40	- `scripts/clean_search_term_report.py` — 清洗底层
41	- `scripts/fetch_listing_context.py` — 可选 Listing 上下文抓取
42
43	## Stage A：准备分析工作簿
44
45	```bash
46	python3 skills/zach-search-term-report-analyzer/scripts/prepare_search_term_analysis.py \
47	<input_file> \
48	--asin B0XXXXXXXX \
49	--brand ExampleBrand \
50	--site US \
51	--target-acos 0.20 \
52	--windows 7,14,30 \
53	--listing-context-file <optional-listing-context.md> \
54	--output-dir outputs/search-term-report-analyzer/ExampleBrand/intermediate/
55	```
56
57	`--listing-context-file` 与 `--report-type` 均为可选参数，不使用时删除对应命令行。
58
59	Stage A 只做可复现计算：
60
61	- 标准化字段、搜索词和数值格式
62	- 识别无法解析的非空数值，禁止静默清零
63	- 按 7/14/30 天窗口聚合并重新计算 CTR、CVR、ACOS、ROAS
64	- 聚类搜索词词根
65	- 标记确定性的 `asin_term` 与 `brand_term`
66
67	它会在中间目录生成：
68
69	- `workbook.json`：term、root、窗口指标和分类请求
70	- `roots_for_review.md`：按花费排序的待分类词根表
71
72	## Stage B：完成词根分类
73
74	读取 `roots_for_review.md`、`workbook.json` 中的 Listing 上下文和 `references/term_classification.md`，为 `classification_request.roots_to_classify` 中每一个词根填写：
75
76	- `category`
77	- `relevance`
78	- 一句话 `note`
79	- 可选的 `needs_listing_check`
80
81	输出 `root_classifications.json`。示意结构：
82
83	```json
84	{
85	"asin": "B0XXXXXXXX",
86	"classified_by": "ai_assistant",
87	"listing_context_source": "workbook.meta.listing_context",
88	"roots": {
89	"portable karaoke": {
90	"category": "core_category_term",
91	"relevance": "high",
92	"note": "与目标商品的核心用途直接一致",
93	"needs_listing_check": false
94	}
95	},
96	"term_overrides": {}
97	}
98	```
99
100	分类纪律：
101
102	1. 禁止使用 `uncertain_term`，必须给出 category 和 relevance。
103	2. 所有待分类词根必须覆盖，缺一个 Stage C 都会失败。
104	3. `needs_listing_check` 只用于少数确实依赖页面能力才能判断的词根。
105	4. 只有成员词明显偏离词根语义时才写 `term_overrides`。
106	5. 否词判断必须同时考虑相关性、样本量和 Listing 承接，不因一次点击机械否定。
107
108	## Stage C：生成正式结果
109
110	```bash
111	python3 skills/zach-search-term-report-analyzer/scripts/finalize_search_term_report.py \
112	outputs/search-term-report-analyzer/ExampleBrand/intermediate/workbook.json \
113	--classifications outputs/search-term-report-analyzer/ExampleBrand/intermediate/root_classifications.json \
114	--output-dir outputs/search-term-report-analyzer/ExampleBrand/
115	```
116
117	Stage C 启动时会严格校验分类覆盖率和枚举值。校验通过后，每个搜索词得到一个主决策、一个决策依据层级 `basis`、置信度和原因。
118
119	## 输出
120
121	输出目录建议为 `outputs/search-term-report-analyzer/{brand}/`：
122
123	\| 文件 \| 用途 \|
124	\|------\|------\|
125	\| `..._搜索词报告分析.md` \| 主报告 \|
126	\| `..._搜索词分析明细.csv` \| 全词明细 \|
127	\| `..._否词清单.csv` \| exact 否词候选与 root 级 phrase 建议 \|
128	\| `..._搜索词分析操作台.html` \| 可筛选、排序、勾选和导出 CSV 的交互工作台 \|
129	\| `..._搜索词分析汇报.html` \| KPI、决策分布和花费去向静态汇报页 \|
130	\| `..._run_summary.json` \| 验收指标与文件清单 \|
131
132	两个 HTML 都是自包含单文件，数据内联，无 CDN、Webfont、外链图片或运行时 `fetch`，可直接用浏览器打开。
133
134	## 验收
135
136	读取 `run_summary.json` 并核对：
137
138	1. `pending_ratio_terms` 与 `pending_ratio_spend` 均不高于 `0.10`；超标必须解释。
139	2. `pool` 的词数、点击、花费和订单在报告中单独披露，且不计入 pending。
140	3. 六类正式输出全部存在，两个 HTML 不包含“payload 未注入”提示。
141	4. 决策分布、花费去向、主报告和 CSV 相互一致。
142	5. 报告区分数据事实与分析推断，并标注来源文件和时间范围。
143
144	## 风险与边界
145
146	- 本 skill 只输出建议，不自动修改广告预算、bid、匹配类型或否词。
147	- 字段不足时不强行生成 ACOS / CVR 结论；SB / SD 缺少订单或销售字段时，只做可由现有字段支持的判断并声明限制。
148	- ASIN 串号、产品混杂、分类覆盖不全、核心字段缺失或 pending 超标时，必须升级人工复核。
149	- 任何真实广告修改都应在用户确认后通过对应广告平台执行。
150
151	## 旧版兼容入口
152
153	`scripts/analyze_search_term_decisions.py` 暂时保留，供已有自动化过渡使用，但已弃用。新任务只使用 Stage A → Stage B → Stage C；旧入口将在后续大版本移除。

People who liked this also viewed

6 picks

Type