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 或处理脚本之前 ，完成以下对话并 等待用户确认 ： ASIN ：用户消息含 ASIN → 直接使用；否则先问 必问参数 （不可跳过）： 1. 产品阶段：新品期 / 成长期 / 成熟期？ 2. **产品类型**：标品 / 非标品？（决定默认门槛，见 `references/threshold-presets.md`） 3. 精确产品类目（影响表3 缺口词，如「不锈钢保温杯」而非笼统「水杯」）？ 跑前简报 （用自然语言概括，勿只贴命令）： 本次将产出 4 组 Excel + Word（表1/2/3 + PD 主攻词单） 若有历史 → 额外产出词库更新报告（Skill 2） 数据来源：方式 A / B / C（若用户已给文件路径则说明「直接接入」） 预计会在 暂停点 ①② 与你确认门槛与主攻词方向 确认门 ：用户明确回复后，才进入 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 分析段（必须做）： 读取 *_t1_stats_{DATE}.json 以亚马逊顾问身份写 insights_t1.md （仅分析文字，格式见下方「insights 写作规范」） 不要写图表节 ，图表由 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 表格