From cb05b3960bee4a2e31c621ae97697fd7d06710a3 Mon Sep 17 00:00:00 2001
From: Huawei <huawei@mercator.cn>
Date: Thu, 9 Jul 2026 15:10:25 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20suites-help/=E5=BC=80=E5=8F=91=E8=80=85?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97/=E8=84=9A=E6=9C=AC=E5=BC=80=E5=8F=91?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 suites-help/开发者指南/脚本开发指南.md | 62 ++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 suites-help/开发者指南/脚本开发指南.md

diff --git a/suites-help/开发者指南/脚本开发指南.md b/suites-help/开发者指南/脚本开发指南.md
new file mode 100644
index 0000000..bb11a7b
--- /dev/null
+++ b/suites-help/开发者指南/脚本开发指南.md
@@ -0,0 +1,62 @@
+# 脚本开发指南
+
+## 脚本结构
+
+```
+my-suite/
+├── workflow.yaml
+└── scripts/
+    └── run.py          # 主执行文件
+```
+
+## 脚本约定
+
+脚本通过 `PARAMS_FILE` 环境变量获取参数，通过 stdout 输出 JSON 结果。
+
+### 接收参数
+
+```python
+import json, os
+
+params_file = os.environ.get("PARAMS_FILE", "/tmp/params.json")
+with open(params_file) as f:
+    params = json.load(f)
+```
+
+### 输出结果
+
+```python
+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 输出错误信息：
+
+```python
+print(json.dumps({"status": "error", "message": "文件不存在: /data/input.shp"}))
+sys.exit(1)
+```
+
+## 开发建议
+
+1. **先测试**：用 `agc run` 验证后再发布
+2. **输出明确**：结果 JSON 包含关键信息
+3. **错误友好**：失败信息写清楚原因
+4. **使用 GDAL**：GIS 文件处理优先使用 GDAL 命令行工具