项目地址：GitHub - HikaruQwQ/GuEarth
关键词：ElectronVue3CesiumJS数字地球地理教学AI Agent工具调用
文章目录
- 一、前言
- 二、GuEarth 是什么
- 三、技术栈
- 四、整体架构
- EOQ Agent 的工具调用闭环
- 五、教学模块（对标人教版选择性必修一）
- M1 地球运动
- M2 大气
- M3 地貌
- M4 水体与海洋
- M5 整体性与差异性（规划中）
- 六、快速开始
- 八、写在最后
一、前言
Google Earth 很强大，但它在国内访问不稳定、无法定制教学内容、也没有面向课堂的工具链等缺点。于是社区里出现了一个想法：做一个本地运行的、可离线、可定制、内置 AI 助手的"数字地球"，专门服务于中学与高校地理教学。
这就是GuEarth—— 一个基于 Electron + Vue 3 + CesiumJS 的开源桌面端三维数字地球。目前 v0.1.5 已实现核心平台与四大教学模块（地球运动 / 大气 / 地貌 / 水体海洋），并内置了一个能"看图说话"、会开图层、会飞镜头的 AI 地理助手EOQ。
二、GuEarth 是什么
一句话概括：本地版 Google Earth + 地理教学工具箱 + AI 地理助手的合体。
核心能力一览：
- 三维球体与地形：CesiumJS 渲染，支持多地图数据源（OSM / Mapbox / ArcGIS / 高德等）、可插拔地形服务、地形光照与夸张系数调节、2D/3D 场景切换；
- 教学标注工具：绘制点、线、面、箭头、文字框，测距测面，标注就地编辑（颜色 / 字号 / 线宽），自动持久化保存；
- 专题教学图层：晨昏线、气压带风带、柯本气候区、板块边界 + USGS 实时地震火山、ENSO 海温异常、世界洋流、台风历史路径……全部可点击查询成因；
- EOQ AI 助手：流式对话 + 工具调用（Tool Calling），能联网搜索、检索内置地理知识库、查地名并
fly_to带你飞、按剧本自动录制成教学视频； - 本地优先与安全：所有密钥只存在主进程（
safeStorage加密），渲染进程零 Node 权限，瓦片本地缓存。
三、技术栈
| 层 | 选型 | 说明 |
|---|---|---|
| 桌面壳 | Electron + electron-vite | contextIsolation开、nodeIntegration关，typed preload IPC（window.guEarth） |
| 渲染层 | Vue 3 + Pinia + Ant Design Vue | 组件与设计 token 全部遵循 DESIGN.md |
| 图表 | ECharts（vue-echarts） | 按需引入echarts/core+ SVGRenderer |
| 三维地图 | CesiumJS | 静态资源自研插件托管，CESIUM_BASE_URL=./cesium/ |
| AI | 主进程 OpenAI 兼容流式客户端 | 供应商无关（DeepSeek / Qwen / OpenAI…） |
| 存储 | userData下 JSON 文件 | 凭据走safeStorageKeyVault |
| 打包 | electron-builder | Windows NSIS |
四、整体架构
┌─────────────────────────────────────────────┐ │ Renderer (Vue 3) │ │ 球体视图 / 图层注册表 / 绘制工具 / EOQ 对话 UI │ │ 不接触任何 Node API 与密钥 │ └──────────────────┬──────────────────────────┘ │ contextBridge (window.guEarth) ┌──────────────────▼──────────────────────────┐ │ Preload (typed IPC) │ └──────────────────┬──────────────────────────┘ │ ipcMain.handle / event ┌──────────────────▼──────────────────────────┐ │ Main (主进程) │ │ 窗口管理 / KeyVault / AI 代理(流式) │ │ 瓦片缓存 / USGS 数据集拉取 / 地点搜索 │ └─────────────────────────────────────────────┘三条设计原则：
- 渲染进程永远不碰 Node API 和密钥，所有特权操作走 IPC；
- 地图数据源统一实现
LayerProvider接口，影像源与地形源均可插拔，为未来离线地形包留好口子； - AI 工具在渲染侧注册：新增"AI 能操作球体"的能力 = 新增一个工具定义，主进程不需要知道球体 API 细节。
EOQ Agent 的工具调用闭环
这是本项目最有意思的设计：
用户提问（渲染进程） → IPC 到主进程发起 LLM 流式调用 → 模型返回工具调用（flyTo / queryTerrain / setLayer / explainLandform / recordVideo / webSearch / retrieveKnowledge …） → 主进程把工具调用转发给渲染进程的球体 API 执行 → 执行结果回填对话上下文 → 模型继续生成，答案流式返回前端比如老师问"带我看看喀斯特地貌"，EOQ 会：retrieve_knowledge查知识库 →search_place查典型地点坐标（如桂林、石林）→ 逐个fly_to飞过去 →query_terrain查海拔辅助讲解 → 输出成因讲解。
五、教学模块（对标人教版选择性必修一）
这是 GuEarth 区别于通用 GIS 软件的核心价值。专题图层代码集中在src/renderer/src/thematic/，统一在useThematicLayers.ts注册。
M1 地球运动
- 昼夜与太阳直射点时间轴（日期 / 时刻可调，二分二至预设）
- 昼长 & 正午太阳高度随纬度变化图表
- 太阳视运动天穹面板、黄赤交角可调探索器（直射点范围 + 五带划分）
- 自转速度与恒星日 / 太阳日演示、科里奥利力演示图层
- 时区对比工具，以及配套的
set_sim_time/query_solarAI 工具
M2 大气
- 气压带风带图层（1 月 / 7 月位置对比）、全球柯本气候分区
- 专题要素点击 + AI 讲解、锋面气旋锚定叠加层
- 热力环流动画面板（海陆风 / 山谷风 / 城市风）
- 大气受热过程面板（削弱 + 保温，昼夜 / 云量状态可切换）
- 大气垂直分层面板（高度-温度廓线）
- 台风图层（结构锚定叠加 + 历史真实路径）
M3 地貌
- 板块边界 + USGS 地震 / 火山数据（主进程拉取 + 缓存）
- 褶皱断层剖面面板 + 真实地点飞行漫游
- 河流地貌面板（上中下游 + 基于
sampleTerrainMostDetailed的真实地形剖面） - 典型地貌导览（喀斯特 / 雅丹 / 冰川 / 海岸 / 黄土自动飞行）
- 外力作用链、地球内部圈层剖面，以及
explain_landformAI 工具
M4 水体与海洋
- ENSO 相位图层（El Niño / La Niña 海温异常 + 沃克环流 + Niño3.4 关键区）
- 水循环动画面板（与相机联动）
- 海水温度 / 盐度纬度剖面、潮汐与海浪面板
- 河流补给与径流、洋流与风带关联入口
M5 整体性与差异性（规划中）
山地垂直自然带谱、引导式剖面飞行（fly_transect）、find_peaks等。
六、快速开始
可前往下载安装包
https://github.com/HikaruQwQ/GuEarth/releases/download/v0.1.5/guearth-0.1.5-x64-setup.exe
gitclone https://github.com/HikaruQwQ/GuEarth.gitcdGuEarthnpminstall# 国内网络需要手动装 Electron 二进制ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"\nodenode_modules/electron/install.jsnpmrun dev# 开发调试npmrun build# 生产构建npmrun build:win# 打 Windows 安装包首次启动会有使用引导，指引配置地点搜索密钥（高德 / 百度）和 AI 模型供应商，也可以跳过后从底部工具栏重新打开。
八、写在最后
GuEarth 的目标很明确：让地理老师打开一个本地应用，就能拖动晨昏线、点开一条板块边界讲地震成因、或者让 AI 带着全班"飞"过桂林的喀斯特峰林。
项目完全开源，欢迎 Star、提 Issue、提 PR，也欢迎地理老师提出真实课堂需求——功能优先级由教学场景驱动。
