UnityClaw 全球快递查询

解决的问题

物流查询脚本最常见的失败模式，是重写原始状态。很多方案拿到承运商返回后，习惯把 status 映射成一套内部枚举，把缺失的轨迹节点补全成“合理进度”，甚至从运单号前缀猜测承运商。短期内界面看着整齐，代价是丢失了服务端的真实语义：一个“暂无更新”被渲染成“运输中”，一次到仓扫描被当成签收，都会直接误导下游的客服、仓储或对账逻辑。

更实际的麻烦在工程细节：查询必须等承运商响应，超时时间跨度从 1 秒到 1 小时不等；部分承运商要求附带收件人手机号或手机号后四位，这个参数不是固定的，只能在服务端明确提出后补交。把这些写成一次性脚本，很容易出现重复并发请求、失败重试策略混乱、原始字段被裁剪等问题。

核心能力

UnityClaw Global Express Tracking 的定位是一次调用拿到单条运单的原始服务响应，并完整落盘。它的核心设计原则是：不推断、不映射、不补全。

工作流程分为四步：

1. 收集输入：只要求一个运单号 --express-no，可附带 --mobile 供承运商需要时使用。保留用户输入中的字母、数字与标点，只做首尾空白裁剪，不猜测承运商，也不改写标识符格式。
2. 执行查询：调用 scripts/generate.js --json --output-dir，开启 --json 后返回机器可读结果，--retries 控制瞬时失败重试次数（0 到 3）。同一个运单不提交重复并发请求。
3. 保留响应：服务端返回的 express、status、last、detail、updated 以及任何额外字段原样写入 express-tracking.json。即使历史为空，也照实记录。
4. 校验交付：只有 success 为 true、返回对象至少有一个非空字段、resultPath 指向非空 JSON 文件时才算完成。若 status 或事件详情缺失，检查 warnings 中是否给出了说明。

边界与注意点

• 快照而非状态：查询结果是时点快照。某次查询没有新轨迹，不代表包裹丢了；出现到达扫描，也不代表已投递给收件人。下游逻辑必须容忍这种不确定性。
• 不推断承运商：express 字段完全来自服务端返回，脚本不会从运单号结构推断承运商。
• 手机号按需提交：只有在服务端明确提示需要手机号时才补交 --mobile，避免在不必要时收集收件人隐私。
• 重试条件明确：只在 error.retryable 为 true 时重试，其他错误直接返回原始错误码、消息和已尝试次数。
• 未知单号如实上报：遇到无法识别的单号或空轨迹，报回服务端返回的状态，不虚构进度。

适合的场景是需要完整审计链路的单票查询，尤其是要把查询结果存档、追溯或接入自动化流程的工程团队。如果你的需求是批量扫描所有承运商自动识别、或者实时订阅包裹状态变化，这个工具不覆盖。