docs: suites-help/开发者指南/Workflow-规范.md

suites-help/开发者指南/Workflow-规范.md

@@ -0,0 +1,111 @@
+# Workflow 规范
+
+## 文件位置
+
+套件根目录下的 `workflow.yaml`。
+
+## 顶层字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `name` | 是 | 套件名称 |
+| `description` | 否 | 描述 |
+| `version` | 否 | 版本号，默认 1.0.0 |
+| `category` | 否 | 分类标签 |
+| `tags` | 否 | 标签列表 |
+| `params` | 是 | 输入参数的 JSON Schema |
+| `output_schema` | 否 | 输出结果的结构定义 |
+| `steps` | 是 | 执行步骤列表 |
+| `resolved_params` | 是 | 参数解析后的默认值 |
+
+## 参数声明（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_id: run        # 脚本标识（不是 script: run.py）
+    params:
+      input: "${{inputs.input_path}}"   # 双花括号语法
+```
+
+### 常见错误
+
+| ❌ 错误写法 | ✅ 正确写法 | 原因 |
+|-----------|-----------|------|
+| `script: run.py` | `script_id: run` | 执行器读的是 `script_id` |
+| `params_mapping: {...}` | `params: {...}` | 字段名是 `params` |
+| `$inputs.xxx` | `${{inputs.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)
+```
+
+每个步骤也有独立的 `/tmp/step_output` 目录。
+
+## 脚本约定
+
+脚本通过 `PARAMS_FILE` 环境变量获取参数（默认 `/tmp/params.json`），结果通过 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)
+
+# 处理逻辑...
+result = {"status": "ok", "value": 42}
+print(json.dumps(result))
+```
+
+## resolved_params
+
+提供参数解析后的默认值，执行器直接使用这些值：
+
+```yaml
+resolved_params:
+  - step_index: 0
+    step_name: 我的步骤
+    params:
+      input_path: "/data/input.shp"
+      threshold: 0.5
+```