第四章：YAML 流水线格式完全解析
GeoPipeAgent 使用 YAML 文件描述分析流水线。本章完整解析 YAML 格式的每一个字段，帮助你深刻理解流水线的结构规则。
4.1 顶层结构
所有 GeoPipeAgent 流水线 YAML 文件必须有一个顶层 pipeline: 键，所有流水线字段均嵌套在其下：
pipeline:
name: "流水线名称" # 必填
description: "流水线描述" # 可选
crs: "EPSG:4326" # 可选，全局默认 CRS
variables: # 可选，变量字典
var_name: value
steps: # 必填，步骤列表
- id: step_id
use: category.action
params:
key: value
on_error: fail
when: "条件表达式"
backend: native_python
outputs: # 可选，输出声明
result: "$step_id"
常见错误：忘记顶层
pipeline:键。这会导致PipelineParseError: Missing 'pipeline' key at the top level。
4.2 pipeline.name（必填）
流水线名称，字符串类型，出现在 JSON 执行报告的 pipeline 字段中。
pipeline:
name: "建筑物数据质检流水线"
规范建议：使用描述性名称，体现分析目的和数据类型。
4.3 pipeline.description（可选）
流水线的详细描述，字符串类型，用于说明分析目的、数据来源、输出格式等。
pipeline:
name: "NDVI 计算"
description: "读取多光谱影像，使用波段4（近红外）和波段3（红）计算 NDVI，输出为 GeoTIFF"
4.4 pipeline.crs（可选）
全局默认坐标参考系，EPSG 代码字符串（如 "EPSG:4326"）。当步骤没有指定 CRS 时，可参考该值。
pipeline:
name: "全国城市分析"
crs: "EPSG:4326"
注意：
crs字段目前是元数据性质，不会自动对步骤进行投影转换。需要转换坐标系时，仍需显式使用vector.reproject或raster.reproject步骤。
4.5 pipeline.variables（可选）
变量字典，定义可在步骤参数中复用的值。支持字符串、数字、布尔值等类型。
pipeline:
variables:
input_path: "data/buildings.shp"
buffer_dist: 100
output_format: "GeoJSON"
simplify_tolerance: 0.001
enable_qc: true
变量通过 ${变量名} 语法引用（详见第五章）。--var 命令行参数可在运行时覆盖变量值。
变量值的类型规则：
- 当整个参数值是单一
${var}引用时，值的类型等于变量的原始类型（数字仍是数字） - 当变量嵌入字符串中（如
"path/${var}.geojson"）时，变量被转为字符串拼接
4.6 pipeline.steps（必填）
步骤列表，是流水线的核心，定义分析工作流。步骤按列表顺序依次执行。
pipeline:
steps:
- id: step-1
use: io.read_vector
params: { path: "data/input.shp" }
- id: step-2
use: vector.buffer
params: { input: "$step-1", distance: 100 }
4.6.1 步骤字段详解
每个步骤都是一个包含以下字段的 YAML 映射：
id（必填）
步骤的唯一标识符。规则：
- 只允许小写字母、数字、下划线、连字符：
[a-z0-9_-] - 不允许包含点号（
.），因为点号用于属性访问（$step-id.attr） - 在同一流水线中必须唯一
- 推荐使用描述性 ID（
load-roads、buffer-500m）而非无意义缩写（s1、step2）
- id: check-geometry # ✅ 合法
- id: load_buildings # ✅ 合法
- id: step1 # ✅ 合法但不推荐
- id: vector.buffer # ❌ 不合法（含点号）
- id: Load Roads # ❌ 不合法（含空格和大写）
use（必填）
步骤类型，即步骤注册 ID，格式为 类别.动作。完整步骤 ID 列表见第七章至第十二章。
use: io.read_vector
use: vector.buffer
use: qc.geometry_validity
params（可选/通常必填）
步骤参数，键值对映射。不同步骤有不同的参数规范。参数值可使用变量替换 ${var} 和步骤引用 $step-id。
params:
input: "$load-roads" # 步骤引用
distance: "${buffer_dist}" # 变量替换
cap_style: "round" # 直接值
on_error（可选）
步骤失败时的处理策略，默认 fail：
| 值 | 行为 |
|---|---|
fail |
立即终止流水线（默认） |
skip |
跳过该步骤，继续执行后续步骤 |
retry |
自动重试最多 3 次（每次间隔递增：0.5s、1s、1.5s） |
- id: fetch-remote
use: network.geocode
params: { address: "北京市海淀区" }
on_error: retry # 网络请求失败时重试
- id: optional-simplify
use: vector.simplify
params: { input: "$load-data", tolerance: 10 }
on_error: skip # 简化失败时跳过，不影响后续步骤
when（可选）
条件执行表达式。只有当 when 表达式求值为 True 时，步骤才会执行；否则步骤状态为 skipped，输出为空 StepResult。
- id: fix-geometry
use: qc.geometry_validity
params:
input: "$load-data"
auto_fix: true
when: "$check-geometry.issues_count > 0" # 仅当存在几何问题时才修复
when 表达式支持：
- 步骤属性引用：
$step_id.attr（如$check.issues_count） - 变量引用：
${var_name}（如${enable_fix}） - 比较运算：
==、!=、>、<、>=、<= - 逻辑运算：
and、or、not
安全性：
when表达式通过safe_eval.py的 AST 白名单机制求值，防止任意代码执行。
backend（可选）
指定步骤使用的执行后端。不指定时使用该步骤的默认后端（通常是 native_python）。
- id: convert-format
use: vector.reproject
params:
input: "$load-data"
target_crs: "EPSG:3857"
backend: gdal_cli # 使用 GDAL CLI 后端而非 native_python
4.7 pipeline.outputs（可选）
声明流水线的输出引用，这些值会出现在 JSON 报告的 outputs 节中，便于下游系统提取结果。
outputs:
final_data: "$save-result" # 引用步骤输出（文件路径或 GeoDataFrame 摘要）
stats: "$buffer.stats" # 引用步骤统计信息
issue_count: "$check-geo.issues_count" # 引用 QC 步骤的问题数量
4.8 完整 YAML 示例（带所有字段）
pipeline:
name: "建筑物数据标准化处理"
description: "对建筑物矢量数据进行投影转换、几何检查、属性质检，输出标准化结果"
crs: "EPSG:4326"
variables:
input_path: "data/buildings.shp"
target_crs: "EPSG:4549" # CGCS2000 / 3-degree Gauss-Kruger zone
output_path: "output/buildings_std.geojson"
required_fields: ["name", "height", "type"]
steps:
- id: load-data
use: io.read_vector
params:
path: "${input_path}"
- id: check-crs
use: qc.crs_check
params:
input: "$load-data"
expected_crs: "EPSG:4326"
on_error: skip
- id: check-geometry
use: qc.geometry_validity
params:
input: "$load-data"
auto_fix: false
severity: "error"
- id: fix-geometry
use: qc.geometry_validity
params:
input: "$load-data"
auto_fix: true
when: "$check-geometry.issues_count > 0"
on_error: skip
- id: reproject
use: vector.reproject
params:
input: "$load-data"
target_crs: "${target_crs}"
- id: check-attrs
use: qc.attribute_completeness
params:
input: "$reproject"
required_fields: "${required_fields}"
severity: "warning"
on_error: skip
- id: save-result
use: io.write_vector
params:
input: "$reproject"
path: "${output_path}"
format: "GeoJSON"
outputs:
result: "$save-result"
geometry_issues: "$check-geometry.issues_count"
attribute_issues: "$check-attrs.issues_count"
4.9 YAML 格式常见错误
错误 1：缺少顶层 pipeline: 键
# ❌ 错误写法
name: "我的流水线"
steps:
- id: load
use: io.read_vector
...
# ✅ 正确写法
pipeline:
name: "我的流水线"
steps:
- id: load
use: io.read_vector
...
错误 2：步骤 ID 包含点号
# ❌ 错误：点号是属性访问分隔符
- id: io.load # 错误
# ✅ 正确
- id: io-load # 使用连字符
- id: load_data # 或下划线
错误 3：引用不存在的步骤
steps:
- id: load-data
use: io.read_vector
params: { path: "data.shp" }
- id: buffer
use: vector.buffer
params:
input: "$load_data" # ❌ 错误：ID 是 load-data，不是 load_data
distance: 100
# ✅ 正确
- id: buffer-2
use: vector.buffer
params:
input: "$load-data" # 正确引用
distance: 100
错误 4：变量未定义就引用
pipeline:
steps:
- id: load
use: io.read_vector
params:
path: "${data_path}" # ❌ 如果 variables 中没有 data_path 定义，运行时报错
# 解决方案：在 variables 中定义，或通过 --var 传入
pipeline:
variables:
data_path: "data/input.shp" # ✅
4.10 本章小结
本章完整解析了 YAML 流水线格式：
- 顶层
pipeline:键：必须存在，所有字段在其下 steps列表：流水线核心，每个步骤有id、use、params等字段on_error：fail/skip/retry三种错误策略when：基于安全 AST 求值的条件执行backend：步骤级别的后端指定outputs：声明流水线输出，便于下游处理
下一章将深入讲解变量系统与步骤引用的工作原理。
导航：← 第三章：快速上手 ｜ 第五章：变量与步骤引用 →