mcpField
T
track17

track17

github.com/tristanmanchester其他3102 次安装7 周前更新
代码仓库

关于 track17

通过随附的 Python 命令行工具使用 17TRACK 跟踪包裹，涵盖轮询、包裹管理和经过身份验证的 Webhook，并将数据保存在本地，对远程变更设有明确限制。

主要功能

  1. 01按单号和承运商管理包裹
  2. 02轮询跟踪状态与配额
  3. 03接收签名验证的 Webhook
  4. 04保存并去重跟踪更新
  5. 05区分事件时间与刷新时间

适用场景

  1. 01查询不同承运商的包裹状态
  2. 02处理经过身份验证的 17TRACK 推送
  3. 03审查未完成的同步，避免误判为无更新

MCP 相关

输入介绍了 Skill 和命令行工作流，但未说明其与 MCP 的集成。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tristanmanchester/agent-skills --skill track17

安装后在 Claude Code 中输入/track17确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
scripts/
track17.py
tests/
test_review_regressions.py
test_track17.py

详细介绍

使用 17TRACK 跟踪包裹

将 SKILL_DIR 解析为此技能的安装目录。请使用随附的 CLI，不要自行重建存储或签名处理逻辑。命令会返回 JSON；非零退出状态表示失败或同步未完成。

设置

通过宿主的密钥存储/环境变量设置 TRACK17_TOKEN；切勿打印它。将 TRACK17_DATA_DIR 设置为仓库外的私有绝对路径。然后运行：

python3 "$SKILL_DIR/scripts/track17.py" init
python3 "$SKILL_DIR/scripts/track17.py" --help

此版本使用新的本地架构。包含 packages 的旧数据库会被拒绝，且不会被修改。请选择新的数据目录，在本地检查/导出旧记录，并且只注册用户仍需要的包裹。不要删除旧数据库，也不要自动重新注册全部包裹：这可能会消耗服务商配额。

常规工作流

除非需要推送通知，否则优先使用轮询。在添加或移除任何包裹之前，先读取当前包裹列表。请通过跟踪号码加承运商代码确定包裹身份，不要猜测本地 ID。

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

上述承运商号码仅为示例，并非通用默认值。如果自动检测无法确定承运商，请使用 --carrier；仅当承运商需要额外信息时，才使用 --param。注册成功不代表跟踪事件已经可用。

stop、retrack 和 remove 都需要跟踪号码和 --carrier。除非明确提供 --delete-remote，否则 remove 只会在本地移除。执行远程删除前，请先确认。网络故障导致结果不明确后，请在重试更改操作前核对服务商状态；客户端不会自动重放写入操作。

已验证身份的 Webhook

17TRACK 会将原始请求体字节后接 / 和 API 安全密钥，再使用 SHA-256 计算签名。签名通过 sign 标头传入。此辅助工具使用 TRACK17_TOKEN 作为该密钥；切勿另行编造不相关的 Webhook 密钥，也不要用 HMAC 替代服务商的算法。

对于已捕获的投递，请保持请求体不变，并提供其真实签名：

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 和原始请求体。不要随意公开开发服务器。缺失、无效或重复的身份验证标头都会导致请求失败；只有在数据库事务提交后，才会确认已接受的投递。存储失败会返回失败响应，以便服务商重试。没有无签名导入路径，也没有延迟处理的收件箱处理器。

相同的投递具有幂等性。日期较早的更新不会覆盖日期较新的快照。但这不代表能普遍确定顺序：时间戳无法解决时间相同的更正，也无法证明无日期更新的新鲜度。请分别报告事件时间和本地接收时间。

报告

优先关注已送达、派送中、待取件、投递失败和异常状态。请注明承运商、事件时间和最近一次成功刷新时间；区分已保存状态与服务商刚返回的响应。将部分同步和缺失事件视为不完整证据，而非“没有变化”。切勿根据无关包裹或过时快照推断送达日期。

来源和检查

17TRACK API 文档经审阅于 2026-09-13，记录了签名方案，并明确说明 v2.2 仍在线。此辅助工具有意保留该受支持的响应契约；v2.4 并非只需更改版本字符串即可直接替换，因为其注册字段有所不同。

运行离线和环回 HTTP 回归测试：

python3 -m unittest discover -s "$SKILL_DIR/tests" -v

updated_at 记录快照变更；last_refreshed_at 记录最近一次已接受的轮询响应，包括快照未变的情况。两者都不是承运商事件时间。Webhook 接收/去重不计为成功轮询。

评论

支持 Markdown