ShipXY 船讯网海事 API

概述

ShipXY 船讯网 Skill

使用内置 CLI 调用 ShipXY，不要手工拼接 API 请求。选择能够回答问题的最小服务，读取其语义契约，校验参数，执行调用，再依据返回的解释规则分析结果。

能力概览

本 Skill 覆盖 33 项 ShipXY 海事数据服务，可组合完成船舶查询、船队监控、港口分析、航迹研判、航线规划和海洋环境查询。

典型问题包括：

• “查询这条船的最新位置、航速、目的港和周边船舶。”
• “分析某船最近 7 天的轨迹、靠港记录和异常接近事件。”
• “查询上海港当前靠泊、锚泊及未来 24 小时预计到港船舶。”
• “规划宁波港到新加坡港的参考航线，并检查沿途天气、台风和潮汐。”

配置 API Key

SkillHub 安装 Skill 不会附带 ShipXY 凭证。调用前必须让用户配置自己账号的 SHIPXY_API_KEY。先登录 ShipXY API 控制台，进入“应用管理”创建或选择应用并创建 API Key，再到“权限查看”确认已开通的接口、区域、历史范围和额度。

按以下顺序推荐配置方式。

方式一：让 WorkBuddy 配置（推荐）

将占位符替换为自己的 Key，然后向 WorkBuddy 发送：

请帮我配置 ShipXY Skill，我的 API Key 是 <粘贴你的 ShipXY API Key>。请自动识别当前系统，将它写入 WorkBuddy 用户配置文件的 env.SHIPXY_API_KEY，保留原有配置，不要在回复或日志中回显完整 Key。完成后提醒我重启 WorkBuddy，并在重启后运行 auth-check。

方式二：配置到 WorkBuddy env

在 WorkBuddy 用户配置文件顶层加入 env：

• macOS/Linux：~/.workbuddy/settings.json
• Windows：%USERPROFILE%.workbuddysettings.json

{
  "env": {
    "SHIPXY_API_KEY": "<你的 ShipXY API Key>"
  }
}

保留文件中原有配置，不要用以上片段覆盖整个文件。保存后完全退出并重新打开 WorkBuddy。

方式三：配置系统环境变量

• macOS：在 ~/.zshrc 中加入 export SHIPXY_API_KEY="<你的 ShipXY API Key>"。
• Linux：在 ~/.bashrc 中加入 export SHIPXY_API_KEY="<你的 ShipXY API Key>"。
• Windows：搜索并打开“编辑系统环境变量” → “环境变量” → 在“用户变量”中新建 SHIPXY_API_KEY，填写 Key 后保存。

配置后完全重启运行 Skill 的 Agent。

验证配置

在运行 Skill 的同一 Agent/进程中执行：

python3 "$SHIPXY_SKILL_DIR/scripts/shipxy.py" auth-check

configured: true 只表示当前进程能读取环境变量，不代表 Key 远程有效，也不代表所有付费接口均已开通。首次真实调用才会验证 Key、具体服务、区域、历史深度和额度。

需要轮换或排错时，读取 [references/authentication.md](references/authentication.md)。不得打印、记录或通过命令行参数传递 Key。

准备运行

1. 将包含本文件的目录解析为 SHIPXY_SKILL_DIR。
2. 使用 Python 3.10 或更高版本；CLI 仅依赖标准库。
3. 先检查认证，再查看工具：

python3 "$SHIPXY_SKILL_DIR/scripts/shipxy.py" auth-check
python3 "$SHIPXY_SKILL_DIR/scripts/shipxy.py" list
python3 "$SHIPXY_SKILL_DIR/scripts/shipxy.py" describe shipxy_search_ship

选择并检查工具

当两个以上服务都可能回答问题时，读取 [references/intent-routing.md](references/intent-routing.md)。需要完整能力表和标识符说明时，读取 [references/tool-index.md](references/tool-index.md)。

每项工具在本次任务中首次调用前，必须先执行 describe <tool>，并检查：

• use_when 与 do_not_use_when：确认选型；
• prerequisites 与 limits：准备输入并检查边界；
• output_summary 与 response_guidance：理解返回值；
• access 与 source_url：解释已验证的权限或套餐限制。

核心路由规则：

• 已有可信 MMSI 时跳过 search_ship；身份不明确时先搜索并消歧。
• 港名必须先用 search_port 获取五位码，不得猜测港口代码。
• 潮汐站 ID 与普通港口五位码必须分开处理。
• get_area_ship 只查询当前区域快照，不得用于历史区域船舶发现。
• 临时 MMSI 清单使用 get_many_ship；ShipXY 控制台固定船队使用 get_fleet_ship。
• 点天气、海区天气、全球网格天气和潮汐必须按各自的空间产品选择。

多步骤请求读取 [references/workflows.md](references/workflows.md)。

不消耗额度地校验

对不熟悉、大范围、空间或历史查询，先执行 --dry-run：

python3 "$SHIPXY_SKILL_DIR/scripts/shipxy.py" call shipxy_get_ship_track 
  --param mmsi=413000000 
  --param start_time=2026-07-19T00:00:00Z 
  --param end_time=2026-07-20T00:00:00Z 
  --dry-run

结构化输入使用 --params-json，生成或批量参数使用 --params-file。同一字段不得通过多种方式重复传入。

调用服务

python3 "$SHIPXY_SKILL_DIR/scripts/shipxy.py" call shipxy_search_ship 
  --param keywords='EVER GIVEN' 
  --param max_results=10

python3 "$SHIPXY_SKILL_DIR/scripts/shipxy.py" call shipxy_get_single_ship 
  --param mmsi=353136000

大结果使用 --output /tmp/<name>.json。超过 50 KB 的响应会自动写入 /tmp/shipxy-results/；读取返回的 result_path，不要把完整响应复制进对话。

成功包包含 returns、object_refs、response_guidance 和 data。涉及数据新鲜度、分页、哨兵值、时区、靠港推断、天气、台风或潮汐时，读取 [references/return-semantics.md](references/return-semantics.md)。

处理边界

• 轨迹、接近事件、到港清单和靠港接口使用 Unix 秒或带明确时区的 ISO 8601。
• history_weather 使用 yyyy-MM-dd HH:mm:ss；get_nav_warning 使用 yyyy-MM-dd HH:mm；潮汐数据使用 yyyy-MM-dd。
• search_ship_approach 单次不超过 31 天。
• get_port_of_call_by_port 单次不超过 7 天；30 天以内拆成连续窗口并去重，更长时间的完整性取决于购买的历史深度。
• 区域多边形使用 lng,lat-lng,lat-...，至少三个有序点；建议单次接近 1° × 1°，并根据 continue/scode 查询到结束。
• 航线结果仅用于规划参考，不得作为导航指令、安全许可或避碰建议。

处理权限与错误

读取 [references/access-and-errors.md](references/access-and-errors.md)，遵循结构化的 error.type、fix、commercial_action 和 details.access：

• missing_api_key：立即给出本文件“配置 API Key”的完整步骤，不要只说“请配置环境变量”。
• invalid_api_key：提示检查有效期、撤销状态和来源绑定。
• service_not_enabled：只有此时或 ShipXY 明确返回同义信息时，才建议购买具体服务。
• region_out_of_scope、history_depth_exceeded、quota_exhausted：只建议对应的区域、历史范围或额度升级。
• invalid_request、not_found、空结果、network_error 或 timeout：不得建议购买。
• 瞬时网络错误最多重试一次；权限失败不得原参数重复调用。

汇报结果

报告查询标识、观测/事件/预报时间和时区、原始单位、数据新鲜度、关键哨兵值、分页状态与相关权限边界。区分 AIS 上报值、观测数据、推断行为和预测结果。身份仍不明确时，先展示 MMSI、IMO、船名、呼号和更新时间的差异。

实时位置、船队成员、详细轨迹和港口活动可能敏感。只返回用户请求所需的字段，不向第三方发布原始响应。