AgentSkillsCN

track17

通过17TRACK API追踪包裹（本地SQLite数据库、轮询+可选webhook摄入）

SKILL.md
--- frontmatter
name: track17
description: Track parcels via the 17TRACK API (local SQLite DB, polling + optional webhook ingestion)
user-invocable: true
metadata: {"clawdbot":{"emoji":"📦","requires":{"anyBins":["python3","python"],"env":["TRACK17_TOKEN"]},"primaryEnv":"TRACK17_TOKEN"}}

track17 (17TRACK parcel tracking)

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/.

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.

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
# or
python3 {baseDir}/scripts/track17.py status "RR123456789CN"

Webhooks (optional)

17TRACK can push updates to a webhook URL. This skill supports webhook ingestion in two ways:

A) Run the included webhook server

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).

B) Ingest webhook payloads from stdin/file

bash
cat payload.json | python3 {baseDir}/scripts/track17.py ingest-webhook
# 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

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

Operating guidance for the 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.