LinkToolDocs/web/dev/dev-plan.md

GIS与LLM结合Web应用开发计划

一、项目概述

项目背景与目标

本项目的提出源于传统地理信息系统（GIS）操作门槛高、技术壁垒显著的行业痛点。传统GIS工具通常要求用户具备专业的空间分析知识和复杂操作技能，导致普通用户难以高效利用空间分析功能。为解决这一问题，项目定位为“自然语言驱动的空间分析Web应用”，旨在通过整合大型语言模型（LLM）的自然语言理解能力与GIS的空间分析工具，降低空间分析的技术门槛，实现地理信息处理的便捷化。

项目开发的核心背景之一是LLM与业务数据源的集成难题。由于LLM与传统数据源在技术架构上存在天然隔离，以往的集成方式多为碎片化的定制化开发，导致系统扩展性差、维护成本高。为此，项目引入模型上下文协议（MCP，Model Context Protocol）作为连接标准。MCP作为一种统一开放的协议，能够替代传统碎片化的定制集成方式，为AI系统（如LLM）与业务数据源（包括GIS工具、第三方地图服务等）提供安全的双向连接，解决LLM与数据源隔离导致的集成困难问题[1]。

基于上述背景，项目的核心目标是开发一个支持自然语言交互的空间分析Web应用。具体目标包括：用户通过自然语言描述空间分析需求，应用通过MCP协议调用空间分析工具及第三方服务（如高德地图等MCP服务）共同完成需求处理，并将分析结果通过前端地图组件可视化展示。此外，应用需支持多源数据集成与工具调用，实现“自然语言输入-空间分析处理-可视化输出”的全流程闭环，最终满足用户对地理信息处理便捷化、高效化的需求。通过这一目标的实现，项目将推动空间分析工具从专业领域向大众化应用场景延伸，提升地理信息服务的普惠性。

团队组成与分工

为确保项目架构分层（客户端UI/Host/Client层、服务端Server/Resource层）的高效落地，团队需采用客户端与服务端并行协作的组织模式，每组配置2名成员，具体分工如下：

客户端小组：

• 地图负责人：聚焦UI层实现，负责基于Leaflet的地图组件开发与图层管理，包括地图渲染、交互逻辑及多源数据图层的加载与控制；
• AI负责人：聚焦Host层功能，负责LLM调用流程设计、工具解析逻辑开发，以及基于AntDesignX的AI对话模块实现，支撑用户与系统的自然语言交互。

服务端小组：

• 常规负责人：聚焦Server/Resource层基础功能，负责数据库（PostgreSQL+PostGIS）设计与优化、用户鉴权等管理模块开发，保障数据存储与系统安全；
• AI负责人：聚焦AI服务能力构建，负责MCP（工具调用）模块开发、LLM接口适配与集成，实现AI能力与后端资源的协同调度。

协作机制：
为支撑并行开发，团队需明确关键节点输出物：技术验证阶段末完成接口需求文档编制；服务端基于此文档，于产品原型阶段初输出API文档及Mock服务，确保客户端可同步开展UI层与Host层的开发工作，提升整体研发效率。

二、开发计划

项目周期与阶段划分

本项目周期总计2.5个月，自2025年7月27日启动至2025年10月10日结束，整体按“可行性验证→快速迭代→优化交付”的逻辑划分为三个阶段，各阶段任务明确且依次递进。

技术验证阶段（2025年7月27日至2025年8月10日，约15天）为项目启动后的首个阶段，核心目标是完成技术可行性验证。该阶段需重点推进三项任务：一是技术栈选型，确定适配项目需求的开发框架、工具及平台；二是关键技术可行性验证，具体包括MCP协议实现、LLM与GIS功能集成机制、数据隔离方案等核心技术点的验证，确保技术路径的可行性；三是形成技术验证报告，为后续阶段奠定基础。

产品原型阶段（2025年8月11日至2025年8月25日，约15天）聚焦于快速迭代开发，以输出可演示的核心功能为目标。该阶段需实现“自然语言交互→空间分析→结果可视化”的完整核心功能链路，确保用户可通过自然语言输入触发GIS空间分析，并将分析结果以可视化方式呈现。通过原型演示验证产品核心价值与用户交互流程的合理性。

完善开发阶段（2025年8月26日至2025年10月10日，约45天）为项目的优化与交付阶段，重点围绕功能扩展、性能优化、测试与部署展开。在功能层面，基于原型反馈补充次要功能模块，提升产品完整性；在性能层面，针对系统响应速度、并发处理能力、数据加载效率等进行优化；同时完成全面的功能测试、兼容性测试及安全测试，并部署至生产环境，确保产品稳定交付。

为保障阶段目标达成，各阶段间需设置明确的里程碑评审机制。例如，技术验证阶段末需评审MCP协议实现方案及关键技术验证结果，产品原型阶段末需通过核心功能演示评审确认功能链路的完整性与可用性，确保项目按计划有序推进。

技术验证阶段（7.27-8.10）

目标与任务分解

本阶段核心目标为验证关键技术可行性，明确技术栈选型与接口规范，并输出最终技术方案。任务分解如下：

客户端技术验证：由地图负责人执行React+AntDesignX+Leaflet集成测试（7.27-8.1），确保前端地图组件与UI框架的兼容性；同时AI负责人需完成LLM流式响应与工具解析模块原型开发，验证前端与AI能力的交互机制。

服务端技术验证：常规负责人负责Spring Boot+Spring AI+PostgreSQL（含PostGIS）环境搭建及GeoServer部署与配置（7.28-8.2），构建基础数据存储与地图服务支撑；AI负责人需基于JSON-RPC 2.0实现MCP协议，并完成与通义百炼/Deepseek等LLM平台的接口适配及兼容性测试（8.6-8.8），确保服务端与AI模型的稳定通信。

跨团队协作任务：团队共同研究MCP官方规范（https://modelcontextprotocol.io/introduction），输出协议实现指南并完成基础MCP请求/响应格式开发（8.3-8.5）；设计PostgreSQL行级安全（RLS）策略以确保用户数据隔离，同步完成空间数据存储方案验证（8.7-8.9）；开发GeoServer REST API客户端用于地图服务发布，并协调客户端与服务端团队完成API需求文档输出及Mock服务部署（8.10），保障跨模块接口一致性。

交付物与评审标准

本阶段的交付物包括以下核心文档与成果，旨在全面覆盖技术验证阶段的关键技术输出与设计成果：

1. 《技术栈选型报告》：明确项目开发所需的技术组件与架构方案，包含选型依据及可行性分析；
2. 《技术验证报告》：涵盖各核心模块（如LLM集成、地图服务、MCP协议）的可行性结论与验证结果；
3. 《MCP协议实现指南》：详细说明多模态协作协议（MCP）的技术实现细节，指导后续开发；
4. 《数据库设计初稿》：初步完成数据模型与存储结构设计，为数据层开发提供基础；
5. 《API需求文档（客户端输出）与Mock服务》：明确客户端与服务端交互的接口规范，并提供模拟服务支持前端联调。

评审标准将从技术可行性、性能指标与功能完整性三个维度进行验证，具体包括：

1. 技术栈适配性：选型方案需满足性能要求，例如Leaflet地图渲染延迟需控制在500ms以内，且整体技术架构无重大风险；
2. 核心功能验证：MCP协议需支持Tools/Resources/Prompts三类服务调用，LLM接口需实现流式响应机制，确保交互流畅性；
3. 数据安全与隔离：基于行级安全（RLS）策略的用户数据隔离测试需通过验证，确保不同用户无法访问对方数据；
4. 文档完整性：API需求文档需覆盖客户端所有功能点，确保接口设计与业务需求一致；核心技术模块（LLM集成、MCP调用、地图服务）需通过综合验证，确认技术路径可行。

产品原型阶段（8.11-8.25）

目标与任务分解

本阶段的核心目标是交付可演示的最小原型，实现“用户输入自然语言→LLM解析→调用GIS工具→结果可视化”的全流程闭环，并完成核心功能开发及前后端联调。

任务分解如下：

• 客户端：

  1. UI层开发由地图负责人负责，包括地图组件渲染（含图层管理控件、符号化渲染）及AI对话界面实现（支持流式输出与历史记录），其中地图组件开发周期为8.11-8.18，AI对话界面实现周期为8.12-8.19；
  2. 功能模块开发由AI负责人负责，包括Host层工具解析模块（XML格式解析至MCP服务调用逻辑）及Client层MCP客户端（HTTP/SSE请求处理），开发周期为8.15-8.22。

• 服务端：

  1. AI负责人负责Server层MCP模块开发（封装GIS分析工具接口与数据获取接口）及地图服务封装（基于GeoServer REST API实现WMS/WFS接口），其中MCP服务接口开发周期为8.11-8.20，地图服务封装周期为8.13-8.21；
  2. 常规负责人负责管理模块实现（用户登录/注册、权限控制）及数据库表结构完善（含RLS策略部署），用户认证系统实现周期为8.16-8.23。

• 跨团队协作：
  服务端需在8.15前依据客户端API需求文档完成Mock服务部署，客户端需在8.20前完成与Mock服务的联调，并最终在8.24-8.25期间完成客户端与服务端的接口联调。

交付物与评审标准

交付物包括可运行的产品原型（前端界面与后端服务）、《API文档（含Mock配置）》《数据库表结构终稿》及联调测试报告。其中，产品原型需整合客户端的地图与AI对话模块，以实现前端交互与后端服务的联动；API文档应涵盖MCP、地图、认证等核心接口的详细定义及Mock配置；联调测试报告需记录系统集成过程中的测试结果。

评审标准涵盖功能完整性、性能指标及安全要求。功能层面，原型需支持至少2个典型场景（如“分析海珠区建筑密度”“规划广州塔出发路线”），且核心功能流程（自然语言输入→MCP调用→结果渲染）需完整贯通；性能指标方面，自然语言解析准确率需大于80%，API接口覆盖率≥90%，联调测试通过率≥85%；结果呈现要求地图结果渲染正确（符号化显示分析结果）；安全层面需确保用户数据隔离生效。

指标类别	具体指标	要求值	说明
功能完整性	核心功能流程完整性	100%	自然语言输入→MCP调用→结果渲染完整贯通
	典型场景支持数量	≥2个	如“分析海珠区建筑密度”“规划广州塔出发路线”
性能指标	自然语言解析准确率	>80%	用户自然语言指令解析准确度
	API接口覆盖率	≥90%	MCP/地图/认证等核心接口覆盖程度
	联调测试通过率	≥85%	系统集成测试通过率
结果呈现	地图渲染正确率	100%	符号化显示分析结果
安全要求	用户数据隔离生效	100%	用户间数据访问隔离机制

完善开发阶段（8.26-10.10）

目标与任务分解

本阶段的核心目标是提升系统稳定性、完善功能覆盖、完成全面测试并实现部署上线。具体任务分解如下：

功能扩展：

• 客户端：增加管理设置模块（含MCP服务管理、模型参数配置），由AI负责人负责；优化地图组件符号化样式，由地图负责人负责；同步进行客户端交互优化，实施周期为8月26日至9月10日。
• 服务端：增加日志模块与任务进度跟踪功能，由常规负责人负责；扩展对第三方MCP服务的支持（如集成ArcGIS工具），由AI负责人负责；同步开展服务端性能调优，实施周期为8月26日至9月15日。

测试与优化：

• 单元测试：覆盖核心模块代码比例需达到80%以上，实施周期为9月11日至9月25日。
• 集成测试：包含性能测试与安全测试，其中性能测试要求并发用户数≥10时系统响应时间<2秒，安全测试需实现SQL注入防护与XSS过滤功能，实施周期为9月26日至10月1日。
• 用户验收测试：验证系统功能与用户需求的一致性，实施周期为10月2日至10月5日。

部署：

• Docker容器化打包：整合前端、后端、数据库及GeoServer服务进行统一容器化封装，实施周期为9月20日至9月25日。
• 生产环境部署与文档编写：完成容器化应用的生产环境部署，并编写详细的部署文档，实施周期为10月6日至10月10日。

交付物与验收标准

本阶段的交付物包括在生产环境中部署的Web应用（最终版本，包含所有功能模块）、《用户手册》《开发文档》《测试报告》（测试覆盖率需达到95%及以上）、《Docker部署脚本》及配套的部署文档与运维手册。这些交付物需完整覆盖项目从应用使用、开发过程、测试验证到部署运维的全流程需求，确保应用交付后具备可维护性与可扩展性。

验收标准需从功能完整性、系统稳定性、性能指标、用户验证及数据安全五个维度进行评估。在功能方面，Web应用需覆盖所有需求点，包括自然语言交互、空间分析、结果可视化及用户管理模块，并满足需求文档中的具体功能要求。系统稳定性要求连续运行72小时无崩溃，且无致命bug。性能指标需同时满足页面加载时间小于3秒、分析任务执行时间小于10秒、响应时间不超过2秒，以及并发量不低于100的要求。用户验收测试通过率需达到100%，确保应用符合用户实际使用需求。此外，数据安全需严格遵守用户数据隔离要求，确保数据处理与存储的合规性。

指标类型	要求阈值	单位
页面加载时间	<3	秒
分析任务执行时间	<10	秒
响应时间	≤2	秒
并发量	≥100	请求数

三、设计与实施方案

整体架构设计

分层架构

本项目的分层架构设计遵循“前后端分离+分层解耦”原则，将系统划分为客户端三层与服务端两层，各层职责明确且通过标准化接口实现通信，以提升系统的可维护性与扩展性。

客户端三层聚焦用户交互与协议调用，自上而下包括UI层、Host层与Client层。UI层基于React组件构建，负责接收用户输入（如GIS查询参数、LLM指令）并渲染结果（如地图可视化、自然语言回答），实现页面的动态交互与数据展示。Host层作为核心协调者，集成LLM基座与工具解析模块，承担逻辑调度职能：一方面管理Client层实例的生命周期、控制连接权限及执行安全策略，另一方面协调AI能力与GIS工具的调用流程，确保用户请求的合理分发[2]。Client层作为MCP协议的具体实现者，由Host层动态创建并与服务端保持1:1连接，负责按MCP协议规范发起请求、建立有状态会话、处理协议协商及消息路由，支持HTTP/SSE、stdio等多种传输方式[1][3]。

服务端两层专注于业务逻辑处理与资源管理，包含Server层与Resource层。Server层提供HTTP接口，集成MCP模块、地图服务、管理模块及LLM模块，通过解析Client层请求并分派给对应实现者，完成业务逻辑的处理与协调[1]。Resource层作为数据与工具的底层支撑，通过PostgreSQL数据库与文件系统实现数据持久化，并连接第三方数据源或工具（如数据库、文件系统、API服务），为上层提供资源访问能力[2]。

层间通信机制基于清晰定义的接口实现解耦。UI层通过调用Host层的LLM请求方法触发业务流程；Host层通过调用Client层的MCP执行方法完成协议转换与请求转发；Client层与Server层基于JSON-RPC 2.0协议进行通信，支持认证/授权机制（如OAuth 2/OIDC）以保障交互安全性[1]。整体架构通过“客户端-主机-服务器”模式实现跨层协作，其中Host作为协议核心协调者，Client与Server通过MCP协议建立有状态会话，确保上下文交换与采样协调的高效性[4][5][6]。

核心技术栈

核心技术栈的选择以“功能适配+开发效率+性能优化”为核心原则，需在满足GIS与LLM融合需求的同时，确保系统稳定性与部署便捷性。具体技术组合及选型依据如下：

层级	组件	版本/模式	核心功能	参考依据
前端	React	18	组件化开发框架
	TypeScript	5.2	类型安全开发
	Leaflet	1.9.4	轻量级地理数据可视化
	AntDesignX	-	AI对话场景组件库
	JSON-RPC	2.0	消息协议标准	[9][10]
	HTTP传输	Streamable	大数据流交互(取代HTTP+SSE)	[9][10]
	npm	10.5	依赖管理
后端	Spring Boot	3.2	微服务框架
	Spring AI	0.8.0	LLM集成引擎	[11]
	GeoServer	2.23.0	WMS/WFS地理服务
	MCP协议	stdio/SSE/Streamable	进程通信/长连接推送/大数据流传输	[12][13]
	OAuth	2.1	用户认证框架	[9][10]
	Maven	3.9	依赖管理
数据存储	PostgreSQL	16	关系型数据库
	PostGIS	3.4	空间数据扩展
部署	Docker	26.1	容器化封装
	Nginx	-	前端资源托管
	Docker Compose	-	多容器协同部署
扩展	JSON-RPC批处理	-	提升接口调用效率	[9][10]
	多模态数据	文本/图像/音频	多类型内容支持	[9][10]
	参数自动补全	-	交互体验增强	[9][10]

参考依据索引:
[1] JSON-RPC 2.0协议规范
[2] Streamable传输模式解析
[3] Spring AI集成方案
[4] MCP协议传输方式
[5] MCP协议规范

前端技术栈
采用React 18作为核心框架，搭配TypeScript 5.2实现组件化开发与类型安全，通过schema.ts中的TypeScript模式定义权威协议需求，确保前后端数据交互的一致性[4][5]。地图渲染采用Leaflet 1.9.4，其轻量特性可高效适配地理数据可视化需求；UI组件层集成AntDesignX，提供AI对话场景所需的流式输出、历史记录管理等预制组件，提升开发效率。通信协议基于JSON-RPC 2.0消息格式，传输方式采用Streamable HTTP以支持灵活的大数据流交互（取代传统HTTP+SSE模式），满足LLM响应实时性要求[4][5][7]。前端依赖管理工具选用npm 10.5，确保包版本一致性与依赖解析效率。

后端技术栈
后端框架采用Spring Boot 3.2，结合Spring AI 0.8.0简化LLM模型集成流程，支持多语言SDK（如Java、Python）的灵活调用[1]。地理数据服务通过GeoServer 2.23.0实现，提供WMS/WFS标准接口以支撑地图图层发布与空间数据查询。通信层基于MCP协议架构，支持标准输入输出（stdio）用于本地进程间高效通信、服务器发送事件（SSE）实现HTTP长连接推送，以及社区支持的Streamable传输模式（适用于大数据流场景）[7][8]。安全授权方面，集成OAuth 2.1框架确保用户认证与权限控制的全面性[4][5]。后端依赖管理采用Maven 3.9，实现依赖包的自动化构建与版本管控。

数据存储层
采用PostgreSQL 16作为基础数据库，搭配PostGIS 3.4扩展模块，提供空间数据类型（如Geometry）与空间索引能力，支持高效的地理查询（如缓冲区分析、空间叠加）。该组合满足GIS应用中矢量数据存储、拓扑关系管理及复杂空间运算需求，同时兼容关系型数据与空间数据的统一管理。

容器化与部署
通过Docker 26.1实现应用容器化封装，确保开发、测试与生产环境的一致性。前端资源打包为Nginx容器镜像，后端服务与数据库分别构建独立容器，通过Docker Compose实现多容器协同部署，简化跨环境迁移与运维流程。

扩展支持
技术栈支持JSON-RPC批处理请求以提升接口调用效率，兼容文本、图像及音频多模态数据传输，并提供参数自动补全建议功能，增强用户交互体验[4][5]。

数据库设计

表结构设计

本系统设计6张核心数据表，所有表均包含user_id字段以支持行级安全（RLS）隔离机制，确保数据访问的安全性与用户数据隔离。各表结构如下：

• users（用户表）：存储用户基本信息及认证数据，字段包括id（主键，PK）、username（用户名）、password_hash（密码哈希）、api_key（LLM平台访问密钥）、role（用户角色，取值为admin或user）、created_at（创建时间）。其中id作为唯一标识，password_hash保障密码存储安全，role字段用于权限控制。

• conversations（对话表）：记录用户与LLM的对话会话信息，字段包括id（主键，PK）、user_id（外键，FK，关联users表）、title（对话标题）、created_at（创建时间）、updated_at（更新时间）。user_id实现对话数据的用户隔离，title便于用户识别不同对话，updated_at追踪对话最新活动时间。

• conversation_messages（对话消息表）：存储单轮对话消息内容，字段包括id（主键，PK）、conversation_id（外键，FK，关联conversations表）、role（消息角色，取值为user或ai）、content（消息内容）、created_at（创建时间）。通过conversation_id关联至具体对话，role区分消息发送方，content记录消息文本。

• spatial_tasks（空间分析任务表）：管理GIS空间分析任务的生命周期，字段包括id（主键，PK）、user_id（外键，FK，关联users表）、mcp_service（调用的MCP服务名称）、tool_name（使用的空间分析工具名称）、parameters（任务参数，JSON格式）、status（任务状态，取值为pending、running、success或failed）、result_path（分析结果存储路径）、created_at（创建时间）、updated_at（更新时间）。parameters支持复杂参数结构，status追踪任务进度，result_path指向结果数据存储位置。

• mcp_services（MCP服务配置表）：配置外部空间分析服务的连接信息，字段包括id（主键，PK）、user_id（外键，FK，关联users表）、name（服务名称）、type（服务类型，取值为Tools、Prompts或Resources）、url（服务访问地址）、auth_type（认证方式，取值为OAuth 2.1或API Key）、config（服务配置参数，JSON格式）、is_enabled（服务启用状态）。type区分服务类别，auth_type与config保障服务调用的安全性与正确性。

• map_layers（地图图层表）：管理用户自定义地图图层信息，字段包括id（主键，PK）、user_id（外键，FK，关联users表）、name（图层名称）、data_source（数据源地址，支持WMS或WFS协议）、style_config（图层样式配置，JSON格式）、is_visible（图层可见状态）。data_source指定空间数据来源，style_config控制图层可视化效果，is_visible支持图层显示切换。

为实现RLS隔离，需对上述表配置访问策略。例如，针对spatial_tasks表的RLS策略可定义为：CREATE POLICY user_spatial_tasks ON spatial_tasks FOR ALL USING (user_id = current_user_id());，确保用户仅能访问自身创建的空间分析任务数据。

索引与性能优化

为提升系统查询效率，需针对高频访问字段设计合理的索引策略，并结合性能优化措施保障系统响应速度。在常规字段索引设计方面，应在用户表（users）的api_key字段创建唯一索引，以加速用户身份验证过程；在对话记录表（conversations）中基于user_id构建复合索引，优化用户对话历史的查询效率；在空间分析任务表（spatial_tasks）中，针对user_id与status创建复合索引，同时补充对task_id字段的索引，以支持任务状态筛选与单任务查询场景；在地图图层表（map_layers）中，基于user_id与is_visible构建复合索引，提升图层可见性状态的检索速度。此外，用户表、对话记录表及空间分析任务表均需对user_id字段单独创建索引，进一步强化用户维度数据的查询性能。

在空间数据查询优化方面，需利用PostGIS扩展提供的空间索引能力。针对spatial_tasks表中存储结果空间数据的字段（如result_geom），创建GIST索引，以显著加速空间关系判断、范围查询等地理操作。

性能优化措施还包括数据隔离与访问控制机制。通过启用PostgreSQL的行级安全策略（RLS），可实现用户数据的逻辑隔离，防止跨用户数据访问，同时避免因权限校验导致的性能损耗。结合上述索引策略与安全机制，系统可在保障数据安全性的前提下，实现高效的数据检索与空间分析处理。

模块功能设计

客户端模块

UI层

UI层按功能划分子模块，每个子模块实现特定组件与交互函数，具体包括地图组件、AI对话模块和管理设置模块，各模块基于前端技术栈实现组件渲染与用户交互。

地图组件基于Leaflet实现，核心组件包括：MapRenderer负责初始化Leaflet地图实例并加载WMS/WFS地理数据图层；LayerManager提供图层管理功能，支持图层显隐控制与顺序调整，关键函数包括toggleLayer(id)（切换指定ID图层的可见性）和reorderLayers(ids)（按ID序列重新排列图层顺序）；Symbolizer组件根据预设规则对分析结果进行符号化渲染，通过renderResult(geom, style)函数接收几何对象与样式参数并完成可视化呈现。

AI对话模块采用AntDesignX组件库构建，包含三个核心组件：ChatWindow负责展示对话气泡界面，支持用户与AI的消息交互，提供addMessage(role, content)函数添加对话内容，并支持文件上传功能；StreamRenderer处理LLM的流式响应，通过streamResponse(chunk)函数实时接收并渲染响应片段；ChatHistory组件管理对话历史记录，提供loadHistory(conversationId)（加载指定会话ID的历史记录）和saveHistory(conversation)（保存当前对话内容）函数。

管理设置模块涵盖系统配置与用户管理功能，主要组件包括：McpServiceManager实现MCP服务配置的CRUD操作；ModelConfig组件支持LLM模型管理与参数调整，可配置TopP、Temperature等关键参数；UserAuth提供用户登录与注册表单，实现身份验证功能。

Host层

Host层作为GIS与LLM结合Web应用的核心协调与执行层，承担用户交互、LLM集成及工具调用的关键职责，其核心功能围绕模块设计与跨层协调展开。

核心模块及方法方面，Host层包含两大核心组件：

• LLM基座：通过抽象类LLMClient实现不同厂商API的统一调用，其核心方法requestStream(prompt, model, params)支持发起流式请求并返回Observable对象，确保与LLM服务的高效交互。该设计旨在屏蔽底层API差异，为上层应用提供标准化接口。
• 工具解析模块：通过ToolParser实现LLM响应的工具调用解析与执行，具体包括parseToolCall(response)和executeTool(toolName, params)方法。其中，parseToolCall负责从LLM响应中提取XML格式的工具调用信息（如\<tool name="arcgis:clip_analysis" params="{...}"/>），而executeTool则根据解析结果调用Client层对应MCP客户端执行具体工具，实现GIS功能与LLM能力的衔接[7]。

在协调与管理职责上，Host层作为容器和协调器，需创建并管理多个客户端实例，控制连接权限与生命周期，执行安全策略及用户授权决策，并处理跨客户端的上下文聚合[4][5]。同时，其需协调AI/LLM的集成与采样过程，确保用户交互与后端工具调用的高效协同，为应用提供统一的执行环境与安全保障。

Client层

Client层作为MCP（Map Collaboration Protocol）服务的客户端实现层，需根据服务类型差异化构建客户端组件，具体实现方式如下：

McpHttpClient用于处理HTTP类MCP服务，通过封装HTTP请求逻辑提供核心功能方法：

• getResource(uri)：调用Resources服务，通过GET请求获取指定URI的地理空间资源数据，支撑客户端资源管理能力；
• callTool(name, params)：调用Tools服务，采用POST请求并遵循JSON-RPC格式传递工具名称与参数，实现LLM工具调用功能；
• getPrompt(templateId, params)：调用Prompts服务，根据模板ID获取预设提示模板并动态填充参数，支持提示模板选择与个性化配置。

McpSseClient专注于处理SSE（Server-Sent Events）流式MCP服务，核心方法为subscribeToolProgress(toolId)，通过建立持久化连接订阅工具执行进度通知，实现流式状态更新。

Client层需维护与服务端的1:1专属连接，承担协议协商、消息路由及有状态会话管理职责，确保通信链路的稳定性与数据一致性[8]。此外，该层集成资源管理、提示模板选择、工具调用等基础功能，并支持多用户会话管理，例如通过Cloudflare Durable Objects等技术实现会话状态的持久化存储，满足多用户并发场景下的会话隔离需求[1][14]。

服务端模块

Server层

Server层作为GIS与LLM结合Web应用的核心服务中枢，负责处理客户端请求、协调各功能模块交互及资源调度，主要包含以下核心模块及关键方法：

MCP模块
该模块通过McpController实现对MCP（Multi-Component Protocol）请求的统一处理，对外暴露接口路径/api/mcp，核心功能涵盖工具调用、资源查询及提示词模板管理[7][15]。具体方法包括：getResources(uri, userId)用于根据资源标识（uri）和用户ID查询系统资源；callTool(toolName, params, userId)接收工具名称、参数及用户ID，执行指定工具并返回处理结果；getPrompts(templateId, params)根据模板ID和动态参数获取预定义的提示词模板，支持LLM交互流程的标准化。

地图服务模块
基于GeoServerClient组件封装GeoServer REST API调用逻辑，实现地理数据服务的发布与访问[15]。核心方法包括：publishLayer(layerConfig)根据图层配置信息（如数据源、样式、投影等）在GeoServer中发布新图层；getWmsUrl(layerId)根据图层唯一标识生成符合OGC标准的WMS服务URL，支持客户端地图渲染。

管理模块
该模块负责用户生命周期管理与安全认证，包含两个核心控制器：UserController提供用户CRUD操作，接口路径为/api/users；AuthController处理用户登录与注册请求，路径为/api/auth，并基于JWT（JSON Web Token）实现身份鉴权[1]。通过OAuth2.1协议规范用户认证流程，确保系统访问的安全性与可控性。

LLM模块
通过LLMService组件实现对多厂商大模型API的适配与统一调用，支持通义百炼、Deepseek等主流模型[15]。核心方法streamCompletion(prompt, model, userId)支持发起流式对话请求，以响应式编程方式返回Flux\<Chunk>类型结果，满足LLM交互过程中的实时数据传输需求，提升用户体验。

Server层各模块通过标准化接口与协议（如HTTP/JSON-RPC 2.0）协同工作，实现工具调用、地理数据服务、用户管理及LLM能力的有机整合，为应用提供高效、可靠的后端支撑[1]。

Resource层

Resource层作为系统的数据持久化与外部服务对接核心，负责管理数据存储、访问及外部交互，其设计需满足数据安全性、访问灵活性及服务集成可靠性。

在数据库访问方面，该层通过SpatialTaskRepository与UserRepository实现结构化数据的持久化管理。其中，SpatialTaskRepository提供空间任务的CRUD（创建、读取、更新、删除）操作，支持地理空间数据的高效存取；UserRepository则专注于用户数据访问，集成行级安全（RLS）过滤机制，通过应用程序控制访问权限以保障数据安全，确保用户仅能访问其权限范围内的数据[15]。此类数据库交互符合资源（Resources）作为“可被客户端读取并用作与LLM交互的上下文数据”的核心定位，支持通过参数化查询动态获取指定条件的数据，例如基于用户ID或任务ID的过滤查询[16]。

文件系统模块通过ResultStorage组件管理非结构化分析结果文件，采用URI风格路径设计，存储路径规范为/data/{userId}/{taskId}/。该设计借鉴资源访问的URI路径特性，支持按用户和任务维度对结果文件进行分层组织，便于缓存与读取操作[16]。典型场景包括存储LLM生成的地理空间分析报告、可视化图表等，客户端可通过类似REST API的GET请求访问指定路径下的文件内容。

在第三方集成层面，Resource层通过AmapClient与GeoServerManager实现外部服务对接。AmapClient负责调用高德地图API，获取地理编码、路径规划等基础地理服务数据；GeoServerManager则用于管理GeoServer工作区与图层，实现空间数据的发布与可视化。此类集成符合资源作为“与外部服务交互桥梁”的定位，支持将第三方服务返回的结构化数据流（如地图瓦片、空间分析结果）转化为LLM可处理的上下文数据，同时通过应用层权限控制保障外部服务调用的安全性[14]。

综上，Resource层通过数据库访问、文件系统管理及第三方集成的协同设计，构建了高效、安全、可扩展的数据与服务访问体系，为上层业务逻辑提供稳定的数据支撑与外部能力对接。其实现需遵循资源的只读操作特性、URI路径规范及缓存优化策略，确保系统在数据密集型场景下的性能与可靠性[16]。

模块名称	组件	功能	特点/设计
数据库访问	SpatialTaskRepository	提供空间任务的CRUD操作，支持地理空间数据的高效存取	支持行级安全（RLS）过滤机制，通过应用程序控制访问权限以保障数据安全
	UserRepository	用户数据访问
文件系统	ResultStorage	管理非结构化分析结果文件	存储路径规范为/data/{userId}/{taskId}/，支持按用户和任务维度分层组织
第三方集成	AmapClient	调用高德地图API，获取地理编码、路径规划等基础地理服务数据	将第三方服务返回的结构化数据流转化为LLM可处理的上下文数据
	GeoServerManager	管理GeoServer工作区与图层，实现空间数据的发布与可视化

HTTP接口定义

核心接口列表

本章节按功能模块定义HTTP接口，明确路径、方法、参数及响应格式，具体如下：

模块	路径	方法	参数	响应格式
LLM接口	POST /api/llm/stream	POST	prompt：对话提示文本<br>model：模型名称<br>userId：用户唯一标识	Server-Sent Events格式：<br>- chunk：流式对话内容片段<br>- done：对话结束标识
MCP工具调用	POST /api/mcp/tools/call	POST	serviceName：服务名称<br>toolName：工具名称<br>params：工具参数<br>userId：用户标识	JSON对象：<br>{success: boolean, result: any}<br>[3][16]
地图服务	GET /api/map/wms	GET	layerId：图层标识<br>bbox：边界框坐标<br>width：图片宽度<br>height：图片高度	图片流（渲染后的地图图层）
用户登录	POST /api/auth/login	POST	username：用户名<br>password：密码	JSON对象：<br>{token: string, user: User}
对话列表	GET /api/conversations	GET	userId：用户唯一标识	JSON数组：<br>[{id, title, createdAt}, ...]

• LLM接口
  路径：POST /api/llm/stream，方法：POST，功能：提供流式对话服务。参数包括prompt（对话提示文本）、model（模型名称）、userId（用户唯一标识）。响应采用Server-Sent Events（SSE）格式，包含两类事件：chunk（返回流式对话内容片段）和done（标识对话结束）。

• MCP工具调用接口
  路径：POST /api/mcp/tools/call，方法：POST，功能：调用Tools服务执行特定工具操作。该接口基于JSON-RPC 2.0协议实现，支持请求（含唯一ID和方法名）、响应（与请求ID对应，包含成功结果或错误信息）及通知（无ID单向消息）三种消息类型[6]。参数包括serviceName（服务名称）、toolName（工具名称）、params（工具执行参数）、userId（用户唯一标识）。响应格式为JSON对象：{success: boolean, result: any}，其中success指示调用是否成功，result返回工具执行结果[3][16]。

• 地图服务接口
  路径：GET /api/map/wms，方法：GET，功能：获取WMS（Web Map Service）图层数据。参数包括layerId（图层唯一标识）、bbox（边界框坐标，格式为minx,miny,maxx,maxy）、width（图片宽度）、height（图片高度）。响应为图片流，直接返回渲染后的地图图层图像。

• 用户接口

  • 登录接口：路径POST /api/auth/login，方法：POST，功能：用户身份验证。参数包括username（用户名）、password（密码）。响应格式为JSON对象：{token: string, user: User}，其中token为身份认证令牌，user为用户基本信息。
  • 对话列表接口：路径GET /api/conversations，方法：GET，功能：获取用户历史对话列表。参数包括userId（用户唯一标识）。响应格式为JSON数组：[{id, title, createdAt}, ...]，数组元素包含对话id（唯一标识）、title（对话标题）、createdAt（创建时间）。

四、配套讲解PPT

PPT结构设计

本PPT遵循“认知→技术→执行”的逻辑主线，采用模块化设计，共分为6个核心部分，各模块内容及页数规划如下：

项目概述（1-2页）
该部分旨在建立听众对项目的整体认知，包含三个核心要素：背景层面，重点阐述LLM与数据源隔离的行业痛点，引出项目立项的必要性[1]；目标层面，明确解决上述问题的核心方向；核心功能演示层面，通过截图或流程图直观展示系统交互逻辑，突出MCP（Model Context Protocol）的核心组件（Resources/Prompts/Tools）在功能实现中的作用[1]。

架构设计（3-4页）
以分层设计为核心，展示系统的技术骨架。首先呈现5层架构图，清晰标注各层职责与边界；其次通过模块交互流程图详细说明数据流转路径，即从UI层发起请求，依次经过Host层、Client层、Server层，最终与Resource层进行数据交互。该架构设计需体现MCP协议在资源隔离与交互中的关键作用，同时可结合Python/Go服务器实现示例，说明技术落地的可行性[1]。

技术栈详解（5-6页）
系统梳理项目技术体系，分为三个维度：前端、后端及DevOps技术栈列表，明确各环节的工具选型；关键技术点深度解析，重点包括MCP协议的三类服务（解决LLM与数据源隔离问题）、PostgreSQL行级安全控制（RLS）及GeoServer REST API（地理数据服务接口）[1]；技术选型依据说明，如选择Python/Go作为服务器开发语言的性能与兼容性考量。

开发计划（3-4页）
以时间轴甘特图为主视觉元素，呈现项目全周期管理。内容包括阶段任务划分（如需求分析、架构设计、开发测试、部署上线）、各阶段交付物清单（如需求文档、架构蓝图、测试报告），以及团队分工矩阵（明确角色与职责）。长期维护计划可参考MCP协议的更新机制，即基于GitHub进行版本管理，每3-6个月进行技术迭代[17]。

协作流程（2-3页）
聚焦跨团队协同效率，分两部分展开：技术协作流程，涵盖接口梳理、API文档生成、Mock服务联调的全链路环节，确保前后端接口协调一致；沟通机制，明确每日站会（进度同步）、周评审会（问题复盘与计划调整）的执行规范，保障信息流转高效透明。

质量要求（2页）
从标准层面保障项目交付质量，包括代码规范（如命名规则、注释要求）、测试标准（单元测试覆盖率≥80%、接口响应时间≤500ms等性能指标），以及交付验收标准（功能完整性、兼容性、安全性验证流程），确保最终成果符合设计预期与业务需求。

技术培训重点

技术培训分模块设计实操内容，各模块需结合技术规范与最佳实践，确保开发能力的系统性构建：

前端培训聚焦用户交互与地图可视化实现，核心内容包括：基于React+TypeScript的项目工程化搭建，重点强化组件化开发与类型安全；Leaflet地图组件开发，涵盖图层加载、叠加与管理逻辑，实现地理数据的可视化呈现；AntDesignX AI对话组件的集成与定制，满足自然语言交互界面需求；SSE客户端流式响应处理，结合传输协议特性（如SSE在实时数据推送场景的适用性），确保LLM生成内容的流畅展示[2]。

后端培训侧重服务集成与数据安全管控，具体包括：Spring Boot框架与Spring AI的集成方案，实现LLM模型的调用与管理；基于JSON-RPC 2.0规范的MCP协议实现，需明确Host/Client/Server核心组件的职责划分及交互逻辑，保障跨服务通信的标准化[1][2]；PostgreSQL数据库配置，结合PostGIS扩展实现空间数据存储，并通过行级安全策略（RLS）强化数据访问控制，落实安全最佳实践中的权限管理要求[18]；GeoServer REST API的封装与调用，实现地理空间服务的动态管理。

联合培训旨在打通前后端协作流程，关键内容包含：MCP协议三类服务调用的实操演练，需基于功能模块分层控制设计——Resources服务（由应用控制）用于地理数据获取，Tools服务（由AI控制）执行空间分析任务，Prompts服务（由用户控制）生成定制化提示模板，结合多语言SDK（如TypeScript前端与Java后端）的协同使用[1][2]；前后端联调环节重点训练Mock服务的配置与应用，依据联调规范完成API文档验证、错误码定义及接口兼容性测试，确保整体系统交互的稳定性。

培训过程中需同步强调技术选型的核心考量，如MCP协议实现需评估开放性、生态支持、安全性等要素，传输协议选择需结合场景特性（如stdio适用于轻量交互，SSE适用于流式响应），以提升开发团队对技术栈的综合把控能力[2][19]。

项目要求与风险提示

项目要求是确保开发过程规范可控、成果可交付的基础，需明确技术规范、文档标准与管理流程；风险提示则需针对潜在技术瓶颈与外部依赖风险制定前瞻性应对策略，保障项目稳定性与可持续性。

项目要求方面，需严格遵循开发流程规范与质量标准：代码管理采用Git Flow工作流以实现分支策略标准化，确保代码提交的可追溯性与版本控制效率；文档体系需覆盖API接口文档、开发手册及用户操作指南，确保团队协作与后期维护的顺畅性；进度管理通过JIRA任务跟踪系统实现需求拆解、工时评估与里程碑监控，保障开发节奏与交付节点可控。此外，安全性与性能要求需作为核心指标纳入开发规范：安全性层面，需实现基于角色的权限管理、敏感数据加密传输及操作日志审计功能，严格控制地理数据与用户信息的访问权限[4]；性能层面，需重点评估高并发场景下的实时响应能力（如多用户同时发起空间查询请求）及大规模数据交互时的系统负载能力，确保地图服务响应时间≤2秒，满足用户体验需求[2]。

风险提示需聚焦技术依赖与系统稳定性，制定分层应对方案：

• MCP协议相关风险：作为GIS与LLM交互的核心协议，其兼容性与生态成熟度直接影响集成效率。需关注协议规范每3-6个月的更新频率，建立版本跟踪机制以提前适配接口变更[1]；同时优先选择社区活跃度高、文档示例完善的MCP实现库，降低生态依赖风险，并在开发初期与协议厂商开展联合测试，验证数据交互的稳定性[2]。
• LLM接口与第三方服务风险：外部LLM API调用存在限流、延迟波动等不确定性，需实现多厂商 fallback 机制（如同时对接OpenAI与开源模型接口），并对高频查询结果建立本地缓存以降级响应；针对第三方地图服务或空间数据库，需优化连接池配置与索引策略，缓解高并发下的数据库性能瓶颈[2]。
• 性能与安全风险：空间分析模块在处理大规模矢量数据或复杂拓扑计算时易出现性能瓶颈，需通过空间索引优化（如R树、四叉树）与批量任务异步处理提升效率；多用户并发场景下，需采用会话管理机制（如Cloudflare Durable Objects的休眠/唤醒策略）避免资源泄露[1]；安全层面需实施输入校验、参数过滤及传输加密（TLS 1.3）等措施，并遵循最小权限原则，确保工具调用与数据访问需经用户显式批准，防范注入攻击与数据越权风险[4]。

通过明确项目要求与风险应对措施，可系统性降低开发过程中的不确定性，为GIS与LLM融合应用的稳定交付提供保障。