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

Workflow 规范

文件位置

套件根目录下的 workflow.yaml。

顶层字段

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

参数声明（params）

使用 JSON Schema 格式：

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）

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 可以直接读取：

# 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 参数：

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