0xchamin/skyintel

# 🚀 VoyageIntel **统一的实时空中、海上和太空追踪，集成AI查询和沉浸式3D地球仪。** [](https://pypi.org/project/voyageintel/) [](LICENSE) [](https://python.org)  ## 功能 - 🌍 **3D地球仪** — CesiumJS驱动的沉浸式深色地球仪，实时渲染飞行器、船舶和卫星 - ✈️ **飞行追踪** — 通过ADSB.lol全球数据流，实时追踪商业、私人及军用飞机 - 🚢 **船舶追踪** — 通过aisstream.io的WebSocket全球实时监控AIS船舶——涵盖货船、油轮、客船、军舰、渔船、游艇 - ⚔️ **军方监控** — 未经过滤的军用飞机数据流 + 海军舰船探测——不同于隐藏这些信息的商业追踪器（**仅供教育目的**，这些都是公开数据） - 🛰 **卫星追踪** — 6个类别（空间站、军用、气象、导航、科学、星链），通过Celestrak + SGP4获取 - 🚀 **国际空间站追踪** — 实时位置、船员信息、过境预测，一键追踪ISS - ⚓ **港口数据库** — 包含约400个全球港口的世界港口索引，支持空间查询 - 🌤 **天气** — 航空天气（Open-Meteo）+ 海洋天气（波浪、涌浪、海温，Marine API） - 🌍 **地理编码** — Google Maps地理编码，带SQLite缓存，用于AI驱动的位置解析 - 🤖 **MCP服务器** — 25+工具，基于FastMCP，支持可流式HTTP + stdio，适用于Claude Desktop / VS Code / Cursor - 💬 **自带密钥AI聊天** — 带上你自己的API密钥（Claude、OpenAI、Gemini）——密钥仅存储在浏览器中 - ⚡ **SSE流式传输** — 服务器发送事件，用于实时聊天响应及增量令牌渲染 - 🛡️ **安全防护** — 通过系统提示词加固 + 可选的LLM Guard扫描器实现分层聊天安全 - 📊 **演示仪表盘** — `/playground` — 系统健康状况、安全防护监控和LangFuse分析的统一视窗 - 🖥 **命令行界面** — 完整的命令套件，包括 `voyageintel ask`、`voyageintel vessels`、`voyageintel ports` - 📈 **LangFuse可观测性** — 可选的LLM追踪、令牌跟踪和延迟监控，支持仪表盘集成 ## 快速开始 ### 安装 ``` # 推荐用于 MCP 客户端集成（Claude Desktop、VS Code 等） pipx install voyageintel # 或在虚拟环境中安装 pip install voyageintel ``` 升级现有安装： ``` pipx upgrade voyageintel # 或 pip install --upgrade voyageintel ``` ### 验证 ``` voyageintel --version # Check installed version voyageintel --help # View all commands voyageintel status # Check configuration and system status ``` ### 运行 ``` voyageintel serve ``` 打开 [http://localhost:9097](http://localhost:9097) 查看3D地球仪，打开 [http://localhost:9097/playground](http://localhost:9097/playground) 查看可观测性仪表盘。 ### 配置 VoyageIntel 对于飞行和卫星追踪 **开箱即用，无需配置**。API密钥可解锁额外领域： | 功能 | 所需密钥 | 备注 | |------|----------|------| | 3D地球仪 + 飞行 + 卫星 | 无 | 立即可用 | | 船舶追踪 (AIS) | `VI_AISSTREAM_API_KEY` | 从 [aisstream.io](https://aisstream.io) 免费获取 (GitHub登录) | | 地形图层 | `VI_CESIUM_ION_TOKEN` | 从 [cesium.com](https://cesium.com/ion/) 免费获取 | | 地理编码 | `VI_GOOGLE_MAPS_API_KEY` | Google Cloud Console — Geocoding API | | Web端AI聊天 | 无（浏览器中自带密钥） | 在Web界面的⚙设置中设置你的密钥 | | CLI `voyageintel ask` | `VI_LLM_PROVIDER`, `VI_LLM_API_KEY`, `VI_LLM_MODEL` | 存储在 `.env` 文件中 | | LangFuse可观测性 | `VI_LANGFUSE_PUBLIC_KEY`, `VI_LANGFUSE_SECRET_KEY` | [langfuse.com](https://langfuse.com) 提供免费层 | 如需创建 `.env` 文件： ``` # 服务器 VI_HOST=0.0.0.0 VI_PORT=9097 # AIS 数据（船舶追踪所需） VI_AISSTREAM_API_KEY=your_key # AIS 性能 VI_AIS_BATCH_FLUSH_INTERVAL=1.0 VI_AIS_RECONNECT_DELAY=5 VI_VESSEL_PRUNE_HOURS=6 # Cesium Ion（可选 — 启用地形图层） VI_CESIUM_ION_TOKEN=your_token # Google Maps（可选 — 启用地理编码） VI_GOOGLE_MAPS_API_KEY=your_key # LLM — 用于 CLI 'ask' 命令（可选，网络聊天使用浏览器本地存储） VI_LLM_PROVIDER=anthropic # anthropic / openai / google VI_LLM_API_KEY=sk-ant-... VI_LLM_MODEL=claude-sonnet-4-20250514 # LangFuse（可选 — LLM 可观测性 + Playground 分析） VI_LANGFUSE_PUBLIC_KEY=pk-lf-... VI_LANGFUSE_SECRET_KEY=sk-lf-... VI_LANGFUSE_HOST=https://cloud.langfuse.com VI_LANGFUSE_OTEL_HOST=https://cloud.langfuse.com # Playground（可选的可观测性仪表板） VI_PLAYGROUND_ENABLED=true # default: true # 轮询间隔 VI_FLIGHT_POLL_INTERVAL=60 VI_SATELLITE_POLL_INTERVAL=3600 ``` ### 优雅降级 VoyageIntel 会使用任何可用的API密钥启动。缺少密钥会禁用相应领域——不会崩溃，不会显示错误屏幕。 | 提供的密钥 | 可用领域 | 备注 | |------------|----------|------| | 无 | 空中 + 太空 | 零配置，飞行 + 卫星 | | `VI_AISSTREAM_API_KEY` | 空中 + 海上 + 太空 | 启用完整海事追踪 | | `VI_GOOGLE_MAPS_API_KEY` | + 地理编码 | AI查询自动解析地名 | | `VI_CESIUM_ION_TOKEN` | + 3D地形 | 地球仪加载地形瓦片 | | 所有密钥 | 完整体验 | 所有领域 + 地理编码 + 地形 | ## 部署分支 VoyageIntel 使用 `voyageintel` 作为 **默认分支**。`railway` 分支包含原始的SkyIntel（仅飞行 + 卫星）。 | | `voyageintel` (默认) | `railway` | `railway-guardrails` | |---|---|---|---| | **使用场景** | 完整平台 — 空中 + 海上 + 太空 | 云演示 — 仅空中 + 太空（原始SkyIntel） | 云演示 + 增强聊天安全 | | **飞行数据** | ADSB.lol全球数据流 | ADSB.lol全球数据流 | ADSB.lol全球数据流 | | **船舶数据** | aisstream.io WebSocket | — | — | | **轮询策略** | ADSB.lol全局 + `/v2/mil` | ADSB.lol全局 + `/v2/mil` | ADSB.lol全局 + `/v2/mil` | | **安全防护** | 仅系统提示词 | 仅系统提示词 | 系统提示词 + LLM Guard | | **额外内存** | — | — | ~500MB（用于防护模型） | | **MCP工具** | 25+（空中 + 海上 + 太空） | 15（空中 + 太空） | 15（空中 + 太空） | ### ADSB.lol 覆盖范围 ADSB.lol 是一个 **众包网络**，由志愿者ADS-B数据提供者组成。在北美、欧洲和亚洲部分地区覆盖极佳，但在数据提供者较少的地区（如中国中部、非洲大部、俄罗斯中部）覆盖稀疏。这是志愿者数据提供者网络的数据可用性限制，无法在代码层面解决。 ### AIS 覆盖范围限制 VoyageIntel 目前仅使用 **地面AIS**，通过aisstream.io的岸基接收站网络接收。有效范围大约为 **离岸50-70海里**。远洋船舶 **不可见**，除非其进入沿海接收站范围内。 卫星AIS提供商（Spire, exactEarth, ORBCOMM）提供全球海洋覆盖，但 **目前未集成**。这是一个已知的限制——卫星AIS集成是未来开发的候选功能。 ## 架构概览 ``` graph TB subgraph External["☁️ External Data Sources"] ADSB[ADSB.lol
Flights · Military · Search] AIS[aisstream.io
WebSocket · AIS Vessels] CT[Celestrak
TLE Satellite Data] HEX[hexdb.io
Aircraft Meta · Routes] WPI[World Port Index
Static Dataset] OM[Open-Meteo
Land + Marine Weather] ON[Open Notify
ISS Crew] GM[Google Maps
Geocoding API] LF[LangFuse Cloud
OTEL Traces · Analytics] end subgraph Backend["⚙️ Backend · Python · Starlette"] direction TB subgraph Pollers["Background Pollers + Streams"] FP[Flight Poller
60s · ADSB.lol HTTP] WS[AIS WebSocket Client
Persistent · aisstream.io
Batched writes 1-2s] SP[Satellite Poller
1hr · Celestrak TLEs] end subgraph Processing["Data Processing"] FC[Flight Classifier] VC[Vessel Classifier + AIS Parser] PROP[SGP4 Propagator · Skyfield] GEO[Geocoder + Resolver
Google Maps · Cached] end SVC[Unified Service Layer
service.py] API[REST API
/api/*] MCP[MCP Server
FastMCP · /mcp · 25+ tools] GW[LLM Gateway
LiteLLM · BYOK · SSE] GR[Guardrails
LLM Guard · Optional] PG[Playground API
/api/playground/*] end subgraph Storage["💾 SQLite · WAL Mode"] DB[(flights · vessels · satellites
ports · aircraft_meta · geocode_cache
R*Tree indexes)] end subgraph Frontend["🌍 Unified Web UI · Vanilla JS"] GLOBE[CesiumJS Globe
Flights + Vessels + Satellites] DETAIL[Detail Panels
Aircraft · Vessel · Satellite] CHAT[Chat Panel
Cross-domain · BYOK · SSE] DASH[Playground Dashboard
Air + Sea + Space Metrics] end subgraph Clients["🔌 External Clients"] CLI[CLI
voyageintel ask/flights/vessels/iss] CD[Claude Desktop
stdio] CC[Claude Code
Streamable HTTP] VS[VS Code / Cursor
Streamable HTTP] end ADSB -->|Poll 60s + on-demand| FP AIS -->|WebSocket stream| WS CT -->|TLE hourly| SP HEX -->|Cached lookups| SVC WPI -->|Static load| DB OM --> SVC ON --> SVC GM -->|Cached lookups| GEO FP --> FC --> DB WS --> VC --> DB SP --> PROP --> DB DB --> API DB --> SVC ADSB -->|On-demand queries| SVC SVC --> MCP SVC --> GW SVC --> CLI SVC --> PG GW --> GR GW -->|OTEL| LF LF -->|REST reads| PG API --> GLOBE API --> DETAIL GW --> CHAT PG --> DASH MCP --> CD MCP --> CC MCP --> VS ``` VoyageIntel 是一个 **Python/Starlette后端**，配合 **纯JS + CesiumJS前端**，无构建步骤。三个后台数据摄取进程并发运行：一个HTTP飞行轮询器（ADSB.lol，60秒间隔），一个持久WebSocket连接（aisstream.io，实时AIS流，批量写入），以及一个HTTP卫星轮询器（Celestrak，1小时间隔）。所有数据流向一个单一的SQLite数据库（WAL模式）——飞行数据被追加和修剪，船舶数据按MMSI更新或插入，卫星TLE每小时刷新。R*Tree空间索引加速了船舶和港口的半径查询。一个统一的 **服务层** (`service.py`) 提供跨领域查询逻辑，供四个界面使用：REST API（地球仪渲染）、MCP服务器（25+工具，适用于Claude Desktop / VS Code / Cursor）、LLM网关（自带密钥AI聊天，支持SSE流式传输）和CLI。**LLM网关** (`gateway.py`) 通过LiteLLM实现了一个与提供商无关的工具调用循环，支持Claude、OpenAI和Gemini，通过一个统一的自带密钥接口——并使用SSE流式传输实现实时令牌交付。`/playground` 仪表盘提供了跨所有领域的统一可观测性——飞行计数、按类型划分的船舶计数、卫星缓存统计、WebSocket健康状况、轮询状态、安全防护监控和LangFuse分析。所有飞行分类（军用、私人、商业）通过分类器模块中基于模式的启发式算法完成，船舶分类将AIS船舶类型代码映射到类别，并通过MMSI识别船舶国籍，卫星位置使用Skyfield的SGP4传播在本地计算。 ## 船舶图标类型 船舶在CesiumJS地球仪上使用 `BillboardCollection` 渲染，包含9种不同的图标轮廓，根据AIS船舶类型颜色编码： | 类型 | 颜色 | AIS船舶类型代码 | 描述 | |------|------|-----------------|------| | 货船 | 🔵 蓝色 | 70–79 | 散货船、集装箱船、通用货船 | | 油轮 | 🟠 橙色 | 80–89 | 油轮、化学品船、LNG/LPG船 | | 客船 | ⚪ 白色 | 60–69 | 邮轮、渡轮、客运船舶 | | 军舰 | 🔴 红色 | 35 | 海军舰船（也通过名称模式检测：USS, HMS, HMAS等） | | 渔船 | 🟢 绿色 | 30 | 渔船 | | 游艇 | 🩵 青色 | 36–37 | 帆船游艇、游乐船 | | 高速船 | 🟡 黄色 | 40–49 | 高速船、水翼船、地效翼船 | | 特种船 | 🟣 紫色 | 50–59 | 拖船、引航船、搜救船、挖泥船、执法船 | | 未知 | ⬜ 灰色 | 所有其他代码 | 未分类或未指定的船舶类型 | ## MCP客户端设置 VoyageIntel 通过 **两种传输方式** 暴露25+个MCP工具： | 传输方式 | 工作原理 | 使用者 | |----------|----------|--------| | **可流式HTTP** (`/mcp`) | 客户端连接到运行中的VoyageIntel服务器 | Claude Code, VS Code, Cursor | | **stdio** | MCP客户端将 `voyageintel` 作为子进程启动 | Claude Desktop | ### Claude Desktop ✅ 已测试 Claude Desktop 使用 **stdio** 传输方式——它将 `voyageintel` 作为子进程启动。 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows)： **通过 `pipx` 安装（推荐）：** ``` { "mcpServers": { "voyageintel": { "command": "voyageintel", "args": ["serve", "--stdio"] } } } ``` **通过 `pip` 在虚拟环境中安装：** ``` { "mcpServers": { "voyageintel": { "command": "/full/path/to/.venv/bin/voyageintel", "args": ["serve", "--stdio"] } } } ``` 使用 `which voyageintel` (macOS/Linux) 或 `where voyageintel` (Windows) 查找完整路径。 **保存后**，完全重启Claude Desktop（退出并重新打开）。查找🔌工具图标——voyageintel应出现并显示25+个工具。 **故障排除：** - 查看日志：`cat ~/Library/Logs/Claude/mcp-server-voyageintel.log` - “No such file or directory” → 使用完整路径或通过 `pipx` 安装 - “Could not attach” → 确保没有其他 `voyageintel serve` 在同一端口运行 ### Claude Code ✅ 已测试 Claude Code 使用 **可流式HTTP** 传输方式——它连接到运行中的VoyageIntel服务器。 首先，启动服务器： ``` voyageintel serve ``` 然后注册MCP服务器： ``` claude mcp add voyageintel --transport http http://localhost:9097/mcp ``` 验证： ``` claude mcp list ``` 尝试提问：“霍尔木兹海峡附近有哪些军舰和军用飞机？” ### VS Code + GitHub Copilot ✅ 已测试 VS Code 通过 `.vscode/mcp.json` 使用 **可流式HTTP** 传输方式。 首先，启动服务器： ``` voyageintel serve ``` 然后在你的工作区创建 `.vscode/mcp.json`： ``` { "servers": { "voyageintel": { "url": "http://localhost:9097/mcp" } } } ``` 通过命令面板（Cmd+Shift+P）验证：`MCP: List Servers` — voyageintel应出现。在Copilot Chat中使用**代理模式**以访问MCP工具。 尝试提问：“新加坡附近现在有哪些货船？” ### Cursor ✅ 兼容 Cursor 使用与VS Code相同的可流式HTTP传输方式。 启动服务器： ``` voyageintel serve ``` 添加到 `.cursor/mcp.json`： ``` { "servers": { "voyageintel": { "url": "http://localhost:9097/mcp" } } } ``` ### Google Maps MCP Companion（可选） 用于获取路线、地点、距离矩阵和海拔——可将Google官方的MCP服务器与VoyageIntel并行连接： **Claude Desktop:** ``` { "mcpServers": { "voyageintel": { "command": "voyageintel", "args": ["serve", "--stdio"] }, "google-maps": { "command": "npx", "args": ["-y", "@googlemaps/maps-mcp-server"], "env": { "GOOGLE_MAPS_API_KEY": "your-key" } } } } ``` **VS Code:** ``` { "servers": { "voyageintel": { "url": "http://localhost:9097/mcp" }, "google-maps": { "type": "stdio", "command": "npx", "args": ["-y", "@googlemaps/maps-mcp-server"], "env": { "GOOGLE_MAPS_API_KEY": "your-key" } } } } ``` ### 自托管远程部署 如果你在云平台（如Railway, Render, Fly.io）上部署自己的VoyageIntel实例，远程MCP客户端可以直接连接： **VS Code / Cursor:** ``` { "servers": { "voyageintel": { "url": "https://your-deployment-url.example.com/mcp" } } } ``` **Claude Code:** ``` claude mcp add voyageintel --transport http https://your-deployment-url.example.com/mcp ``` ### Gemini CLI 🔜 待定 配置待定——一旦验证Gemini CLI的MCP支持，将添加配置。 ### OpenAI Codex 🔜 待定 配置待定——一旦验证Codex的MCP支持，将添加配置。 ### CLI 辅助 直接生成MCP配置片段： ``` voyageintel mcp-config # Claude Desktop (stdio) voyageintel mcp-config --stdio # Claude Desktop (stdio, explicit) voyageintel mcp-config --vscode # VS Code / Cursor (HTTP) ``` ### 可用MCP工具 **空中领域（12个工具）** | 工具 | 描述 | |------|------| | `flights_near` | 地理点附近的实时飞行器 | | `search_flight` | 按呼号或ICAO24十六进制码搜索 | | `military_flights` | 全球所有在空军用飞机 | | `flights_to` | 飞往目的地机场的航班 | | `flights_from` | 从出发地机场起飞的航班 | | `aircraft_info` | 按ICAO24十六进制码获取飞机元数据 | | `get_satellites` | 按类别获取卫星位置 | | `get_weather` | 任意位置的当前天气 | | `get_status` | 系统健康与诊断 | | `iss_position` | 实时国际空间站位置 | | `iss_crew` | 当前国际空间站船员 | | `iss_passes` | 指定位置的国际空间站过境预测 | **海上领域（10个工具）** | 工具 | 描述 | |------|------| | `vessels_near` | 地理点附近的实时船舶 | | `search_vessel` | 按名称、MMSI或IMO搜索 | | `military_vessels` | 所有追踪到的军用/海军舰船 | | `vessels_by_type` | 按船舶类型筛选（货船、油轮等） | | `vessels_to` | 驶往目的港的船舶 | | `vessels_from` | 在港口附近/离港的船舶 | | `vessel_info` | 按MMSI获取船舶元数据 | | `port_info` | 按UN/LOCODE获取港口详情 | | `ports_near` | 查找附近港口 | | `sea_weather` | 海洋天气——波浪、涌浪、海温 | **跨领域（4个工具）** | 工具 | 描述 | |------|------| | `activity_near` | 一个点附近的所有活动——飞行器 + 船舶 | | `military_activity` | 所有军方资产——军用飞机 + 海军舰船 | | `geocode` | 将地名解析为坐标（Google Maps，已缓存） | | `playground_system` | 统一系统健康状况——空中 + 海上 + 太空指标 | ## 架构决策 | 决策 | 选择 | 原因 | |------|------|------| | **单一地球仪，多领域** | 飞行器 + 船舶 + 卫星在一个CesiumJS查看器上 | 核心价值——统一态势感知。导航栏下拉菜单让用户显示/隐藏每个领域 | | **AIS用WebSocket，飞行用HTTP轮询** | 到aisstream.io的持久WebSocket，对ADSB.lol进行60秒HTTP轮询 | AIS是实时流（~300条消息/秒）。ADSB.lol不提供WebSocket——60秒轮询在数据新鲜度与API礼貌之间取得平衡 | | **船舶用更新插入，飞行用追加** | 不同领域采用不同存储策略 | 船舶在同一MMSI上发送频繁的位置更新——更新插入使数据库保持精简。飞行是基于快照的——追加 + 修剪 | | **AIS批量写入** | 缓冲 + 每1-2秒刷新一次 | 以~300条消息/秒进行单独INSERT会成为SQLite瓶颈。批量操作将写入成本分摊到每次刷新的一个事务中 | | **R*Tree空间索引** | 用于船舶 + 港口的SQLite R*Tree | 在（纬度，经度）上的B树索引对半径查询效果不佳。R*Tree是内置的，并为边界框/半径查询进行了优化 | | **双源数据架构** | 地球仪从SQLite读取（轮询），聊天/MCP实时查询ADSB.lol | 将轮询与按需查询隔离——避免API速率限制竞争，确保地球仪渲染永远不会与用户查询竞争 | | **BillboardCollection 优于 Entity API** | CesiumJS BillboardCollection + LabelCollection | Entity API在25k+对象时会崩溃。BillboardCollection使用基于canvas的图标缓存可顺畅处理10k+架飞机 | | **SQLite + WAL模式** | 位于 `~/.voyageintel/voyageintel.db` 的单文件数据库 | 零配置，无外部依赖，WAL允许3个摄取源在写入期间进行并发读取 | | **SGP4传播优于外部API** | Skyfield + sgp4 用于卫星/ISS位置 | 消除了位置数据对外部API的依赖。TLE每小时刷新，位置在本地计算，精度亚公里级 | | **地理编码内建，其他Maps API外部** | 在服务层中使用Google Maps Geocoding，其他API通过配套MCP | 地理编码直接提升AI查询质量——“新加坡附近的船”能直接工作。路线/地点保持外部以控制范围 | | **静态港口数据库** | 打包World Port Index为JSON（约400个港口） | 消除外部依赖。很少更改。首次启动时加载到SQLite | | **工具调用循环与结果上限** | 每个工具默认50个结果，始终返回 `total_count` | 防止上下文窗口爆炸，同时为LLM提供准确计数以进行报告 | | **BYOK安全模型** | API密钥仅存在于浏览器localStorage中 | 密钥绝不接触服务器——通过POST正文按请求发送，从不记录，从不在服务端持久化 | | **Cesium令牌屏蔽** | 通过HTML模板替换进行服务端注入 | 令牌在任何API响应中都不会暴露。在服务时通过 `%%CESIUM_TOKEN%%` 占位符注入 | | **纯JS，无构建步骤** | 纯JS + CesiumJS CDN | 前端工具链零复杂性。无npm，无webpack，无转译 | | **FastMCP双传输** | 可流式HTTP (`/mcp`) + stdio模式 | HTTP用于远程/Web客户端，stdio用于本地桌面客户端 | | **LiteLLM作为LLM网关** | Claude, OpenAI, Gemini的统一API | 单一的工具调用实现通过提供商前缀支持所有主要提供商 | | **SSE流式传输（简单方法）** | 完整的工具调用循环在服务端运行，仅最终LLM响应被流式传输 | 避免复杂的部分流/工具调用交错。处理期间发送工具状态消息，最终回复逐令牌流式传输 | ### 安全防护策略 VoyageIntel 对聊天安全采用 **分层防御** 方法： | 层 | 机制 | 成本 | 分支 | |----|------|------|------| | **系统提示词** | 指示LLM仅回答空中/海上/太空主题 | 零——每个请求的一部分 | 所有分支 | | **LLM Guard（轻量级）** | `BanTopics`, `Toxicity`, `InvisibleText` 扫描器 | 首次聊天时约500MB模型下载 | 仅 `railway-guardrails` 分支 | 重量级的 `PromptInjection` 扫描器（约738MB）和 `NoRefusal` 扫描器（约827MB）被排除，转而采用系统提示词加固——这是一个针对云部署（内存按GB/小时计费）的深思熟虑的 **成本/安全权衡**。 ### 分类 **飞机** — 通过ICAO十六进制范围、呼号前缀、应答机代码和ADSB.lol的 `/v2/mil` 数据流检测。私人喷气机通过已知的ICAO型号代码检测。参见 `src/voyageintel/flights/classifier.py`。 **船舶** — 通过AIS船舶类型代码（0–99）映射到类别（货船、油轮、客船、军舰、渔船、游艇、特种、高速）。军舰还通过名称模式（USS, HMS, HMAS等）检测。船籍国根据MMSI海事识别数字得出。参见 `src/voyageintel/vessels/classifier.py`。 ## 数据源 | 来源 | 用途 | 认证 | 传输方式 | 备注 | |------|------|------|----------|------| | **ADSB.lol** | 全球飞行数据、军方数据流、按需查询 | 无 | HTTP REST（轮询 + 按需） | 众包——覆盖范围取决于志愿者数据提供者的密度 | | **aisstream.io** | 实时AIS船舶位置 + 静态数据 | API密钥（免费，GitHub登录） | WebSocket（持久流） | 仅地面接收器——离岸约50-70海里。全球约300条消息/秒。批量写入SQLite | | **Celestrak** | 卫星TLE轨道数据（6个类别） | 无 | HTTP REST（每小时轮询） | | | **hexdb.io** | 飞机元数据 + 航线查询 | 无 | HTTP REST（缓存30天/7天） | 可能会间歇性宕机。错误已优雅处理 | | **World Port Index** | 港口名称、坐标、代码（约400个港口） | 无 | 静态数据集（打包JSON） | 首次启动时加载到SQLite | | **Open-Meteo** | 陆地/航空天气 | 无 | HTTP REST（按需） | 免费，无需API密钥 | | **Open-Meteo Marine** | 海况——波浪、涌浪、风、海温 | 无 | HTTP REST（按需） | 与陆地天气不同的API端点 | | **Open Notify** | 国际空间站船员信息 | 无 | HTTP REST（按需） | | | **Google Maps** | 将地名解析为经纬度（用于AI查询） | API密钥（BYOK） | HTTP REST（按需，缓存30天） | 可选——LLM回退到内置地理知识 | | **LangFuse** | LLM可观测性 + 演示仪表盘分析 | BYOK密钥 | OTEL回调 + REST读取 | 提供免费层 | ## 演示仪表盘 `/playground` 路由提供了一个 **AI工程可观测性界面** ——用于系统健康、安全防护监控和LangFuse分析的统一视窗。 ### 系统指标 - **追踪的飞行器** — 总数及商业/军用/私人细分（来自实时轮询数据） - **追踪的船舶** — 总数及类型细分（货船/油轮/客船/军舰/渔船等） - **AIS WebSocket** — 连接状态、消息数/秒、刷新吞吐量 - **缓存的卫星** — 数量及类别 - **轮询与运行时间** — 轮询周期数、运行时间、轮询间隔 - **数据库** — SQLite文件大小、保留策略、路径 - **数据源健康状况** — ADSB.lol, aisstream.io, Celestrak, hexdb.io, Open-Meteo 的实时状态 - **LLM配置** — 提供商、模型、API密钥状态、LangFuse状态 ### 安全防护监控 - **扫描计数** — 执行的输入和输出扫描 - **拦截率** — 拦截计数和百分比 - **扫描器状态** — 每个扫描器的已加载/延迟加载/不可用状态 - **最近拦截的查询** — 最后20个拦截的输入（已匿名化） - 当LLM Guard未安装时，优雅降级为“在railway-guardrails分支可用” ### LangFuse分析 - **聊天会话** — 来自LangFuse的追踪总数 - **工具调用频率** — MCP工具使用的热图（为精确性进行内存中跟踪） - **打开LangFuse仪表盘** — 一键跳转到完整的LangFuse UI - 当未配置LangFuse密钥时优雅隐藏 每15秒自动刷新。深色主题，卡片式网格，完全响应式。 ## Web UI 指南 - **地球仪** — 旋转、缩放和平移3D地球仪。飞行器、船舶和卫星实时渲染。 - **导航栏下拉菜单** — 导航栏中的 **飞行器 ▾**、**卫星 ▾** 和 **船舶 ▾** 下拉菜单。每个下拉菜单包含复选框，用于切换各个子类型（例如，飞行器下的商业、军用、私人；船舶下的货船、油轮、客船、海军、渔船、游艇）。使用每个下拉菜单顶部的 **显示全部** / **隐藏全部** 按钮进行批量切换。在下拉菜单外部单击可关闭它。 - **点击查看** — 单击任何飞行器、船舶或卫星以查看详细面板。船舶详细面板显示身份信息（名称、MMSI、IMO、船籍国）、运动信息（速度、航向、航迹）、尺寸、航次信息（目的地、ETA、吃水深度）以及船舶位置的海况。 - **状态栏** — 所有追踪领域的统一领域细分： ✈ 9,335 ⚔ 127 🔒 974 | 🚢 8,231 ⚓ 42 🎣 1,890 | 🛰 346 | 🛰 追踪ISS - **追踪ISS** — 单击状态栏中的🛰追踪ISS按钮，使地球仪旋转至国际空间站。 - **图层** — 在深色、卫星、街道和地形之间切换（地形需要免费的Cesium Ion令牌）。 - **分享**快照你当前的视图并通过URL或Web Share API分享。 - **聊天** — 单击💬浮动按钮打开AI聊天。首先在⚙设置中设置你的API密钥。响应通过SSE实时流式传输。 - **演示仪表盘** — 导航到 `/playground` 查看系统健康、安全防护统计和LangFuse分析。 ## CLI 参考 | 命令 | 描述 | |------|------| | `voyageintel --version` | 显示已安装版本 | | `voyageintel serve` | 启动服务器（MCP + REST + Web UI） | | `voyageintel serve --stdio` | Claude Desktop的MCP stdio模式 | | `voyageintel status` | 显示配置和系统状态 | | `voyageintel init` | 初始化数据库 | | `voyageintel config` | 以JSON格式显示当前配置 | | `voyageintel ask "问题"` | 向AI提问（使用.env凭据） | | `voyageintel flights --military` | 列出军用飞行器 | | `voyageintel flights --search RYR123` | 按呼号/十六进制码搜索 | | `voyageintel flights --lat 51 --lon -0.5` | 某点附近的飞行器 | | `voyageintel vessels --military` | 海军舰船 | | `voyageintel vessels --near 51 --lon -0.5` | 某点附近的船舶 | | `voyageintel vessels --type tanker` | 按类型筛选 | | `voyageintel vessels --search "Ever Given"` | 搜索船舶 | | `voyageintel ports --lat 51 --lon -0.5` | 附近港口 | | `voyageintel ports --code SGSIN` | 按代码查询港口详情 | | `voyageintel satellites --category iss` | 按类别列出卫星 | | `voyageintel iss` | 国际空间站位置 + 船员 | | `voyageintel iss --passes --lat 51 --lon -0.5` | 国际空间站过境预测 | | `voyageintel mcp-config` | 打印Claude Desktop的MCP配置 | | `voyageintel mcp-config --vscode` | 打印VS Code的MCP配置 | ## API 参考 | 方法 | 路径 | 描述 | |------|------|------| | GET | `/` | Web UI（统一地球仪） | | GET | `/playground` | 演示仪表盘 | | GET | `/api/status` | 系统状态 + 配置 | | GET | `/api/flights?lat_min&lat_max&lon_min&lon_max` | 缓存的飞行器（边界框） | | GET | `/api/aircraft/{icao24}` | 飞机元数据 | | GET | `/api/route/{callsign}` | 飞行航线 | | GET | `/api/satellites?category=` | 卫星位置 | | GET | `/api/weather?lat=&lon=` | 当前天气 | | GET | `/api/sea-weather?lat=&lon=` | 海洋天气——波浪、涌浪、海温 | | GET | `/api/iss` | 国际空间站位置 + 船员 | | GET | `/api/iss/passes?lat=&lon=` | 国际空间站过境预测 | | GET | `/api/vessels?lat_min&lat_max&lon_min&lon_max` | 船舶（边界框） | | GET | `/api/vessel/{mmsi}` | 按MMSI获取船舶详情 | | GET | `/api/vessels/stats` | 按类型统计船舶数量 | | GET | `/api/ports?lat=&lon=&radius_km=` | 附近港口 | | GET | `/api/port/{code}` | 按UN/LOCODE获取港口详情 | | POST | `/api/chat` | BYOK聊天 | | POST | `/api/chat/stream` | 支持SSE流式传输的BYOK聊天 | | GET | `/api/playground/system` | 系统健康指标 | | GET | `/api/playground/guardrails` | 安全防护扫描/拦截统计 | | GET | `/api/playground/langfuse` | LangFuse分析 | | POST | `/mcp` | MCP可流式HTTP端点 | ## 上下文管理与速率限制 VoyageIntel 采用工具调用架构，其中LLM每次查询会进行多次API调用。我们实施了几种策略来管理令牌使用量： - **聊天历史窗口化** — 每次请求仅向LLM发送最后6条消息，在保留上下文的同时减少输入令牌。 - **结果上限** — 工具结果默认为50项，始终返回 `total_count`，防止上下文窗口爆炸。 - **带退避的重试** — 速率限制错误触发自动重试（最多3次尝试，30秒/60秒等待）。 - **双系统提示词** — Web聊天使用HTML格式，CLI使用markdown，为每个界面保持响应简洁。 - **SSE流式传输** — 最终LLM响应通过服务器发送事件逐令牌流式传输，提升感知响应速度。 ## 路线图 | 功能 | 状态 | |------|------| | 实时飞行追踪（ADSB.lol） | ✅ 已完成 | | 军用飞机监控 | ✅ 已完成 | | 卫星追踪（6个类别） | ✅ 已完成 | | 国际空间站追踪 + 过境预测 | ✅ 已完成 | | CesiumJS 3D地球仪 | ✅ 已完成 | | MCP服务器（25+工具） | ✅ 已完成 | | 支持SSE流式传输的BYOK AI聊天 | ✅ 已完成 | | `/playground` 仪表盘 | ✅ 已完成 | | 通过aisstream.io进行AIS船舶追踪 | ✅ 已完成 | | 港口数据库（World Port Index） | ✅ 已完成 | | 海洋天气（波浪、涌浪、海温） | ✅ 已完成 | | 带缓存的Google Maps地理编码 | ✅ 已完成 | | 跨领域查询（空中 + 海上） | ✅ 已完成 | | Claude Desktop MCP集成 | ✅ 已测试 | | Claude Code MCP集成 | ✅ 已测试 | | VS Code + GitHub Copilot MCP集成 | ✅ 已测试 | | CesiumJS地球仪上的船舶（BillboardCollection，9种图标轮廓） | ✅ 已完成 | | 船舶详细面板（点击查看：身份、运动、尺寸、航次、海况） | ✅ 已完成 | | 导航栏下拉菜单（飞行器 ▾, 卫星 ▾, 船舶 ▾，带复选框 + 显示全部/隐藏全部） | ✅ 已完成 | | 统一状态栏（完整的领域细分计数） | ✅ 已完成 | | PyPI发布 (`pip install voyageintel`) | ✅ 已完成 | | Railway部署 ([voyage.skyintel.dev](https://voyage.skyintel.dev)) | ✅ 已完成 | | 安全防护分支 | 🔜 计划中 | | 船舶轨迹（最近30分钟的轨迹） | 🔜 计划中 | | 港口活动监控（到港/离港） | 🔜 计划中 | | 跨领域关联警报 | 🔜 计划中 | | 历史回放 / 时间滑块 | 🔮 未来 | | 水下情报层 | 🔮 未来 | | 异常检测（异常航线、AIS间隙） | 🔮 未来 | | 制裁船舶名单集成 | 🔮 未来 | | 卫星AIS集成（Spire, exactEarth, ORBCOMM） | 🔮 未来 | ## 与SkyIntel的关系 VoyageIntel 是 [SkyIntel](https://github.com/0xchamin/skyintel/tree/railway) (`pip install skyintel`, `skyintel.dev`) 的演进版本——一个空中 + 太空追踪平台。VoyageIntel 是其超集：包含SkyIntel的所有功能，外加海事（AIS船舶追踪、港口、海洋天气）以及未来的水下情报。 | 方面 | SkyIntel | VoyageIntel | |------|----------|-------------| | **范围** | 空中 + 太空 | 空中 + 海上 + 太空（+ 未来水下） | | **包** | `pip install skyintel` | `pip install voyageintel` | | **域名** | `skyintel.dev` | `voyage.skyintel.dev` | | **分支** | `railway` | `voyageintel` (默认) | | **端口** | 9096 | 9097 | | **配置前缀** | `SKYINTEL_` | `VI_` | | **MCP工具** | 15（空中 + 太空） | 25+（空中 + 海上 + 太空 + 跨领域） | | **数据摄取** | 仅HTTP轮询 | HTTP轮询 + WebSocket（批量） | | **空间索引** | 无 | 用于船舶 + 港口的R*Tree | 两个项目独立共存，可同时运行。 ## 贡献 VoyageIntel 是基于Apache 2.0许可证的开源项目。我们欢迎贡献： - 🐛 **错误报告** — 附上重现步骤提交问题 - 💡 **功能建议** — 通过GitHub Issues提出想法 - 🔧 **拉取请求** — 特别欢迎在以下方面贡献： - 海事数据增强（船舶照片、分类改进） - 飞机分类器改进（参见 `src/voyageintel/flights/classifier.py`） - 船舶分类器改进（参见 `src/voyageintel/vessels/classifier.py`） - 地球仪渲染性能 - 其他数据源 - 测试覆盖率 - 文档 ### 开发环境设置 ``` git clone https://github.com/0xchamin/skyintel.git cd skyintel git checkout voyageintel python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" cp .env.example .env # Add your API keys voyageintel serve ``` ## 支持项目 如果你觉得VoyageIntel有用，请考虑支持其开发： [](https://buymeacoffee.com/0xchamin) ⭐ 如果你觉得有用，请 **Star这个仓库** — 这有助于其他人发现该项目。 ## 企业版 需要托管部署、自定义集成、SLA支持或其他数据源？ 📧 **聊聊** — 通过 [GitHub Issues](https://github.com/0xchamin/skyintel/issues) 或 [Buy Me a Coffee](https://buymeacoffee.com/0xchamin) 联系我们开始对话。 ## 免责声明 VoyageIntel 是一个 **教育项目和技术演示**，展示了实时多领域数据集成、[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 工具调用模式以及AI驱动的地理空间智能。 所有数据均来自 **公开可用的开放API** — 未使用任何机密、专有或受限数据。飞行位置来自 [ADSB.lol](https://adsb.lol)，船舶位置来自 [aisstream.io](https://aisstream.io)，卫星TLE来自 [Celestrak](https://celestrak.org)，ISS数据来自 [Open Notify](http://open-notify.org)，天气来自 [Open-Meteo](https://open-meteo.com)。 - 飞行、船舶和卫星数据按原样来自第三方来源。不保证准确性、完整性和可用性。 - 军用飞机数据来自公开的ADS-B信号。并非所有军用飞机都广播ADS-B。 - 军用舰船检测基于AIS类型代码和名称模式。许多军舰禁用或限制AIS传输。 - 飞机分类（军用/私人/商业）和船舶分类基于已知模式和启发式算法——仅供教育目的。 - ADSB.lol的覆盖范围取决于志愿者ADS-B数据提供者的密度——某些地区覆盖有限。 - AIS覆盖范围取决于aisstream.io的地面接收器网络（离岸约50-70海里）。远洋船舶不可见。卫星AIS目前未集成。 - LLM生成的报告和分析是AI辅助的，不应作为运营、安全或安保决策的唯一来源。 - BYOK API密钥仅存储在浏览器localStorage中——从不在服务端持久化。 本项目与任何政府、军事或情报机构无关。显示的飞机、船舶和卫星位置是近似值，**不得** 用于导航、安全关键决策或运营目的。 ## 许可证 Apache 2.0 — 详情请参阅 [LICENSE](LICENSE)。 由 [0xchamin](https://buymeacoffee.com/0xchamin) 用 ❤️ 构建

标签：3D地球可视化, ADS-B数据, AIS数据, AI查询系统, BYOK AI聊天, Celestrak, CesiumJS, ISS实时位置, MCP服务器, SGP4算法, SSE实时流, 军事监测, 卫星追踪, 地理空间数据, 地理编码服务, 天气数据集成, 太空追踪, 安全防护栏, 海上追踪, 航空追踪, 逆向工具