技能介绍

要解决的问题

船期数据分散在承运人、港口和第三方平台上，格式互不兼容。同一个港口在不同系统里有不同代码（例如 ShipXY 的编码可能与 Cargogo 的 port_code 不一致），承运人标识也依赖 4 位 SCAC 代码。人工比对计划 ETD、预计开航、实际离港和目的港的预计/实际到港，还要区分直达与中转，极易出错。中转方案里挂靠港和中转港的语义也常被混用，导致航程天数和节点时间轴解读错误。

技能如何工作

该技能通过随附的 Python 脚本 scripts/cargogo_schedule.py 调用 Cargogo 船期 API，只依赖标准库，提供三个工具：

query_global_schedule：查询港到港船期、开航计划、ETD/ETA、船名航次和直达/中转方案；
subscribe_global_schedule：创建远程业务订阅，调用前必须确认意图，并用 --dry-run 预演；
get_schedule_page_url：获取对应的船期页面链接。

调用前先把自然语言的港口名、船公司名解析成 Cargogo 主数据中的 port_code 与 SCAC，脚本提供 port / scac 命令（MCP 环境为 cargogo_resolve_port / cargogo_resolve_carrier），只有 status=resolved 时才使用 match.code，清单无可靠匹配时不猜测。第一次使用某工具前，通过 describe 读取接口路径、HTTP 方法和参数映射（集中维护在 references/catalog.json），再按契约构造参数。本地校验不请求远程；查询失败时返回结构化 error.type。

结果解析有几个固定约定：起运港看 wayPortList 中 portType="0"，目的港看 portType="3"；depS/depE/depA 分别是计划、预计、实际 ETD，arrS/arrE/arrA 是对应 ETA，必须保留时区与时间语义。直达/中转以主对象的 transitCount 为准，portType="2" 才是明确中转港。响应超过 50 KB 时脚本返回 spooled=true 和 result_path，可从文件继续分析。

适用边界与注意点

需要 Python 3.10+、对 Cargogo API 域名的网络访问，以及通过 CARGOGO_SCHEDULE_API_KEY 注入的凭据。Key 应放在 Secret 或运行变量中，不要写进提示词、Skill 文件或工具参数，也不要要求用户在公开聊天里粘贴；一个运行实例只绑定一个凭据，服务多客户时需隔离进程或 Secret 作用域。用户指定日期范围、“未来 N 天”等条件时，ETD/ETA 过滤是强约束，其中“未来 N 天船期”默认按开航 ETD 过滤，只有明确说到港范围才用 ETA。空数组代表查询成功但暂无匹配船期，不是报错。另外，query_global_schedule 会保留上游原始字段，不要把摘要字段当成完整数据丢弃。

截图预览

使用场景

货代销售需要给客户报某一港到另一港未来 14 天有哪些可用班轮，并确认哪些是直达、哪些需要中转。
操作人员拿到一份用港口中文名写的托书，要先解析成 Cargogo 的 5 位 port_code 才能查船期。
计划员想筛选只有马士基等特定 SCAC 承运人的船期，排除其他船司的班次。
船公司市场部要持续跟进某条航线的班期变化，确认后通过订阅方式获取更新的船期数据。

适合人员

国际货代操作或客服：经常按客户给出的港口和日期查可用班轮，再回复直达与中转方案和运价参考时间。
船公司或集装箱班轮的船期计划员：需要维护航线班期表，核对 ETD 与 ETA，并区分计划、预计和实际开航时间。
供应链数据工程师：把船期接口接入内部系统，负责港口代码、SCAC 和接口字段映射的解析与清洗。
航运数据分析人员：研究某条航线近期的班期密度、挂靠港和中转港构成，需要从原始船期记录中提取字段。

Cargogo 全球船期查询