diff --git a/suites-help/开发者指南/Workflow-规范.md b/suites-help/开发者指南/Workflow-规范.md index 20e55bd..c588dfd 100644 --- a/suites-help/开发者指南/Workflow-规范.md +++ b/suites-help/开发者指南/Workflow-规范.md @@ -1,101 +1,85 @@ # Workflow 规范 -## 文件位置 +## 概述 -套件根目录下的 `workflow.yaml`。 +`workflow.yaml` 定义套件的步骤、参数和执行流程。 -## 顶层字段 +## 文件结构 + +```yaml +name: 套件名称 +description: 套件功能描述 +version: 1.0.0 +author: 作者名 +tags: [标签1, 标签2] +category: 业务分类(如:土地整治) + +params: + input_path: + type: string + required: true + desc: 输入文件路径 + buffer_distance: + type: number + default: 100 + desc: 缓冲区半径(米) + +base_image: gis-base:latest + +env: + LOG_LEVEL: INFO + +steps: + - id: step1 + name: 步骤名称 + script_id: run + params: + input: $params.input_path + distance: $params.buffer_distance +``` + +## 字段说明 | 字段 | 必填 | 说明 | |------|------|------| -| `name` | 是 | 套件名称 | -| `description` | 否 | 描述 | -| `version` | 否 | 版本号,默认 1.0.0 | -| `category` | 否 | 分类标签 | -| `tags` | 否 | 标签列表 | -| `params` | 是 | 输入参数的 JSON Schema | -| `steps` | 是 | 执行步骤列表 | +| `name` | ✅ | 套件名称 | +| `description` | ✅ | 套件功能描述 | +| `version` | ✅ | 语义化版本号 | +| `params` | ❌ | 参数声明(供用户查看) | +| `base_image` | ❌ | Docker 镜像,默认 `gis-base:latest` | +| `steps` | ✅ | 步骤列表,至少 1 步 | -## 参数声明(params) +### steps 字段 -使用 JSON Schema 格式: +| 字段 | 必填 | 说明 | +|------|------|------| +| `id` | ✅ | 步骤唯一 ID | +| `name` | ❌ | 步骤显示名称 | +| `script_id` | ✅ | 脚本 ID(对应 scripts/ 下的 .py 文件名,不含扩展名) | +| `params` | ❌ | 步骤参数,值中使用 `$params.xxx` 引用用户输入 | +| `depends_on` | ❌ | 依赖的步骤 ID 列表,控制执行顺序 | + +## 参数传递 + +步骤参数通过 `$params.xxx` 语法引用用户输入: ```yaml params: - type: object - required: - - input_path - properties: - input_path: - type: string - description: 输入文件路径 - threshold: - type: number - default: 0.5 - description: 阈值 + input: $params.input_path # 引用用户的 input_path 参数 + distance: $params.buffer_distance # 引用用户的 buffer_distance 参数 ``` -### 参数类型 +引擎会自动: +1. 将用户提供的文件路径复制到工作目录 +2. 替换路径为容器内可访问的路径(`/tmp/output/文件名`) +3. shapefile 自动复制配套文件(.shx/.dbf/.prj) -| 类型 | 说明 | 示例 | -|------|------|------| -| `string` | 文本或文件路径 | `/data/input.shp` | -| `number` | 浮点数 | `0.5` | -| `integer` | 整数 | `100` | -| `boolean` | 布尔值 | `true` | +## 执行顺序 -## 步骤定义(steps) +- 无 `depends_on` 的步骤并行执行 +- 有 `depends_on` 的步骤在依赖步骤完成后执行 +- 默认串行(`depends_on` 为空时按列表顺序执行) -```yaml -steps: - - id: my-step # 步骤 ID,唯一 - name: 我的步骤 # 步骤名称 - script: run # 脚本标识(scripts/run.py 中的 run) - params: - input: $params.input_path # 使用 $params.xxx 引用参数 -``` +## 步骤输出 -### 常见错误 - -| ❌ 错误写法 | ✅ 正确写法 | 原因 | -|-----------|-----------|------| -| `script: run.py` | `script: run` | 不带 .py 后缀 | -| `script_id: run` | `script: run` | 字段名是 `script` 不是 `script_id` | -| `params_mapping: {...}` | `params: {...}` | 字段名是 `params` | -| `${{inputs.xxx}}` | `$params.xxx` | 使用 `$params.xxx` 语法 | -| `$inputs.xxx` | `$params.xxx` | 使用 `$params.xxx` 语法 | - -## 文件共享 - -所有步骤共享 `/tmp/output` 目录。Step 1 写入的文件,Step 2 可以直接读取: - -```python -# Step 1:写文件 -with open("/tmp/output/result.json", "w") as f: - json.dump(data, f) - -# Step 2:读文件 -with open("/tmp/output/result.json") as f: - data = json.load(f) -``` - -## 脚本约定 - -脚本通过 `PARAMS_FILE` 环境变量获取参数文件路径,或通过 `sys.argv[1]` 获取 JSON 参数: - -```python -import json, os, sys - -# 方式一:从 PARAMS_FILE 读取 -params_file = os.environ.get("PARAMS_FILE", "/tmp/params.json") -with open(params_file) as f: - params = json.load(f) - -# 方式二:从 sys.argv[1] 读取 -if len(sys.argv) > 1: - params = json.loads(sys.argv[1]) - -# 处理逻辑... -result = {"status": "ok", "value": 42} -print(json.dumps(result)) -``` +每个步骤执行完成后,脚本向 stdout 输出 JSON 结果。步骤间的数据通过 `/tmp/output/` 目录共享。