# GeoAI-Universal-Platform **Repository Path**: helloyangxp/geo-ai-universal-platform ## Basic Information - **Project Name**: GeoAI-Universal-Platform - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 9 - **Created**: 2026-04-27 - **Last Updated**: 2026-04-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GeoAI 通用平台 一个智能地理空间 AI 助手，能够自主规划、执行并从复杂的空间分析任务中学习。采用多层架构，结合自主代理编排与强大的执行基础设施。 ## 🎯 愿景 GeoAI 通用平台通过智能代理系统将自然语言查询转换为复杂的空间操作。与传统需要专业技术的 GIS 工具不同，我们的平台充当主动助手，能够理解上下文、规划多步骤工作流、适应错误并从经验中持续改进。 演示视频详见[视频](./examples/show_video_zh.mp4) ![show](./examples/show_zh.gif) ### 核心能力 - **🤖 自主智能**: GeoAgent 层提供自主任务规划、动态工具选择和自我纠正能力 - **🧠 上下文感知记忆**: 维护对话历史，学习用户偏好，根据过往交互调整响应 - **🔍 反思式执行**: 实时质量评估，自动调整计划和错误恢复 - **📊 多提供商 LLM 支持**: Qwen、Ollama、Anthropic Claude、OpenAI，支持无缝运行时切换 - **🗂️ 智能数据集成**: 自动发现本地文件（GeoJSON、Shapefile、CSV、Excel）、PostGIS 数据库和 Web 服务（WFS、PostgREST） - **🔌 可扩展插件系统**: 动态策略加载，SQLite 状态持久化和安全验证 - **⚡ 策略链架构**: 20+ 内置地理空间策略，在自适应多步骤工作流中执行 - **🌐 自然语言界面**: 支持中英文对话交互，提供透明的推理轨迹 ## 🎯 开发理念：文档驱动开发（DDD） **本项目严格遵循 DDD（Documentation-Driven Development，文档驱动开发）方法论：** 1. **设计优先**：所有功能在实现前必须有详细的设计文档 2. **代码其次**：实现严格遵循已批准的设计规范 3. **测试第三**：全面的测试验证设计和实现 4. **持续文档化**：保持文档与代码更改同步 ### DDD 工作流程 ``` 需求 → 设计文档 → 评审 → 实现 → 测试 → 文档更新 ``` **设计文档位置：** [`docs/design/`](docs/design/) ## 🏗️ 架构 平台采用清晰的双层架构，将智能与执行分离： ``` ┌─────────────────────────────────────────────┐ │ 接口层 │ │ REST API / Web 演示 │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ 服务器服务层 │ │ GeoAgentService（单例） │ │ - 配置加载 │ │ - 插件系统初始化 │ │ - 代理生命周期管理 │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ SDK 核心（框架无关） │ │ │ │ ┌──────────────────────────────────────┐ │ │ │ GeoAgent 智能层 │ │ │ │ ├─ IntentClassifier（意图分类器） │ │ │ │ ├─ ExecutionOrchestrator（执行编排） │ │ │ │ ├─ EnhancedToolRegistry（工具注册） │ │ │ │ ├─ AgentMemory（代理记忆） │ │ │ │ └─ ResultReflector（结果反思） │ │ │ └──────────────┬───────────────────────┘ │ │ │ 委托执行 │ │ ┌──────────────▼───────────────────────┐ │ │ │ 执行引擎层 │ │ │ │ ├─ LangChainTaskExecutor │ │ │ │ ├─ StepExecutor（共享工具） │ │ │ │ ├─ Strategy Registry（25+内置策略） │ │ │ │ └─ Plugin System（动态加载） │ │ │ └──────────────┬───────────────────────┘ │ │ │ │ │ ┌──────────────▼───────────────────────┐ │ │ │ 支持模块 │ │ │ │ ├─ LLM Providers（Qwen/Ollama等） │ │ │ │ └─ Data Sources（本地/PostGIS/WFS） │ │ │ └──────────────────────────────────────┘ │ └─────────────────────────────────────────────┘ ``` ### 架构理念 **双层设计原则：** - **GeoAgent（智能层）**：“大脑” - 分类意图、编排执行、管理记忆、反思结果 - **执行引擎（基础设施层）**：“双手” - 解析查询、执行策略、流式输出结果 **服务器-SDK 分离：** - **服务器层**：处理配置、插件初始化、代理生命周期（框架特定） - **SDK 层**：纯业务逻辑、框架无关、可作为独立库重用 这种分离实现了： - ✅ **灵活性**：复杂查询使用 GeoAgent，简单任务直接调用 Executor - ✅ **可维护性**：通过共享的 StepExecutor 实现单一执行逻辑源 - ✅ **可扩展性**：添加智能功能无需修改执行核心 - ✅ **可重用性**：SDK 可在任何 Node.js 项目中独立导入 - ✅ **性能**：根据复杂度需求选择合适的层级 ### 设计模式 - **代理模式**：自主编排，包含意图分类、执行协调和反思 - **工厂模式**：GeoAgent 创建（依赖注入）、LLM 提供商实例化 - **策略模式**：25+ 可插拔地理空间操作，按类别组织（data-access、spatial-ops、analytical、visual-render） - **管道模式**：通过 StepExecutor 实现自适应多步骤策略链执行 - **观察者模式**：事件驱动的 SSE 流式传输，提供实时反馈 - **记忆模式**：基于 SQLite 的持久化记忆，用于对话上下文和用户偏好 - **插件架构**：动态 ES 模块加载，AJV 验证，SQLite 状态持久化 - **服务定位器**：单例模式的 GeoAgentService 管理代理生命周期 - **依赖注入**：所有组件通过构造函数注入，便于测试 ## ✨ 主要特性 ### 🤖 GeoAgent 智能 - **自主任务规划**: 将复杂查询分解为可执行的多步骤工作流，无需预定义模板 - **动态工具选择**: 根据上下文、数据可用性和用户意图，从 25+ 策略中智能选择 - **反思式执行**: 实时质量评估，当结果不符合预期时自动调整计划 - **上下文感知对话**: 维护多轮对话历史，根据之前的交互调整响应 - **自我纠正工作流**: 检测执行错误，并使用替代方法自主恢复 - **透明推理**: 通过 ReAct 模式（思考 → 行动 → 观察）提供清晰的决策过程解释 - **双层架构**: 将智能（规划、记忆、反思）与执行（策略链、流式输出）分离 ### 🧠 自适应记忆系统 - **工作记忆**: 跟踪当前会话状态、中间结果和对话流程 - **情景记忆**: 存储任务执行历史，用于模式识别和经验重用 - **用户偏好学习**: 根据个人用户调整输出格式、可视化风格和分析深度 - **语义搜索**: 检索相关的过去任务，为当前执行策略提供参考 - **持续改进**: 系统随着每次交互变得更加准确和高效 ### ⚡ 增强策略执行 - **25+ 内置策略**: 跨 4 个类别的综合地理空间操作： - **数据访问**: 过滤、排序、搜索、提取 - **空间操作**: 缓冲区、连接、叠加、转换、邻近度、最近搜索、距离计算 - **分析功能**: 统计、分类、聚类、网络分析、表面分析、热力图生成 - **可视化**: 样式、分级统计图、热力图、标签、布局 - **共享 StepExecutor**: GeoAgent 和直接执行器调用共用的统一执行逻辑 - **自适应策略链**: 按顺序执行多个策略，支持动态参数传递 - **插件可扩展性**: 上传自定义策略，自动发现并基于 SQLite 的状态管理 - **质量引导执行**: 监控中间结果，并相应调整后续步骤 ### LLM 集成 - **多提供商支持**: Qwen、Ollama、Anthropic Claude、OpenAI GPT，通过 API 或 UI 运行时切换 - **动态配置**: 管理多个 LLM 配置文件，SQLite 持久化并即时激活 - **前端覆盖**: 用户可以通过 Web 界面提供自定义 API 密钥和模型偏好 - **智能缓存**: 优化的提供商实例管理，减少延迟 - **安全凭证处理**: 服务器端密钥保护与临时前端令牌 ### 数据源支持 - **本地文件**: GeoJSON、Shapefile (.shp/.shx/.dbf)、CSV、Excel (.xlsx/.xls)，具有自动类型推断和几何检测 - **数据库**: PostGIS，强制执行只读查询并防止 SQL 注入 - **Web 服务**: WFS（OGC 标准）、PostgREST，支持身份验证 - **自动发现**: 基于 SQLite 的注册表和本地文件扫描器，实现零配置设置 - **统一接口**: 所有源类型的一致 IDataSource API ### 安全与隐私 - **离线优先架构**: 无需外部依赖即可在本地处理敏感地理数据 - **安全凭证管理**: 服务器端密钥保护与临时前端令牌 - **只读数据库访问**: PostGIS 连接强制执行只读查询，防止 SQL 注入 - **隔离网络部署**: 支持本地 LLM（Ollama），在隔离网络中完整运行 - **插件沙箱**: 策略安装前的安全验证和代码扫描 ### 架构与可扩展性 - **SDK + 服务器模式**: 作为 TypeScript 库导入或作为独立 Express REST API 服务器运行 - **自主代理编排**: GeoAgent 层提供智能任务规划和执行监控 - **插件系统**: 行业特定策略扩展，具有动态加载和状态持久化 - **事件流式传输**: 逐步进度的实时执行反馈和推理透明度 - **类型安全**: 完整的 TypeScript 覆盖，全面的类型定义和 Zod 验证 ## 📦 项目结构 ``` GeoAI-Universal-Platform/ ├── src/ │ ├── sdk/ # 核心 SDK 库 │ │ ├── agent/ # GeoAgent 智能层 │ │ ├── execution-engine/ # 执行基础设施（策略、执行器） │ │ ├── llm/ # LLM 提供商抽象 │ │ ├── datasources/ # 数据源适配器 │ │ ├── types/ # TypeScript 定义 │ │ └── utils/ # 工具和助手 │ ├── server/ # Express REST API 服务器 │ │ ├── controllers/ # 请求处理器 │ │ ├── routes/ # API 路由定义 │ │ ├── services/ # 业务逻辑 │ │ ├── config/ # 配置加载器 │ │ └── index.ts # 服务器入口点 │ └── index.ts # SDK 入口点 ├── examples/ │ └── web-demo/ # Vue.js 演示应用 ├── docs/ │ ├── architecture/ # 高层设计文档 │ ├── design/ # 详细设计规范（DDD） │ ├── development/ # 实现指南 │ └── references/ # 参考资料 ├── tests/ # 单元测试、集成测试和端到端测试 ├── data/ # 示例数据、插件、配置、注册表 ├── dist/ # 编译输出 ├── .env # 环境变量 └── package.json ``` ## 🚀 快速开始 ### 前置要求 - Node.js >= 24.0.0 - npm 或 pnpm - （可选）PostgreSQL + PostGIS 用于数据库支持 - （可选）Ollama 用于本地 LLM 推理 ### 安装 ```bash # 克隆并安装 git clone cd GeoAI-Universal-Platform npm install npm run build ``` ### 配置 ```bash # 复制环境模板 cp .env.example .env # 编辑 .env 文件 PORT=3000 LOCAL_DATA_DIR=./data/sources ``` **LLM 配置：** 服务器启动后通过 API、UI 或配置文件进行配置。详见 [LLM 配置设计](docs/design/design-18-multi-llm-config.md)。 ### 运行平台 **方式 1：REST API 服务器** ```bash npm start # 开发模式：npm run server:dev ``` 将数据文件放入 `data/sources/` 目录以自动发现。访问 `http://localhost:3000`。 **方式 2：Web 演示** ```bash cd examples/web-demo && npm install && npm run dev # 打开 http://localhost:5173 ``` 提供对话式 UI、交互式地图、插件管理和实时 LLM 配置功能。 **方式 3：SDK 库** ```typescript import { GeoAgent, LlmProviderFactory } from '@geoai/universal-platform'; const llmProvider = LlmProviderFactory.create('qwen', { apiKey: 'your-api-key', model: 'qwen-plus' }); const agent = new GeoAgent(llmProvider, toolRegistry); const response = await agent.processQuery('显示所有城市'); ``` ## 📋 开发状态 ### ✅ 已完成核心功能 - **GeoAgent 智能**：自主任务规划、增强工具注册中心、执行监控、反思式适应、多层记忆系统、ReAct 模式、多轮上下文管理 - **策略执行**：25+ 内置地理空间策略（4个类别）、共享 StepExecutor、基于 LangChain 的任务执行、流式执行、智能数据源选择、模式感知参数生成 - **插件系统**：动态上传/安装、安全扫描验证、SQLite 状态持久化、启动时自动扫描、热重载支持、Web UI 管理器 - **LLM 集成**：多提供商支持（Qwen、Ollama、Anthropic、OpenAI）、运行时切换、前端 API 密钥覆盖、实例缓存、安全凭证管理 - **数据源**：本地文件（GeoJSON、Shapefile、CSV、Excel）、PostGIS（只读强制）、Web 服务（WFS、PostgREST）、SQLite 注册表自动发现 - **Web 演示**：Vue.js 3.5 前端、对话界面、Leaflet 地图集成、实时流式响应、插件管理仪表板、LLM 配置 UI - **基础设施**：Express REST API、TypeScript 严格模式、Rollup 打包（CJS/ESM/UMD）、Jest 测试框架、环境配置、DDD 方法论 ### 🔄 进行中 - 业务 API 服务注册表，支持 OpenAPI 导入 - 高级地理空间分析（网络路由、表面建模） - 全面的测试覆盖扩展（>80%） - API 文档（OpenAPI/Swagger） - 速率限制和请求节流 - 身份验证和授权（JWT/OAuth2） - WebSocket 支持实时通信 - 插件市场，版本管理 ### 📅 未来路线图 - 3D 可视化，Cesium.js 集成 - 移动应用（React Native / Flutter） - 高级缓存策略，Redis - 负载均衡水平扩展 - 使用分析和计费跟踪 - LLM 模型微调管道，领域适应 - 增强的插件生态系统，市场功能 ## 📚 文档 所有文档遵循**文档驱动开发（DDD）**方法论。 ### 关键文档 - **[GeoAgent 架构](docs/architecture/arch-04-geoagent-architecture.md)** - 智能代理层设计 - **[架构分析](docs/architecture/arch-11-why-two-components.md)** - 双层架构解释 - **[技术路线图](docs/development/dev-76-technical-roadmap.md)** - 未来增强计划 - **[系统架构](docs/architecture/arch-02-architecture.md)** - 整体系统设计 ### 设计文档 浏览 [`docs/design/`](docs/design/) 获取详细的 DDD 规范，涵盖 LLM 集成、数据源、插件系统和策略执行。 ### 开发指南 浏览 [`docs/development/`](docs/development/) 获取实现进度、迁移指南和技术深入分析。 ## 🛠️ 技术栈 **核心：** TypeScript 6.0, Node.js 24+, Express 5.x, Vue.js 3.5 **地理空间：** @turf/turf 7.3, leaflet 1.9, shapefile 0.6 **数据库：** PostgreSQL/PostGIS (pg 8.20), better-sqlite3 12.9 **AI/LLM：** @langchain/core, openai 6.34, axios 1.12 **代理智能：** ReAct 模式, 增强工具注册中心, 多层记忆, 反思式规划 **插件：** multer, ajv 8.x, 动态 ES 模块导入 **开发工具：** Rollup 4.60, Jest 30.3, ESLint 10.0, Prettier 3.8 ## 🤝 贡献 欢迎贡献！请遵循以下准则： 1. **首先阅读设计文档**：所有功能在实现前都需要设计文档（DDD 方法论） 2. **遵循 TypeScript 标准**：严格模式、全面类型、JSDoc 注释 3. **编写测试**：为新功能编写单元测试，保持 >80% 覆盖率 4. **更新文档**：保持文档与代码更改同步 5. **提交 PR**：包括描述、测试说明和相关问题 ### 开发工作流程 ```bash # 1. Fork 并克隆仓库 git clone https://github.com/rzcgis/GeoAI-Universal-Platform.git # 2. 创建功能分支 git checkout -b feature/your-feature-name # 3. 进行更改、编写测试并验证 npm install && npm test && npm run lint && npm run build # 4. 提交拉取请求，包含描述和测试说明 ``` ## 📞 支持 - **问题**：通过 GitHub Issues 报告错误和功能请求 - **讨论**：在 GitHub Discussions 中提问和分享想法 - **文档**：浏览 `docs/` 目录中的 comprehensive 文档 --- *为地理空间 AI 社区用心构建 ❤️*