有状态 GIS 智能体
系统边界与职责划分
LLM 不直接执行 GIS 代码。它在工具结构约束下选择下一步；本地 GIS 工具完成数据读取、制图、综合和渲染；每次结果写入状态和版本，供后续修改复用。
规划：自然语言需求 →
结构化意图 → 工具调用执行：GeoPandas /
Shapely / Matplotlib 完成真实空间处理延续：MapState、版本与工具追踪支撑可追溯的多轮编辑
项目定义
不是“LLM 生成地图代码”，而是一条受约束的 GIS 任务链
Map-LLM 将自然语言理解、工具协议、空间计算和状态版本拆开负责：模型做规划，本地 GIS 工具做确定性执行，MapState 让下一轮操作继续基于已有地图。
三项核心能力
自动成图、路网综合、增量调整，构成完整的 GIS 智能体闭环
从首次制图到路网综合、持续修改的三个任务阶段，展示自然语言输入如何转为工具调用、地图结果和可追溯状态。
01 · 自动制图
单一尺度自动成图
用户只需要用自然语言描述想要制作的地图，例如地图范围、标题、行政区划、道路网络以及比例尺、指北针等要求，系统就会自动理解需求，调用本地地理数据和制图工具，将不同地图要素进行组合、样式配置和渲染，最终生成指定尺度下的专题地图。
状态结果：工具执行完成后，统一工具状态汇总为
MapState，保存图层、样式、版式、输出路径和初始版本，供下一轮复用。
02 · 路网综合
多尺度路网综合
在已有道路数据基础上，用户可以通过自然语言指定目标比例尺或综合要求，系统自动调用 Stroke 构建、网眼密度、层次选取、GCNN 等路网综合算法，对原始大比例尺道路网络进行筛选、简化和缩编，在尽量保留主要道路结构和路网特征的同时，生成更适合小比例尺地图展示的道路网络，并能够对比展示综合前后的结果。
结果链：统一引擎输出综合前后的统计指标与结果文件，写入路网综合
MapState；综合结果可视化工具再生成可对比的地图视图。
03 · 动态调整
多轮动态调整
用户不需要重新描述整张地图，只需要继续输入“把高速公路改成红色”“删除铁路图层”“调整综合参数”“修改标题”等指令，系统就会读取当前地图状态，识别具体修改内容，在已有结果上进行局部调整并重新渲染，同时保存新的地图状态和版本。
确定性执行：LLM
只产生受约束的结构化意图；修改引擎按白名单逐步应用、生成差异、重新渲染并创建父子版本，失败时保留原状态。
智能体架构
从请求到地图状态的端到端执行链
Django 负责请求与会话，LangGraph 负责流程节点和条件路由，LangChain 负责模型与工具协议；LLM 只规划下一步，本地 GIS 执行环境才执行数据处理、综合和渲染，最终结果回到 MapState、版本和追踪记录。
接收前端自然语言请求，根据 Session ID 定位对应会话 Agent，并将请求交给 ConversationalAgent；任务完成后保存 AI 回复与地图结果，并返回前端。
通过 Session ID 维护会话上下文：ConversationState 保存消息、 意图和流程状态，MapState 保存图层、样式、地图范围等地图配置；后续请求加载已有状态并继续增量处理。
意图分类节点先调用 LLM；异常或非法返回时使用规则兜底，再路由创建、综合、调整、查询和错误节点，最终统一生成响应。
LangChain 将 GIS 工具及参数 Schema 绑定给 LLM，LLM 根据当前任务选择下一步工具； 项目代码执行对应本地工具，并通过 ToolMessage 将执行结果回传模型，循环直至任务完成。
GeoPandas、Shapely 等负责空间数据读取与几何处理，制图工具完成图层组织与 Matplotlib 渲染； 路网综合引擎根据任务调用 Stroke、网眼密度、层次选取或 GCNN 等算法。
地图渲染结果与 MapState 统一保存，每次修改生成新的状态版本，并通过 parent_version 维护版本链； 同时记录工具调用 Trace，最终结果返回前端，下一轮修改继续基于当前状态执行。
制图规格
把“想画什么”拆成可执行的制图规格
自然语言需求 → 结构化 MapSpec / MapState → GIS 工具调用 → 地图渲染
输入约定
自然语言 → 结构化制图参数
用户不需要记住 GIS 工具或参数名称，只需描述目标地图。系统从自然语言中提取数据、范围、表达和输出要求， 并整理为后续工具可以直接执行的结构化制图参数；缺失信息则根据数据自动推断或在后续交互中补充。
数据：使用哪些空间文件、字段或数据集。范围：制作区域、尺度、中心位置和保留范围。表达：图层顺序、颜色、线型、标注与专题规则。输出：确定图幅、DPI、地图元素和最终输出文件。
双状态架构
ConversationState × MapState 双状态架构
系统不依赖 LLM 从完整聊天记录中反复推断当前地图，而是将对话流程状态与可持久化的地图业务状态分层管理，并通过 Session ID 关联同一轮持续演进的制图任务。
Stateful Agent
将“对话状态”与“地图业务状态”解耦，构建真正可持续运行的 Stateful Agent
ConversationState 服务于 LangGraph 的流程编排，保存消息、当前意图、待确认操作、澄清问题、补丁、错误和渲染结果；MapState 作为地图业务状态源，保存配置、图层、样式、范围、注记、版本与修改记录。
对话层：负责当前流程如何继续，随着交互快速变化。地图层：负责当前成果的真实配置，按 Session ID 持久化并可加载。增量演进：下一轮请求直接恢复当前 MapState，在既有地图上修改并生成版本链。
多轮动态调整
真实工作台：从一段需求到可继续修改的地图
地图生成并不是任务的终点。系统持续维护当前 MapState，后续自然语言指令会在已有结果上执行局部更新，重新渲染并保存新的状态版本。
制图流程 · 当前任务
制图过程可见，结果可继续修改
每轮修改都会先加载当前 MapState，保留地图范围、图层、样式、比例尺和指北针等已完成配置，只更新真正发生变化的对象。
加载已有地图状态读取当前地图的图层、样式、范围、比例尺、指北针及版本信息，作为本轮修改的真实业务上下文。
解析修改意图自然语言 → IntentAnalysisV2：通过 Function Calling 提取 intent、target、样式参数及批量操作等字段。
生成 AdjustmentPatch结合当前 MapState 校验目标和参数，再将合法意图编译为受控 PatchOperation。
增量更新 MapState按照 action、target、parameters 更新对应图层或地图配置，其余已有状态保持不变。
自动重新渲染基于最新状态生成地图结果，未变化的数据继续复用，只处理受影响的样式或地图元素。
生成新版本保存新的 MapState，记录本轮 Patch 与修改关系，为历史追踪、撤销和版本回退提供依据。
上下文连续结构化意图受控 Patch增量执行自动重渲染版本演进
工程设计与可靠性
让概率型 LLM 安全驱动确定性 GIS
LLM 只负责理解与决策，所有可能改变地图状态的操作都必须经过结构化解析、 状态校验和白名单编译；执行失败则进入重试、澄清或版本恢复链路。
版本管理与撤销
地图状态可追踪、可恢复
系统不会在每次修改后直接覆盖原有地图状态，而是基于当前 MapState 创建新版本，并保留上一版本，形成连续的状态演进记录。
完整快照 · 版本链
从当前状态创建新版本，保留每一次修改依据
每个版本记录版本号、父版本和对应的修改记录。系统采用 Full Snapshot 保存完整 MapState，历史版本可以直接加载，不需要让 LLM 重新推导反向操作。
可追踪：每次修改都有明确版本和修改记录，状态演进关系清晰可见。
可撤销：直接恢复上一版本，而不是重新生成地图或猜测反向操作。
可恢复：历史版本保存完整状态，可按版本重新加载地图。
高可靠：状态持久化采用事务机制，避免生成不完整的版本。
MapStateFull Snapshotparent_versionModificationRecordUndo
空间数据辅助
基于空间数据的智能辅助制图
能够由数据和规则确定的信息，由系统自动计算，而不是要求用户重复输入或依赖 LLM 猜测。LLM 负责理解制图目标，确定性 GIS 规则负责参数推断与空间布局。
参数自动推断
从已有数据中补齐专业制图参数
用户只需提供基本制图需求，系统会结合空间数据和当前地图状态补齐缺失配置，减少对专业 GIS 参数的依赖。
地图范围自动计算
制图智能体调用范围计算工具读取输入文件的空间边界，自动生成适合当前数据的地图范围。
几何类型自动识别
添加图层时读取数据中的主导几何类型，自动区分点、线、面并匹配对应的绘制与图例方式。
比例尺自动配置
初始化制图时可自动加入比例尺；后续任务会从当前 MapState 继承比例尺是否启用的配置。
Extent Auto FitGeometry DetectionAdaptive Scale
智能文本定位
根据空间分布主动避让地图主体
读取当前图层的空间边界，转换为地图相对坐标后检查候选点与要素范围的重叠关系。要素较少的候选位置会优先用于标题和注记。
空间分布分析
收集各图层的边界范围，形成地图主体的占用区域，为候选位置判断提供依据。
空白区域检测
以候选位置及 0.15 缓冲区检查是否与占用范围重叠，筛选更适合放置文本的区域。
文本尺寸适配
长文本优先考虑底部和角落，短文本可使用其他候选区；写入时还会自动换行并提供安全兜底。
Grid AnalysisEmpty Area DetectionAdaptive Text Placement
技术栈
技术栈完整说明
从 Web 请求接入、Agent 流程编排，到 GIS 确定性执行、地图状态持久化和实时结果反馈，各层职责相互解耦。
- Web / 服务层
- Python · Django · Django Channels：负责用户、会话、制图请求和 API 接入，并通过 Channels 向工作台推送任务状态与结果。
- Agent / AI 层
- LangGraph · LangChain · LLM · Pydantic：LangGraph 管理意图路由与多轮状态流转； LangChain 负责模型接入和 Tool Calling；LLM 负责理解与决策，Pydantic 约束结构化输出。
- GIS / 制图层
- GeoPandas · Shapely · Matplotlib：负责空间数据读取、几何计算、地图范围处理、图层样式组织以及专题地图渲染输出。
- 路网综合 / 算法层
- NetworkX · PyTorch · Stroke · 网眼密度 · 层次选取 · GCNN 通过统一综合引擎封装多种路网缩编算法，根据目标尺度和任务要求选择对应算法执行。
- 状态管理
- MapState · SQLite · Redis · Trace MapState 保存地图配置与版本快照；SQLite 持久化会话和版本状态；Redis 支撑实时通信与任务消息；Trace 记录工具调用和异常链路。