agent-profiles/suites-help/开发者指南/脚本开发指南.md

脚本开发指南

脚本执行环境

脚本在两种环境中执行：

1. Linux Docker 容器（runtime: docker）—— 隔离执行，gis-base 镜像
2. Windows 本机进程（runtime: python3 / arcpy）—— 直接 subprocess 执行

执行环境由 workflow.yaml 中步骤的 runtime 字段决定。下面以 Docker 为例说明容器结构：

容器内目录结构

/tmp/
├── scripts/          ← 套件脚本包（只读）
│   ├── run.py
│   └── ...其他脚本文件
├── output/           ← 工作目录（读写，步骤间共享）
│   ├── 点状工程.shp    ← 用户提供的输入文件
│   └── computed_data.json
├── params.json       ← 参数文件（只读）
└── step_output/      ← 当前步骤输出目录

基础镜像

• 镜像：gis-base:latest（执行 agc run 时自动从 Gitea Packages 下载）
• 内置：Python 3.11, GDAL, Shapely, GeoPandas, numpy, openpyxl, xlrd, fiona
• 参数文件：/tmp/params.json
• 输出目录：/tmp/output/

脚本入口

脚本通过命令行参数接收参数：

import sys, json

if __name__ == "__main__":
    params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
    # params = {"input_path": "/tmp/output/data.shp", ...}
    result = run(params)
    print(json.dumps(result, ensure_ascii=False))

依赖管理

脚本中缺失的依赖通过运行时 pip 安装：

import subprocess, sys
try:
    import openpyxl
except ImportError:
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'openpyxl'])

输出规范

脚本执行完成后，向 stdout 输出 JSON：

{"status": "completed", "output_path": "/tmp/output/result.shp"}