亚马逊市场调研收集表

给运营部门用的指定品类亚马逊竞品调研工具：输入一个亚马逊畅销榜 URL，自动采集该品类全部商品的多项数据，并按固定调研模板生成 Excel（含 WPS 单元格内嵌图）与 HTML 报告，最后回填卖家精灵的销量与趋势数据。

快速开始

# 1. 安装依赖
pip install -r requirements.txt

# 2. 准备配置（填入 DeepSeek API Key）
cp config.yaml.example config.yaml
#   编辑 config.yaml -> deepseek.api_key: "sk-xxxx"

# 3. 阶段一：采集亚马逊侧字段 + 西柚关键词，生成调研表
python src/main.py "https://www.amazon.com/gp/bestsellers/kitchen/289756/ref=pd_zg_hrsr_kitchen"
#   可选：--top-n 3 只采集前 3 个（联调用）

# 4. 阶段二：回填卖家精灵「销量趋势」「核心关键词趋势」
python scripts/fill_sellersprite.py
#   单测一个 ASIN：SS_ONE=1 python scripts/fill_sellersprite.py

两个阶段分别在做什么

阶段一 src/main.py：抓畅销榜全部商品 → 逐商品采集首图/售价/功能简介(DeepSeek)/BSR/ASIN/评价/品牌店铺(DeepSeek)/西柚关键词截图 → 生成 output/<品类>_调研_<时间戳>.xlsx 和 .html。
阶段二 scripts/fill_sellersprite.py：自动读取阶段一成品表第 6 行的 ASIN，逐个到卖家精灵查询，提取指定年 1-12 月月销量（写入行 10，每月一行）并截取核心关键词趋势图（内嵌行 20-29），写回原表。

字段一览（模板行号）

| 行 | 字段 | 来源 | |---|---|---| | 2-5 | 首图 | 商品主图 | | 6 | ASIN | 商品页（阶段二据此读 ASIN） | | 7 | 评价数量/星级 | 评论区 | | 8 | 售价 | 优惠后价格 | | 9 | 类目/排名 BSR | Product Information | | 10 | 销量 | 卖家精灵·销量趋势（阶段二） | | 11-13 | 功能简介 | About this item → DeepSeek | | 14-17 | 好评差评 | 不抓取（业务要求） | | 18 | 品牌/店铺 | 自营留空；否则店铺遍历 → DeepSeek | | 19 | 关键词前10 | 西柚截图 | | 20-29 | 核心关键词趋势 | 卖家精灵截图（阶段二） |

登录说明（重要）

卖家精灵、西柚的登录是 SPA 门控，无法用脚本自动填账号密码。正确做法：复用你本机已登录的 Chrome 会话。

脚本用 CDP 连接系统 Chrome（user_data_dir: chrome_data，调试端口 9222），登录态由 Chrome 用户目录持久化。
首次运行前请关闭正在使用的 Chrome（否则报 user data directory is already in use）。
可选：先 python scripts/open_sellersprite.py 打开卖家精灵页，手动登录一次，之后自动复用。

配置项（config.yaml）

deepseek.api_key：必填（功能简介/店铺总结用）。
xydc.api_key：选填，西柚 OpenAPI Key；留空则只用网站截图方式。
output.out_dir：调研表输出目录，默认 output。
output.year：销量取哪一年（默认 2025）。
output.top_n：0 = 全部；也可用 --top-n N 或环境变量 AMA_TOP_N=N 临时覆盖。
browser.cdp_port / user_data_dir：持久 Chrome 连接参数。

注意事项

config.yaml 含密钥，已加入 .gitignore，上传技能时只带 config.yaml.example。
ce_img_ll（WPS 单元格内嵌图）已内嵌在 src/ce_img_ll/，无需额外安装。
若目标 xlsx 正被 WPS 打开，阶段二会提示关闭后重试，不会另存新文件。
各站点选择器基于当前页面结构，若改版可能需微调（见 SKILL.md 的"已知需真机微调项"）。