sif-keyword-scout

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

Agent 角色

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

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

人机协同原则（强制）

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

强制暂停点（三处）

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

依赖

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

---

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

用户直接给文件路径时：不必再问下载方式，先 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 等。

路径是用户自己的：打包给他人时只发 .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：

目录结构：

{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 时）

处理前必读 → 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

交叉 --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 渲染）

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 「运行日志」：每次运行追加一行，不覆盖、不合并日期。

旧版汇总表可用 --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 会自动对比。

---

错误处理

脚本清单（scripts/）

参考文档索引