前言¶
做航运、港口、物流或海事风控的同事，常见需求是查一条船的实时 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 海事数据服务：
| 方向 | 能力 |
|---|---|
| 船舶搜索与识别 | 按 MMSI、IMO、船名或呼号搜索，处理同名船 |
| 实时 AIS | 单船/多船最新船位、航速、航向、状态；目标船周边约 10 海里船舶 |
| 区域与船队 | 多边形内当前船舶；ShipXY 控制台固定船队 |
| 船籍与档案 | 船籍、船旗、Lloyd’s 船舶档案 |
| 历史与事件 | 历史 AIS 轨迹、船舶接近事件、挂靠状态、靠港记录 |
| 港口与 ETA | 港口五位码搜索、靠泊/锚泊/预计到港、港口历史活动；单船精准 ETA |
| 航线 | 港到港或坐标到港口的参考航线（规划参考，非导航指令） |
| 海洋环境与安全 | 海洋气象、海区天气、全球台风、国内外潮汐、中国海事局航行警告 |
用户提到 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
