pyqgis-development

name	pyqgis-development
description	用于进行 QGIS Python/PyQGIS 二次开发、插件开发、桌面端操作 CLI 封装、Processing 算法、地图工具、QGIS Server 插件、自动化脚本、测试、调试、API 查询和代码评审。

PyQGIS 二次开发

使用范围

当任务涉及 QGIS 3.x 的 Python 二次开发时使用本 skill。典型场景包括：QGIS 桌面插件、Python 控制台脚本、独立 PyQGIS 程序、QGIS 桌面端操作 CLI 封装、Processing 算法和 provider、自定义地图工具、后台任务、图层/工程自动化、QGIS Server 插件、测试、打包发布和 API 排错。

本 skill 依据 QGIS 官方资料整理，已本地化为中文说明。遇到版本敏感 API 时，仍要以用户当前安装版本和官方文档为准：

• QGIS Documentation 仓库：https://github.com/qgis/QGIS-Documentation/tree/master
• PyQGIS Cookbook 3.44：https://docs.qgis.org/3.44/en/docs/pyqgis_developer_cookbook/index.html
• PyQGIS API：https://qgis.org/pyqgis/

本地检索

优先用本地检索脚本查本 skill 的中文资料和 API 索引：

python3 scripts/search_skill.py 插件 metadata
python3 scripts/search_skill.py QgsVectorLayer 编辑
python3 scripts/search_skill.py 后台任务
python3 scripts/search_skill.py CLI 命令行
python3 scripts/search_skill.py --json Processing provider

检索范围包括 SKILL.md、references/*.md、官方 QGIS Documentation RST 本地副本和 PyQGIS API HTML 本地副本，支持中文关键词、英文 API 名、常见别名扩展、上下文片段和 JSON 输出。需要列出全部可检索文件时运行：

python3 scripts/search_skill.py --list

入口判断

先判断目标运行时，再加载对应参考文件：

• 新建或维护插件：读 developer-playbooks.md、plugin-development.md。
• 把 QGIS 桌面端操作封装为 CLI：读 desktop-cli-architecture.md、desktop-operation-capability-matrix.md、cli-command-catalog.md、cli-runtime-safety.md。
• 把 CLI 能力暴露为 MCP 服务：读 mcp-service-architecture.md，再回查 CLI 架构、安全边界和命令目录。
• 查 API、类名、典型调用：读 api-index.md，必要时检索 API 名。
• 处理渲染、Layout、Atlas、样式、标注、数据库/网络图层、3D、Mesh、Point Cloud、Vector Tile、Temporal 等高级能力：读 advanced-capabilities.md。
• 写脚本、图层、几何、CRS、表达式、设置、日志、认证、任务：读 core-patterns.md。
• 写 Processing 算法、provider 或 QGIS Server 插件：读 server-processing.md。
• 写测试、排错、验证、打包前检查：读 testing-debugging.md。
• 查官方章节映射与本地摘要：读 cookbook-3.44-local.md、official-sources.md。
• 查本地下载资料、官方 API inventory 和符号索引：读 local-source-index.md、api-inventory-index.md、api-symbol-index.md。

资料更新

官方 API 全量边界来自 vendor/pyqgis-api/3.44/objects.inv；官方 QGIS Documentation RST 全量边界来自 references/generated/qgis-documentation-rst-list.txt。继续补齐或刷新本地资料时按这个流程：

python3 scripts/build_api_inventory_index.py
python3 scripts/fetch_public_sources.py --from-inventory --inventory-limit 100 --max-time 25
python3 scripts/fetch_public_sources.py --docs-tree --max-time 35
python3 scripts/build_source_index.py
python3 scripts/build_api_symbol_index.py
python3 scripts/validate_skill.py

api-page-list.txt 是官方 inventory 解析出的 API 页面清单；qgis-documentation-rst-list.txt 是官方 QGIS Documentation 仓库 docs/**/*.rst 清单。可以多轮运行下载命令逐步补齐缺失页面。遇到大量文档缺失时，优先用 Git sparse checkout 获取官方 docs 目录，再同步 RST 到 vendor/qgis-documentation/。

查看本地覆盖进度：

python3 scripts/report_coverage.py
python3 scripts/report_documentation_coverage.py

基本规则

• qgis.core 放核心 API，如 QgsProject、QgsVectorLayer、QgsGeometry、QgsApplication。
• qgis.gui 放地图画布、地图工具、rubber band、vertex marker 等 GUI API。
• Qt 相关导入使用 qgis.PyQt，不要直接依赖 PyQt5 或 PyQt6。
• 独立脚本和测试必须显式初始化 QgsApplication，并在结束时调用 exitQgis()。
• 桌面插件必须实现 metadata.txt、__init__.py::classFactory(iface)、主插件类、initGui()、unload() 的生命周期契约。
• 修改矢量图层必须使用编辑事务：with edit(layer): ... 或显式 startEditing()/commitChanges()/回滚处理。
• QgsTask.run() 里不要访问 QgsProject、QgsVectorLayer、widgets、iface 或其他主线程拥有的 QObject；启动任务前复制数据，结果在 finished() 回到主线程处理。
• Processing 算法必须传递 context、feedback，子算法调用使用 is_child_algorithm=True，长循环检查 feedback.isCanceled()。
• 插件日志使用 QgsMessageLog.logMessage()；短消息用 iface.messageBar()；持久配置用 QgsSettings；认证信息用 QGIS 认证基础设施，不要写入日志或明文配置。
• 可测试逻辑尽量放在纯 Python 模块，QGIS UI 壳层只负责 iface、菜单、工具栏、dock、map tool、provider 注册。

开发流程

1. 确认 QGIS 版本、平台、运行时和现有项目结构。
2. 本地检索相关 API/主题，优先读最小参考文件。
3. 先实现或更新纯 Python 单元测试；只在 QGIS API 边界添加集成测试。
4. 按官方 API 和本地插件风格实现。
5. 运行项目已有测试、插件加载 smoke、Processing 算法执行或地图渲染验证。
6. 涉及发布时验证 metadata.txt、许可证、资源文件、版本范围、启停重复性和打包结果。

常见高风险信号

• 独立脚本依赖 iface。
• initGui() 添加动作，但 unload() 没有删除。
• QgsTask 后台线程直接使用图层、工程、feature iterator 或界面对象。
• 几何逻辑忽略 CRS、transform context、无效几何、多部件、Z/M 值。
• Processing 算法没有处理取消、进度、context 和 feedback。
• 插件 metadata 缺字段、不是 UTF-8、版本范围过宽，或发布前未按官方 validator 检查。