租赁-货找船

SKILL.md

---
name: find-vessel-for-cargo
description: 为货主按装货港、卸货港、货名、货量和预计装货日期查找内贸或外贸空船。用于“货找船”“找空船”“某港有什么船”“我的货什么时候能装”等场景；从航运在线空船数据源获取列表和详情，按贸易类型、空船港距离、载重吨及时间窗口筛选，并在完整查询后记录货主需求。
---

# 租赁-货找船

为 ShippingClaw/OpenClaw 执行货主找船工作流。调用脚本获取真实数据，不要猜测船舶、港口坐标、距离、日期或联系方式。

## 必需输入

收集以下五项后立即查询：

- 装货港：港口名称或 UN/LOCODE。
- 卸货港：港口名称或 UN/LOCODE。
- 货物名称。
- 货量：正数，单位为吨。
- 预计装货日期。

不要追问船型、舱容、最低装载率或最大吨位差。货名和卸货港不参与船舶适配筛选；卸货港仅用于判断内外贸、展示和需求入库。

## 查询工作流

调用：

```bash
python scripts/find_vessel.py search \
  --load-port "<装货港>" \
  --discharge-port "<卸货港>" \
  --cargo-name "<货名>" \
  --cargo-tons <吨位> \
  --loading-date "<YYYY-MM-DD>" \
  --user-id "<当前登录货主用户ID>"
```

测试阶段用户 ID 为空时添加 `--skip-demand-sync`，正常返回查询结果但不入库。

默认展示前10条。逐条展示可点击编号、公司、船名、船型、船舶载重吨、货量、空船港、空船日期、更新日期、空船港至装货港距离及时间差：

- 将编号渲染为 `[编号](detail_url)`。
- 支持结构化交互时，把整条记录或“查看详情”按钮绑定到 `detail_action`。
- 仅展示脚本返回的结果。
- `manual_confirmation_fields` 非空时，明确标注对应的载重吨、空船港或空船日期“需人工确认”。

## 匹配规则

- 两端都在中国大陆为内贸；任一端为境外或港澳台为外贸。
- 内贸空船港至装货港不超过150海里；外贸不超过300海里。
- 卸货港不与空船描述中的航向比较。
- 船舶可解析的最大载重吨不小于货量即可保留，不设最大吨位差和最低装载率。
- 空船日期在预计装货日期前7天至后15天之间（包含边界）即可保留。
- 缺年份的空船日期按距离预计装货日期最近的合理年份解析。
- 载重吨、空船港或空船日期无法可靠解析时保留，并标记人工确认。
- 排序依次为：可确认字段优先、港口距离升序、日期差绝对值升序、富余载重吨升序；人工确认记录排后。

## 详情工作流

搜索结果返回 `solid`、`detail_url` 和 `detail_action`。点击后只打开站内详情：

```bash
python scripts/find_vessel.py detail --solid "<solid>"
```

展示业务详情和公开可见个人联系方式，不返回原始网站链接。付费、遮罩或登录后可见的数据按空值处理；不得登录、支付、绕过限制或推断联系方式。

列表和详情缓存12小时。部署时设置 `VESSEL_MATCHER_PUBLIC_URL` 为用户浏览器可访问的服务地址；本机默认使用 `http://127.0.0.1:8766`。

## 运行服务

安装 `requirements.txt` 后启动：

```bash
uvicorn scripts.service:app --host 0.0.0.0 --port 8766
```

接口为 `GET /health`、`POST /search`、`GET /vessel/{solid}`（JSON）和 `GET /vessel/{solid}/view`（站内详情页）。后台接口接入说明见 [references/backend-api.md](references/backend-api.md)。