Back to Details

track17

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

track17 (17TRACK parcel tracking)

track17（17TRACK包裹追踪）

This skill lets Clawdbot keep a local list of your parcels, track their state via the 17TRACK Tracking API v2.2, and summarise changes.
It stores everything in a small SQLite DB under your workspace (by default: 
<workspace>/packages/track17/track17.sqlite3
).
<workspace>
is auto-detected as the parent directory of the nearest 
skills/
directory that contains this skill. For example, if you install it at 
/clawd/skills/track17/
, data will be stored at 
/clawd/packages/track17/
.
该Skill可让Clawdbot保存你的包裹本地列表，通过17TRACK Tracking API v2.2追踪包裹状态，并汇总状态变化。
所有数据都存储在你的工作区下的小型SQLite DB中（默认路径：
<workspace>/packages/track17/track17.sqlite3
）。
<workspace>
会自动检测为包含该Skill的最近
skills/
目录的父目录。例如，若你将其安装在
/clawd/skills/track17/
，数据将存储在
/clawd/packages/track17/
。

Requirements

必要条件

  • TRACK17_TOKEN
    must be set (17TRACK API token; used as the 
    17token
    header).
  • Python (
    python3
    preferred).
Optional:
  • TRACK17_WEBHOOK_SECRET
    if you want to verify webhook signatures.
  • TRACK17_DATA_DIR
    to override where the DB/inbox live.
  • TRACK17_WORKSPACE_DIR
    to override what this tool considers the workspace directory.
  • 必须设置
    TRACK17_TOKEN
    （17TRACK API令牌；用作
    17token
    请求头）。
  • Python（推荐使用
    python3
    ）。
可选配置：
  • 若需验证Webhook签名，需设置
    TRACK17_WEBHOOK_SECRET
    。
  • 可通过
    TRACK17_DATA_DIR
    覆盖数据库/收件箱的存储路径。
  • 可通过
    TRACK17_WORKSPACE_DIR
    覆盖工具识别的工作区目录。

Quick start

快速开始

  1. Initialise storage (safe to run multiple times):
bash
python3 {baseDir}/scripts/track17.py init
  1. Add a package (registers it with 17TRACK and stores it locally):
bash
python3 {baseDir}/scripts/track17.py add "RR123456789CN" --label "AliExpress headphones"
If carrier auto-detection fails, specify a carrier code:
bash
python3 {baseDir}/scripts/track17.py add "RR123456789CN" --carrier 3011 --label "..."
  1. List tracked packages:
bash
python3 {baseDir}/scripts/track17.py list
  1. Poll for updates (recommended if you don't want webhooks):
bash
python3 {baseDir}/scripts/track17.py sync
  1. Show details for one package:
bash
python3 {baseDir}/scripts/track17.py status 1
  1. 初始化存储（可重复执行，安全无风险）：
bash
python3 {baseDir}/scripts/track17.py init
  1. 添加包裹（在17TRACK注册并本地存储）：
bash
python3 {baseDir}/scripts/track17.py add "RR123456789CN" --label "AliExpress headphones"
若承运商自动识别失败，指定承运商代码：
bash
python3 {baseDir}/scripts/track17.py add "RR123456789CN" --carrier 3011 --label "..."
  1. 列出已追踪的包裹：
bash
python3 {baseDir}/scripts/track17.py list
  1. 轮询更新（若不使用Webhook，推荐此方式）：
bash
python3 {baseDir}/scripts/track17.py sync
  1. 查看单个包裹详情：
bash
python3 {baseDir}/scripts/track17.py status 1

or

or

python3 {baseDir}/scripts/track17.py status "RR123456789CN"
undefined
python3 {baseDir}/scripts/track17.py status "RR123456789CN"
undefined

Webhooks (optional)

Webhook（可选）

17TRACK can push updates to a webhook URL. This skill supports webhook ingestion in two ways:
17TRACK可将更新推送到Webhook URL。该Skill支持两种Webhook接收方式：

A) Run the included webhook server

A) 运行内置Webhook服务器

bash
python3 {baseDir}/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789
Then point 17TRACK's webhook URL at that server (ideally via a reverse proxy or Tailscale Funnel).
bash
python3 {baseDir}/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789
随后将17TRACK的Webhook URL指向该服务器（理想情况下通过反向代理或Tailscale Funnel实现）。

B) Ingest webhook payloads from stdin/file

B) 从标准输入/文件导入Webhook负载

bash
cat payload.json | python3 {baseDir}/scripts/track17.py ingest-webhook
bash
cat payload.json | python3 {baseDir}/scripts/track17.py ingest-webhook

or

or

python3 {baseDir}/scripts/track17.py ingest-webhook --file payload.json

If you saved webhook deliveries to the inbox directory, process them:

```bash
python3 {baseDir}/scripts/track17.py process-inbox
python3 {baseDir}/scripts/track17.py ingest-webhook --file payload.json

若已将Webhook交付内容保存到收件箱目录，可处理它们：

```bash
python3 {baseDir}/scripts/track17.py process-inbox

Common actions

常用操作

  • Stop tracking:
bash
python3 {baseDir}/scripts/track17.py stop 1
  • Retrack a stopped parcel:
bash
python3 {baseDir}/scripts/track17.py retrack 1
  • Delete a parcel from local DB (does not delete at 17TRACK unless you also call 
    delete-remote
    ):
bash
python3 {baseDir}/scripts/track17.py remove 1
  • Show API quota:
bash
python3 {baseDir}/scripts/track17.py quota
  • 停止追踪：
bash
python3 {baseDir}/scripts/track17.py stop 1
  • 重新追踪已停止的包裹：
bash
python3 {baseDir}/scripts/track17.py retrack 1
  • 从本地数据库删除包裹（若不同时调用
    delete-remote
    ，不会在17TRACK端删除）：
bash
python3 {baseDir}/scripts/track17.py remove 1
  • 查看API配额：
bash
python3 {baseDir}/scripts/track17.py quota

Operating guidance for the agent

Agent操作指南

  • Prefer sync (polling) for simplicity unless the user explicitly wants webhooks.
  • After adding a package, run 
    status
    once to confirm a valid carrier/status was returned.
  • When summarising, prioritise:
    • delivered/out for delivery
    • exception/failed delivery
    • customs holds
    • carrier handoffs
  • Never echo 
    TRACK17_TOKEN
    or 
    TRACK17_WEBHOOK_SECRET
    .
  • 除非用户明确要求使用Webhook，否则优先选择sync（轮询）方式以简化操作。
  • 添加包裹后，运行
    status
    命令一次，确认返回有效的承运商/状态信息。
  • 汇总状态时，优先关注：
    • 已送达/正在派送中
    • 异常/派送失败
    • 海关扣留
    • 承运商交接
  • 切勿输出
    TRACK17_TOKEN
    或
    TRACK17_WEBHOOK_SECRET
    。