🗺️ QGIS Agent

版本 2.1.0 | 将大语言模型嵌入QGIS的智能助手

用自然语言操控 QGIS，无需编写代码

✨ 核心亮点

📚 RAG API 文档检索 - 380+ PyQGIS API 文档，自动查询准确参数
🧰 679 个 Processing 工具 - 完整的工具文档和代码示例
🐛 SmartDebugger - 智能调试系统，自动分析错误并提供修复建议
🔄 工作流固化 - 将对话中的工具链保存为可重用工作流
❓ 主动提问 - 识别模糊请求，主动向用户澄清
📊 Task Graph - 任务流程图可视化
🎯 Query Tuning - 用户查询优化

🏗️ 系统架构

graph TB subgraph UI["🖥️ QGIS 主线程 — GUI"] direction LR A["🧩 QGISAgent
主控制器"] B["🪟 DockWidget
UI 面板"] C["💬 Conversation
会话管理"] end subgraph WORKER["⚙️ 工作线程 — QThreadPool"] direction LR D["🔧 ToolAgentWorker
异步执行"] E["🧠 Processor
Agent 循环 + RAG + Cookbook"] end subgraph TOOLS["🔩 QGIS 工具层 — 主线程调度"] direction LR F["📞 call_tool()
线程桥"] G["🧰 15+ QGIS 工具"] H["🗺️ QGIS API
QgsProject / iface / Processing"] end subgraph RAG["📚 RAG 引擎 (本地)"] direction LR J["📖 DocStore
SQLite FTS5"] K["🔍 Retriever
关键词搜索"] L["🧰 ToolDocs
679 Processing 工具"] end subgraph EXT["☁️ 外部服务"] I["🤖 LLM API
DeepSeek / OpenAI 兼容"] end A -->|创建/管理| B A -->|创建/管理| C C -->|async_response| D D -->|在线程中运行| E E -->|API 调用| I E -->|检索文档| K K -->|查询| J E -->|检索工具| L E -->|跨线程调用工具| F F -->|QTimer 调度到主线程| G G -->|操作| H

🚀 快速开始

1. 安装插件

打开 QGIS → 菜单栏插件 → 管理和安装插件

从 ZIP 安装 → 选择 qgis_agent_v2.1.0_20260612_flat.zip

启用插件 → 在已安装列表中勾选 QGIS Agent

2. 配置 LLM API

打开 QGIS Agent 面板，切换到 模型配置 标签页

点击 + 添加模型

填写配置信息：

名称: DeepSeek (或自定义名称)
API 端点: https://api.deepseek.com/v1
API Key: 你的密钥

💡 支持的 LLM 提供商

提供商	API 端点	模型
DeepSeek	`https://api.deepseek.com/v1`	deepseek-chat
OpenAI	`https://api.openai.com/v1`	gpt-4o, gpt-4o-mini
智谱 GLM	`https://open.bigmodel.cn/api/paas/v4/`	glm-4, glm-4-flash
Google	`https://generativelanguage.googleapis.com/v1beta/openai/`	gemini-2.0-flash
小米 MiMo	`https://api.xiaomimimo.com/v1`	mimo-v2.5
自定义	任何 OpenAI 兼容接口	任意模型名

3. 基本使用

操作	示例指令	预期结果
查询	`查看当前项目有哪些图层`	显示图层列表和属性
加载	`添加图层 D:/data/roads.shp`	加载矢量图层
分析	`对道路图层做100米缓冲区分析`	执行缓冲区分析
分析	`用AOI图层裁剪道路图层`	执行裁剪分析
分析	`筛选面积大于100的建筑`	属性查询筛选
输出	`将地图渲染导出为PNG`	导出地图截图

🔧 核心功能详解

📚 RAG API 文档检索

执行代码前自动查询 PyQGIS API 签名和参数，确保代码准确性：

graph LR A[用户请求] --> B[Query Tuning] B --> C[RAG 检索] C --> D[PyQGIS API] C --> E[Processing 工具] D --> F[LLM 生成代码] E --> F F --> G[执行分析] G --> H[返回结果]

用户: 对道路图层做缓冲区分析
↓
RAG 检索: QgsVectorLayer, processing.run
↓
LLM 生成: 准确的 PyQGIS 代码
↓
执行: 缓冲区分析完成

🐛 SmartDebugger 智能调试

代码执行失败时，自动分析错误并提供修复建议：

错误类型	识别模式	修复建议
ImportError	`ModuleNotFoundError`	检查库安装，尝试替代导入
QgsVectorLayer 错误	`invalid layer`	检查路径，验证图层有效性
Processing 算法错误	`Algorithm not found`	检查算法ID，验证参数
几何错误	`Invalid geometry`	使用 buffer(0) 修复
字段错误	`Field not found`	检查字段名，验证数据类型
内存错误	`MemoryError`	分块处理，简化几何

🔄 工作流固化

将对话中的工具调用序列保存为可重用工作流：

graph TB A[第一次对话] --> B[执行工具链] B --> C[录制工作流] C --> D[保存为模板] D --> E[第二次对话] E --> F[加载工作流] F --> G[参数替换] G --> H[直接执行] H --> I[返回结果]

# 录制工作流
workflow = recorder.record_from_conversation(
    tool_calls=[
        {"tool": "native:buffer", "args": {"INPUT": "${input_layer}", "DISTANCE": "${distance}"}},
        {"tool": "native:savefeatures", "args": {"OUTPUT": "${output_path}"}}
    ],
    workflow_name="缓冲区分析工作流"
)

# 下次直接执行
results = executor.execute_workflow(
    template=workflow,
    parameters={
        "input_layer": "D:/data/rivers.shp",
        "distance": 200,
        "output_path": "D:/output/rivers_buffer.shp"
    }
)

❓ 主动提问

识别模糊或不完整的请求，主动向用户澄清：

用户输入	识别问题	Agent 提问
`分析一下`	请求模糊	请具体说明要分析什么内容
`添加图层`	缺少路径	请提供数据文件的完整路径
`缓冲区分析`	缺少距离	请指定缓冲区距离（单位：米）
`按字段筛选`	缺少字段	请指定要使用的字段名称

📋 内置工具

工具	功能	分类	示例
`get_qgis_info`	获取项目信息	📊 查询	查看当前项目有哪些图层
`get_layer_features`	查询图层属性	📊 查询	查看道路图层的属性表
`add_vector_layer`	添加矢量图层	📂 管理	添加图层 D:/data/roads.shp
`add_raster_layer`	添加栅格图层	📂 管理	添加栅格 D:/data/dem.tif
`remove_layer`	移除图层	📂 管理	移除道路图层
`zoom_to_layer`	缩放到图层	🔎 导航	缩放到道路图层
`set_layer_labeling`	设置图层标注	🏷️ 标注	显示道路名称标注
`execute_processing`	执行 Processing 算法	⚙️ 分析	执行缓冲区分析
`execute_pyqgis`	执行 PyQGIS 代码	🐍 高级	自定义空间分析
`search_pyqgis_api`	检索 API 文档	📚 RAG	查询 QgsGeometry 方法
`render_map`	渲染地图截图	📸 输出	导出当前地图为PNG
`save_project`	保存项目	💾 项目	保存当前项目
`load_project`	加载项目	💾 项目	加载项目文件
`save_memory`	保存长期记忆	🧠 记忆	记住用户偏好
`load_memory`	加载长期记忆	🧠 记忆	读取之前保存的信息

🧰 工具文档系统

内置 679 个 QGIS Processing 工具 文档，支持 RAG 检索：

graph LR A[用户请求] --> B{工具检索} B --> C[native:buffer] B --> D[native:clip] B --> E[native:intersection] B --> F[native:dissolve] B --> G[... 679 个工具] C --> H[参数说明] D --> H E --> H F --> H G --> H H --> I[代码示例] I --> J[LLM 生成代码] J --> K[执行分析]

支持的工具类型

前缀	说明	示例工具
`native:`	QGIS 原生算法	buffer, clip, dissolve, intersection
`gdal:`	GDAL/OGR 工具	aspect, slope, contour, rasterize
`qgis:`	QGIS 扩展工具	heatmap, idw, tininterpolation
`3d:`	3D 分析工具	tessellate
`pdal:`	点云处理工具	boundary, density, filter

💡 最佳实践

✅ 正确示例

使用绝对路径：添加图层 D:/data/roads.shp
明确指定参数：对道路图层做100米缓冲区分析
分步骤执行：先加载数据 → 再执行分析 → 最后保存结果
指定图层名称：用AOI图层裁剪道路图层

❌ 错误示例

使用相对路径：添加图层 roads.shp（可能找不到文件）
请求模糊：分析一下（不知道要分析什么）
缺少参数：缓冲区分析（没有指定距离）
一次性复杂任务：加载数据、分析、保存（建议分步执行）

🐛 故障排除

问题	可能原因	解决方案
插件无法加载	QGIS 版本过低	升级到 QGIS 3.0+
API 调用失败	网络连接或密钥错误	检查网络和 API 密钥
代码执行错误	语法或参数错误	查看 SmartDebugger 的修复建议
图层加载失败	文件路径错误	检查文件路径是否正确
工具调用失败	算法ID或参数错误	使用 search_pyqgis_api 查询正确用法
内存不足	数据量过大	分块处理或简化几何

📊 工作流示例

示例1: 缓冲区分析工作流

graph LR A[加载道路图层] --> B[执行缓冲区分析] B --> C[保存结果] C --> D[加载结果图层]

# 缓冲区分析工作流代码
import processing
from qgis.core import QgsVectorLayer, QgsProject

# Step 1: 加载道路图层
roads = QgsVectorLayer('D:/data/roads.shp', 'roads', 'ogr')
QgsProject.instance().addMapLayer(roads)

# Step 2: 执行缓冲区分析
result = processing.run('native:buffer', {
    'INPUT': 'D:/data/roads.shp',
    'DISTANCE': 100,
    'SEGMENTS': 25,
    'END_CAP_STYLE': 0,
    'JOIN_STYLE': 0,
    'DISSOLVE': False,
    'OUTPUT': 'D:/output/roads_buffer.shp'
})

# Step 3: 加载结果图层
buffer_layer = QgsVectorLayer(result['OUTPUT'], 'roads_buffer', 'ogr')
QgsProject.instance().addMapLayer(buffer_layer)

print('缓冲区分析完成！')

示例2: 空间叠加分析工作流

graph LR A[加载土地利用图层] --> B[加载行政区划图层] B --> C[执行相交分析] C --> D[统计各区域面积] D --> E[导出结果]

📄 更新日志

v2.1.0 (2026-06-12)

✨ 集成 SmartDebugger 智能调试系统
✨ 添加 Task Graph 任务流程可视化
✨ 添加 Query Tuning 查询优化
✨ 集成 679 个 Processing 工具文档
✨ 添加 Code Review 代码审查
✨ 添加 Workflow Recorder 工作流录制
✨ 添加 Workflow Executor 工作流执行
✨ 添加 Clarification Manager 主动提问
✨ 添加帮助/关于页面

v1.2.0 (2026-06-06)

✅ RAG API 文档检索 (380+ 文档)
✅ Cookbook 自我进化机制
✅ 15 个内置 QGIS 工具
✅ 多 LLM 提供商支持
✅ 代码执行确认机制