YAML 任务编排

PyFlowX 支持 GitHub Actions 风格的声明式 YAML 任务编排，从 YAML 文件直接加载任务图。

编程式 API

import pyflowx as px

# 从 YAML 文件加载任务图
graph = px.Graph.from_yaml("pipeline.yaml")
report = px.run(graph, strategy="thread")

# 或用函数式 API
graph = px.load_yaml("pipeline.yaml")

# 从字符串解析
graph = px.parse_yaml_string("""
jobs:
  hello:
    cmd: ["echo", "hello"]
""")

YAML Schema

strategy: thread              # 图级默认策略
defaults:                     # 图级默认值
  retry: {max_attempts: 3}
  verbose: true
  env: {CI: "true"}

variables:                    # 变量定义 (可在 cmd/env 中 ${VAR} 引用)
  OUTPUT: "dist"

jobs:
  setup:
    cmd: ["git", "clone", "..."]
    runs-on: linux

  build:
    needs: [setup]            # 依赖列表
    cmd: ["python", "-m", "build"]
    timeout: 300
    retry: {max_attempts: 2, delay: 1.0}

  test:
    needs: [build]
    cmd: ["python${{ matrix.version }}", "-m", "pytest"]
    strategy:
      matrix:                  # 笛卡尔积展开为 6 个任务
        version: ["3.8", "3.9", "3.10"]
        os: ["linux", "macos"]
    if: "env.CI"             # 条件: 环境变量存在

  lint:
    needs: [build]
    cmd: ["ruff", "check"]
    if: "env.CI == 'true'"

  deploy:
    needs: [test, lint]        # 矩阵依赖自动展开
    cmd: ["twine", "upload"]
    if: "env.DEPLOY_TOKEN != ''"
    allow-upstream-skip: true
    concurrency-key: deploy_lock

字段映射

YAML 字段	TaskSpec 字段	说明
jobs.<id>	name	job ID 作为任务名
cmd / run	cmd	cmd 为列表形式，run 为 shell 字符串
needs	depends_on	依赖列表（矩阵任务自动展开）
if	conditions	success() / always() / env.VAR / env.VAR == 'x'
strategy.matrix	矩阵扇出	笛卡尔积展开为多个任务
${{ matrix.key }}	占位符	在 cmd/run/cwd/env 中替换
timeout	timeout	超时秒数
retry	retry	{max_attempts, delay, backoff, jitter}
cwd	cwd	工作目录
env	env	环境变量
verbose	verbose	详细输出
continue-on-error	continue_on_error	失败不中止整图
skip-if-missing	skip_if_missing	命令不存在时跳过
allow-upstream-skip	allow_upstream_skip	上游跳过时仍执行
priority	priority	同层优先级
concurrency-key	concurrency_key	并发限制键
tags	tags	自由标签
runs-on	``tags``（追加）	运行环境标签

CLI 配置段（cli:）

工具 YAML 还可定义 cli: 段，声明命令行参数 schema，由 pf 自动解析：

cli:
  description: "FileDate - 文件日期处理工具"
  usage: "pf filedate <command> [files...]"
  subcommands:
    add:
      help: "添加日期前缀"
      positional:
        - name: FILES
          nargs: "+"
          type: path
          help: "文件路径"
      options:
        - name: CLEAR
          flag: "--clear"
          action: store_true
          help: "清除已有日期前缀"

支持的 type：str / int / float / path。

完整 API 说明详见 API 参考。