[English](./README_en.md) | **中文** # GIS Data Agent (ADK Edition) v12.0 基于 **Google Agent Developer Kit (ADK)** 构建的 AI 驱动地理空间分析平台。通过自然语言语义路由，自动调度四大专业管道完成空间数据治理、用地优化、多源数据融合和商业智能分析。 系统实现了《Agentic Design Patterns》21 种设计模式中的 **21 种 (100%)**，包括 SequentialAgent / LoopAgent / ParallelAgent 三种 ADK Agent 类型、4 个 Agent Plugins、4 个输入/输出 Guardrails、SSE 流式输出、A2A 智能体互操作、Pareto 多目标优化、动态 Agent 组合、主动探索建议、推理链与置信度评分以及自我改进。前端为 React 三面板 SPA（11 标签页），后端集成 85 个 REST API。 ## 📚 官方技术文档 本项目提供基于 **DITA XML** 标准编写的工业级技术文档，内容涵盖架构白皮书、API 参考及多引擎配置指南等。 👉 **[在线阅读完整的 HTML 预览版 (中文)](docs/dita/preview.html)** > **提示：** > 您可以通过运行 `python preview_docs.py` 自行编译最新的 DITA XML 源文件（位于 `docs/dita/` 目录），并查阅《多智能体架构深度解析》、《多源多模态数据融合引擎(MMFE)》、《GraphRAG 知识图谱》等深度内容。 ## 核心指标 | 指标 | 数值 | |------|------| | 测试覆盖 | 2104 tests, 92 test files | | 工具集 | 22 BaseToolset, 5 SkillBundle, 122+ 工具 | | ADK Skills | 16 场景化领域技能 + DB 驱动自定义 Skills | | REST API | 85 endpoints | | Agent Plugins | 4 (CostGuard, GISToolRetry, Provenance, HITLApproval) | | Guardrails | 4 (InputLength, SQLInjection, OutputSanitizer, Hallucination) | | ADK Agent 类型 | SequentialAgent + LoopAgent + ParallelAgent | | 设计模式覆盖 | **21/21 (100%)** | | Streaming | 批量 + SSE 流式 | ## 核心能力 ### 多源数据智能融合 (v5.5–v7.0) - **五阶段流水线**：画像 → 评估 → 对齐 → 融合 → 验证 - **10 种融合策略**：空间连接、属性连接、分区统计、点采样、波段叠加、矢量叠加、时态融合、点云高度赋值、栅格矢量化、最近邻连接 - **5 种数据模态**：矢量、栅格、表格、点云 (LAS/LAZ)、实时流 - **智能语义匹配**： - 四层渐进式匹配：精确 → 等价组 → 单位感知 → 模糊匹配 - **v7.0 向量嵌入匹配**：Gemini text-embedding-004 语义相似度（可选启用） - 目录驱动等价组 + 分词相似度 + 类型兼容检查 + 单位自动转换 - **LLM 增强策略路由 (v7.0)**：Gemini 2.0 Flash 根据用户意图智能推荐融合策略 - **分布式/核外计算 (v7.0)**：大数据集（>50万行/500MB）自动分块处理，避免 OOM - **地理知识图谱 (v7.0)**：networkx 实体关系建模，空间邻接/包含关系检测，N跳邻居查询 - **栅格自动处理**：CRS 重投影、分辨率重采样、大栅格窗口采样 - **增强质量验证**：10 项检查（空值率、几何有效性、拓扑验证、KS 分布偏移检测等） ### 数据治理 - 拓扑审计（重叠、自相交、间隙检测） - 字段合规性检查（GB/T 21010 国标） - 多模态校验：PDF 报告 vs SHP/数据库指标 - 自动生成治理报告（Word/PDF） - 多源数据融合（v6.0 集成） ### 空间优化 - 深度强化学习引擎（MaskablePPO）用地布局优化 - 耕地/林地配对交换，严格面积平衡 - 分类着色地图渲染（Categorized Layer）：按地类/变化类型自动着色，中文图例 ### 商业智能 - 语义查询：自然语言 → 自动映射 SQL + 空间算子 - 选址推理链（查询 → 缓冲 → 叠加 → 过滤） - DBSCAN 聚类、KDE 热力图、分级设色 - POI 搜索、驾车距离、批量/反向地理编码 - 交互式多图层合成 + 自然语言图层控制 ### 智能 Agent 协作 (v9.0) - **Agent Plugins**：CostGuard (Token 预算)、GISToolRetry (智能重试)、Provenance (数据溯源)、HITLApproval (人机审批) - **并行 Pipeline**：ParallelAgent 数据摄取，多源并行处理 - **跨会话记忆**：PostgresMemoryService 持久化对话记忆，跨会话上下文延续 - **智能任务分解**：TaskGraph DAG 分解 + 波次并行执行 - **Pipeline 分析**：延迟/成功率/Token 效率/吞吐量/Agent 分布 5 维度分析 - **Agent 生命周期钩子**：Prometheus 指标 + ProgressTracker 进度追踪 ### 生产就绪加固 (v9.5) - **Guardrails (4)**：InputLength (>50k 拒绝) + SQLInjection (注入检测) + OutputSanitizer (敏感信息清理) + Hallucination (幻觉警告)，递归挂载到所有子 Agent - **SSE Streaming**：`run_pipeline_streaming()` 异步流式输出 + `/api/pipeline/stream` REST 端点 - **LongRunningFunctionTool**：DRL 优化异步执行，防止 Agent 重复调用 - **集中测试夹具**：conftest.py 共享 fixture，事件循环安全隔离 ### 智能平台扩展 (v10.0) - **GraphRAG 知识增强**：实体抽取 (Gemini+正则) → 共现图谱构建 → 图增强检索（向量 + 图邻居重排序），9 个 KB 工具 - **Per-User MCP 隔离**：用户可创建私有 MCP 服务器，owner_username + is_shared 控制可见性 - **用户自定义技能包**：DB 驱动的工具集 + ADK Skills 自由组合，意图触发匹配 - **高级空间分析 Tier 2**：IDW 插值、Kriging、地理加权回归 (GWR)、多时相变化检测、DEM 可视域分析 - **工作流模板市场**：5 个预置模板 + 发布/克隆/评分，一键复用工作流 ### 多模态输入 (v5.2) - 图片理解：自动分类上传图片，Gemini 视觉分析 - PDF 解析：文本提取 + 原生 PDF Blob 双策略 - 语音输入：Web Speech API，中/英文切换 ### 3D 空间可视化 (v5.3) - deck.gl + maplibre 3D 渲染器 - 支持拉伸体、柱状图、弧线图、散点图层 - 2D/3D 视图一键切换 ### 工作流编排 (v5.4) - 多步管道链式执行，参数化 Prompt 模板 - React Flow 可视化拖拽编辑器（数据输入/管道/输出三种节点） - APScheduler Cron 定时执行 - Webhook 结果推送 ## 核心架构：多智能体协作网络 GIS Data Agent 采用了先进的**层级式多智能体架构（Hierarchical Multi-Agent Architecture）**。系统内置了三种主要的工作流（Pipeline），并由一个顶层的 `Dynamic Planner` 进行意图识别和动态分发，完美践行了 ADK 的 `Generator-Critic` 和 `AgentTool` 最佳实践。 ```mermaid graph TD User["用户输入"] --> Root["顶层 Agent"] Root --> Planner["Dynamic Planner"] Planner -- 优化 --> OptP["Data Pipeline"] Planner -- 治理 --> GovP["Governance Pipeline"] Planner -- 通用 --> GenP["General Pipeline"] OptP --> Exp1["Exploration"] --> Proc1["Processing"] Proc1 --> Ana1["Analysis"] --> QC["Quality Check"] QC -- 不达标 --> Ana1