用途：通过 17TRACK API 登记和追踪包裹，查看已保存的配送事件，并接收经过认证的 17TRACK webhook。
主要能力：提供捆绑 CLI 管理包裹，命令返回 JSON，非零退出状态表示失败或同步不完整。支持 list（列出包裹）、carriers-search（搜索承运商）、add（登记包裹）、sync（同步）、status（查询状态，可加 --refresh）、quota（查询配额）、stop、retrack、remove 等操作。支持通过 ingest-webhook 处理已捕获的推送，或用 webhook-server 启动本地接收服务。
使用方式：先设置 TRACK17_TOKEN（通过主机密钥存储或环境变量，切勿打印），并设置 TRACK17_DATA_DIR 为仓库外的私有绝对目录。然后运行： python3 "$SKILL_DIR/scripts/track17.py" init python3 "$SKILL_DIR/scripts/track17.py" --help
常用命令示例： python3 "$SKILL_DIR/scripts/track17.py" list python3 "$SKILL_DIR/scripts/track17.py" carriers-search DHL python3 "$SKILL_DIR/scripts/track17.py" add RR123456789CN --label "Headphones" python3 "$SKILL_DIR/scripts/track17.py" sync python3 "$SKILL_DIR/scripts/track17.py" status RR123456789CN --carrier 3011 --refresh python3 "$SKILL_DIR/scripts/track17.py" quota
包裹身份由追踪号加承运商代码确定，而非猜测的本地 ID。自动检测无法解析承运商时使用 --carrier；仅当承运商需要额外信息时使用 --param。登记成功不代表追踪事件已可用。stop、retrack、remove 需要追踪号和 --carrier；remove 默认仅本地删除，除非显式提供 --delete-remote。
Webhook：17TRACK 对原始请求体字节加 / 和 API 安全密钥做 SHA-256 签名，签名位于 sign 头。helper 使用 TRACK17_TOKEN 作为该密钥。处理已捕获推送时保留原始请求体并传入真实签名： python3 "$SKILL_DIR/scripts/track17.py" ingest-webhook --file delivery.json --signature "$DELIVERY_SIGN" 推送接收： python3 "$SKILL_DIR/scripts/track17.py" webhook-server --port 8789 接收器绑定回环地址，需在前端配置 TLS 反向代理并保留 sign 和原始请求体，不要随意暴露开发服务器。
限制：本版本使用新的本地 schema，含包裹的旧数据库会被拒绝且不做修改，需选择新数据目录并仅登记用户仍需要的包裹，不要删除旧库或自动重新登记全部（可能消耗配额）。相同推送幂等，较旧的带日期更新不能覆盖较新的带日期快照，但时间戳无法解决同时刻更正或证明无日期更新的新鲜度。网络失败后应先核对提供方状态再重试变更，客户端不会自动重放写入。报告应优先展示已送达、派送中、待取件、派送失败和异常，并区分已保存状态与最新提供方响应。运行离线与回环 HTTP 回归测试： python3 -m unittest discover -s "$SKILL_DIR/tests" -v
17TRACK API 文档（2026-09-13 审阅）记录了签名方案并明确保留 v2.2 在线；本 helper 有意保留该受支持的响应契约，v2.4 并非仅改版本字符串即可替换，因为额外登记字段不同。