agent-profiles/suite-developer/knowledge/script-dependencies.md

脚本依赖管理规范

归属： SuiteForge 知识库 | knowledge/script-dependencies.md 版本： 1.0.0 关联： 脚本数据类型分类规范

---

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 中声明

# 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 中声明

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

- id: parse-excel
  type: script
  script_id: run
  dependencies:
    pip:
      - openpyxl>=3.0

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

---

4. 依赖分级处理机制

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

适用场景：

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

处理流程：

# 容器启动时自动安装
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 秒以上的

扩展镜像命名规则：

registry.mercator.cn/agentgis/gis-ext-{功能}:{版本}

已规划扩展镜像：

镜像名	包含依赖	典型脚本场景
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.ext
FROM registry.mercator.cn/agentgis/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 只能引用 registry.mercator.cn/agentgis/* 系列镜像
• 不允许 FROM 外部镜像库（安全性）
• RUN pip 的来源 URL 必须在白名单内（PyPI 官方默认通过）
• RUN apt 来源必须在 apt allowlist 内

CI 流水线（Cron 兜底）：

脚本发布 → 检测到 Dockerfile.ext
         → 合规检测通过
         → 构建自定义镜像
         → 推送到 registry.mercator.cn/agentgis/custom/{suite_id}:{version}
         → 将镜像 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. agc publish → 合规检测自动处理

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

---

9. 与相关服务的关系

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