租赁-货找船

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

必需输入

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

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

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

查询工作流

调用：

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。点击后只打开站内详情：

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

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

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

运行服务

安装 requirements.txt 后启动：

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。