Ecommerce Logistics

SKILL.md

---
name: ecommerce-logistics
description: "Aggregate logistics information from Taobao, JD, PDD, and Douyin. One-click query for multi-platform order tracking. Supports persistent cookie storage and QR code login. Use when user asks to check orders, track packages from shopping platforms, or mentions 淘宝/京东/拼多多/抖音 物流/订单."
---

# E-commerce Logistics Aggregator（电商物流聚合）

Query order logistics from Taobao, JD.com, Pinduoduo, and Douyin with persistent authentication.

## Features

- 🔗 **Multi-platform**: Taobao, PDD (JD & Douyin not supported due to anti-bot)
- 🔒 **Persistent login**: Cookie storage, no repeated logins
- 🛡️ **Stealth mode**: Bypass basic anti-bot detection
- ⏱️ **Rate limiting**: Built-in request throttling
- 📱 **QR login**: Graceful handling of expired sessions
- 🚚 **In-transit filter**: Only show orders currently in transit

## Setup

```bash
# Install dependencies
cd scripts && npm install

# Required environment variables (optional, for headless operation)
export ECOM_LOGISTICS_DATA_DIR="$HOME/.ecommerce-logistics"
```

## Usage

### First Time: Login to Platforms

```bash
cd scripts

# Login to Taobao (opens browser for QR scan)
npm run query -- --platform taobao --login

# Login to PDD
npm run query -- --platform pdd --login

# Note: JD and Douyin are not supported due to strict anti-bot measures
```

### Query Logistics

```bash
# Query all platforms (requires prior login)
npm run query -- --all

# Query specific platform
npm run query -- --platform taobao
npm run query -- --platform pdd

# Query with custom data directory
npm run query -- --all --data-dir /path/to/cookies

# Run in headless mode (no browser window)
npm run query -- --all --headless
```

### QR Login Process

When cookies are missing or expired:

1. The skill opens a browser window with the platform login page
2. A QR code screenshot is saved to `~/.ecommerce-logistics/{platform}-qr.png`
3. **Scan the QR code with the platform's mobile app**
4. Complete login in the browser window
5. Cookies are automatically saved for future use

**Note:** If you see "Cookie 已过期，需要重新登录", run the login command again.

## Cookie Storage

Cookies are stored encrypted in:
- Default: `~/.ecommerce-logistics/cookies/`
- Each platform has separate cookie file
- Auto-refresh on expiration

## Architecture

```
scripts/src/
├── index.ts              # CLI entry
├── core/
│   ├── aggregator.ts     # Main orchestrator
│   ├── auth-manager.ts   # Cookie & QR login
│   ├── rate-limiter.ts   # Request throttling
│   └── stealth-browser.ts # Anti-detection browser
├── adapters/
│   ├── base-adapter.ts   # Abstract base class
│   ├── taobao-adapter.ts
│   ├── jd-adapter.ts
│   ├── pdd-adapter.ts
│   └── douyin-adapter.ts
└── types/
    └── index.ts          # TypeScript interfaces

references/
└── selectors.md          # Platform-specific CSS selectors
```

## Error Handling

| Error | Handling |
|-------|----------|
| Cookie expired | Prompt QR re-login |
| Rate limited | Auto-backoff retry |
| Login page detected | Graceful error with instructions |
| Network timeout | 3 retries with exponential backoff |

## Platform Support Status

| Platform | Status | Notes |
|----------|--------|-------|
| Taobao | ✅ Available | Order list + logistics info |
| JD | ❌ Unsupported | Anti-bot detection too strict |
| PDD | ✅ Available | Order list + tracking number + pickup code |
| Douyin | ❌ Unsupported | Requires mobile app access |

## Implementation Notes

### Anti-Detection Measures

The skill implements several stealth techniques:

1. **navigator.webdriver override** - Hides automation flag
2. **Plugins spoofing** - Simulates real browser plugins
3. **Viewport & User-Agent** - Uses realistic desktop/mobile profiles
4. **Permissions API** - Overrides notification permissions
5. **Playwright-specific cleanup** - Removes `__playwright` properties

### Rate Limiting

Each platform has independent rate limits:

| Platform | Max Requests | Window |
|----------|-------------|--------|
| Taobao | 10 | 60s |
| JD | 15 | 60s |
| PDD | 8 | 60s |
| Douyin | 10 | 60s |

### Cookie Expiration

- Cookies are considered expired after **30 days**
- Expired cookies trigger QR re-login prompt
- Each platform stores cookies independently

## Development

### Updating Selectors

Platform websites change frequently. Update selectors in:
- `references/selectors.md` - Documentation
- `src/adapters/*-adapter.ts` - Implementation

### Testing

```bash
# Compile TypeScript
cd scripts && npm run build

# Run in development mode
npm run dev -- --platform taobao

# Debug with visible browser
npm run query -- --platform taobao --headless=false
```