Cargogo 全球船期查询服务

概述

Cargogo 船期查询 API

使用 Skill 自带的 Python 调用脚本访问 Cargogo 船期服务，查询起运港到目的港的全球船期、开航计划、船名航次和直达/中转方案。

已实现能力

当前提供 3 个工具：

• query_global_schedule：查询港到港船期、近期或未来开航计划、ETD/ETA、船名航次及直达/中转方案。
• subscribe_global_schedule：订阅全球船期数据。该操作会创建远程业务订阅，调用前必须确认用户意图。
• get_schedule_page_url：获取全球船期页面 URL。

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

港口代码和船公司 SCAC 必须来自随 Skill 发布的 Cargogo 主数据清单。不得使用 ShipXY 或其他系统返回的港口代码代替 Cargogo port_code。

• SCAC 清单：[references/scac-carriers.md](references/scac-carriers.md)

当用户提供港口名或船公司名称时，先使用脚本的 port / scac 命令解析；MCP 环境中使用 cargogo_resolve_port / cargogo_resolve_carrier。只有 status=resolved 时才使用 match.code；清单中没有可靠匹配时不要猜测。

准备运行条件

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

• Python 3.10 或更高版本；
• 允许访问目标 Cargogo API 域名；
• 已通过 Secret 或运行变量配置 Cargogo 船期 API Key。

CARGOGO_SCHEDULE_API_KEY 需要联系 Cargogo 平台获取或确认。平台信息与服务入口：Cargogo 官网。

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

python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" auth-check
python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" list
python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" port --query 上海港
python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" scac --query Maersk

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

智能体中的凭据使用

• 在智能体平台的 Secret、Runtime Variables 或容器密钥配置中，以变量名 CARGOGO_SCHEDULE_API_KEY 注入凭据；不要把值写入提示词、Skill 文件或工具参数。
• 确保执行 scripts/cargogo_schedule.py 的进程继承该变量；配置变更后重启智能体或其工具执行器。
• 一个智能体运行实例只绑定一个船期服务凭据。服务多个客户或业务方时，为每个客户或业务方使用独立的进程、容器或 Secret 作用域，避免凭据和业务数据串用。

完整配置示例和验证步骤见 [references/authentication.md](references/authentication.md)。

标准调用流程

1. 明确起运港、目的港、日期范围、直达/中转偏好和承运人条件。
   • 用户给出明确日期、“未来 N 天”、“本周”或“下周”时，日期范围是强约束，不得省略。
   • “未来 N 天船期”默认按开航 ETD 过滤：etd_from=当前日期，etd_to=当前日期+N天。只有用户明确说到港/ETA 范围时才使用 eta_from/eta_to。
2. 使用 Cargogo 主数据解析港口和船司：

python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" port --query 上海港
python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" port --query Rotterdam --country-code NL
python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" scac --query Maersk

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

python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" describe query_global_schedule

接口路径和参数映射集中维护在 references/catalog.json。describe 会显示目标地址、实际 path、完整 url、HTTP 方法以及 Skill 参数到接口字段的映射。

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

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

1. 调用只读查询：

python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" call query_global_schedule 
  --params-json '{"dep_port":"CNSHA","arr_port":"NLRTM","etd_from":"2026-08-13","etd_to":"2026-08-20"}'

1. 订阅会创建新的业务状态。先执行 --dry-run，确认用户确实要订阅后再调用：

python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" call subscribe_global_schedule 
  --params-json '{"pol_code":"CNSHA","pod_code":"NLRTM","scac":"MAEU","request_id":"demo-001"}' 
  --dry-run

python3 "$CARGOGO_SCHEDULE_SKILL_DIR/scripts/cargogo_schedule.py" call subscribe_global_schedule 
  --params-json '{"pol_code":"CNSHA","pod_code":"NLRTM","scac":"MAEU","request_id":"demo-001"}' 
  --confirm-side-effect

参数原则

• 小型参数对象使用 --params-json；生成参数或复杂业务参数使用 --params-file。
• 简单标量可以使用 --param name=value。
• 同一字段只能由一种参数来源提供。
• 只使用 describe 返回的参数名，不把接口字段名或自然语言名称直接当参数。
• 港口使用最新 Cargogo 港口清单中的 5 位 port_code。该代码可能与 ShipXY 或当前 UNECE UN/LOCODE 不同；自然语言港口名必须先解析。
• 承运人使用最新 Cargogo 船司清单中的 4 位字母或数字 SCAC，例如马士基 MAEU、正利航运 11DX、山东远洋 43LW、上海海华 12GE。合法性仅以清单成员为准，不要求纯字母；清单备注只用于解释，不影响参数有效性。
• 用户未指定船司或清单无法可靠匹配时，可不传 scac 查询全承运人船期；不得猜测代码。
• 除非工具契约另有说明，日期使用 YYYY-MM-DD。
• “船期”表示港到港开航班次、ETD/ETA、船名航次及直达/中转方案，应使用 query_global_schedule。

结果与文件

• 成功结果包含 ok=true、tool、returns、object_refs 和 data。
• query_global_schedule 保留上游原始字段，并返回 result_contract。船期列表位于 data.data；不得因为常用摘要字段而丢弃原始数据。
• 成功响应的 effective_query 是实际传给上游的查询条件。用户指定了时间范围时，返回后必须检查对应 etd_* 或 eta_* 字段存在；缺失表示本次查询未按用户时间执行。
• ETD/ETA 不在船期主对象顶层。先在 wayPortList 中定位起运港（portType="0"）和目的港（portType="3"）；缺失时再分别按 depPortCode/arrPortCode 匹配 portCode。
• 起运港 depS/depE/depA 分别是计划/预计/实际 ETD；目的港 arrS/arrE/arrA 分别是计划/预计/实际 ETA。必须保留时间语义和节点 timeZone，不得混成一个无标签日期。
• 直达/中转以主对象 transitCount 为准；wayPortList 中 portType="2" 是明确中转港，portType="1" 是普通挂靠港。
• 失败结果包含结构化 error.type、消息、状态码或字段详情。
• 空数组或零记录通常表示查询成功但当前没有匹配船期。
• 响应超过 50 KB 时脚本返回 spooled=true 和 result_path；读取该文件继续分析。
• 使用 --output <path> 可以把完整结果写入指定文件。

处理时间、直达/中转、空结果和页面 URL 时读取 [references/return-semantics.md](references/return-semantics.md)。

汇报要求

• 说明起运港、目的港、时间范围、承运人过滤条件和时区。
• 区分计划 ETD/ETA、预计时间、实际观测和接口返回时间。
• 明确结果是否为空、是否分页或是否写入文件。
• 船期结果优先摘要展示：承运人、航线、船名、航次、ETD、ETA、航程天数、直达/中转、途经港。
• 只返回用户需要的字段，不暴露 API Key、Token、认证 Header 或无关客户数据。