名称： track17
描述： 通过 17TRACK API 追踪包裹（本地 SQLite 数据库，轮询 + 可选 Webhook 接收）
user-invocable: true
元数据： {"clawdbot":{"emoji":"📦","requires":{"anyBins":["python3","python"],"env":["TRACK17_TOKEN"]},"primaryEnv":"TRACK17_TOKEN"}}

track17 (17TRACK 包裹追踪)

此技能允许 Clawdbot 在本地维护您的包裹列表，通过 17TRACK Tracking API v2.2 追踪其状态，并汇总变更信息。

所有数据都存储在您工作空间下的一个SQLite 数据库中（默认位置：<workspace>/packages/track17/track17.sqlite3）。

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

环境要求

• 必须设置 TRACK17_TOKEN（17TRACK API 令牌；用作 17token 请求头）。
• 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 "阿里耳机"

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

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

Webhook（可选）

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) 从 stdin 或文件接收 Webhook 数据

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

给代理的操作指引

• 为简化操作，优先使用 sync（轮询），除非用户明确需要 Webhook。
• 添加包裹后，运行一次 status 以确认返回了有效的承运商和状态。
• 汇总信息时，按以下优先级排序：
• 已送达/派送中
• 异常/投递失败
• 海关扣留
• 承运商交接
• 切勿回显 TRACK17_TOKEN 或 TRACK17_WEBHOOK_SECRET。