第十五章：实战案例与最佳实践

15.1 概述

本章通过实战案例展示 GeoPipeAgent 的完整使用流程，并总结最佳实践和开发指南。

15.2 实战案例

15.2.1 案例一：缓冲区分析

场景：对城市道路进行 500 米缓冲区分析，用于噪音影响评估。

# buffer-analysis.yaml
pipeline:
  name: "缓冲区分析"
  description: "对道路数据进行缓冲区分析并输出结果"

  variables:
    input_path: "data/roads.shp"
    buffer_dist: 500
    output_format: "GeoJSON"

  steps:
    - id: load-roads
      use: io.read_vector
      params:
        path: "${input_path}"

    - id: reproject
      use: vector.reproject
      params:
        input: "$load-roads.output"
        target_crs: "EPSG:3857"

    - id: buffer-analysis
      use: vector.buffer
      params:
        input: "$reproject.output"
        distance: "${buffer_dist}"
        cap_style: "round"

    - id: save-result
      use: io.write_vector
      params:
        input: "$buffer-analysis.output"
        path: "output/road_buffer.geojson"
        format: "${output_format}"

  outputs:
    result: "$save-result.output"
    stats: "$buffer-analysis.stats"

执行：

geopipe-agent run buffer-analysis.yaml

# 或覆盖参数
geopipe-agent run buffer-analysis.yaml --var buffer_dist=1000

15.2.2 案例二：叠加分析

场景：分析洪泛区内的土地利用类型。

# overlay-analysis.yaml
pipeline:
  name: "叠加分析"
  description: "对两个矢量图层进行交集叠加分析"

  steps:
    - id: load-layer1
      use: io.read_vector
      params:
        path: "data/landuse.shp"

    - id: load-layer2
      use: io.read_vector
      params:
        path: "data/flood_zone.shp"

    - id: overlay-analysis
      use: vector.overlay
      params:
        input: "$load-layer1.output"
        overlay_layer: "$load-layer2.output"
        how: "intersection"

    - id: save-result
      use: io.write_vector
      params:
        input: "$overlay-analysis.output"
        path: "output/landuse_in_flood_zone.geojson"
        format: "GeoJSON"

  outputs:
    result: "$save-result.output"
    stats: "$overlay-analysis.stats"

15.2.3 案例三：批量格式转换

场景：将 Shapefile 转换为 GeoJSON 格式并投影到 WGS84。

# batch-convert.yaml
pipeline:
  name: "批量转换"
  description: "将 Shapefile 转换为 GeoJSON 格式并投影到 WGS84"

  variables:
    input_path: "data/buildings.shp"
    output_path: "output/buildings_wgs84.geojson"

  steps:
    - id: read-data
      use: io.read_vector
      params:
        path: "${input_path}"

    - id: reproject
      use: vector.reproject
      params:
        input: "$read-data.output"
        target_crs: "EPSG:4326"

    - id: write-output
      use: io.write_vector
      params:
        input: "$reproject.output"
        path: "${output_path}"
        format: "GeoJSON"

  outputs:
    result: "$write-output.output"

批量处理多个文件：

for file in data/*.shp; do
    name=$(basename "$file" .shp)
    geopipe-agent run batch-convert.yaml \
        --var input_path="$file" \
        --var output_path="output/${name}_wgs84.geojson"
done

15.2.4 案例四：数据筛选与简化

场景：从地块数据中筛选面积大于 1000 平方米的地块，并简化几何。

# filter-simplify.yaml
pipeline:
  name: "数据筛选与简化"
  description: "筛选特定属性的要素，然后简化几何以减少文件大小"

  variables:
    input_path: "data/parcels.shp"
    filter_expression: "area_sqm > 1000"
    simplify_tolerance: 1.0

  steps:
    - id: read-data
      use: io.read_vector
      params:
        path: "${input_path}"

    - id: filter
      use: vector.query
      params:
        input: "$read-data.output"
        expression: "${filter_expression}"

    - id: simplify
      use: vector.simplify
      params:
        input: "$filter.output"
        tolerance: "${simplify_tolerance}"

    - id: save
      use: io.write_vector
      params:
        input: "$simplify.output"
        path: "output/filtered_simplified.geojson"

  outputs:
    result: "$save.output"
    filter_stats: "$filter.stats"

15.2.5 案例五：融合分析

场景：按用地类型融合面要素。

# dissolve-analysis.yaml
pipeline:
  name: "融合分析"
  description: "按类型字段融合面要素"

  steps:
    - id: read-data
      use: io.read_vector
      params:
        path: "data/landuse.shp"

    - id: dissolve
      use: vector.dissolve
      params:
        input: "$read-data.output"
        by: "landuse_type"
        aggfunc: "first"

    - id: save
      use: io.write_vector
      params:
        input: "$dissolve.output"
        path: "output/landuse_dissolved.geojson"

  outputs:
    result: "$save.output"
    stats: "$dissolve.stats"

15.3 最佳实践

15.3.1 流水线设计原则

1. 始终使用变量

将可能变化的值提取为变量，使流水线可复用：

# ✅ 好的做法
variables:
  input_path: "data/roads.shp"
  buffer_dist: 500
steps:
  - id: read
    use: io.read_vector
    params:
      path: "${input_path}"

# ❌ 不好的做法
steps:
  - id: read
    use: io.read_vector
    params:
      path: "data/roads.shp"      # 硬编码

2. 在缓冲区分析前投影转换

缓冲区距离取决于 CRS 单位，使用地理坐标系时距离单位是度。始终先投影到米为单位的坐标系：

steps:
  - id: reproject
    use: vector.reproject
    params:
      input: "$read.output"
      target_crs: "EPSG:3857"    # 投影到米单位
  - id: buffer
    use: vector.buffer
    params:
      input: "$reproject.output"
      distance: 500               # 500 米

3. 使用有意义的 step_id

# ✅ 好的命名
- id: load-roads
- id: buffer-analysis
- id: save-result

# ❌ 不好的命名
- id: step1
- id: a
- id: x

4. 添加描述

为流水线和关键步骤添加描述，便于理解和维护：

pipeline:
  name: "城市绿地可达性分析"
  description: "分析城市居民步行15分钟范围内的绿地覆盖情况"

15.3.2 错误处理策略

1. 对网络操作使用 retry

- id: download
  use: io.read_vector
  params:
    path: "http://example.com/data.geojson"
  on_error: retry

2. 对可选步骤使用 skip

- id: optional-simplify
  use: vector.simplify
  params:
    input: "$buffer.output"
    tolerance: 0.5
  on_error: skip    # 简化失败不影响流水线

3. 使用 when 条件避免空数据错误

- id: filter
  use: vector.query
  params:
    input: "$read.output"
    expression: "area > 1000"

- id: buffer
  use: vector.buffer
  params:
    input: "$filter.output"
    distance: 500
  when: "$filter.feature_count > 0"    # 只在有数据时执行

15.3.3 性能优化建议

建议	说明
先筛选再分析	减少分析步骤的数据量
使用合适的后端	大文件用 `gdal_cli`
合理设置简化容差	减少不必要的精度
避免不必要的投影转换	如果 CRS 已满足需求则跳过
使用变量避免重复	减少 YAML 冗余

15.3.4 调试技巧

1. 使用 validate 命令预检

geopipe-agent validate pipeline.yaml

2. 使用 DEBUG 日志级别

geopipe-agent run pipeline.yaml --log-level DEBUG

3. 使用 info 命令检查数据

geopipe-agent info data/input.shp

4. 逐步添加步骤

先写一个最小流水线，验证通过后逐步添加步骤：

# 先确认数据能读取
pipeline:
  name: "调试"
  steps:
    - id: read
      use: io.read_vector
      params:
        path: "data/input.shp"

# 然后添加分析步骤...

15.3.5 安全注意事项

事项	说明
不要从不信任的来源加载 YAML	YAML 可能包含恶意表达式
注意 query 表达式安全	vector.query 使用 pandas eval
使用变量而不是硬编码路径	便于环境切换
检查输入数据来源	确保数据完整性

15.4 添加新步骤的检查清单

当你需要为 GeoPipeAgent 添加新的分析步骤时，按照以下检查清单操作：

创建步骤模块文件（如 steps/vector/centroid.py）
使用 @step 装饰器声明元信息
实现步骤函数，接受 StepContext，返回 StepResult
在 steps/__init__.py 的 load_builtin_steps() 中添加 import
如需 Backend 支持，在 GeoBackend 基类添加抽象方法
在所有 Backend 实现类中实现具体方法
编写单元测试
运行 geopipe-agent generate-skill-doc 验证文档自动生成
运行全部测试确认不影响已有功能

15.5 Windows 兼容性注意

在 Windows 环境下使用 GeoPipeAgent 时：

YAML 文件路径使用正斜杠：path: "C:/data/roads.shp"
测试中使用 POSIX 路径：在 YAML 模板中嵌入路径时转换为正斜杠
注意编码问题：中文 Shapefile 可能需要指定 encoding: "gbk"

15.6 项目状态与扩展方向

15.6.1 当前状态

GeoPipeAgent v0.1.0 已实现的功能：

模块	状态
项目结构	✅ 完成
错误处理	✅ 完成
数据模型	✅ 完成
Step 插件系统	✅ 完成
Backend 系统	✅ 完成（3 个后端）
Engine 核心	✅ 完成（6 个子模块）
CLI	✅ 完成（8 个命令）
IO Steps	✅ 完成（4 个）
Vector Steps	✅ 完成（7 个）
Raster Steps	✅ 完成（5 个）
Analysis Steps	✅ 完成（4 个）
Network Steps	✅ 完成（3 个）
Skill 生成	✅ 完成
测试	✅ 完成（95 个）
Cookbook	✅ 完成（5 个示例）

15.6.2 可能的扩展方向

方向	说明
并行执行	支持无依赖的步骤并行执行
PostGIS Backend	支持直接在数据库中执行空间操作
Web API	提供 REST API 接口
更多分析步骤	添加更多空间分析算法
可视化步骤	添加地图输出步骤
流水线嵌套	支持子流水线调用
条件分支	支持 if/else 分支逻辑

15.7 学习资源

资源	说明
GeoPipeAgent 源码	项目源代码
`cookbook/` 目录	5 个示例流水线
`tests/` 目录	95 个测试用例，可作为使用示例
`geopipe-agent generate-skill-doc`	自动生成的步骤参考
GeoPandas 文档	矢量数据处理参考
Rasterio 文档	栅格数据处理参考
Shapely 文档	几何引擎参考

15.8 总结

GeoPipeAgent 是一个创新性的 GIS 分析框架，它将 AI 和 GIS 的结合推向了新的高度。通过 YAML 声明式流水线、插件化的步骤系统、多后端支持和自动化的 Skill 文件生成，GeoPipeAgent 使得 AI Agent 能够自主理解和执行复杂的 GIS 分析任务。

无论你是 GIS 开发者希望提高分析效率，还是 AI 开发者希望为你的 Agent 添加空间分析能力，GeoPipeAgent 都提供了一个简洁而强大的解决方案。