---
name: jd-price-compare
description: 京东商品多SKU价格/促销比价系统。配置 sku_config.xlsx 填入我的SKU、控价、竞品SKU，自动抓取京东价、到手价、促销拆解（已生效/未生效）、满减档位、赠品、跨店满减、返京豆、凑单均价等完整优惠信息，输出瑞士风格可视化HTML对比报告和结构化JSON。
version: 3.0.0
license: MIT
metadata:
  author: hxhw
  last_reviewed: 2026-08-04
  python_dependencies:
    - playwright
    - openpyxl
---

# 京东多SKU比价系统

读取 `sku_config.xlsx`（优先）或 `sku_config.csv` 中的SKU配置，通过Playwright+登录Cookie调用京东 `pc_detailpage_wareBusiness` API 批量抓取，输出瑞士国际主义风格可视化HTML对比报告。

## 触发词（何时调用）

当用户提到以下任一意图时触发：
- "比价"、"价格对比"、"竞品价格"、"SKU对比"
- "京东促销分析"、"满减拆解"、"凑单计算"
- "破价检查"、"控价监控"、"价格监控"
- "生成比价报告"、"做一份价格分析"

## 前置准备

**首次使用前，确认依赖已安装：**
```bash
pip install playwright openpyxl
playwright install chromium
```

> 检查点：如果运行时报 `ModuleNotFoundError`，先执行上方命令安装依赖。

**文件结构要求（工作目录）：**
```
工作目录/
├── sku_config.xlsx    # SKU配置表
├── cookie.txt         # 京东登录Cookie
└── output/            # 自动创建，存放报告
```

脚本位置：`{skill_dir}/scripts/jd_compare.py`
模板位置：`{skill_dir}/assets/sku_config_template.csv`

## 使用流程

### 1. 配置文件

**sku_config.xlsx**（推荐）:
| 列 | 内容 | 必填 |
|---|---|---|
| A | 分类 | 是 |
| B | 我的SKU | 是 |
| C | 我的控价 | 否（填写则启用破价预警） |
| D | 竞品SKU | 是 |
| E | 竞品名称 | 是 |

**cookie.txt** - 京东登录Cookie（F12→Network→api.m.jd.com→任意请求→Cookie完整复制）

> Cookie 只保存在你自己的工作目录中。公开下载包不包含 Cookie，也不要把 `cookie.txt` 上传到公共仓库或转发给他人。

### 2. 运行

```bash
python scripts/jd_compare.py            # 完整模式（默认）
python scripts/jd_compare.py --compact  # 精简模式（节省token，推荐）
```

### 3. 产出（output/目录）

| 文件 | 说明 |
|------|------|
| `compare.html` | 瑞士风格可视化HTML对比报告 |
| `result.json` | 完整结构化数据（完整模式） |
| `result_compact.json` | 精简结构化数据（精简模式） |

### 4. 展示结果

使用 `preview_url` 打开 `output/compare.html`

## 数据项

- **价格**: 京东价、到手价、价格拆解（基础价→促销减→到手）
- **促销拆分**: 已生效优惠（单件可达）/ 未生效优惠（需凑单）
- **凑单均价**: 根据全部优惠信息计算极限凑单的每件均价
- **破价预警**: 到手价低于控价时红色加粗提醒
- **赠品**: 名称、数量
- **店铺**: 店铺名
- **返京豆**: 订单完成后返豆数量

## HTML报告特性（v2.0 瑞士国际主义风格）

### UI设计风格
- **颜色方案**: 纸白背景(#fafaf8) + 纯黑文字(#0a0a0a) + 安全橙强调色(#FF6B35)
- **高对比度**: 无阴影设计，用颜色对比和极细分割线创造层次
- **字体**: Inter（标题）+ JetBrains Mono（代码/SKU）
- **统计数字**: 56px超大字重，font-feature-settings数字等宽

### 摘要仪表盘（点击筛选）
- 4个KPI卡片：总计对比 / 有价格优势 / 需关注 / 价格持平
- **点击任意卡片可筛选**，只展示对应分类的SKU
- 选中状态：黑底白字高亮

### 差异优先展示
- 需关注SKU排最前面，红色左边框标识
- 有优势SKU绿色左边框标识
- 持平SKU灰色左边框标识

### 详情展开（点击SKU卡片）
字段顺序（运营逻辑）：
1. SKU
2. 店铺
3. 京东价
4. ✅ 已生效优惠（单件可达）
5. ⏳ 未生效优惠（需凑多件）
6. **到手价**（红色加粗 + 计算公式）
7. **凑单均价**（红色加粗 + 极限凑单公式）
8. 赠品

### 凑单均价计算逻辑
- 每满减：可叠加计算（如每满150减69，买2件减138）
- 普通满减：不叠加
- 首购礼金/优惠券：参与凑单计算（作为固定减免项）
- 优惠券识别：通过API `t`字段为空区分（非满减档位）

## 精简模式（推荐）

**使用场景**: 几十个SKU比价时，节省token消耗

**精简模式特性**:
1. **摘要卡片**: 总对比、有优势、需关注、持平（可点击筛选）
2. **差异优先**: 需关注SKU排前面，红色高亮
3. **精简JSON**: 只保留关键字段
4. **促销拆分**: 已生效/未生效 + 凑单均价

**token节省效果**:
- 2个SKU：节省约50%
- 50个SKU：预计节省约80%

## Cookie更新

Cookie有效期有限（几小时到几天），过期后需重新获取：
1. F12打开开发者工具
2. Network → 过滤 `api.m.jd.com`
3. 任意请求 → Request Headers → Cookie
4. 完整复制到 `cookie.txt`

## 常见问题与边界处理

| 问题 | 现象 | 处理 |
|---|---|---|
| `ModuleNotFoundError` | 缺少playwright/openpyxl | 执行前置准备中的pip安装命令 |
| `cookie.txt 不存在` | 脚本退出并报错 | 确认cookie.txt放在工作目录，或按Cookie更新章节获取 |
| 抓取成功0个SKU | 全部数据缺失 | Cookie可能已过期，重新获取；或IP被风控，更换网络环境 |
| 到手价显示`None` | 商品无促销信息 | 正常现象，该SKU当前无满减/优惠券活动 |
| 促销信息不全 | 部分优惠未显示 | 不同Cookie账号权限不同（如Plus会员专属价），用目标账号Cookie抓取 |
| SKU配置格式错误 | 脚本报错或跳过行 | 确认xlsx列顺序：分类/我的SKU/我的控价/竞品SKU/竞品名称 |
| 报告样式异常 | CSS未生效或布局错乱 | 用Chrome/Edge打开HTML，避免IE；或检查是否使用了 `--compact` |

## 检查点（关键决策前确认）

1. **运行前**：确认 `sku_config.xlsx` 和 `cookie.txt` 已放在工作目录
2. **Cookie更新后**：确认cookie.txt内容完整（含thor/token等关键字段）
3. **报告生成后**：用 `preview_url` 预览确认数据无误再汇报

## 注意事项

- 每个SKU抓取约需3秒（domcontentloaded模式）
- 139个SKU约4分钟完成
- 京东反爬严格，环境IP可能被风控
- 几十个SKU时使用 `--compact` 模式节省token
- 控价字段为空则不启用破价预警

## 跨电脑使用

### 安装方法
1. 将 `jd-price-compare-v3.0.0.zip` 上传到目标电脑
2. 解压到 `~/.workbuddy/skills/jd-price-compare/`
3. WorkBuddy会自动识别skill

### 首次使用步骤
1. 安装依赖：`pip install playwright openpyxl && playwright install chromium`
2. 在工作目录创建 `sku_config.xlsx`（参考 `assets/sku_config_template.csv` 格式）
3. 获取京东Cookie并保存到 `cookie.txt`
4. 运行：`python ~/.workbuddy/skills/jd-price-compare/scripts/jd_compare.py --compact`

### 注意
- zip包不含任何比价数据，用户需自行配置
- Cookie需在目标电脑重新获取（与浏览器登录状态绑定）