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

快速开始

Initialise storage (safe to run multiple times):

bash

python3 {baseDir}/scripts/track17.py init

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

List tracked packages:

bash

python3 {baseDir}/scripts/track17.py list

Poll for updates (recommended if you don't want webhooks):

bash

python3 {baseDir}/scripts/track17.py sync

Show details for one package:

bash

python3 {baseDir}/scripts/track17.py status 1

初始化存储（可重复执行，安全无风险）：

bash

python3 {baseDir}/scripts/track17.py init

添加包裹（在17TRACK注册并本地存储）：

bash

python3 {baseDir}/scripts/track17.py add "RR123456789CN" --label "AliExpress headphones"

若承运商自动识别失败，指定承运商代码：

bash

python3 {baseDir}/scripts/track17.py add "RR123456789CN" --carrier 3011 --label "..."

列出已追踪的包裹：

bash

python3 {baseDir}/scripts/track17.py list

轮询更新（若不使用Webhook，推荐此方式）：

bash

python3 {baseDir}/scripts/track17.py sync

查看单个包裹详情：

bash

python3 {baseDir}/scripts/track17.py status 1

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

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
```
。