能跑一次，不等于处理工具可交付

在 QGIS 中把一个脚本包装成 Processing 工具后，最容易看到的是成功提示和一份输出文件。可复用的 GIS 自动化真正要交代的是：谁传了什么参数、输入图层的坐标参考是否适合、生成的输出是什么、运行环境是否一致，以及别人能否用相同的命令复现。QgsProcessingAlgorithm 是处理算法的抽象基类。它提供的接口正好能把这些原本散落在界面、脚本和日志里的约束整理成一个可审查合同。

对接智能体、批处理或模型生成脚本时，这种合同尤其重要。模型能填写参数不代表参数语义正确；一个输出路径存在也不代表其字段、几何、CRS 或覆盖范围符合预期。应先让算法自身声明输入、输出和校验，再让自动化层只在这些边界内调用。

核心机制

子类必须实现 createInstance、displayName、initAlgorithm、name 和 processAlgorithm。这五项分别对应干净实例、面向用户的名称、参数与输出初始化、稳定识别名和实际处理逻辑。实现时应将 name() 视为机器稳定标识，将 displayName() 视为可翻译的界面文字；不要用翻译后的标题作为自动化调用键。

算法唯一 ID 由 provider ID 与算法唯一名称组成，例如 qgis:mergelayers。发布团队应在算法登记表中记录完整 ID、provider、插件版本、QGIS 版本、输入模式和输出契约。这样模型、批处理任务和桌面用户面对的是同一个可追踪入口，而不是一串容易改名的菜单文字。

initAlgorithm 应在创建算法后调用，以正确配置参数和输出定义。参数声明不是界面装饰，它决定自动化能否知道需要什么数据、允许哪些范围、结果应写到哪里。不要在 processAlgorithm() 才临时猜测字段或创建未声明的副产物；这样会让模型器、批处理和命令行调用难以发现真实依赖。

GIS 场景

以地块缓冲、叠加统计或栅格裁剪为例，输入层、距离单位、区域边界、时间范围与目标 CRS 都会改变结果。即使地图上看起来“差不多”，在经纬度坐标中直接按米缓冲、混用垂直基准或把裁剪范围当作研究范围，都可能造成数量级错误。因此应在运行前把输入数据版本、图层 URI、字段、范围和 CRS 写进运行记录。

QGIS 处理工具也常要给下游交付表格、矢量层、栅格层或 HTML 报告。输出不能只以文件是否存在验收，还要抽样检查要素数、几何类型、字段模式、无数据值、CRS、空间范围和写入位置。若工具允许原位编辑，必须额外确认目标图层、可撤销性和项目备份，避免批量操作把原始数据当成临时结果覆盖。

技术路径

第一步，显式定义参数与输出。addParameter 在适当情况下会自动创建对应的输出定义。对于矢量目的地参数，自动创建能减少遗漏，但仍需在测试中确认输出名、格式、字段和几何类型满足约定。对可选参数、枚举、范围和表达式，说明默认值、可接受单位和缺省后的业务含义。

第二步，先校验再执行。checkParameterValues 会检查给定参数是否满足算法在指定上下文中的要求。团队可在算法运行前调用或依赖该阶段返回的错误信息，但要补充业务层检查，例如面积阈值、数据日期、敏感区域权限和输出目录策略。参数类型正确不等于研究设计正确。

第三步，单独验证坐标参考。validateInputCrs 会检查一组参数的坐标参考系统是否对算法有效。对于测距、面积、栅格重采样和空间连接，建议将允许的 CRS、是否自动重投影、单位和精度要求写为明确规则；对不满足规则的输入停止运行并给出可操作的错误，而不是静默转换。

第四步，留下可复现命令。asPythonCommand 可返回可执行算法的 Python 命令字符串，asQgisProcessCommand 可返回等价的 qgis_process 命令。每次验收应保存实际参数快照、命令、算法 ID、QGIS 版本、环境依赖和输入摘要；对不能表达为命令行的参数组合，要明确标记并保存结构化参数而非假称可完全复现。

检查清单

  • 算法 ID、provider、插件与 QGIS 版本是否固定并可查？
  • 参数、默认值、单位、范围与输出定义是否在初始化阶段完整声明？
  • 执行前是否检查参数值、输入数据版本和业务约束？
  • 涉及距离、面积和叠加时，CRS 与单位是否经过独立验证？
  • 输出是否检查字段、几何、要素数、范围、CRS 和写入位置？
  • 是否保存 Python 或 qgis_process 复现命令及参数快照？

来源事实与数据口径

本文关于抽象基类、必实现方法、算法 ID、初始化、参数—输出关系、参数校验、CRS 校验和命令生成的事实，均来自 QGIS 官方 PyQGIS API 文档。文档还说明，在 PyQGIS 中只有标记为 virtual 的方法才能安全地在 Python 子类中覆写。本文的运行记录、业务校验和发布流程是工程建议，不代表 QGIS 自动验证了任何具体空间分析结论。

风险边界

Processing 的参数和 CRS 校验只能验证已编码的约束，不能证明输入观测真实、字段语义一致或模型适用于研究问题。自动重投影、默认单位、临时图层、编码和外部依赖仍可能改变结果。涉及资源审批、执法、财产或公共安全的输出，需由具备数据责任的人员复核数据来源、方法和结论。

结论

把参数、CRS、输出定义、执行前校验和可复现命令纳入同一条处理合同，QGIS 自动化才不会停留在“这次能跑”。当桌面用户、批任务和智能体都调用同一份声明与验收记录时，空间分析结果才能被复查、重跑和安全地交给下游。

关键词：GIS 是地理信息系统的处理环境；空间分析的输入、CRS 与输出必须共同验收；遥感技术数据进入处理算法前还应核对波段、时相和无数据值。

来源：https://qgis.org/pyqgis/master/core/QgsProcessingAlgorithm.html