opencli-plugin-shipxy

船讯网 (www.shipxy.com) 船舶查询 CLI 插件，基于 @jackwener/opencli。

支持通过船名、IMO、MMSI 或呼号批量查询船舶参数（船长/船宽/吃水/类型）与实时 AIS 位置（经纬度/航速/航向/目的地/更新时间）。

命令一览

命令	是否需登录	用途
opencli shipxy search --kw "…"	否	关键字搜索 → MMSI/IMO/船名候选列表
opencli shipxy info --mmsi "…"	是	完整船舶参数 + 实时位置
opencli shipxy position --mmsi "…"	是	实时位置子集（脚本友好）

安装

# 前置：opencli CLI + Chrome extension（首次用需 Chrome 里 Load Unpacked 装扩展）
opencli plugin install /path/to/opencli-plugin-shipxy
opencli doctor        # 应看到 Extension: connected

登录

info / position 命令依赖 shipxy 的登录态，请先在 opencli 桥接的 Chrome 里手动打开 https://www.shipxy.com/ 完成登录，token cookie 会自动被复用。未登录时命令会抛出 AuthRequiredError 并给出提示。

例子

# 1. 搜索：船名/MMSI/呼号都吃
opencli shipxy search --kw "COSCO12,MAERSK,9525338" --limit 5

# 2. 完整信息（船参数 + 位置）
opencli shipxy info --mmsi 413543265
opencli shipxy info --mmsi "413543265,574952645" --format json

# 3. 只要位置，输出 CSV
opencli shipxy position --mmsi 413543265 --format csv
opencli shipxy position --kw "COSCO12,MSC" --format csv

管道场景：先 search 拿 MMSI 再 info 补齐参数：

opencli shipxy search --kw "MAERSK ESSEX" --limit 3 --format json \
  | jq -r '.[] | select(.mmsi != "") | .mmsi' \
  | tr '\n' ',' \
  | xargs -I {} opencli shipxy info --mmsi {}

输出字段（info）

字段	含义
mmsi	9 位海事移动业务标识
imo	IMO 号（无则为空）
name / cnname	英文名 / 中文名
callsign	呼号
type / typeLabel	AIS 船舶类型代码 + 中文标签
length_m / width_m / draught_m	船长 / 船宽 / 吃水（米）
lon / lat	经纬度（十进制度）
sog_kn	对地航速（节）
cog_deg / hdg_deg	对地航向 / 船首向（度）。511 是 AIS 里"未知"的哨兵值
navistatus	航行状态码（0=在航, 1=锚泊, 5=系泊, 255=未知...）
dest / eta	目的港 / 预到时间（AIS 由船员手工输入，可能过时）
lastPositionUtc	最近一次位置更新时间（UTC）

技术设计

• search 走 PUBLIC：GET searchv4.shipxy.com/index.ashx?f=srch&kw=...，无需登录，返回 {status,ship:[{m,n,i,c,t}],port:[]}。这是唯一能免登录联通船名 → MMSI 的入口。
• info / position 走 INTERCEPT + browser=true：POST www.shipxy.com/ship/GetShipm body 只是 mmsi=xxx，但服务端要 header s(签名) + t(unix 秒)。签名逻辑封装在页面 JS window.R0VOQ1NJR04(data) 里（Base64 = "GENCSIGN"），jQuery 全局 beforeSend → setHeaders(xhr, o) 会自动注入。所以我们不自己算签名，而是 page.evaluate 里用 window.jQuery.ajax 发请求，签名 + HttpOnly token cookie 全部由页面自身处理。
• 规避 401 的关键：goto https://www.shipxy.com/ship/{mmsi} 会返回 {"status":401,"msg":"未授权"}（该路径就是 API 端点）。必须留在主页 https://www.shipxy.com/ 里 evaluate。ensureShipxyReady 会检测 window.jQuery + window.R0VOQ1NJR04 + token cookie 三者齐全再放行。
• 数值单位换算：API 返回的整数是放大过的：length/width /10 = 米、draught /1000 = 米、lon/lat /1e6 = 度、sog /1000 = 节、cog/hdg /100 = 度。已在 normalizeShipm 里统一。

局限 & 已知坑

• shipxy 搜索接口 f=srch 只识别船名/MMSI，输入 IMO 号不一定命中；如需按 IMO 查，请先手动查到 MMSI 或走 f=auto（页面自身也是这么做的，未来可以扩展）。
• 部分船的 AIS 数据不完整时，hdg 会是 511、cog 是 3600 之类的哨兵值——这些是数据源问题，本工具不做二次修正。
• GetShipm 一次只查一个 MMSI，批量在客户端 for-loop，规模大时耗时线性增长（每个约 200-500ms）。
• 详情页面里其他信息（船东/建造年/吨位/历史轨迹）需要另一个接口 POST /ship/GetIHSData，本插件暂未纳入，可作 v0.2 扩展。

License

MIT