fix(#8): 脚本开发指南 — 替换 registry.mercator.cn 为 gis-base:latest

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

@@ -1,55 +1,60 @@
 # 脚本开发指南
 
-## 脚本约定
+## 脚本执行环境
 
-`scripts/run.py` 通过环境变量获取参数，通过 stdout 输出 JSON 结果。
+所有脚本在 **用户本地的 Docker 容器** 中执行。
 
-### 接收参数
+### 容器内目录结构
 
-```python
+```
-import json, os
+/tmp/
-
+├── scripts/          ← 套件脚本包（只读）
-params_file = os.environ.get("PARAMS_FILE", "/tmp/params.json")
+│   ├── run.py
-with open(params_file) as f:
+│   └── ...其他脚本文件
-    params = json.load(f)
+├── output/           ← 工作目录（读写，步骤间共享）
-
+│   ├── 点状工程.shp    ← 用户提供的输入文件
-expression = params.get("expression", "1+1")
+│   └── computed_data.json
-precision = int(params.get("precision", 2))
+├── params.json       ← 参数文件（只读）
+└── step_output/      ← 当前步骤输出目录
 ```
 
-### 输出结果
+### 基础镜像
 
-```python
+- **镜像**：`gis-base:latest`（执行 `agc run` 时自动从 Gitea Packages 下载）
-result = {"status": "ok", "result": 42, "output_path": "/tmp/output/result.geojson"}
+- **内置**：Python 3.11, GDAL, Shapely, GeoPandas, numpy, openpyxl, xlrd, fiona
-print(json.dumps(result))
-```
-
-stdout 的 JSON 会被执行器捕获并作为步骤结果。
-
-### 文件输出
-
-- 输出文件写入 `/tmp/output/`（步骤间共享）
-- 执行结束后脚本目录自动清理
-
-## 执行环境
-
-- **基础镜像**：`gis-base:latest`（从 Gitea Packages 加载 tar.gz）
-- **包含**：Python 3.11, GDAL, Shapely, GeoPandas, Fiona, PyProj, Rasterio, numpy
-- **脚本路径**：`/tmp/scripts/run.py`（只读）
-- **工作目录**：`/tmp/output`（读写，步骤间共享）
 - **参数文件**：`/tmp/params.json`
+- **输出目录**：`/tmp/output/`
 
-## 错误处理
+### 脚本入口
 
-退出码非 0 表示失败：
+脚本通过命令行参数接收参数：
 
 ```python
-print(json.dumps({"status": "error", "message": "文件不存在"}))
+import sys, json
-sys.exit(1)
+
+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))
 ```
 
-## 开发建议
+### 依赖管理
 
-1. **输出明确**：结果 JSON 包含关键信息
+脚本中缺失的依赖通过运行时 pip 安装：
-2. **错误友好**：失败信息写清楚原因
+
-3. **使用 GDAL**：GIS 文件处理优先使用 GDAL 命令行工具
+```python
+import subprocess, sys
+try:
+    import openpyxl
+except ImportError:
+    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'openpyxl'])
+```
+
+## 输出规范
+
+脚本执行完成后，向 stdout 输出 JSON：
+
+```json
+{"status": "completed", "output_path": "/tmp/output/result.shp"}
+```