# 脚本依赖管理规范

> **归属：** SuiteForge 知识库 | `knowledge/script-dependencies.md`
> **版本：** 1.0.0
> **关联：** [脚本数据类型分类规范](./script-data-types.md)

---

## 1. 核心原则

- **gis-base 保持精干** — 只放所有脚本绝对需要的核心库
- **依赖按需加载** — 不允许在基础镜像预装所有可能的依赖
- **依赖类型决定加载策略** — 轻量运行时装、中量预构建镜像、重型发布时构建

---

## 2. gis-base 内置依赖（开箱即有）

以下库在 `gis-base` 镜像中预置，脚本无需额外声明依赖即可使用：

| 类别 | 库 | 用途 |
|------|----|------|
| Python 标准库 | `os`, `sys`, `json`, `csv`, `math`, `re`, `pathlib`, `shutil`, `subprocess`, `tempfile`, `zipfile`, `tarfile`, `uuid`, `datetime`, `logging` | 基础操作 |
| 数值计算 | `numpy` | 核心数组运算 |
| GIS 核心 | `gdal`（含 `ogr`, `osr`, `gdalconst`）, `osgeo` | 栅格/矢量读写 |
| GIS 扩展 | `shapely`, `geopandas`, `pyproj`, `fiona` | 空间分析 |
| 序列化 | `orjson` | 高性能 JSON |

> **注意：** gis-base 镜像内容由平台团队维护。需要新增内置库时，请通过 Issue 提出，交 Admin 处理。

---

## 3. 依赖声明方式

### 3.1 脚本 metadata 中声明

```yaml
# scripts/run.py 同目录的 metadata.yaml
name: 读取 Excel 坐标转 Shapefile
version: 1.0.0
data_type: document/xlsx
dependencies:
  # 轻量运行时依赖
  pip:
    - openpyxl>=3.0
    - python-docx>=0.8

  # 系统级依赖（apt 包）
  system:
    - libpdal-dev        # 点云处理库

  # 构建时依赖（必须通过 Dockerfile.ext 安装）
  build:
      # 空数组表示无构建时依赖
```

### 3.2 workflow.yaml 中声明

当在套件中直接引用脚本时，也可以在步骤级别声明：

```yaml
- id: parse-excel
  type: python
  script_id: run
  dependencies:
    pip:
      - openpyxl>=3.0
```

> 步骤级声明会覆盖脚本自带的依赖声明。

---

## 4. 依赖分级处理机制

### 4.1 级别一：轻量运行时依赖（pip）

**适用场景：**
- 纯 Python 包，无编译依赖
- 体积小，安装快（< 30 秒）
- 非高频调用（偶尔使用）

**处理流程：**
```bash
# 容器启动时自动安装
docker run --rm gis-base   pip install openpyxl python-docx --no-cache-dir   && python /tmp/scripts/run.py
```

**限速规则：** 单次任务安装的 pip 包不超过 10 个，总安装时间不超过 60 秒。

### 4.2 级别二：中量扩展镜像（预构建）

**适用场景：**
- 经常被调用的扩展依赖
- 有编译环节的包（C 扩展）
- 安装需要 30 秒以上的

**扩展镜像命名规则：**

```
gis-ext-{功能}:latest（自托管）
```

**已规划扩展镜像：**

| 镜像名 | 包含依赖 | 典型脚本场景 |
|--------|---------|-------------|
| `gis-ext-doc` | `openpyxl`, `python-docx`, `pypdf2`, `python-pptx` | Office 文档处理 |
| `gis-ext-pointcloud` | `laspy`, `pdal`, `open3d-python` | 点云处理 |
| `gis-ext-raster` | `rioxarray`, `rasterio`, `xarray`, `scipy` | 高级栅格分析 |
| `gis-ext-geoanalysis` | `scipy`, `scikit-learn`, `statsmodels` | 空间统计分析 |
| `gis-ext-ml` | `scikit-learn`, `xgboost`, `lightgbm` | 地理空间机器学习 |
| `gis-ext-web` | `requests`, `httpx`, `aiohttp`, `beautifulsoup4` | 网络数据抓取 |
| `gis-ext-db` | `psycopg2-binary`, `sqlalchemy`, `sqlite-utils` | 数据库连接 |

**匹配逻辑（调度中心）：**

```
脚本声明的 pip 依赖
           ↓
调度中心匹配 → 命中扩展镜像 → 使用扩展镜像运行
           → 未命中 → 回退级别一（运行时安装）
```

匹配是取**最小子集**——如果脚本只需要 `openpyxl`，就用 `gis-ext-doc`，而不是选所有包含 `openpyxl` 的镜像。

### 4.3 级别三：重型自定义镜像（构建时）

**适用场景：**
- 深度学习框架（PyTorch, TensorFlow）
- 需要 GPU 加速（CUDA 依赖）
- 专有库/商业许可库（选装）
- 安装时间 > 120 秒的

**处理方式：**

脚本发布时附带 `Dockerfile.ext`：

```dockerfile
# Dockerfile.ext
FROM gis-base:latest

# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends     libgl1-mesa-glx     && rm -rf /var/lib/apt/lists/*

# 安装 Python 依赖
RUN pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu     opencv-python-headless     --no-cache-dir
```

**合规检测规则：**
- `FROM` 只能引用 `gis-base:*` 系列镜像
- 不允许 `FROM` 外部镜像库（安全性）
- `RUN pip` 的来源 URL 必须在白名单内（PyPI 官方默认通过）
- `RUN apt` 来源必须在 `apt allowlist` 内

**CI 流水线（Cron 兜底）：**

```
脚本发布 → 检测到 Dockerfile.ext
         → 合规检测通过
         → 构建自定义镜像
         → 推送到自建 Docker Registry 或 Gitea Packages OCI
         → 将镜像 ID 写入脚本 metadata
```

---

## 5. 依赖来源安全白名单

### 5.1 Python 包

| 来源 | 状态 | 说明 |
|------|------|------|
| `pypi.org`（官方） | ✅ 白名单 | 默认允许 |
| `download.pytorch.org` | ✅ 白名单 | ML 框架 |
| `github.com/releases` | ⚠️ 需审核 | 非标准包需要人工审核 |

### 5.2 系统包（apt）

| 来源 | 状态 | 说明 |
|------|------|------|
| `archive.ubuntu.com` | ✅ 白名单 | Ubuntu 官方源 |
| `security.ubuntu.com` | ✅ 白名单 | 安全更新 |
| `ppa.launchpad.net` | ❌ 禁止 | PPA 源不稳定 |

---

## 6. 常见场景参考

| 脚本要做什么 | 推荐方案 | 依赖示例 |
|------------|---------|---------|
| 读取 Excel 坐标转点 | 级别一 | `openpyxl` |
| PDF 空间信息提取 | 级别一 | `pypdf2` |
| 点云格式转换（LAS → LAZ）| 级别二 | 预置 `gis-ext-pointcloud` |
| 地形分析（坡度/坡向）| 内置 | `numpy` + `gdal` 已内置 |
| 地理空间分类模型 | 级别二 | 预置 `gis-ext-geoanalysis` |
| 遥感影像深度学习分类 | 级别三 | `torch`, `opencv` |
| 企业微信消息推送 | 级别一 | `requests` 已内置 |
| 大量 GeoJSON 合并 | 内置 | `geopandas` 已内置 |

---

## 7. 镜像更新策略

### 扩展镜像
- 每月重建一次（拉取最新安全更新）
- 有 CVE 时立即重建
- 版本锁定的包如无必要不升级大版本

### gis-base
- 仅在有架构级更新时重建
- 版本变更需经过完整回归测试
- 历史版本保留至少 3 个次要版本

### 自定义镜像
- 由脚本开发者管理版本
- 重新发布脚本时自动重建
- 无自动更新，需要开发者主动重新发布

---

## 8. 开发者工作流（供 SuiteForge 参考）

```
1. 想清脚本需要什么依赖
2. 查 gis-base 内置列表 → 已有的不声明
3. 查扩展镜像列表 → 匹配的用级别二
4. 都不行 → 看看能不能用轻量安装（级别一）
5. 真不行 → 写 Dockerfile.ext（级别三）
6. 完成 metadata.yaml 声明
7. 通过 API 发布（详见套件发布指南）
```

**SuiteForge 应在初始化套件时根据脚本内容自动推断依赖**，无需开发者手动填写 metadata。开发者只需要告诉 SuiteForge "我想处理 Excel 文件"，剩下的由 Agent 完成。

---

## 9. 与相关服务的关系

| 服务 | 对接方式 |
|------|---------|
| **合规检测服务** | 读取 dependencies 字段 + Dockerfile.ext 进行安全校验 |
| **调度中心** | 根据依赖选择镜像层次（base / ext / custom） |
| **构建流水线（Cron）** | 检测到 Dockerfile.ext 时触发自定义镜像构建 |
| **镜像仓库（Registry）** | 存储 gis-base、扩展镜像、自定义镜像 |