第二章：安装与环境配置

2.1 系统要求

GeoPipeAgent 的运行环境要求如下：

2.1.1 可选依赖

根据使用场景，可能还需要安装以下可选组件：

2.2 安装方式

2.2.1 从源码安装（推荐开发者）

# 克隆仓库
git clone https://github.com/znlgis/GeoPipeAgent.git
cd GeoPipeAgent

# 创建虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows

# 安装基础依赖
pip install -e .

# 安装开发依赖（含测试工具）
pip install -e ".[dev]"

# 安装全部可选依赖
pip install -e ".[dev,analysis,network]"

2.2.2 依赖组说明

GeoPipeAgent 使用 pyproject.toml 管理依赖，分为以下几组：

核心依赖（自动安装）：

dependencies = [
    "click>=8.0",         # CLI 框架
    "pyyaml>=6.0",        # YAML 解析
    "geopandas>=0.14",    # 矢量数据处理
    "shapely>=2.0",       # 几何引擎
    "fiona>=1.9",         # 矢量 IO
    "rasterio>=1.3",      # 栅格数据处理
    "jsonschema>=4.0",    # Schema 验证
]

开发依赖（[dev]）：

dev = [
    "pytest>=7.0",        # 测试框架
    "pytest-cov>=4.0",    # 覆盖率
]

分析依赖（[analysis]）：

analysis = [
    "scipy>=1.10",        # 科学计算
    "scikit-learn>=1.2",  # 机器学习
    "matplotlib>=3.7",    # 可视化
]

网络依赖（[network]）：

network = [
    "networkx>=3.0",      # 图论算法
    "geopy>=2.3",         # 地理编码
]

2.3 验证安装

2.3.1 检查 CLI 可用性

安装完成后，可以通过以下命令验证：

# 查看版本
geopipe-agent --version

# 查看帮助
geopipe-agent --help

期望输出：

Usage: geopipe-agent [OPTIONS] COMMAND [ARGS]...

  GeoPipeAgent — AI-Native GIS Analysis Pipeline Framework.

Options:
  --version  Show the version number and exit.
  --help     Show this message and exit.

Commands:
  backends            List available GIS backends and their status.
  describe            Show detailed information about a specific step.
  generate-skill      Generate complete Skill file set for AI.
  generate-skill-doc  Generate steps reference Markdown for AI consumption.
  info                Show summary information about a GIS data file.
  list-steps          List all available pipeline steps.
  run                 Run a YAML pipeline file.
  validate            Validate a YAML pipeline file without executing it.

2.3.2 检查后端可用性

geopipe-agent backends

期望输出（取决于你的系统安装情况）：

[
  {"name": "gdal_python", "available": true},
  {"name": "gdal_cli", "available": false},
  {"name": "qgis_process", "available": false}
]

• gdal_python：如果 GeoPandas 和 Shapely 安装成功，该后端即可用
• gdal_cli：需要系统安装 GDAL 命令行工具（ogr2ogr 可执行）
• qgis_process：需要安装 QGIS 并且 qgis_process 在系统 PATH 中

2.3.3 列出可用步骤

geopipe-agent list-steps

期望输出：

ID                             Name                 Category     Backends
--------------------------------------------------------------------------------
io.read_vector                 读取矢量数据          io           -
io.write_vector                写入矢量数据          io           -
io.read_raster                 读取栅格数据          io           -
io.write_raster                写入栅格数据          io           -
vector.buffer                  矢量缓冲区分析        vector       gdal_python, qgis_process
vector.clip                    矢量裁剪             vector       gdal_python, qgis_process
vector.reproject               投影转换             vector       gdal_python, qgis_process
...

Total: 23 steps

2.3.4 运行测试

如果安装了开发依赖，可以运行测试来验证一切正常：

# 运行所有测试
pytest

# 运行测试并显示覆盖率
pytest --cov=geopipe_agent

# 只运行特定模块的测试
pytest tests/test_engine/
pytest tests/test_steps/
pytest tests/test_backends/

期望看到 95 个测试全部通过：

======================== 95 passed in X.XXs ========================

2.4 GDAL CLI 后端安装

如果需要使用 gdal_cli 后端（适合处理大文件），需要安装 GDAL 命令行工具。

2.4.1 Ubuntu/Debian

sudo apt-get update
sudo apt-get install gdal-bin

2.4.2 macOS（Homebrew）

brew install gdal

2.4.3 Windows

推荐通过 OSGeo4W 安装器安装 GDAL：

1. 下载 OSGeo4W 安装器
2. 选择安装 GDAL 包
3. 将安装路径添加到系统 PATH 环境变量

或者通过 conda 安装：

conda install -c conda-forge gdal

2.4.4 验证 GDAL CLI

ogr2ogr --version

期望输出类似：

GDAL 3.x.x, released 202x/xx/xx

2.5 QGIS Process 后端安装

如果需要使用 qgis_process 后端（提供 QGIS 的高级 GIS 算法），需要安装 QGIS。

2.5.1 安装 QGIS

从 QGIS 官网 下载并安装适合你操作系统的版本。

2.5.2 配置 PATH

确保 qgis_process 可执行文件在系统 PATH 中：

Linux：

# 通常在以下路径
export PATH=$PATH:/usr/bin

macOS：

export PATH=$PATH:/Applications/QGIS.app/Contents/MacOS/bin

Windows：

将 QGIS 安装路径（如 C:\Program Files\QGIS 3.x\bin）添加到系统 PATH。

2.5.3 验证 QGIS Process

qgis_process --help

2.6 开发环境配置

2.6.1 推荐的 IDE 配置

VS Code 推荐插件：

VS Code settings.json 推荐配置：

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.testing.pytestArgs": ["tests"],
  "python.testing.pytestEnabled": true,
  "[python]": {
    "editor.formatOnSave": true
  }
}

2.6.2 项目构建配置

GeoPipeAgent 使用 setuptools 作为构建后端：

[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

包查找配置指向 src 目录：

[tool.setuptools.packages.find]
where = ["src"]

测试配置：

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]

2.6.3 调试配置

在 VS Code 中调试 GeoPipeAgent CLI：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Pipeline",
      "type": "debugpy",
      "request": "launch",
      "module": "geopipe_agent.cli",
      "args": ["run", "cookbook/buffer-analysis.yaml"],
      "cwd": "${workspaceFolder}"
    },
    {
      "name": "Validate Pipeline",
      "type": "debugpy",
      "request": "launch",
      "module": "geopipe_agent.cli",
      "args": ["validate", "cookbook/buffer-analysis.yaml"],
      "cwd": "${workspaceFolder}"
    }
  ]
}

2.7 常见安装问题

2.7.1 GDAL/GEOS 编译问题

在某些系统上，安装 GeoPandas 或 Fiona 时可能遇到编译问题。推荐解决方案：

方案一：使用 conda

conda create -n geopipe python=3.10
conda activate geopipe
conda install -c conda-forge geopandas fiona rasterio shapely
pip install -e .

方案二：安装系统依赖

Ubuntu/Debian：

sudo apt-get install libgdal-dev libgeos-dev libproj-dev

macOS：

brew install gdal geos proj

2.7.2 Python 版本不兼容

GeoPipeAgent 要求 Python >= 3.10，因为使用了以下语法特性：

# 类型联合语法（Python 3.10+）
def func(value: str | None = None):
    ...

# match 语句（如果使用到）
match step.on_error:
    case "skip": ...
    case "retry": ...

如果系统默认 Python 版本较低，可以使用 pyenv 管理多版本：

pyenv install 3.10.12
pyenv local 3.10.12

2.7.3 Windows 路径问题

在 Windows 上使用 YAML 流水线时，文件路径中的反斜杠 \ 可能被 YAML 解析器解释为转义字符。建议在 YAML 中始终使用正斜杠 /：

# ✅ 正确
path: "C:/data/roads.shp"

# ❌ 错误（反斜杠可能导致解析错误）
path: "C:\data\roads.shp"

2.8 下一步

安装完成后，建议按以下顺序继续学习：

1. 阅读 第三章：核心架构与模块设计 了解整体架构
2. 阅读 第四章：YAML 流水线 Schema 详解 学习如何编写流水线
3. 尝试运行 cookbook/ 目录下的示例流水线