介绍
# track17 (17TRACK parcel tracking)
此技能允许 Clawdbot 维护您的本地包裹列表，通过 **17TRACK Tracking API v2.2** 跟踪其状态，并汇总变更。
它将所有内容存储在 **workspace**（工作区）下的一个小型 **SQLite 数据库**中（默认位置：`<workspace>/packages/track17/track17.sqlite3`）。
`<workspace>` 会自动检测为包含此技能的最近的 `skills/` 目录的父目录。
例如，如果您将其安装在 `/clawd/skills/track17/`，数据将存储在 `/clawd/packages/track17/` 中。
## Requirements
- 必须设置 `TRACK17_TOKEN`（17TRACK API 令牌；用作 `17token` 请求头）。 - Python（推荐使用 `python3`）。
可选：
- 如果您想验证 Webhook 签名，请设置 `TRACK17_WEBHOOK_SECRET`。 - `TRACK17_DATA_DIR` 用于覆盖数据库/收件箱的存储位置。 - `TRACK17_WORKSPACE_DIR` 用于覆盖此工具视为工作区的目录。
## Quick start
1) 初始化存储（多次运行是安全的）：
```bash python3 {baseDir}/scripts/track17.py init ```
2) 添加包裹（向 17TRACK 注册并在本地存储）：
```bash python3 {baseDir}/scripts/track17.py add "RR123456789CN" --label "AliExpress headphones" ```
如果承运商自动检测失败，请指定承运商代码：
```bash python3 {baseDir}/scripts/track17.py add "RR123456789CN" --carrier 3011 --label "..." ```
3) 列出正在跟踪的包裹：
```bash python3 {baseDir}/scripts/track17.py list ```
4) 轮询更新（如果您不想使用 Webhook，推荐此方式）：
```bash python3 {baseDir}/scripts/track17.py sync ```
5) 显示单个包裹的详细信息：
```bash python3 {baseDir}/scripts/track17.py status 1 # or python3 {baseDir}/scripts/track17.py status "RR123456789CN" ```
## Webhooks (optional)
17TRACK 可以将更新推送到 Webhook URL。此技能支持两种方式接收 Webhook：
### A) 运行内置的 Webhook 服务器
```bash python3 {baseDir}/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789 ```
然后将 17TRACK 的 Webhook URL 指向该服务器（理想情况下通过反向代理或 Tailscale Funnel）。
### B) 从 stdin/文件 接收 Webhook 负载
```bash cat payload.json | python3 {baseDir}/scripts/track17.py ingest-webhook # or python3 {baseDir}/scripts/track17.py ingest-webhook --file payload.json ```
如果您将 Webhook 投递保存到收件箱目录，请处理它们：
```bash python3 {baseDir}/scripts/track17.py process-inbox ```
## Common actions
- 停止跟踪：
```bash python3 {baseDir}/scripts/track17.py stop 1 ```
- 重新跟踪已停止的包裹：
```bash python3 {baseDir}/scripts/track17.py retrack 1 ```
- 从本地数据库删除包裹（不会在 17TRACK 上删除，除非您同时调用 `delete-remote`）：
```bash python3 {baseDir}/scripts/track17.py remove 1 ```
- 显示 API 配额：
```bash python3 {baseDir}/scripts/track17.py quota ```
## Operating guidance for the agent
- 除非用户明确需要 Webhook，否则为简单起见，优先使用 **sync**（轮询）。 - 添加包裹后，运行一次 `status` 以确认返回了有效的承运商/状态。 - 汇总时，请优先关注： - 已送达/派送中 - 异常/派送失败 - 海关扣留 - 承运商转运 - 切勿回显 `TRACK17_TOKEN` 或 `TRACK17_WEBHOOK_SECRET`。