walmart-keyword 0.1.1

沃尔玛关键词排名监控工具 - 自动监控 Young Electric 产品搜索排名

沃尔玛关键词排名监控工具

每天定时从钉钉表格读取关键词，搜索沃尔玛并提取 Young Electric 产品的广告和自然排名，结果写回钉钉表格。

功能特性

• 定时任务自动执行（支持 Cron 表达式）
• 从钉钉表格读取关键词分组和 SKU 映射
• 自动搜索 Walmart 并提取排名
• 区分广告排名（Sponsored）和自然排名
• 智能防爬验证处理（Logo点击、验证码、按住验证等）
• 排名数据按关键词分组写回钉钉表格
• 钉钉机器人通知（启动/完成/异常）
• 失败关键词自动重试
• 多实例并发支持

快速开始

1. 安装

# 使用 uvx 一键运行（推荐）
uvx walmart-keyword

# 或使用 pip 安装
pip install walmart-keyword

# 或克隆项目手动安装
git clone <repo-url>
cd WalmartKeyword
pip install -e .

2. 配置

复制 .env-example 为 .env，填入配置：

cp .env-example .env

必填配置项：

配置项	说明	示例
CRON_EXPRESSION	定时任务表达式	0 8 * * *（每天8点）
DINGTALK_WEBHOOK	钉钉机器人 Webhook	https://oapi.dingtalk.com/robot/send?access_token=...
DINGTALK_SECRET	钉钉机器人密钥	SECxxxx
DINGTALK_DOC_URL	钉钉表格链接	https://alidocs.dingtalk.com/i/nodes/xxx
DINGTALK_APP_KEY	钉钉应用 AppKey	dingxxxx
DINGTALK_APP_SECRET	钉钉应用 AppSecret	xxxx
DINGTALK_OPERATOR_ID	操作人 UnionId	xxxx
KEYWORD_SHEET_NAME	关键词工作表名	关键词
SKU_MAPPING_SHEET_NAME	SKU映射工作表名	SKU映射表

可选配置项：

配置项	说明	默认值
WALMART_ZIP_CODE	Walmart 位置邮编	空
DINGTALK_AT_MOBILES	@指定人员手机号	空
CHROME_USER_DATA_PATH	Chrome 用户数据目录	空（自动管理）
RATE_LIMIT_PER_MINUTE	每分钟请求限制	15
RATE_LIMIT_PER_HOUR	每小时请求限制	500
PROXY_ENABLED	是否启用代理	false
PROXY_POOL	代理地址池	空

3. 运行

# 首次运行：设置 Walmart 配送位置
walmart-keyword --setup
# 或
wkm --setup

# 单次执行模式
walmart-keyword --once
wkm --once

# 定时任务模式（默认）
walmart-keyword
wkm

钉钉表格结构

关键词 Sheet

行	A列	B列	C列	...
1	Bike Rack	Power Jack	...	关键词组名
2	bicycles rack	power jack	...	关键词
3+	bike rack for hitch	...	...	关键词

排名结果 Sheet（以 Bike Rack 为例）

每个关键词占 4 列（BE 为第一个关键词，FI 为第二个，依次类推）：

• 第1列：广告排名位置（如 1&2）
• 第2列：广告 SKU（如 SKU1/SKU2）
• 第3列：自然排名位置
• 第4列：自然 SKU

SKU映射表 Sheet

将 data-dca-id 映射为可读的 SKU 编号。

多实例运行

# Windows CMD
set INSTANCE_ID=0 && walmart-keyword --once   # 端口 9333
set INSTANCE_ID=1 && walmart-keyword --once   # 端口 9334

# Windows PowerShell
$env:INSTANCE_ID=1; walmart-keyword --once

# Linux/macOS
INSTANCE_ID=1 walmart-keyword --once

目录结构

WalmartKeyword/
├── app/
│   ├── cli.py                       # 入口（定时任务/单次执行/位置设置）
│   ├── config.py                    # 配置管理
│   ├── notifier.py                  # 钉钉通知
│   ├── dingtalk_doc_reader.py       # 钉钉文档API
│   ├── models/
│   │   └── ranking_result.py        # 排名结果模型
│   ├── readers/
│   │   ├── keyword_reader.py        # 关键词读取器
│   │   └── sku_mapping_reader.py    # SKU映射读取器
│   ├── recorders/
│   │   └── ranking_recorder.py      # 排名记录器（写入钉钉表格）
│   ├── selectors/
│   │   ├── walmart_selectors.py     # 页面选择器
│   │   └── walmart_search_selectors.py  # 搜索页选择器
│   ├── spiders/
│   │   ├── base_spider.py           # 爬虫基类
│   │   ├── walmart_search_spider.py # 搜索排名爬虫
│   │   └── walmart_bot_handler.py   # 防爬处理器
│   └── utils/
│       ├── rate_limiter.py          # 频率限制
│       └── behavior_simulator.py    # 人类行为模拟
├── data/                            # 数据目录（日志、浏览器数据、备份）
├── run.py                           # 启动脚本
├── .env-example                     # 配置示例
└── pyproject.toml                   # 项目配置

技术栈

• Python >= 3.9
• DrissionPage - 浏览器自动化
• alibabacloud-dingtalk - 钉钉文档 API
• dingtalkchatbot - 钉钉通知
• croniter - 定时任务

License

MIT