def parse_yaml(source: str | Path) -> PipelineDefinition:
    raw = _load_yaml(source)       # 读取文件或字符串 → dict
    return _build_pipeline(raw)    # 构建 PipelineDefinition

@dataclass
class PipelineDefinition:
    name: str
    steps: list[StepDefinition]
    description: str = ""
    crs: str | None = None
    variables: dict = {}
    outputs: dict = {}

@dataclass
class StepDefinition:
    id: str
    use: str
    params: dict = {}
    when: str | None = None
    on_error: str = "fail"  # "fail" | "skip" | "retry"
    backend: str | None = None

class PipelineContext:
    variables: dict              # 流水线变量（含 --var 覆盖）
    _step_outputs: dict[str, StepResult]  # 已完成步骤的输出

    def set_output(step_id, result)  # 步骤完成后存储结果
    def get_output(step_id)          # 获取步骤结果
    def resolve(value)               # 解析值（变量替换/步骤引用）
    def resolve_params(params)        # 解析整个 params 字典

def resolve(self, value):
    if not isinstance(value, str):
        return value           # 非字符串直接返回

    if value.startswith("$") and not value.startswith("${"):
        return self._resolve_step_ref(value)  # 步骤引用

    if "${" in value:
        return self._substitute_variables(value)  # 变量替换

    return value               # 普通字符串

def _resolve_step_ref(self, ref):
    ref_body = ref[1:]
    if "." not in ref_body:
        step_id, attr = ref_body, "output"   # $step → $step.output
    else:
        step_id, attr = ref_body.split(".", 1)
    result = self._step_outputs[step_id]
    return getattr(result, attr)             # 访问 StepResult 属性

class StepContext:
    def param(self, name, default=None)  # 获取指定参数值
    def input(self, name="input")        # input("input") 的快捷方式
    @property params                      # 完整参数字典
    backend                              # 后端对象（可能为 None）

def execute_pipeline(pipeline) -> dict:
    context = PipelineContext(variables=pipeline.variables)
    backend_manager = BackendManager.default()

    for step_def in pipeline.steps:
        # 1. 条件判断
        if step_def.when and not _evaluate_condition(step_def.when, context):
            context.set_output(step_def.id, StepResult())
            # → 记录 status=skipped，继续

        # 2. 执行步骤（含重试）
        result = _execute_step(step_def, context, backend_manager)
        context.set_output(step_def.id, result)

    # 3. 解析 outputs
    resolved_outputs = {k: context.resolve(v) for k, v in pipeline.outputs.items()}

    # 4. 生成 JSON 报告
    return build_report(...)

def _with_retry(fn, max_attempts, step_id):
    for attempt in range(1, max_attempts + 1):
        try:
            return fn()
        except StepExecutionError:
            raise    # 已封装的执行错误不重试
        except Exception as e:
            if attempt < max_attempts:
                time.sleep(0.5 * attempt)  # 递增等待：0.5s, 1s, 1.5s
    raise last_error

patterns = [
    ("crs" in msg and "degree" in msg → 建议添加 reproject 步骤),
    ("file not found" → 检查文件路径),
    ("invalid geometry" → 添加 qc.geometry_validity),
    ("keyerror" → 检查字段名是否存在),
    ...
]

import geopipe_agent  # 触发内置步骤的自动注册

from geopipe_agent.engine.parser import parse_yaml
from geopipe_agent.engine.validator import validate_pipeline
from geopipe_agent.engine.executor import execute_pipeline
from geopipe_agent.errors import GeopipeAgentError

# 方式一：从文件加载
pipeline = parse_yaml("my_pipeline.yaml")

# 方式二：从字符串加载
yaml_str = """
pipeline:
  name: "inline pipeline"
  steps:
    - id: load
      use: io.read_vector
      params: { path: "data.shp" }
"""
pipeline = parse_yaml(yaml_str)

# 运行时覆盖变量
pipeline.variables["input_path"] = "data/roads.shp"
pipeline.variables["buffer_dist"] = 500

# 校验（返回警告列表，或抛出异常）
warnings = validate_pipeline(pipeline)

# 执行（返回 JSON 报告字典）
try:
    report = execute_pipeline(pipeline)
    print(f"Status: {report['status']}")
    print(f"Duration: {report['duration']}s")
except GeopipeAgentError as e:
    print(f"Error: {e}")