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

脚本开发指南

脚本结构

my-suite/
├── workflow.yaml
└── scripts/
    └── run.py          # 主执行文件

脚本约定

脚本通过 PARAMS_FILE 环境变量获取参数，通过 stdout 输出 JSON 结果。

接收参数

import json, os

params_file = os.environ.get("PARAMS_FILE", "/tmp/params.json")
with open(params_file) as f:
    params = json.load(f)

输出结果

result = {"status": "ok", "result": 42, "output_path": "/tmp/output/result.geojson"}
print(json.dumps(result))

stdout 的 JSON 会被执行器捕获并作为步骤结果写入调度中心。

文件输出

• 输出文件写入 /tmp/output/（步骤间共享的目录）
• 执行结束后脚本目录会被自动清理

执行环境

• 基础镜像：registry.mercator.cn/agentgis/gis-base:latest
• 包含：Python 3.11, GDAL, Shapely, GeoPandas, Fiona, PyProj, Rasterio, numpy
• 脚本目录：挂载到 /tmp/scripts（只读）
• 工作目录：挂载到 /tmp/output（读写，步骤间共享）
• 参数文件：/tmp/params.json（只读）

错误处理

脚本退出码非 0 表示执行失败。失败时在 stdout 输出错误信息：

print(json.dumps({"status": "error", "message": "文件不存在: /data/input.shp"}))
sys.exit(1)

开发建议

1. 先测试：用 agc run 验证后再发布
2. 输出明确：结果 JSON 包含关键信息
3. 错误友好：失败信息写清楚原因
4. 使用 GDAL：GIS 文件处理优先使用 GDAL 命令行工具