# ebay

**Repository Path**: anbeime/ebay

## Basic Information

- **Project Name**: ebay
- **Description**: 一个轻量级的趋势聚合器（支持 Google Trends + 模拟数据源）
爆品打分与排序引擎
与现有 pipeline 打通：auto-pipeline 命令每天自动挖掘 → 上架 → 生成视频
结果输出为候选清单，你可以选择"全自动执行"或"人工确认后再执行"
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 跨境电商选品上架推广工具

一套可直接运行的 Python 自动化工具，覆盖从自动选品、全球供应商搜索、数据清洗、多平台上架到推广关键词生成的完整链路。

---

## 功能特性

| 模块 | 功能 |
|------|------|
| **选品 (Trend)** | 自动爆品挖掘、多源趋势聚合、需求热度分析、季节趋势预测 |
| **全球供应商 (Supplier)** | 阿里巴巴国际站、中国制造网、环球资源、IndiaMART 多平台供应商搜索与比较 |
| **采集 (Scraper)** | 1688 关键词搜索、商品详情页解析、图片批量下载 |
| **清洗 (Cleaner)** | NLP 噪音词过滤、属性中英映射、动态定价计算、供应商评分、合规检测 |
| **上架 (Publisher)** | CSV/Excel/JSON 导出、微信小店/Shopify/TikTok 上架模板生成 |
| **推广 (Promoter)** | 关键词智能挖掘、竞品分析、广告文案生成、预算分配建议 |
| **视频 (Video)** | 商品图片自动合成短视频（9:16竖屏、钩子文案、价格叠加、Ken Burns效果、BGM） |
| **代发 (Fulfill)** | 1688 一键无痕代发（Playwright浏览器自动化、自动填地址、备注无痕发货、物流回填） |

---

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 修改配置（可选）

编辑 `config.yaml`，按需调整：
- `pricing`：汇率、运费、利润率
- `platforms`：填入各平台 API 密钥即可启用自动上架
- `cleaning`：噪音词库、属性映射字典

### 3. 运行

**全自动选品+全球供应商搜索（推荐）**

```bash
python main.py auto-select --categories "electronics,home" --top-n 5 --product-limit 3
```

执行顺序：爆品挖掘 -> 全球多平台供应商搜索 -> 供应商比较推荐 -> 生成上架模板

**全球供应商搜索**

```bash
python main.py source --keyword "wireless charger" --pages 1 --detail --top-n 10
```

执行顺序：多平台搜索（阿里巴巴国际站/中国制造网/环球资源/IndiaMART）-> 详情获取 -> 比较推荐

**全流程自动化（1688）**

```bash
python main.py pipeline --keyword "收纳盒" --pages 2 --min-margin 0.20
```

执行顺序：采集 -> 清洗 -> 上架模板 -> 推广方案 -> 推广视频（5步全链路）

**分步运行**

```bash
# 自动选品（爆品挖掘）
python main.py trend --categories "electronics,home" --top-n 10

# 全球供应商搜索
python main.py source --keyword "wireless charger" --pages 1 --top-n 10

# 1688采集
python main.py scrape --keyword "收纳盒" --pages 2 --detail

# 清洗
python main.py clean --input data/raw_products.json --min-margin 0.20

# 上架
python main.py publish --input data/cleaned_products.json --platform all

# 推广
python main.py promote --input data/cleaned_products.json --keyword-count 20
```

---

## 命令说明

### `scrape` — 采集

```bash
python main.py scrape --keyword "收纳盒" --pages 2 --detail --download-images
```

参数：
- `--keyword`：1688 搜索关键词（必填）
- `--pages`：采集页数（默认 1）
- `--detail`：同时采集商品详情页
- `--detail-limit`：详情采集数量上限（默认 10）
- `--download-images`：下载商品图片到 `data/images/`

### `clean` — 清洗

```bash
python main.py clean --input data/raw_products.json --min-margin 0.15 --min-score 60
```

参数：
- `--input`：原始数据 JSON 文件路径（必填）
- `--min-margin`：最低毛利率过滤（默认 0.15）
- `--min-score`：最低供应商评分过滤（默认 60）

### `publish` — 上架

```bash
python main.py publish --input data/cleaned_products.json --platform all --export all
```

参数：
- `--input`：清洗后数据 JSON 文件路径（必填）
- `--platform`：目标平台（all/wechat_shop/shopify/tiktok，默认 all）
- `--export`：导出格式（csv/excel/json/all/none，默认 all）

### `promote` — 推广

```bash
python main.py promote --input data/cleaned_products.json --limit 10 --daily-budget 50
```

参数：
- `--input`：清洗后数据 JSON 文件路径（必填）
- `--limit`：处理商品数量上限（默认 10）
- `--keyword-count`：每商品生成关键词数（默认 20）
- `--daily-budget`：每日广告预算 USD（默认 50）

### `video` — 生成推广短视频

```bash
python main.py video --input data/cleaned_products.json --limit 5 --duration 15
```

参数：
- `--input`：清洗后数据 JSON 文件路径（必填）
- `--limit`：生成视频数量上限（默认 5）
- `--duration`：单个视频时长秒数（默认 15）

输出：9:16 竖屏 MP4，含钩子开头 + 商品图片轮播（Ken Burns 缩放效果 + 价格/标题叠加）+ Shop Now CTA 结尾

### `fulfill` — 一键代发（无痕发货）

```bash
# 创建代发任务（生成任务清单，供 Playwright 执行或手动下单）
python main.py fulfill \
  --source-url "https://detail.1688.com/offer/123456789.html" \
  --receiver-name "张三" \
  --receiver-phone "13800138000" \
  --receiver-address "广东省深圳市南山区科技园"

# 使用 Playwright 浏览器自动下单（首次需手动登录 1688）
python main.py fulfill \
  --source-url "https://detail.1688.com/offer/123456789.html" \
  --receiver-name "张三" \
  --receiver-phone "13800138000" \
  --receiver-address "广东省深圳市南山区科技园" \
  --sku-spec "白色/大号" \
  --quantity 3 \
  --remark "礼品包装，无痕发货，请勿放价格单" \
  --use-playwright
```

参数：
- `--source-url`：1688 商品详情页 URL（必填）
- `--receiver-name`：收货人姓名（必填）
- `--receiver-phone`：收货人电话（必填）
- `--receiver-address`：收货地址（必填）
- `--sku-spec`：规格选择（如：白色/大号）
- `--quantity`：购买数量（默认 1）
- `--remark`：订单备注（默认"无痕发货，请勿放价格单"）
- `--use-playwright`：使用浏览器自动化下单（首次运行会弹出浏览器窗口，需手动登录一次，后续自动复用 cookie）

### `pipeline` — 全流程

一键执行：采集 -> 清洗 -> 上架 -> 推广

```bash
python main.py pipeline --keyword "收纳盒" --pages 2 --min-margin 0.20
```

### `source` — 全球供应商搜索

在多个国际供应商平台（阿里巴巴国际站、中国制造网、环球资源、IndiaMART）上搜索商品，并进行比较推荐。

```bash
python main.py source --keyword "wireless charger" --pages 1 --detail --top-n 10
```

参数：
- `--keyword`：搜索关键词（必填）
- `--pages`：每个平台搜索页数（默认 1）
- `--detail`：获取商品详情（默认不获取）
- `--top-n`：返回推荐供应商数量（默认 10）

输出：
- 供应商比较报告（排名、价格、MOQ、评分、综合得分、推荐理由）
- JSON 数据文件保存到 `data/supplier_report_xxx.json`

### `auto-select` — 全自动选品+全球供应商搜索

完整流水线：自动爆品挖掘 -> 全球多平台供应商搜索 -> 综合比较推荐 -> 生成上架模板

```bash
python main.py auto-select \
  --categories "electronics,home" \
  --top-n 5 \
  --product-limit 3 \
  --supplier-limit 5 \
  --top-suppliers 10 \
  --detail \
  --generate-templates
```

参数：
- `--categories`：限定品类，逗号分隔（如: electronics,home,beauty）
- `--seed-keywords`：种子关键词，逗号分隔
- `--top-n`：挖掘爆品数量（默认 5）
- `--product-limit`：执行供应商搜索的爆品数量（默认 3）
- `--supplier-limit`：每爆品返回供应商数量（默认 5）
- `--top-suppliers`：综合推荐供应商数量（默认 10）
- `--pages`：每个平台搜索页数（默认 1）
- `--detail`：获取商品详情
- `--generate-templates`：生成上架模板

---

## 项目结构

```
ecommerce-tool/
|-- main.py                    # CLI 入口
|-- config.yaml                # 配置文件
|-- requirements.txt           # 依赖列表
|-- test_run.py                # 测试脚本
|-- ecommerce_tool/
|   |-- __init__.py
|   |-- utils.py               # 工具函数（请求、日志、导出）
|   |-- scraper.py             # 1688 采集器
|   |-- supplier_sourcing.py   # 全球供应商采购（阿里巴巴国际站/中国制造网/环球资源/IndiaMART）
|   |-- supplier_comparator.py # 供应商比较引擎（价格/MOQ/评分/位置综合评分）
|   |-- trend_detector.py      # 爆品趋势探测器（自动选品）
|   |-- cleaner.py             # 数据清洗器
|   |-- publisher.py           # 上架发布器
|   |-- promoter.py            # 推广助手
|   |-- video_generator.py     # 视频生成器
|   |-- fulfillment.py         # 一键代发引擎
|-- data/                      # 输出目录（自动创建）
|   |-- raw_products.json      # 原始采集数据
|   |-- cleaned_products.json  # 清洗后数据
|   |-- supplier_report_xxx.json # 供应商比较报告
|   |-- global_suppliers_xxx.json # 全球供应商数据
|   |-- *.csv / *.xlsx         # 导出文件
|   |-- listing_templates.json # 上架模板
|   |-- promotion_plan.json    # 推广方案
|-- logs/                      # 日志目录（自动创建）
```

---

## 动态定价公式

系统默认采用**成本加成 + 利润率保障**双模式：

```
售价 = max(成本 × 倍率, 成本 / (1 - 目标利润率))
其中：成本 = (1688采购价 + 国内运费) / 汇率 + 国际运费 + 平台扣点
```

若计算出的毛利率低于 `min_profit_margin`（默认 15%），系统会自动上调售价以保障最低毛利。

---

## 注意事项

1. **1688 反爬**：工具已内置 UA 轮换、随机延迟、重试机制。如仍被封 IP，请在 `config.yaml` 中配置代理池。
2. **翻译 API**：当前英文标题使用规则替换 + SEO 优化。如需更精准的翻译，请在 `cleaner.py` 中接入 Google Translate / DeepL API。
3. **平台 API 上架**：当前上架模块生成标准模板文件。配置各平台 API 密钥后，可在 `publisher.py` 中扩展实际的 API 调用逻辑。
4. **合规风险**：工具内置广告法违禁词检测，但无法覆盖所有平台规则，上架前建议人工复核。

---

## 扩展开发

- **接入更多供应商平台**：在 `supplier_sourcing.py` 中继承 `SupplierSource` 基类，实现新平台的 `search()`、`fetch_detail()`、`download_images()` 方法
- **接入翻译 API**：替换 `cleaner.py` 中的 `_translate_title` 方法
- **接入 LLM**：在 `promoter.py` 中接入 OpenAI/Claude API 实现更智能的文案生成
- **数据库持久化**：将 `save_json` 替换为 SQLite/MySQL 写入
- **自定义供应商评分权重**：在 `config.yaml` 的 `supplier_sourcing.comparison_weights` 中调整各维度权重

---

## License

MIT