def parse_yaml(file_path: str) -> PipelineDefinition:
    """读取 YAML 文件，解析并返回 PipelineDefinition。"""

class PipelineDefinition(BaseModel):
    name: str                           # 流水线名称（必填）
    description: str | None = None      # 描述（可选）
    crs: str | None = None              # 默认 CRS（可选）
    variables: dict = {}                # 变量字典
    steps: list[StepDefinition] = []   # 步骤列表
    outputs: dict[str, str] = {}       # 输出映射

class StepDefinition(BaseModel):
    id: str                             # 步骤 ID（必填）
    use: str                            # 步骤类型（必填）
    params: dict = {}                  # 步骤参数
    when: str | None = None            # 条件表达式
    on_error: str = "fail"             # 错误策略
    backend: str | None = None         # 后端指定

def validate_pipeline(pipeline: PipelineDefinition) -> list[str]:
    """校验流水线，返回警告列表（空列表表示无问题）。"""

class PipelineContext:
    variables: dict                        # 全局变量表
    _step_outputs: dict[str, StepResult]  # 步骤结果缓存（key：步骤ID）
    
    def set_output(self, step_id: str, result: StepResult) -> None:
        """记录步骤执行结果。"""
    
    def get_output(self, step_id: str) -> StepResult:
        """获取已执行步骤的结果。"""
    
    def resolve(self, value: Any) -> Any:
        """解析一个可能含有引用的值。"""
    
    def resolve_params(self, params: dict) -> dict:
        """递归解析步骤参数字典中的所有引用。"""

# 1. 步骤引用：$step_id → step_outputs[step_id].output
context.resolve("$load-roads")    
# 返回 load-roads 步骤的输出 GeoDataFrame

# 2. 步骤属性引用：$step_id.attr → step_outputs[step_id].attr
context.resolve("$load-roads.crs")
# 返回 load-roads 步骤输出的 crs 属性

# 3. 变量引用：${var_name} → variables[var_name]
context.resolve("${input_path}")
# 返回 variables["input_path"] 的值

# 4. 字符串插值：包含 ${var} 的字符串
context.resolve("output/${run_id}.geojson")
# 返回 "output/20240115.geojson"（假设 run_id=20240115）

# 5. 普通值：直接返回
context.resolve(500)    # 返回 500
context.resolve(True)   # 返回 True

class StepContext:
    _params: dict          # 已解析的步骤参数
    backend: Any           # 步骤指定的后端（如有）
    pipeline_context: PipelineContext  # 全局上下文引用
    
    def param(self, name: str, default=None) -> Any:
        """获取步骤参数值。"""
    
    def input(self, name: str = "input") -> Any:
        """获取 input 参数（常见模式的快捷方式）。"""

@step(id="vector.buffer", name="缓冲区分析", ...)
def buffer_step(ctx: StepContext) -> StepResult:
    gdf = ctx.input()                           # 获取 input 参数
    distance = ctx.param("distance")            # 获取 distance 参数
    cap_style = ctx.param("cap_style", "round") # 获取可选参数，指定默认值
    
    result = gdf.buffer(distance, cap_style=cap_style)
    return StepResult(output=result, stats={"feature_count": len(result)})

def execute_pipeline(pipeline: PipelineDefinition) -> dict:
    """执行已校验的流水线，返回 JSON 可序列化的报告。"""
    context = PipelineContext(variables=pipeline.variables)
    backend_manager = BackendManager.default()
    
    step_reports = []
    
    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())  # 空结果，用于透明引用
            step_reports.append({"status": "skipped", ...})
            continue
        
        try:
            # 2. 执行步骤（含重试）
            result = _execute_step(step_def, context, backend_manager)
            # 3. 记录结果
            context.set_output(step_def.id, result)
            step_reports.append({"status": "success", ...})
        
        except Exception as e:
            if step_def.on_error == "skip":
                # 跳过：记录空结果，继续
                context.set_output(step_def.id, StepResult())
                step_reports.append({"status": "skipped", "error": str(e)})
            else:
                # 终止：记录错误，抛出异常
                raise StepExecutionError(step_def.id, str(e), ...) from e
    
    # 4. 解析 outputs 声明
    resolved_outputs = {}
    for key, ref in pipeline.outputs.items():
        resolved_outputs[key] = _summarize_output(context.resolve(ref))
    
    # 5. 构建报告
    return build_report(...)

def _execute_step(step_def, context, backend_manager):
    """执行单个步骤（支持重试）。"""
    max_attempts = 3 if step_def.on_error == "retry" else 1
    
    def _run():
        # 1. 解析参数（替换所有引用）
        resolved_params = context.resolve_params(step_def.params)
        
        # 2. 查找步骤注册信息
        step_info = registry.get(step_def.use)
        
        # 3. 验证参数（必填字段检查 + 类型转换）
        _validate_step_params(step_def.id, resolved_params, step_info)
        
        # 4. 获取后端（如步骤需要）
        backend = backend_manager.get(step_def.backend) if step_info.backends else None
        
        # 5. 构建 StepContext 并调用步骤函数
        ctx = StepContext(params=resolved_params, backend=backend, pipeline_context=context)
        result = step_info.func(ctx)
        
        return result
    
    return _with_retry(_run, max_attempts, step_def.id)

def _with_retry(fn, max_attempts: int, step_id: str):
    """指数退避重试。"""
    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, 1.0s, 1.5s
                continue
            raise

patterns = [
    ("crs" in msg and "mismatch" in msg → "添加 vector.reproject 步骤"),
    ("file not found" in msg → "检查文件路径是否正确"),
    ("self-intersection" in msg → "添加 qc.geometry_validity 步骤修复几何"),
    # ...
]

def build_report(
    pipeline_name: str,
    status: str,
    duration: float,
    step_reports: list[dict],
    outputs: dict,
) -> dict:
    return {
        "pipeline": {
            "name": pipeline_name,
            "status": status,           # "success" 或 "error"
            "duration": duration,       # 总耗时（秒）
            "timestamp": "2024-01-15T10:30:00Z",
        },
        "steps": step_reports,         # 每步的执行摘要
        "outputs": outputs,            # 输出声明的解析结果
    }

from geopipe_agent.steps.registry import step, StepContext
from geopipe_agent.models.result import StepResult

@step(
    id="vector.buffer",
    name="缓冲区分析",
    category="vector",
    description="对矢量要素进行缓冲区分析",
    params={
        "input": {"required": True, "type": "geodataframe", "description": "输入 GeoDataFrame"},
        "distance": {"required": True, "type": "number", "description": "缓冲距离"},
        "cap_style": {"required": False, "type": "string", "description": "端点样式"},
    },
    backends=["native_python"],
)
def buffer_step(ctx: StepContext) -> StepResult:
    gdf = ctx.input()
    distance = ctx.param("distance")
    cap_style = ctx.param("cap_style", "round")
    result = gdf.buffer(distance, cap_style={"round": 1, "flat": 2, "square": 3}.get(cap_style, 1))
    return StepResult(
        output=result,
        stats={"feature_count": len(result), "distance": distance}
    )

# src/geopipe_agent/__init__.py
import pkgutil
import geopipe_agent.steps as _steps_pkg

for _finder, _name, _ispkg in pkgutil.walk_packages(
    _steps_pkg.__path__, prefix=_steps_pkg.__name__ + "."
):
    import importlib
    importlib.import_module(_name)
    # 每个模块被导入时，其中的 @step 装饰器触发注册

class StepInfo:
    id: str              # 步骤 ID（如 "vector.buffer"）
    name: str            # 步骤名称
    category: str        # 步骤类别（io/vector/raster/analysis/network/qc）
    description: str     # 步骤描述
    params: dict         # 参数规格（required/type/description）
    backends: list[str]  # 支持的后端列表
    func: Callable       # 步骤执行函数