sif-keyword-scout

name	sif-keyword-scout
description	亚马逊 Sif 关键词情报侦察系统（Skill 1）。用户输入 ASIN，获取 Sif 三张报表（关键词调研/反查流量词/查广告词）， Python 完成分层、机会评级、缺口分析，三表交叉输出 PD 主攻词单。支持「用户手动导出」与「AI 浏览器导出」两种方式。 路径通过工作区 .sif-config.json 解析，不写死本机路径。Agent 以亚马逊关键词策略顾问角色解读结果并引导参数。 若 ASIN 有历史记录则自动触发 sif-keyword-tracker。触发：sif关键词、PD备战关键词、ASIN关键词调研、运行skill1。

Sif 关键词情报侦察（Skill 1）

Agent 角色

执行本 skill 时，同时阅读并遵循 references/amazon-expert-guide.md：

• 以亚马逊关键词/PPC 顾问身份解读结果，参数异常时主动引导用户
• 不是只跑脚本；S/A 门槛、类目描述、SS/SSS 数量异常时要说明原因并建议修正

人机协同原则（强制）

禁止「静默跑完全程」。本 skill 是顾问 + 自动化，不是批处理脚本。

规则	说明
跑前必聊	在 ingest_raw 或任何 --mode process 之前，必须与用户确认 ASIN、阶段、类目、数据来源
三处卡点	见下方「强制暂停点」——未获用户明确确认前，不得进入下一步
确认方式	用户回复「可以 / 继续 / 用自动值 / 按你说的」等明确许可；沉默或只给 ASIN 不算确认
异常先停	sanity check 触发时，先解释原因并给出选项，等用户选后再重跑或继续

强制暂停点（三处）

#	时机	Agent 做什么	用户确认什么
①	表1 compute-thresholds 之后、process 之前	展示 S/A 门槛、竞价/集中度中位数；结合阶段 + 类目说明是否偏高/偏低	维持自动值，或指定 --s-threshold / --a-threshold
②	三表 + 交叉 --skip-word 完成后、写 insights_cross 之前	解读 SSS/SS/S 数量、表3 缺口/离群词；列出建议主攻 SS 清单与应排除词	确认主攻方向与是否重跑表3（改类目/--sv-threshold）
③	Skill 2 compare_versions --skip-word 完成后、写 insights_tracker 之前	解读新增/消失/份额变化；给出试投/暂停/调价建议	确认是否按建议调整投放，或仅存档观察

话术与解读细则 → references/amazon-expert-guide.md 各节。

依赖

依赖	说明
Python	pip install pandas openpyxl matplotlib python-docx numpy
web-access	仅方式 B 需要；第三方 eze-is/web-access（作者一泽 Eze，MIT）；路径见 references/path-setup.md

最终产物：处理结果目录仅保留 Excel（.xlsx）+ Word（.docx）。 图表由脚本生成 PNG 后内嵌进 Word，不保留 charts/ 目录。 Agent 写的 insights_*.md 是中间稿（供 Word 渲染 AI 分析段），生成 Word 后自动删除。

---

三种输入方式（Agent 自动判断）

方式	用户怎么说	Agent 做什么
C 直接给路径（最快）	发来 3 个 xlsx 路径，或一个下载文件夹	ingest_raw.py 识别表类型 → 复制到标准目录 → 跑处理
A 手动导出	「我自己下好了」或放到指定目录	发 manual-export-guide.md，或 ingest_raw --from-dir
B 浏览器导出	「你帮我下」	web-access + browser-export-sop.md

用户直接给文件路径时：不必再问下载方式，先 resolve_workspace → 跑前简报（Step 1）获确认 → 调 ingest_raw → 从 Step 5 继续。

# 三个路径
python "{scripts.ingest_raw}" --asin {ASIN} --output-dir "{output_dir}" --stage {阶段} --product-category "{类目}" \
  --product-type {标品|非标品} \
  --t1 "D:/Downloads/Sif关键词调研-....xlsx" \
  --t2 "D:/Downloads/asinKeywords_....xlsx" \
  --t3 "D:/Downloads/asinAdKwView_....xlsx"

# 或一个文件夹（自动识别）
python "{scripts.ingest_raw}" --asin {ASIN} --output-dir "{output_dir}" --from-dir "D:/Downloads"

---

Step 0：工作区与路径初始化（每次运行开头）

python "{SKILL_SCOUT}/scripts/resolve_workspace.py"

解析 JSON，得到 workspace、config_path、output_dir、download_dir、scripts.*、web_access 等。

情况	动作
workspace_found: false	让用户指定工作区根目录，或复制 .sif-config.example.json → .sif-config.json
needs_output_dir: true	必读 first-time-setup.md，向用户询问输出根目录，禁止填他人路径 → --init-output-dir
needs_download_dir: true	仅方式 B：询问浏览器下载目录 → --init-download-dir（方式 A/C 可跳过）
返回 first_time_guide	按其中 steps 逐条引导，配置完成后再跑 ASIN

路径是用户自己的：打包给他人时只发 .sif-config.example.json（空字段）；每人首次使用自己指定 output_dir。

详述 → references/path-setup.md · 首次对话脚本 → references/first-time-setup.md

---

Step 1：跑前简报（ASIN + 参数 + 用户确认）

在调用 ingest_raw 或处理脚本之前，完成以下对话并等待用户确认：

1. ASIN：用户消息含 ASIN → 直接使用；否则先问
2. 必问参数（不可跳过）：

1. 产品阶段：新品期 / 成长期 / 成熟期？
2. **产品类型**：标品 / 非标品？（决定默认门槛，见 `references/threshold-presets.md`）
3. 精确产品类目（影响表3 缺口词，如「不锈钢保温杯」而非笼统「水杯」）？

3. 跑前简报（用自然语言概括，勿只贴命令）：

   • 本次将产出 4 组 Excel + Word（表1/2/3 + PD 主攻词单）
   • 若有历史 → 额外产出词库更新报告（Skill 2）
   • 数据来源：方式 A / B / C（若用户已给文件路径则说明「直接接入」）
   • 预计会在 暂停点 ①② 与你确认门槛与主攻词方向

4. 确认门：用户明确回复后，才进入 Step 2~3。

类目引导规则 → references/amazon-expert-guide.md

---

Step 2：检查 ASIN 历史

python "{scripts.check_history}" --asin {ASIN} --output-dir "{output_dir}"

保存 has_history、prev_path 供 Step 10 使用。

---

Step 3：建目录 + 接入原始表

方式 C（已有文件路径）：Step 0 后直接调 ingest_raw（见上），本步合并完成。

方式 A/B（尚未有标准命名文件）：

python "{scripts.ingest_raw}" --asin {ASIN} --output-dir "{output_dir}" --stage {阶段} --product-category "{精确类目}" --product-type {标品|非标品}

解析 stdout JSON：

字段	含义
date / run_id	YYYYMMDD，用于文件名后缀
run_path	{ASIN}/{date}
raw_dir	原始数据目录
result_dir	处理结果目录
raw_files	三张原始表标准文件名
datetime_display	写入历史表的实际跑库时刻（含时分）

目录结构：

{output_dir}/{ASIN}/{DATE}/
├── 原始数据/
│   ├── 关键词调研_{DATE}.xlsx
│   ├── 反查流量词_{DATE}.xlsx
│   └── 查广告词_{DATE}.xlsx
└── 处理结果/          ← 最终仅保留 xlsx + docx
    ├── {ASIN}_关键词分层分析_{DATE}.xlsx
    ├── {ASIN}_关键词调研分析报告_{DATE}.docx
    ├── {ASIN}_竞品弱点分析_{DATE}.xlsx
    ├── {ASIN}_竞品弱点分析报告_{DATE}.docx
    ├── {ASIN}_竞品缺口分析_{DATE}.xlsx
    ├── {ASIN}_竞品广告缺口分析报告_{DATE}.docx
    ├── {ASIN}_PD主攻词单_{DATE}.xlsx
    └── {ASIN}_PD主攻词单报告_{DATE}.docx

中间产物（stats JSON、insights_*.md、charts/）在 Word 生成后由脚本 cleanup_intermediate_files 自动删除。

---

Step 4：获取三张原始表（仅 A/B 且 Step 3 尚未 ingest 时）

方式	动作
C 已有路径	跳过，Step 3 的 ingest_raw 已完成
A 手动	发 manual-export-guide.md；用户下完后 ingest_raw --from-dir 或 --t1/--t2/--t3
B 浏览器	web-access + browser-export-sop.md；下完后同样 ingest_raw

处理前必读 → references/table-schema.md

---

Step 5：处理表1 → 生成 Word 报告

计算基准：

python "{scripts.process_table1}" --mode compute-thresholds --input "{raw_dir}/关键词调研_{DATE}.xlsx"

向用户展示基准，按 amazon-expert-guide.md 话术询问是否调整 S/A 门槛。

暂停点 ①：用户确认门槛（或明确「用自动值」）后，才执行下方 process。

第一轮（Excel + stats，跳过 Word）：

python "{scripts.process_table1}" --mode process --input "{raw_dir}/关键词调研_{DATE}.xlsx" --output-dir "{result_dir}" --asin {ASIN} --date {DATE} --stage {阶段} --product-type {标品|非标品} [--s-threshold N --a-threshold N --s-conc-max 0.30] --skip-word

Agent 写 AI 分析段（必须做）：

1. 读取 *_t1_stats_{DATE}.json
2. 以亚马逊顾问身份写 insights_t1.md（仅分析文字，格式见下方「insights 写作规范」）
3. 不要写图表节，图表由 Word 自动内嵌

第二轮（生成 Word，自动清理中间文件）：

python "{scripts.process_table1}" --mode process ... --insights-file "{result_dir}/insights_t1.md"

产出：{ASIN}_关键词分层分析_{DATE}.xlsx + {ASIN}_关键词调研分析报告_{DATE}.docx

---

Step 6 / 7 / 8：表2、表3、交叉分析

流程同表1：先 --skip-word → 写 insights_t2.md / insights_t3.md / insights_cross.md → 带 --insights-file 重建 Word。

# 表2
python "{scripts.process_table2}" --input "..." --output-dir "{result_dir}" --asin {ASIN} --date {DATE} --skip-word
# → 写 insights_t2.md → 去掉 --skip-word 加 --insights-file

# 表3
python "{scripts.process_table3}" --input "..." --output-dir "{result_dir}" --asin {ASIN} --date {DATE} --product-category "{精确类目}" --product-type {标品|非标品} [--sv-threshold 1000] --skip-word

# 交叉（输入必须是**处理后的**三表 Excel，不是原始数据目录）
python "{scripts.cross_analysis}" \
  --t1 "{result_dir}/{ASIN}_关键词分层分析_{DATE}.xlsx" \
  --t2 "{result_dir}/{ASIN}_竞品弱点分析_{DATE}.xlsx" \
  --t3 "{result_dir}/{ASIN}_竞品缺口分析_{DATE}.xlsx" \
  --output-dir "{result_dir}" --asin {ASIN} --date {DATE} --skip-word

参数	何时调	说明
--product-type	每次 ASIN	默认非标品；标品/非标品预设见 threshold-presets.md
--sv-threshold	小类目缺口词过少	0=用预设（非标2000/标品3000），可降至 500–1000
--product-category	每次必问	影响词类型判定

交叉 --skip-word 完成后做 sanity check（缺口词为 0、SSS 为 0 等）→ 见 amazon-expert-guide。

暂停点 ②：向用户汇报交叉结果与建议主攻 SS 清单；确认后写 insights_cross.md 并生成 PD Word。若需重跑表3，在此停止并调整参数。

表2、表3 的 insights_t2/t3 可在暂停点 ② 之前并行撰写；PD 报告与 cross Word 必须在暂停点 ② 之后。

insights 写作规范（供 Word 渲染）

写法	说明
## 标题	分节标题，会渲染为 Word 二级标题
- 列表项	无序列表
**加粗**	加粗文字
| 列 | 列 |	可选，会转为 Word 表格
	禁止 — 图表由脚本插入 Word
***文字***	禁止 — 会显示为乱码星号
# 总标题	禁止 — Word 已有封面标题

TOP5 / 逐词点评（必须）：每条 = 数据括号 + 策略句（竞争判断、阶段是否投、匹配方式、与 listing 关系）。禁止「词名：词名，搜索量…」式复读。

反例：- **sofa cover**：sofa cover，搜索量 58321，竞价 $1.04
正例：- **sofa cover**（S级，搜索量 58321，竞价 $1.04，集中度 0.22）：核心品类词，集中度低于类目中位；新品期精准小预算试投，与三座规格 listing 匹配再加码。

最终产出（处理结果目录仅保留）

• {ASIN}_关键词分层分析_{DATE}.xlsx + _关键词调研分析报告_{DATE}.docx
• {ASIN}_竞品弱点分析_{DATE}.xlsx + _竞品弱点分析报告_{DATE}.docx
• {ASIN}_竞品缺口分析_{DATE}.xlsx + _竞品广告缺口分析报告_{DATE}.docx
• {ASIN}_PD主攻词单_{DATE}.xlsx + _PD主攻词单报告_{DATE}.docx

---

Step 9：更新历史（每次跑完必做，追加一行）

python "{scripts.update_history}" --asin {ASIN} --output-dir "{output_dir}" --date {DATE} --run-path "{run_path}"

ASIN历史记录.xlsx → Sheet 「运行日志」：每次运行追加一行，不覆盖、不合并日期。

列	说明
运行时间	YYYY-MM-DD HH:MM
数据日期	YYYYMMDD（文件夹日期）
快照路径	{ASIN}/{DATE}/{HHmm}，同日多次跑库可区分

旧版汇总表可用 --migrate-only 一次性迁移：

python "{scripts.update_history}" --migrate-only --output-dir "{output_dir}"

---

Step 10：条件触发 Skill 2（1~7 天窗口对比）

当 check_history 显示该 ASIN 已有 ≥2 次运行 → 执行 Skill 2。

python "{scripts.check_history}" --asin {ASIN} --output-dir "{output_dir}" --curr-date {DATE}

自动选对比基准：优先 1~7 天窗口内最近一次；同日多次则对比同日前一次。

Skill 2 两轮流程（与 Skill 1 相同）：

# 1) 对比 + stats
python "{scripts.compare_versions}" --auto --output-root "{output_dir}" --output-dir "{result_dir}" --asin {ASIN} --curr-date {DATE} --skip-word

# → 暂停点 ③：解读变化，与用户确认投放策略

# 2) Agent 写 insights_tracker.md → 重建 Word
python "{scripts.compare_versions}" --auto ... --insights-file "{result_dir}/insights_tracker.md"

产出：{ASIN}_词库更新报告_{DATE}.docx（含数据表 + AI 策略段）

---

Step 11：汇报

汇报产出路径、SS/SSS 主攻词摘要、是否建议调整参数；首次运行说明下次同 ASIN 会自动对比。

---

错误处理

错误	处理
Python 报错	对照 table-schema.md 检查表结构，再问用户是否重导出
Sif 未登录	方式 B：请用户浏览器登录后继续；或改方式 A
找不到下载文件	确认 download_dir 或改方式 A
类目/阶段明显不对	顾问模式：暂停并引导修正参数

脚本清单（scripts/）

脚本	用途
resolve_workspace.py	解析配置与全部脚本绝对路径
ingest_raw.py	建目录 + 接入用户文件（任意路径/文件夹）
check_history.py / update_history.py	历史 ASIN 查询与更新
process_table1/2/3.py	三表处理
cross_analysis.py	三表交叉 → PD 主攻词单
run_context.py / report_utils.py	内部模块，不直接调用
batch_regenerate_word.py	开发/批跑：重建 Word；加 --full-pipeline 可一键跑完 Skill1+2
create_mock_sif_exports.py	仅开发测试用 mock 数据

参考文档索引

文件	用途
first-time-setup.md	首次使用：output_dir / download_dir 引导（Agent 必读）
path-setup.md	工作区、配置、路径解析
manual-export-guide.md	方式 A 用户操作指引
browser-export-sop.md	方式 B URL/按钮 SOP
table-schema.md	三张表结构（防出错）
amazon-expert-guide.md	顾问角色与参数引导
sop-tables.md	分级/交叉规则细节