logistics-tracker

---

name: logistics-tracker

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

---

# logistics-tracker

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

---

概述

| 属性 | 值 |

|------|-----|

| 版本 | 1.0.0 |

| 状态 | 生产就绪 |

| 依赖 | `order-tracker`, `imap-smtp-email` |

| API | [17Track REST v2.2](https://api.17track.net/) |

| Node.js | ≥ 18 |

功能特性

---

目录结构

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

手动注册运单

node -e "
const store = require('./scripts/shipment-store');
store.upsertShipment({
  trackingNumber: '1Z999AA10123456784',
  carrier: 'ups',
  status: 'in_transit',
  orderId: 'ORD-001',
  customerEmail: 'customer@example.com'
}).then(() => console.log('Done'));
"

手动触发客户通知

node -e "
const notify = require('./scripts/customer-notify');
notify.sendShippedNotification({
  trackingNumber: '1Z999AA10123456784',
  carrier: 'ups',
  orderId: 'ORD-001',
  customerEmail: 'customer@example.com',
  customerName: 'John'
}).then(console.log);
"

---

Cron 调度建议

在 crontab 中添加以下任务：

# 每 6 小时执行一次完整调度周期
0 */6 * * * cd /Users/wilson/.openclaw/workspace/skills/logistics-tracker && node scripts/scheduler.js >> /tmp/logistics-tracker.log 2>&1

# 每天早上 9 点执行异常检测（可独立运行，也会在 scheduler 中执行）
0 9 * * * cd /Users/wilson/.openclaw/workspace/skills/logistics-tracker && node scripts/anomaly-detector.js >> /tmp/logistics-anomaly.log 2>&1

> **注意：** 17Track 免费版每天 100 次配额。每 6h 跑一次（4次/天），每次最多 25 运单可安全使用。活跃运单超过 25 时，调度器会自动按优先级分配配额。

---

API 参考

tracking-api.js

| 函数 | 说明 |

|------|------|

| `registerTracking(trackingNumbers)` | 批量注册运单到 17Track |

| `getTrackingInfo(trackingNumbers)` | 批量查询运单状态 |

| `shouldRefresh(shipment)` | 判断运单是否需要刷新 |

| `filterForRefresh(shipments)` | 过滤需要刷新的运单列表 |

| `buildRefreshQueue(shipments)` | 构建优先级刷新队列 |

| `getQuotaStatus()` | 获取当日配额状态 |

| `incrementQuotaUsage(n)` | 增加配额计数 |

| `isQuotaExhausted()` | 检查配额是否耗尽 |

shipment-store.js

| 函数 | 说明 |

|------|------|

| `getShipment(trackingNumber)` | 获取单个运单 |

| `upsertShipment(data)` | 创建或更新运单 |

| `addEvents(trackingNumber, events)` | 添加物流事件（自动去重） |

| `transitionStatus(trackingNumber, newStatus)` | 状态机流转 |

| `getAllShipments()` | 获取所有运单 |

| `getShipmentsByStatus(status)` | 按状态筛选 |

| `getStaleShipments(days)` | 获取超过 N 天无更新的运单 |

customer-notify.js

| 函数 | 说明 |

|------|------|

| `sendNotification(shipment, event)` | 通用通知入口 |

| `sendShippedNotification(shipment)` | 发送发货通知 |

| `sendDeliveredNotification(shipment)` | 发送签收通知 |

| `sendEventNotification(shipment, event)` | 发送中间节点通知 |

| `processBatchNotifications(shipments)` | 批量通知处理 |

| `shouldNotify(shipment, eventType)` | 通知决策引擎 |

anomaly-detector.js

| 函数 | 说明 |

|------|------|

| `detectAnomalies(shipments, opts)` | 批量异常检测 |

| `detectNoUpdateAnomaly(shipment)` | 超时无更新检测 |

| `detectCustomsHoldAnomaly(shipment)` | 清关滞留检测 |

| `detectReturnAnomaly(shipment)` | 退回检测 |

| `detectLostAnomaly(shipment)` | 丢失检测 |

| `sendAnomalyAlerts(anomalies, opts)` | 双渠道告警发送 |

| `syncShippedOrders(opts)` | 从 order-tracker 同步已发货订单 |

| `runFullDetection(opts)` | 完整检测流程 |

tracking-extractor.js

| 函数 | 说明 |

|------|------|

| `extractTrackingNumbers(text, opts)` | 从文本提取所有运单号 |

| `extractFromEmail(emailObj, opts)` | 从邮件对象提取运单号 |

| `extractFromFile(filePath, opts)` | 从文件提取运单号 |

| `identifyCarrier(trackingNumber)` | 识别快递商 |

| `validateTrackingNumber(num, carrier)` | 验证运单号格式 |

| `linkToOrder(trackingNumber, ordersPath, opts)` | 关联到订单 |

| `processEmailBatch(emails, opts)` | 批量处理邮件 |

---

状态机

pending → in_transit → customs_clearance → out_for_delivery → delivered
                    ↘ returning → returned
                    ↘ lost
                    ↘ customer_rejected

---

依赖 Skills

| Skill | 路径 | 用途 |

|-------|------|------|

| `order-tracker` | `../order-tracker/` | 读取已发货订单，自动创建跟踪记录 |

| `imap-smtp-email` | `../imap-smtp-email/` | 通过 SMTP 发送客户邮件和告警通知 |

---

开发历史