本地化包裹追踪助手，支持 17TRACK API 查询与 webhook 推送，适合跨境购物者自主管理物流状态。
说明：
## 核心用法
track17 是一款面向个人用户的包裹追踪 Skill，基于 17TRACK Tracking API v2.2 实现。它通过本地 SQLite 数据库持久化存储包裹信息，支持两种数据同步模式：主动轮询（polling）和被动 webhook 推送。
**基础操作流程：**
1. 初始化存储：`init` 命令创建本地数据库
2. 添加包裹：`add` 命令将单号注册到 17TRACK 并本地存档，支持自动识别物流商或手动指定 carrier code
3. 查询状态：`status` 查看单件详情，`list` 浏览全部包裹
4. 同步更新：`sync` 轮询 API 获取最新物流动态
5. 生命周期管理：`stop`/`retrack` 控制追踪状态，`remove` 清理本地记录
**Webhook 进阶功能：**
– 内置轻量级 HTTP 服务器接收 17TRACK 主动推送
– 支持从文件/stdin 批量导入 webhook payload
– `process-inbox` 处理离线保存的推送数据
## 显著优点
1. **数据自主权**：所有包裹信息存储于本地 SQLite，避免依赖第三方平台账户，支持离线历史查询
2. **灵活架构**：polling + webhook 双模式覆盖不同场景，轻量服务器可配合 Tailscale Funnel 等工具实现内网穿透
3. **Carrier 覆盖广**：依托 17TRACK 支持全球 2000+ 物流商，跨境购物（AliExpress、Amazon 海外购等）场景友好
4. **CLI 原生设计**：脚本化操作便于与 cron/systemd 集成，适合自动化工作流
## 潜在缺点与局限性
1. **API 配额限制**：17TRACK 免费 tier 有调用次数上限，高频轮询可能触发限流
2. **Webhook 配置门槛**：需自行部署反向代理或内网穿透工具，对非技术用户不够友好
3. **单数据库架构**：SQLite 并发写入能力有限，不适合多用户/高并发场景
4. **Carrier code 依赖**：部分小众物流商自动识别失败，需人工查询 carrier 编号
5. **无推送通知**：原生仅支持命令行查询，需额外配置（如结合 ntfy/Apprise）才能实现主动提醒
## 适合人群
– **跨境购物常客**：需要集中管理多平台、多物流商订单
– **隐私敏感用户**：不愿将购物记录托管于云端追踪服务
– **CLI/自动化爱好者**：希望将物流查询纳入脚本化工作流
– **小型代购/转运从业者**：轻量级本地数据库满足基础客户包裹管理
## 常规风险
| 风险类型 | 说明 | 缓解建议 |
|———|——|———|
| API Token 泄露 | TRACK17_TOKEN 泄露可能导致配额被盗用 | 使用环境变量注入，避免硬编码；定期轮换 |
| Webhook 签名绕过 | 若未配置 TRACK17_WEBHOOK_SECRET，存在伪造推送风险 | 生产环境务必启用签名验证 |
| 数据丢失 | 单文件 SQLite 无自动备份机制 | 定期复制 `track17.sqlite3` 或使用 Litestream 等工具 |
| 依赖服务变更 | 17TRACK API 版本升级或费率调整可能影响功能 | 关注官方 changelog，预留迁移预算 |
会员专属
