在线体验 · 怎么用 · 架构 · 评测 · 文档 · English

VoyageGuard · 出行气象决策 Agent

订了船票机票，遇上大风天，到底还走不走？

把实时气象数据和官方发布的预警、禁航标准自动比对，告诉你今天有没有越过某条官方的线，
每一条都点名出处；证据不够时明说「证据不足」，不硬给结论。飞机与船只两种场景，中英双语。

_{线上真实结果（舟山 → 嵊泗，船只）：左栏是结论和 4 条带出处的触发项（含航线中点），右栏是备选建议和真实执行轨迹}

目录

• 怎么用
• 它解决什么问题
• 需求分析：先划清能说什么
• 架构
• 技术构成
• 关键设计决策
• 评测 · 结果
• 已知边界
• 快速上手
• 详细文档
• 同作者的其他项目

怎么用

打开 voyageguard-two.vercel.app，不用登录：

几个值得试的输入：

右上角可以切中英文（只在填表页），也可以回到本仓库。

它解决什么问题

大风天要不要出发，普通人现在只能自己拼凑答案，而三个渠道各差一块：

缺的是中间那一层：把气象数字翻译成「有没有越过官方的线」。
这一层不难做，难的是做得住——它是安全相关的，说错话的代价不对称：该提醒时没提醒，比多提醒一次严重得多。

需求分析：先划清能说什么

做之前先查了一个关键问题：「这条船会不会停航」，我有资格回答吗？

答案是没有。交通运输部对人大建议的答复函
写得很清楚：船舶抗风能力按风压计算，与蒲福风级不是对应关系，所以官方故意不在船舶证书上标注抗风等级。
真实的决策链是：每条船有自己的稳性限制 → 船公司判断 → 海事部门可下令 → 地方另有一刀切规定。

所以这个产品只说一件事：今天有没有越过某条官方发布预警或禁航的线。 至于会不会停航，那是承运人和主管部门的决定。

这一条判断直接决定了三个设计：

第三条最能看出区别——「证据不足」不是一句免责声明，而是一种和其他三种结论完全不同的输出：

_{北京 → 西安 选船只：没有风险等级、没有「建议出行」徽章；轨迹里的 abstention_gate 说明模型这一次根本没被调用}

判断「什么该用 AI 做、什么不该」，是这个项目最核心的产品决策。

架构

flowchart TD
    A["用户输入<br/>出发地 · 目的地 · 日期 · 交通方式"] --> B

    subgraph S1["① 确定性证据管线 —— 不经模型"]
        B["解析坐标<br/>白名单 → 名字校验 → 海域回验"] --> C["抓取必需证据<br/>风速 / 阵风 / 能见度 / 有效浪高"]
        C --> D{"证据够不够？"}
    end

    D -->|不够| G
    D -->|够| E

    subgraph S2["② 模型 —— 负责解释，不负责判定"]
        E["ReAct 循环<br/>可自行补查预警、第三地天气<br/>产出通俗解释与备选建议"]
    end

    E --> G

    subgraph S3["③ 规则引擎 verifier —— 持有最终判定权"]
        G["证据不足 → UNKNOWN<br/>越过红线但模型判低了 → 强制升级<br/>模型判高但指标不支持 → 降级"]
    end

    G --> H["结论 + 带出处的触发项 + 真实执行轨迹"]

    style S1 fill:#0d2b33,stroke:#00c8e8,color:#e8edf5
    style S2 fill:#2b2416,stroke:#f0b429,color:#e8edf5
    style S3 fill:#0d2b1c,stroke:#00e676,color:#e8edf5

核心原则：安全关键证据的获取和红线判定，都不取决于模型的自由裁量。
三段的职责边界写死在代码里，不靠 prompt 约束。详细设计见 docs/architecture.md。

技术构成

有什么写什么，一条都不硬凑。 下面每一条都能指到具体代码。

加粗的四条是真正的重点，其余是标配。「证据预取与结构化注入」刻意不叫 Context Engineering——
业界那个词指 Memory / Compaction / 上下文窗口管理，这个项目一样都没有。

故意没做的，和为什么

这个项目对「什么该用 AI」的回答是：在安全关键的判定上，尽量少用。

关键设计决策

1. 必需证据不交给模型去取。 模型可以自己调工具，但风速、能见度、浪高这些必需数据在调模型之前就已经取好了。
依据是 AgentAbstain（arXiv 2607.10059）：最强模型在成对弃权任务上只有 59.5% 准确率，
而且弃权能力与通用任务能力基本无关——换个更强的模型解决不了。这个结论在本项目的评测里复现了。

2. 判定权在规则引擎，不在模型。 规则引擎站在模型循环之外，做三件事：证据不足直接 UNKNOWN；
越过硬红线但模型判低了就强制升级；模型判 HIGH 但结构化指标不支持就降级。
走了哪条路径通过 decision_source 字段透出，用户看得见。

3. 拦住「前提不成立」的查询。 比判错等级更危险的是在一个根本不成立的前提上给出自信的结论。
航空侧有机场白名单——判据只要风速和能见度，而任何地名都能查到这两样，没有白名单，「上海 → 南极」会返回「低风险，建议出行」。
地名解析有两道关——Geocoding 是模糊匹配，搜 Xian 返回的是 Xián(西班牙) / Xianning / 咸阳 / 珠海市，里面没有西安，
所以候选地名必须先和输入对得上，再经海域回验。

4. 覆盖率本身就是产品质量。 38 个机场有官方 METAR/TAF，其余没有。但不是「没有官方数据就拒绝回答」——
拆开看航空判据，只有能见度那条真的需要跑道观测，大风预警本来就是对区域发布的，城市地面风正是它的输入。
所以数据源是分级的：官方优先，取不到就回落，并在结果里标明这次用的是哪一种。

评测

当产品功能做，不是当测试做。

• L1 把工具全 mock 掉，能干净地隔离推理能力，代价是把数据管线的洞藏起来——mock 数据总是「正好」符合解析逻辑。
  L3 用零 token 补上这一层，不需要 API Key 就能跑
• 数据管线的错误有「取到 / 取不到」这种客观状态，测试抓得到；知识库的错误是静默的——阈值写错一个数字，
  所有测试照样全绿，因为期望值就是照着那个阈值标的。L4 用真实世界的结果回验阈值，是唯一能发现「阈值本身有缺口」的层
• L4 的标签不需要专家判断——「那天实际停没停航」是官方与媒体已公布的客观事实

完整设计与断言清单见 docs/evaluation.md。

结果

评测脚本只打印到终端、不存档，下面的数字都可以用快速上手里的命令重跑复现。
L1 数字来自 2026-09-01 的一次运行；L4 零 LLM，2026-09-26 重跑结果逐项一致。

L4：把阈值放到 25 条真实停航 / 通航记录上验（风用 ERA5 历史存档、浪高用 Open-Meteo Marine 历史数据重建当天风浪）

• 误报率 0%（10 个正常通航日一次都没判 HIGH）——从没在服务正常运行的日子里喊过狼来了
• 召回率的缺口反而是最有价值的产出：9 条漏判里 7 条是台风相关，定位出缺了「台风预警」这一整条轴——
  承运人依据台风预警提前停运，那是独立于风力 / 浪高的另一套官方信号。这个缺口选择记录下来，而不是补一个拍脑袋的阈值

L1：四家模型横评

裸判从 56.4% 到 89.7%，安全网之后全部 100%。判据越细，模型越容易在某一档上滑一格，
确定性 verifier 的价值也就越大——它把一个 56% 的模型和一个 90% 的模型拉到了同一条线上。

最值得说的一个数字：87.5%。 6 条证据有洞的用例，system prompt 明确写了「宁可说不知道，不要猜」，
证据 JSON 里那些字段明明白白是 null。四家模型合计 24 次弃权机会，错过 21 次，而且 21 次全部判 LOW。
deepseek 全部 4 条错误、kimi 全部 5 条错误都是弃权用例——在有数据的 33 条上它们一条不错。
这 24 次最终全部正确，因为弃权判定压根没交给模型。

已知边界

一个安全相关的工具，说清楚自己判不了什么同等重要：

• 台风预警没有建模 —— L4 定位出的最大缺口，选择记录而不是补一个无来源阈值
• 内河与湖泊航线不覆盖 —— 内河另有一套官方标准，判据是风力分档且不含浪高，与海事判据不通用
• 不核实航线是否存在 —— 只校验两端各自是真实港口 / 机场，不校验两地之间真的通航
• 三条 PROD 规则不是法规 —— 小船遇海浪蓝色预警、航空 15 m/s、航空雷暴，已单独标出并附理由
• 两条来源是二手转述（一条新闻、一条厂商手册值）—— 找不到原文的如实标注，而不是假装是官方
• ERA5 是再分析不是预报 —— L4 验证的是「阈值对不对」，不是「预报够不够用」

完整版见 docs/limitations.md。

快速上手

pip install -r requirements.txt
echo "DASHSCOPE_API_KEY=your_key_here" > .env
uvicorn app:app --reload          # 打开 http://localhost:8000

支持四家模型，VOYAGEGUARD_PROVIDER 切换（qwen / deepseek / kimi / glm），每家的 model id 可用
VOYAGEGUARD_MODEL_<PROVIDER> 覆盖，都不用改代码。

不用信 README 里的数字，自己跑：

python -m evals.l3_sufficiency    # 约 2 分钟，零 token，不需要任何 API Key，187 条确定性断言
python -m evals.run_all           # L3 → L2（真实网络 + 真实模型，含 3 组故障注入）→ L4（真实记录回验）

部署：Vercel 的 Python framework preset 自动识别项目根 app.py 里的顶层 app 作为 ASGI 入口，不需要 api/ 目录。
推 GitHub 即自动部署，环境变量配在 Vercel 项目设置里。Dockerfile 保留给自托管场景（端口 7860）。

技术栈：FastAPI · OpenAI 兼容 SDK（Qwen / DeepSeek / Kimi / GLM）· aviationweather.gov（METAR / TAF / SIGMET）·
wttr.in · Open-Meteo Marine / Geocoding / ERA5 · DDGS · 纯单文件前端（无构建步骤）· Vercel

详细文档

同作者的其他项目

三个项目按任务选形态：单轮决策用被围起来的 Agent，多视角批判用多 Agent 工作流，每天固定跑的流程用定时工作流。

作者

夏文博（Wenbo Xia）· AI 产品经理 · MIT License