前言¶

做航运、港口、物流或海事风控的同事，常见需求是查一条船的实时 AIS、靠港记录、区域船位，或顺带看气象、台风和航行警告。若自己拼 HTTP、对照 33 类接口文档和参数格式，Agent 对话里很难稳定复现。ShipXY 船讯网海事 API 是 SkillHub 上的企业级 Skill，把 ShipXY v3 能力封装成目录驱动的 CLI，让 Cursor、WorkBuddy 等 Agent 按语义选服务、校验参数后再调用。

这是什么¶

ShipXY 船讯网海事 API（坐标 @org-988us9gb/shipxy-skill，当前版本 1.0.2）由 亿海蓝 发布，来源标注为 enterprise，分类为 professional。它整合 ShipXY 船讯网海事数据，通过内置 scripts/shipxy.py 调用官方 API，而不是在对话里手工拼接请求。

SkillHub 页面显示：评分 100000，下载 1199 次；标签标明 requires_api_key=true，需使用你自己在 ShipXY 控制台申请的 Key。

核心功能¶

以下能力与 SkillHub 简介及 Skill 内 SKILL.md 一致，覆盖 33 项 ShipXY 海事数据服务：

用户提到 ShipXY、船讯网、MMSI、IMO、AIS、靠港记录、船舶轨迹或港口五位码时，Agent 应按 Skill 路由规则选用对应工具（如已有可信 MMSI 可跳过搜索；港名须先 search_port 再传五位码）。

安装与启用¶

安装 SkillHub CLI（未安装时）¶

command -v skillhub && skillhub --version

未安装时可执行完整安装（CLI + 默认 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

仅 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安装本 Skill¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被识别。SkillHub 官方安装说明见 skillhub.cn/install/skillhub.md。

skillhub install shipxy-skill --namespace org-988us9gb --dir <你的 Agent skills 目录>

常见路径示例（以 SkillHub 文档为准）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/
• WorkBuddy：~/.workbuddy/skills/

SkillHub 页面亦提示：让 AI 根据上述安装文档安装 @org-988us9gb/shipxy-skill。

配置 SHIPXY_API_KEY¶

Skill 安装包不包含 ShipXY 凭证。调用前在 ShipXY API 控制台 创建应用与 API Key，并在「权限查看」中确认已开通的接口、区域、历史范围与额度。

环境变量名固定为 SHIPXY_API_KEY。可选方式包括：WorkBuddy 用户配置 ~/.workbuddy/settings.json 的 env.SHIPXY_API_KEY、或在 Linux 的 ~/.bashrc 中 export SHIPXY_API_KEY="..." 等。配置后需完全重启运行 Skill 的 Agent。

将 Skill 目录设为 SHIPXY_SKILL_DIR 后，本地检查是否读到 Key（不连远程、不耗额度）：

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

configured: true 只表示进程能读取变量；Key 是否有效、某服务是否开通，需首次真实调用才会由 ShipXY 返回。

运行环境要求 Python 3.10+；CLI 仅依赖标准库。

典型用法¶

下面步骤来自 Skill 自带的 SKILL.md，可在安装目录内直接复现。

1、准备与列工具

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

首次使用某工具前应先 describe <tool>，核对 use_when、limits 与权限说明。

2、大范围或历史查询先 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

3、搜索船舶并查单船位置

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，避免把完整 JSON 贴进对话。

在 Agent 里，也可用自然语言描述任务（例如查最新船位与周边船、某港靠泊与 ETA、规划参考航线并查沿途天气），由 Skill 按 references/intent-routing.md 与 references/workflows.md 组合多步调用。

适用场景与注意¶

适合谁：需要在对话或自动化里查 ShipXY 数据的开发、运营、分析人员；已具备 ShipXY API 账号与相应套餐权限的团队。

限制与坑：

• 不得通过 --param 传入 API Key；不得使用文档中的示例 Key。
• 权限类错误（service_not_enabled、region_out_of_scope、quota_exhausted 等）应按 Skill 指引说明套餐边界，勿对空结果或参数错误建议购买。
• 时间格式因接口而异（轨迹用 Unix 秒或带时区 ISO 8601；部分气象/警告/潮汐有固定格式）；search_ship_approach 单次不超过 31 天；按港口查靠港单次窗口不超过 7 天等，见 SKILL.md「处理边界」。
• 区域查询 get_area_ship 是当前快照，不能当历史区域发现；航线结果为规划参考，不能作为避碰或航行许可。
• 实时船位、轨迹、港口活动可能敏感，只返回任务所需字段。

结尾¶

ShipXY 船讯网海事 API 把船讯网 v3 的搜索、监控、档案、轨迹、港口、ETA、航线与环境类接口收敛成一套可校验的 CLI 工作流，适合挂在支持 Skill 的 Agent 上做海事问答与脚本化查询。安装与元数据以 SkillHub 为准：

• API 入口：https://api.skillhub.cn/org-988us9gb/shipxy-skill
• 技能页：https://www.skillhub.cn/skills/org-988us9gb/shipxy-skill