track17（17TRACK包裹追踪）

此技能让Clawdbot能够在本地维护您的包裹列表，通过17TRACK追踪API v2.2追踪其状态，并总结变化。

它将所有数据存储在一个位于您工作空间下的小型SQLite数据库中（默认路径为：<workspace>/packages/track17/track17.sqlite3）。

<workspace>会被自动检测为包含此技能的最邻近skills/目录的父目录。 例如，如果您将其安装在/clawd/skills/track17/，数据将存储在/clawd/packages/track17/。

要求

• 必须设置TRACK17_TOKEN（17TRACK API令牌；用作17tokenheader)。
• Python (python3首选)。

可选：

• TRACK17_WEBHOOK_SECRET若需验证webhook签名。
• TRACK17_DATA_DIR用于覆盖数据库/收件箱的存储位置。
• TRACK17_WORKSPACE_DIR用于覆盖此工具认定的工作空间目录。

快速开始

1. 初始化存储（可安全多次运行）：

python3 {baseDir}/scripts/track17.py init

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

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

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

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

3. 列出已追踪的包裹：

python3 {baseDir}/scripts/track17.py list

4. 轮询更新（若不希望使用webhook，推荐此方式）：

python3 {baseDir}/scripts/track17.py sync

5. 显示单个包裹详情：

python3 {baseDir}/scripts/track17.py status 1
# or
python3 {baseDir}/scripts/track17.py status "RR123456789CN"

Webhooks（可选）

17TRACK可将更新推送至webhook URL。此技能支持两种webhook接收方式：

A) 运行包含的Webhook服务器

python3 {baseDir}/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789

然后将17TRACK的Webhook URL指向该服务器（最好通过反向代理或Tailscale Funnel实现）。

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

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

如果您将Webhook投递内容保存到了收件箱目录，请处理它们：

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

常见操作

• 停止追踪：

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

• 重新追踪已停止的包裹：

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

• 从本地数据库中删除包裹（除非同时调用delete-remote，否则不会在17TRACK端删除）：

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

• 显示API配额：

python3 {baseDir}/scripts/track17.py quota

代理操作指南

• 为求简便，优先使用同步（轮询）方式，除非用户明确要求使用Webhooks。
• 添加包裹后，运行一次状态命令以确认返回了有效的承运商/状态。
• 总结时，优先关注：
  • 已送达/正在派送
  • 异常/派送失败
  • 海关扣留
  • 承运商交接
• 切勿回显TRACK17_TOKEN或TRACK17_WEBHOOK_SECRET。