logistics-tracker

物流跟踪 Skill — 对接 17Track 批量 API，自动跟踪运单状态，向客户发送邮件通知，并在异常时告警。

概述

功能特性

• 17Track 批量查询 — 单次最多 40 运单，自动分批
• 智能刷新调度 — 新单每 6h，在途每 24h，临近到达加密查询
• 配额管理 — 免费版 100 次/天，四级监控 + 降级策略
• 完整状态机 — 9 种状态（待发货→运输中→清关→派送→签收 + 退回/丢失/拒收）
• 客户邮件通知 — 发货 + 签收默认推送，中间节点 opt-in，eventId 幂等
• 异常检测告警 — 超时无更新、清关滞留、退回、丢失 → Discord + 邮件双渠道
• 运单号自动提取 — 从邮件正文提取 DHL/FedEx/UPS/SF/EMS 等格式运单号
• 原子写入 — write→rename 防并发，事件 eventId 去重
• Exponential Backoff — 失败重试 3 次（1/5/15 分钟）

目录结构

logistics-tracker/
├── config/
│   └── logistics-config.json     # 全局配置
├── data/
│   ├── shipments.json            # 运单状态持久化
│   ├── shipments/                # 备份目录
│   └── alert-history.json        # 告警历史去重
├── scripts/
│   ├── tracking-api.js           # 17Track API 适配器
│   ├── shipment-store.js         # 运单状态管理
│   ├── customer-notify.js        # 客户邮件通知
│   ├── scheduler.js              # 主调度器（cron 入口）
│   ├── anomaly-detector.js       # 异常检测告警
│   └── tracking-extractor.js     # 运单号提取器
├── templates/                    # 邮件模板目录（预留）
├── package.json
└── SKILL.md                      # 本文件

配置说明

必填配置项

编辑 config/logistics-config.json：

{
  "api": {
    "17track": {
      "apiKey": "YOUR_17TRACK_API_KEY_HERE",
      "batchSize": 40
    }
  }
}

申请 17Track API Key：https://api.17track.net/
免费版：100 次/天，单次最多 40 运单

SMTP 集成

运单通知通过 imap-smtp-email skill 的 SMTP 发送：

/Users/wilson/.openclaw/workspace/skills/imap-smtp-email/scripts/smtp.js

确保 imap-smtp-email skill 的 .env 已配置正确的 SMTP 凭证。

order-tracker 集成

异常检测器从 order-tracker 读取已发货订单自动创建跟踪记录：

/Users/wilson/.openclaw/workspace/skills/order-tracker/data/orders.json

使用方法

主调度器（推荐入口）

cd /Users/wilson/.openclaw/workspace/skills/logistics-tracker

# 执行一次完整调度周期（查询 + 状态更新 + 通知 + 异常检测）
node scripts/scheduler.js

# Dry-run 模式（不实际发送通知）
node scripts/scheduler.js --dry-run

# 查看调度状态
node -e "const s = require('./scripts/scheduler'); s.getSchedulerStatus().then(console.log)"

异常检测

# 完整检测（同步订单 + 检测 + 告警）
node scripts/anomaly-detector.js

# 跳过 order-tracker 同步
node scripts/anomaly-detector.js --skip-sync

# 只检测，不发告警
node scripts/anomaly-detector.js --skip-alerts

# Dry-run
node scripts/anomaly-detector.js --dry-run

运单号提取器

# 从文本提取运单号
node scripts/tracking-extractor.js --text "Your UPS shipment 1Z999AA10123456784 has shipped"

# 从文件提取
node scripts/tracking-extractor.js --file /path/to/email.txt

# 设置最低置信度阈值
node scripts/tracking-extractor.js --text "..." --min-confidence=0.7

手动注册运单