fix(#8): Workflow-规范 — 统一为 script_id + $params.xxx 唯一格式
This commit is contained in:
@@ -1,101 +1,85 @@
|
|||||||
# Workflow 规范
|
# 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` | 是 | 套件名称 |
|
| `name` | ✅ | 套件名称 |
|
||||||
| `description` | 否 | 描述 |
|
| `description` | ✅ | 套件功能描述 |
|
||||||
| `version` | 否 | 版本号，默认 1.0.0 |
|
| `version` | ✅ | 语义化版本号 |
|
||||||
| `category` | 否 | 分类标签 |
|
| `params` | ❌ | 参数声明（供用户查看） |
|
||||||
| `tags` | 否 | 标签列表 |
|
| `base_image` | ❌ | Docker 镜像，默认 `gis-base:latest` |
|
||||||
| `params` | 是 | 输入参数的 JSON Schema |
|
| `steps` | ✅ | 步骤列表，至少 1 步 |
|
||||||
| `steps` | 是 | 执行步骤列表 |
|
|
||||||
|
|
||||||
## 参数声明（params）
|
### steps 字段
|
||||||
|
|
||||||
使用 JSON Schema 格式：
|
| 字段 | 必填 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `id` | ✅ | 步骤唯一 ID |
|
||||||
|
| `name` | ❌ | 步骤显示名称 |
|
||||||
|
| `script_id` | ✅ | 脚本 ID（对应 scripts/ 下的 .py 文件名，不含扩展名） |
|
||||||
|
| `params` | ❌ | 步骤参数，值中使用 `$params.xxx` 引用用户输入 |
|
||||||
|
| `depends_on` | ❌ | 依赖的步骤 ID 列表，控制执行顺序 |
|
||||||
|
|
||||||
|
## 参数传递
|
||||||
|
|
||||||
|
步骤参数通过 `$params.xxx` 语法引用用户输入：
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
params:
|
params:
|
||||||
type: object
|
input: $params.input_path # 引用用户的 input_path 参数
|
||||||
required:
|
distance: $params.buffer_distance # 引用用户的 buffer_distance 参数
|
||||||
- input_path
|
|
||||||
properties:
|
|
||||||
input_path:
|
|
||||||
type: string
|
|
||||||
description: 输入文件路径
|
|
||||||
threshold:
|
|
||||||
type: number
|
|
||||||
default: 0.5
|
|
||||||
description: 阈值
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 参数类型
|
引擎会自动：
|
||||||
|
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 引用参数
|
|
||||||
```
|
|
||||||
|
|
||||||
### 常见错误
|
每个步骤执行完成后，脚本向 stdout 输出 JSON 结果。步骤间的数据通过 `/tmp/output/` 目录共享。
|
||||||
|
|
||||||
| ❌ 错误写法 | ✅ 正确写法 | 原因 |
|
|
||||||
|-----------|-----------|------|
|
|
||||||
| `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))
|
|
||||||
```
|
|
||||||
|
|||||||
Reference in New Issue
Block a user