# Workflow 规范

## 文件位置

套件根目录下的 `workflow.yaml`。

## 顶层字段

| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | 是 | 套件名称 |
| `description` | 否 | 描述 |
| `version` | 否 | 版本号，默认 1.0.0 |
| `category` | 否 | 分类标签 |
| `tags` | 否 | 标签列表 |
| `params` | 是 | 输入参数的 JSON Schema |
| `steps` | 是 | 执行步骤列表 |

## 参数声明（params）

使用 JSON Schema 格式：

```yaml
params:
  type: object
  required:
    - input_path
  properties:
    input_path:
      type: string
      description: 输入文件路径
    threshold:
      type: number
      default: 0.5
      description: 阈值
```

### 参数类型

| 类型 | 说明 | 示例 |
|------|------|------|
| `string` | 文本或文件路径 | `/data/input.shp` |
| `number` | 浮点数 | `0.5` |
| `integer` | 整数 | `100` |
| `boolean` | 布尔值 | `true` |

## 步骤定义（steps）

```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))
```