@click.group()
@click.version_option(package_name="geopipe-agent")
def main():
    """GeoPipeAgent — AI-Native GIS Analysis Pipeline Framework."""
    pass

def parse_yaml(source: str | Path) -> PipelineDefinition:
    """Parse a YAML pipeline file or string into a PipelineDefinition."""

def validate_pipeline(pipeline: PipelineDefinition) -> list[str]:
    """Validate a parsed pipeline definition. Returns warnings."""

def resolve_step_params(pipeline, step_index, context) -> dict:
    """Resolve all parameters for a step."""

class PipelineContext:
    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:
        """批量解析参数字典"""

class StepContext:
    def param(self, name: str, default=None) -> Any:
        """获取解析后的参数"""

    def input(self, name: str = "input") -> Any:
        """获取输入数据（param('input') 的快捷方式）"""

    @property
    def backend(self) -> GeoBackend:
        """获取当前后端"""

def execute_pipeline(pipeline: PipelineDefinition) -> dict:
    """Execute a validated pipeline and return a JSON report."""

if step_def.when:
    if not _evaluate_condition(step_def.when, context):
        # 跳过此步骤

match step_def.on_error:
    case "fail":   # 停止流水线（默认）
    case "skip":   # 跳过失败的步骤，继续执行
    case "retry":  # 重试最多 3 次，指数退避

def _suggest_fix(step_use: str, error: Exception) -> str | None:
    """Generate an AI-friendly fix suggestion."""
    # 例如：CRS 不匹配时建议添加 reproject 步骤
    # 文件不存在时建议检查路径

def build_report(pipeline_name, status, duration, step_reports, outputs) -> dict:
    """Build a JSON-serializable execution report."""

class StepRegistry:
    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance._steps = {}
        return cls._instance

@step(
    id="vector.buffer",
    name="矢量缓冲区分析",
    description="...",
    category="vector",
    params={...},
    outputs={...},
    backends=["gdal_python", "qgis_process"],
    examples=[...],
)
def vector_buffer(ctx: StepContext) -> StepResult:
    ...

def load_builtin_steps() -> None:
    """Import all built-in step modules to trigger registration."""
    import geopipe_agent.steps.io.read_vector
    import geopipe_agent.steps.io.write_vector
    # ... 共 23 个 import

class GeoBackend(ABC):
    @abstractmethod
    def name(self) -> str: ...
    @abstractmethod
    def is_available(self) -> bool: ...
    @abstractmethod
    def buffer(self, gdf, distance, **kwargs): ...
    @abstractmethod
    def clip(self, input_gdf, clip_gdf, **kwargs): ...
    @abstractmethod
    def reproject(self, gdf, target_crs, **kwargs): ...
    @abstractmethod
    def dissolve(self, gdf, by=None, **kwargs): ...
    @abstractmethod
    def simplify(self, gdf, tolerance, **kwargs): ...
    @abstractmethod
    def overlay(self, gdf1, gdf2, how="intersection", **kwargs): ...

class BackendManager:
    def __init__(self):
        self.backends = []
        self._detect_available()  # 自动检测

    def get(self, preferred=None) -> GeoBackend:
        """获取后端（指定或默认第一个可用的）"""

@dataclass
class PipelineDefinition:
    name: str
    steps: list[StepDefinition]
    description: str = ""
    crs: str | None = None
    variables: dict = field(default_factory=dict)
    outputs: dict = field(default_factory=dict)

@dataclass
class StepDefinition:
    id: str                     # 唯一标识符
    use: str                    # 步骤类型（如 "vector.buffer"）
    params: dict = {}           # 参数
    when: str | None = None     # 条件执行表达式
    on_error: str = "fail"      # 错误处理策略
    backend: str | None = None  # 指定后端

@dataclass
class StepResult:
    output: Any = None          # 主要输出（通常是 GeoDataFrame）
    stats: dict = {}            # 统计信息
    metadata: dict = {}         # 元数据

class StepExecutionError(GeopipeAgentError):
    def __init__(self, step_id, message, cause=None, suggestion=None):
        self.step_id = step_id
        self.suggestion = suggestion  # AI 修复建议
        self.cause = cause

    def to_dict(self) -> dict:
        """转为 JSON，便于 AI 解析"""

def setup_logging(level: str = "INFO", json_format: bool = False):
    ...

def normalize_crs(crs_input: str) -> str:
    """将各种 CRS 表示归一化为 EPSG 代码"""

# 安全的做法：先验证 AST，再执行
tree = ast.parse(expression, mode="eval")
for node in ast.walk(tree):
    if not isinstance(node, _SAFE_NODES):
        raise ValueError("不安全的表达式")
result = eval(compile(tree, ...))