内容
<div align="center">
<img src="docs/logo.svg" width="110" alt="交通侦察 logo">
<h1>交通侦察</h1>
<p><b>加利福尼亚道路的实时地图、路线规划和 AI 助手。<br>
同时也是一个 MCP 服务器，您的助手也可以使用。</b></p>
[](https://github.com/nicglazkov/commutescout/actions/workflows/ci.yml)
[](https://github.com/nicglazkov/commutescout/releases)
[](EVALS.md)
[](LICENSE)
[](pyproject.toml)
<p>
<a href="#在线应用">在线应用</a> ·
<a href="#添加到克劳德">添加到克劳德</a> ·
<a href="#自我托管">自我托管</a> ·
<a href="#数据来源">数据来源</a> ·
<a href="#工具">工具</a> ·
<a href="#评估">评估</a>
</p>
<p>
<a href="https://commutescout.com">
<img src="docs/try-demo-button.svg" width="230" alt="试用在线演示">
</a>
</p>
<p>
无需安装，无需账户：
<a href="https://commutescout.com"><b>commutescout.com</b></a>
</p>
<a href="https://commutescout.com">
<img src="docs/demo.gif" width="880"
alt="演示：自动补全旧金山和洛杉矶，规划带有两个交通色选项（Bayshore 和 Nimitz）的路线，切换它们，点击建议的问题获取实时 AI 答案，然后闪烁全州实时交通叠加层">
</a>
</div>
这最初是一个 MCP 服务器，提供给 AI 助手加利福尼亚道路的实时数据。在它的周围增加了一个 Web 应用。该地图显示了 CHP 和 Caltrans 馈送的内容，您可以规划路线并打印方向，如果您想用普通英语询问驾驶情况，还有一个助手。
我托管了一个任何人都可以使用的副本。如果您想运行自己的，请参见[自我托管](#自我托管)。
## 在线应用
**[commutescout.com](https://commutescout.com)**
它包含的内容：
- 地图，带有每个图层的过滤面板：事件类型、关闭类别、链式控制、气象站、火灾及其燃烧足迹、大约 3300 个摄像头（有一个复选框仅限实时视频），以及当前显示内容的讯息标志。点击摄像头获取实时验证的快照。标志弹窗逐字引用标志内容。
- 路线规划器。地址在您输入时自动补全，“出发”字段有一个使用我的位置的选项，模糊名称会询问您要哪个。您会获得逐步指示（隐藏在下拉菜单中）、沿途发生的一切以及打印或导出为 .txt。
- 助手。规划路线后，会出现几个关于该驾驶的预制问题。点击一个，答案会根据相同的实时馈送流式传输，时间以您的时区为准。
- 监视区域（仅限邀请试用）。登录，绘制加利福尼亚州的圆形或多边形，当事件、关闭、链式控制或野火出现在其中时，获取推送通知。访问需要邀请码，而功能和码都是免费的。自我托管者可以获得所有功能（参见[deploy.md](docs/deploy.md)以获取额外的设置）。
<table>
<tr>
<td width="34%"><img src="docs/shots/planner.png" alt="路线规划器，带有两个路线选项、逐步指示和建议问题"><br><sub><b>规划行程。</b> 自动补全、路线选项、指示、打印或导出。</sub></td>
<td width="34%"><img src="docs/shots/answer.png" alt="关于驾驶的 AI 答案，带有实时速度和状况"><br><sub><b>询问它。</b> 点击建议问题；答案读取实时馈送。</sub></td>
<td width="32%"><img src="docs/shots/map.png" alt="全州地图，带有每层过滤器和实时计数"><br><sub><b>或者只是查看。</b> 每个图层都可切换，从完全关闭到空白标志。</sub></td>
</tr>
</table>
关于托管的警告：这是在小个人预算上运行的。AI 答案有每日上限，服务扩展到零，因此当天的第一次加载可能需要几秒钟，并且没有正常运行时间保证。这是一个投资组合项目，而不是实用程序。
## 添加到克劳德
这使用我的托管服务器，因此适用相同的警告。使用此 URL 添加自定义连接器：
```
https://ca-roads-mcp-15002631928.us-west1.run.app/mcp
```
## 自我托管
这里的所有内容都使用 MIT 许可，并且在没有帐户或密钥的情况下运行。可选的交通速度和湾区馈送需要免费密钥。
在 stdio 上本地运行 MCP 服务器（这是克劳德桌面或克劳德代码的配置）：
```json
{
"mcpServers": {
"commutescout": {
"command": "uvx",
"args": ["--from", "git+https://github.com/nicglazkov/commutescout", "ca-roads-mcp"]
}
}
}
```
从检查点：`pip install .` 然后 `ca-roads-mcp` 用于 stdio，或 `ca-roads-mcp --transport http` 用于可流式传输的 HTTP，端口为 `$PORT`。Web 应用是 `pip install ".[demo]"` 然后 `ca-roads-demo`，环境中带有 `ANTHROPIC_API_KEY`。
要将您自己的副本放到 Cloud Run 上（足够小，可以适应大多数月份的免费层），[docs/deploy.md](docs/deploy.md) 具有确切的命令、环境变量和可选 API 密钥的位置。
## 数据来源
| 来源 | 数据 | 刷新 |
|--------|------|---------|
| **CHP 实时馈送** | 全州事件（碰撞、危险、关闭），由调度员记录，位置文本中解析出行方向 | 按需获取；馈送更新约 1 分钟 |
| **Caltrans LCS** | 物理上当前实施的车道和道路关闭（CHP 代码 1097），按对通过交通的影响分类 | 5 分钟缓存 |
| **Caltrans 链式控制** | 山区检查站的 R-1/R-2/R-3 要求 | 5 分钟缓存 |
| **WFIGS** | 活跃的野火（名称、大小、控制情况），在主要高速公路约 10 英里范围内标记；周边边缘细化大火的距离 | 5 分钟缓存 |
| **CAL FIRE** | CAL FIRE 自己的事件发布，合并到野火层中，用于 WFIGS 尚未列出的火灾 | 5 分钟缓存 |
| **Caltrans CMS** | 当前显示的变更信息标志（过滤空白标志） | 2 分钟缓存 |
| **Caltrans CCTV** | 路边摄像头快照，图像验证实时后返回 | 按查询 |
| **Caltrans RWIS** | 路面温度、阵风、能见度在山口 | 5 分钟缓存 |
| **NWS 警报** | 冬季风暴、风、洪水、雾和火天气警告沿路线 | 5 分钟缓存 |
| **USGS 地震** | 走廊附近 24 小时内的 M4.5+ 地震 | 5 分钟缓存 |
| **TomTom** （可选密钥） | 沿路线实际当前速度与自由流动速度 | 1 分钟缓存 |
| **511 SF Bay** （可选密钥） | 湾区交通事件 | 3 分钟缓存 |
| **内华达州交通局** （可选密钥） | I-80、US-50、I-15 在州界后的延伸 | 3 分钟缓存 |
每个关闭记录都带有从 Caltrans 设施和关闭类型派生的 `closure_class`。原始馈送将上坡维修标记为“完全”，而将其报告为关闭的高速公路是不正确的，因此类别将它们分开：
| closure_class | 含义 | 你可以开车通过吗？ |
|---|---|---|
| `full-roadway` | 道路本身在该方向关闭 | 否 |
| `one-way-traffic` | 带有旗帜的交替单车道 | 是的，有延迟 |
| `alternating-lanes` / `moving` / `traffic-break` | 滚动或短暂工作 | 是的，轻微延迟 |
| `lane` | 一些车道关闭（“2 of 4 车道关闭”） | 是的 |
| `ramp` | 一个坡道或连接器关闭，道路不受影响 | 是的 |
每个响应都带有每个来源的 `data_as_of` 时间戳和明确的注释，当馈送过时或失败时，以便助手可以判断信任程度。馈送失败从不沉默：提供最后的好数据，标记为过时，并附上错误。
## 工具
| 工具 | 它回答什么 |
|------|-----------------|
| `check_route(from_place, to_place)` | 主要走廊（17 个精选走廊：I-80 萨克拉门托-雷诺、US-50 到塔霍、I-5、US-101、SR-17、SR-99、SR-1、I-15 到拉斯维加斯、湾区高速公路、塔霍本地）沿线的活跃事件， 按路线顺序排列 |
| `check_region(region)` | 整个区域的一键式报告（湾区、南加州、 Sierra、中央谷地等 4 个）：精确计数、事件严重程度排序、完全关闭优先、有限列表，显示何时截断 |
| `get_incidents(highway?, area?, center?)` | 按路线、调度区域或点和半径获取实时 CHP 事件 |
| `get_lane_closures(route?, district?, center?)` | 当前实施的关闭，按上述表格分类 |
| `get_chain_controls(route?, center?)` | 当前链式要求；明确表示在淡季“无活动” |
| `get_wildfires(near_route?, center?)` | 具有大小、控制情况和映射周边边缘的活跃火灾，在主要高速公路附近标记 |
| `get_cameras(center?, route?)` | 路边摄像头快照，每个在返回前实时验证（离线占位符帧通过图像新鲜度过滤） |
| `get_road_signs(route?, center?)` | 当前显示的变更信息标志，原样 |
| `rank_routes(by?, limit?)` | 所有 17 个走廊按实时事件或测量拥堵排名，附带原因 - 回答“当前最繁忙的路线是什么” |
路线和区域报告还包含改变建议的上下文：沿途采样的天气警报、报告异常的路面气象站、最近的重大地震、沿途的标志和摄像头，当设置 TomTom 密钥时，还有实时速度。地名通过真正的地理编码器，并当街道存在于多个城镇时，询问而不是猜测。
## 评估
评估套件与服务器一起提供，并为每个版本提供关卡：
- **记录的固定装置**，适用于四种场景：一个 Sierra 风暴日（R-2 链条 Twin Bridges 至 Meyers，Emerald Bay 雪崩关闭）、一个火灾关闭日（I-5 在 Grapevine 两个方向关闭）、一个安静的夏季日和一个实际捕捉的来自实际火季节日的馈送，包括一个区的 500 错误。
- **91 个黄金问题**，带有基本事实，包括陷阱：预定但未建立的关闭、坡道关闭表述为“高速公路是否关闭”，数据无法回答的预测问题。
- **评分挂钩**，在固定装置模式下将 Claude 与工具结合使用，并评估事实匹配和 LLM 评委（claude-sonnet-4-6，从未评估模型），带有失败分类法和工具选择漂移指标。每次运行都追加到已提交的历史文件中，因此趋势是公开的。
当前记分卡：[EVALS.md](EVALS.md)。每次发布都重新运行评估，根据发布标签进行评估，并更新上方的徽章。
```sh
pip install -e ".[dev,evals]"
python evals/build_fixtures.py # 重新生成场景固定装置
python evals/run_evals.py # 需要 ANTHROPIC_API_KEY
```
## 工作原理
```mermaid
flowchart LR
subgraph feeds["13 个公共馈送"]
CHP["CHP 事件"]
CT["Caltrans：关闭、链条、<br/>标志、摄像头、路面天气"]
WF["WFIGS + CAL FIRE 火灾 + 周边"]
WX["NWS 警报 / USGS 地震"]
OPT["TomTom / 511 / NV DOT<br/>(可选密钥)"]
end
subgraph pkg["ca_roads（馈送层）"]
F["异步获取器<br/>TTL 缓存 + 过时服务<br/>解析器"]
D["跨源重复数据删除"]
end
subgraph srv["ca_roads_mcp"]
T["9 个 MCP 工具<br/>走廊 + 区域<br/>关闭分类法<br/>地理编码"]
end
CHP & CT & WF & WX & OPT --> F --> D --> T
T -->|"stdio / 流式 HTTP"| MCP["克劳德和 MCP 客户端"]
T -->|"进程内"| DEMO["Web 应用<br/>地图 + 规划器 + 助手"]
```
三个包，干净地分层：
- **`ca_roads`**：馈送层。无 MCP 依赖。异步 httpx 获取器、分区 TTL 缓存、馈送失败时的过时服务、解析器从截断的馈送中抢救完整记录（CHP 在繁忙时段将其 XML 记录截断），以及从这些馈送在生产中运行中学习到的规则，例如将缺少的区馈送视为空结果而不是错误。
- **`ca_roads_mcp`**：MCP 接口。快速 MCP 服务器、精选的走廊和区域表、路线名称规范化（“17”、“hwy 50”、“I80”都有效），以及为 LLM 消费者编写的文档字符串：数据是什么、其刷新节奏及其限制。
- **`ca_roads_demo`**：公共 Web 应用。独立的地图和路线规划器（视口驱动的数据 API、地址自动补全、通过 OSRM 和 Valhalla 备用进行转弯）、以及与工具循环中的 Claude 结合，流式传输 SSE 与地图几何图形，具有严格的成本上限（每 IP 速率限制、每日问题上限、每日美元预算）。
## 开发
```sh
python -m venv .venv && . .venv/bin/activate # 或 .venv\Scripts\activate
pip install -e ".[dev]"
pytest # 基于固定装置，无网络
ruff check .
```
在本地工作时使用 stdio 传输。HTTP 传输针对 Cloud Run 进行了优化：它绑定 0.0.0.0 并关闭主机头检查，因此如果必须在本地运行，请将其绑定到 localhost（`ca-roads-mcp --transport http --host 127.0.0.1`）。
文档：[部署](docs/deploy.md) · [添加数据源](docs/adding-a-source.md) · [注册提交](docs/registry.md)
## 免责声明
数据：CHP、Caltrans、WFIGS、CAL FIRE。不与任何机构关联。情况变化比任何馈送都快；在驾驶前请验证（511 或 [quickmap.dot.ca.gov](https://quickmap.dot.ca.gov)）。
服务器通过 Nominatim 和 Photon OpenStreetMap 地理编码器解析地名。Web 演示还加载 CARTO 的地图瓦片，并从公共 OSRM 和 Valhalla 路由器获取其路线预览，因此这些服务会看到涉及的坐标。字体和地图库在本地提供。
