Cargogo 物流跟踪数据 API

概述

Cargogo 国际物流 API

使用 Skill 自带的 Python 调用脚本访问 Cargogo OAuth API。脚本从内置能力目录读取接口契约，负责参数校验、OAuth 认证、租户注入、HTTP 请求、结构化错误和大结果落盘。

已实现能力

当前业务目录提供 36 个远程 API 工具，并配套两个本地主数据解析能力：cargogo_resolve_port 与 cargogo_resolve_carrier。

• 船舶与口岸计划（3项）：按 IMO、MMSI 或船名查询船舶档案与身份；查询口岸进出口船舶计划。
• 全球船期（3项）：订阅或查询港到港船期、ETD/ETA、船名航次及直达/中转方案；获取船期页面 URL。
• 口岸货物跟踪（2项）：按提单号、订舱号或箱号创建口岸跟踪，并通过 queryId 查询节点动态。
• 集装箱海运（8项）：识别候选船公司 SCAC，创建货物跟踪，查询节点、实际轨迹、未来轨迹和来船轨迹，获取在途大屏与单票地图 URL。
• 空运（4项）：创建空运主单跟踪，查询节点与实际轨迹，获取单票地图 URL。
• RoRo 滚装船（7项）：按 VIN、订舱号或提单号创建跟踪，查询节点、实际轨迹和未来轨迹，获取在途大屏、单票地图与预警大屏 URL。
• 陆运（3项）：创建陆运跟踪，获取单票地图 URL，查询门点围栏详情。
• 中欧/中亚班列（4项）：创建班列跟踪，查询节点与实际轨迹，获取单票地图 URL。
• 北美铁路（2项）：创建北美铁路跟踪并查询节点动态。

查看全部工具名称和用途时读取 [references/tool-index.md](references/tool-index.md)；查看准确参数、接口路径和字段映射时运行 list 和 describe <tool>。

准备环境

将包含本文件的目录解析为 CARGOGO_SKILL_DIR。运行环境需要：

• Python 3.10 或更高版本；
• 允许访问目标 Cargogo API 域名；
• 已通过 Secret 或环境变量配置 Cargogo OAuth 凭据。

CARGOGO_CLIENT_ID 和 CARGOGO_CLIENT_SECRET 由 Cargogo 平台提供；尚未取得凭据时，请联系 Cargogo 平台申请。平台信息与服务入口：Cargogo 官网。

脚本仅使用 Python 标准库，不需要安装其他程序或 Python 包。首次使用时执行：

python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" auth-check
python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" list

如果凭据未配置，读取 [references/authentication.md](references/authentication.md)。不得要求用户在公开或共享聊天中粘贴 Client Secret、Access Token 或认证 Header。

智能体中的凭据使用

• 在智能体平台的 Secret、Environment 或容器密钥配置中，以环境变量名 CARGOGO_CLIENT_ID、CARGOGO_CLIENT_SECRET 和 CARGOGO_TENANT_ID 注入凭据；不要把值写入提示词、Skill 文件或工具参数。
• 确保执行 scripts/cargogo.py 的进程继承这些环境变量；配置变更后重启智能体或其工具执行器。
• 不要预先获取或向智能体传递 Access Token。脚本在真实调用时使用 Client Credentials 自动获取短期 Token，并自动添加 Authorization: Bearer ...。
• 一个智能体运行实例只绑定一个租户环境。服务多个租户时，为每个租户使用独立的进程、容器或 Secret 作用域，避免凭据和业务数据串用。

完整配置示例、验证步骤和多租户要求见 [references/authentication.md](references/authentication.md)。

标准调用流程

1. 根据用户目标选择最小能力。产品或标识类型不明确时读取 [references/intent-routing.md](references/intent-routing.md)。
2. 用户提供自然语言港口名或船公司名时，先解析为 Cargogo 自有代码：

python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" port --query 上海港
python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" scac --query 马士基

在 MCP 环境中优先直接调用 cargogo_resolve_port / cargogo_resolve_carrier。解析结果只有 status=resolved 时才能使用 match.code；ambiguous 必须结合国家、航线或用户上下文确认。

1. 本次任务第一次使用工具前读取准确契约：

python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" describe query_global_schedule

接口路径和参数映射集中维护在 references/catalog.json。describe 会显示实际 path、完整 url、HTTP 方法以及 Skill 参数到接口字段的映射。服务地址由 Skill 内置管理，Agent 无需也不应配置或切换。

1. 按契约中的参数名称构造 JSON object。
2. 先执行本地校验；校验不会请求远程 API：

python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" validate query_global_schedule 
  --params-json '{"dep_port":"CNSHA","arr_port":"NLRTM","route_type":"0"}'

1. 调用只读工具：

python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" call query_global_schedule 
  --params-json '{"dep_port":"CNSHA","arr_port":"NLRTM","etd_from":"2026-07-28","etd_to":"2026-08-04"}'

1. 订阅会创建新的业务查询。先执行 --dry-run，确认用户意图和关键标识后再调用：

python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" call subscribe_ocean_tracking 
  --params-file /tmp/cargogo-subscribe.json 
  --dry-run

python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" call subscribe_ocean_tracking 
  --params-file /tmp/cargogo-subscribe.json 
  --confirm-side-effect

--dry-run 会输出脱敏后的目标 URL、Query 参数或 JSON Body，不申请 Access Token，也不会建立远程连接。

在智能体中复用 queryId

跟踪类订阅成功后，从脚本结果顶层读取标准字段 query_id。将它与 product、原始业务标识和 request_id 一起保存在当前任务状态中；跨任务复用时写入智能体的受控业务存储。后续调用使用 Skill 参数名 query_id，脚本会转换成接口字段 queryId。

python3 "$CARGOGO_SKILL_DIR/scripts/cargogo.py" call query_ocean_tracking_nodes 
  --params-json '{"query_id":"订阅结果中的 query_id"}'

只把 query_id 交给同一产品的后续工具。结果中没有 query_id 时，先检查业务状态和原始 data，不得猜测标识或用原始单号代替。完整产品映射和保存规则见 [references/workflows.md](references/workflows.md)。

参数原则

• 小型参数对象使用 --params-json；生成参数或复杂业务参数使用 --params-file。
• 简单标量可以使用 --param name=value。
• 同一字段只能由一种参数来源提供。
• 只使用 describe 返回的参数名，不把接口字段名或自然语言名称直接当参数。
• 港口参数必须使用最新 Cargogo 港口清单中的 port_code。它可能与 ShipXY 或当前 UNECE UN/LOCODE 不同；禁止把其他系统查询到的港口代码直接传入 Cargogo。
• 船司参数必须使用最新 Cargogo 船司清单中的 SCAC。SCAC 是 4 位字母或数字业务代码，例如 MAEU、11DX、43LW、12GE；合法性仅以清单成员为准，不得按纯字母格式猜测。清单备注只用于解释，不影响参数有效性。
• 用户提供港口名或船司名时先调用 cargogo_resolve_port / cargogo_resolve_carrier（或脚本的 port / scac 命令）。
• 用户提供提单号或箱号、需要从单号识别承运人时，使用 query_ocean_scac_candidates；它与按船公司名称解析 SCAC 的 cargogo_resolve_carrier 用途不同。
• 除非工具契约另有说明，日期使用 YYYY-MM-DD。
• “船期”表示港到港开航班次、ETD/ETA、船名航次及直达/中转方案，应使用 query_global_schedule。
• 用户指定日期或“未来 N 天”时，时间是强约束：默认按 ETD 传 etd_from=当前日期 和 etd_to=当前日期+N天，不得省略后查全部船期；用户明确说 ETA/到港范围时才改用 eta_from/eta_to。
• “货物跟踪”表示某个提单、订舱单、箱、主单、VIN 或铁路箱的节点和轨迹，应先选择对应产品订阅，再使用返回的 queryId。

结果与文件

• 成功结果包含 ok=true、tool、returns、object_refs 和 data。
• query_global_schedule 对上游船期原始字段做无损保留，船期列表位于 data.data，并通过 outputSchema/result_contract 提供只出现一次的字段语义。
• effective_query 回显实际传给上游的条件。问题含时间范围时，必须确认其中对应 etd_* 或 eta_* 字段存在且与用户要求一致。
• ETD/ETA 需从 wayPortList 取值：起运港 portType="0" 的 depS/depE/depA 分别是计划/预计/实际 ETD；目的港 portType="3" 的 arrS/arrE/arrA 分别是计划/预计/实际 ETA。
• 港口类型缺失时，分别使用 depPortCode/arrPortCode 匹配节点 portCode。保留 timeZone 和计划/预计/实际标签，不得合并为无语义日期。
• 直达/中转以 transitCount 为准；portType="2" 是中转港，portType="1" 是挂靠港。
• 失败结果包含结构化 error.type、消息、状态码或字段详情。
• 空数组或零记录通常表示查询成功但当前没有匹配数据。
• 响应超过50 KB时脚本返回 spooled=true 和 result_path；读取该文件继续分析。
• 使用 --output <path> 可以把完整结果写入指定文件。

处理查询 ID、时间、轨迹、预测数据、地图 URL 和空结果时读取 [references/return-semantics.md](references/return-semantics.md)。执行跨步骤订阅与查询时读取 [references/workflows.md](references/workflows.md)。

汇报要求

• 说明查询产品、关键标识、时间范围和时区。
• 区分接口观测值、业务事件、推导路线和预测结果。
• 说明结果是否为空、是否分页或写入文件。
• 订阅成功后保存并明确返回 queryId，供后续节点、轨迹和地图查询复用。
• 只返回用户需要的字段，不暴露 OAuth 凭据、Token、认证 Header 或无关客户数据。