eve-pipelines-workflows

Eve 流水线和工作流

使用这些模式自动执行构建和部署操作，并调用工作流作业。

流水线（v2 步骤）

• 在 .eve/manifest.yaml 的 pipelines 下定义流水线。
• 步骤可以是 action、script 或 agent。
• 使用 depends_on 控制执行顺序。
• 内置操作包括 build、release、deploy、run、job、create-pr。
• 手动运行：
  • eve pipeline list
  • eve pipeline show <project> <name>
  • eve pipeline run <name> --ref <sha> --env <env> --repo-dir ./my-app
• 清单中可以定义触发器块；GitHub 和 Slack Webhook 可以创建流水线运行。

内置操作

build 操作

构建操作会创建 BuildSpec 和 BuildRun 记录，这些记录可供跟踪和观测：

• 在数据库中创建 BuildSpec（定义要构建的内容）和 BuildRun（执行记录）
• 输出包括 build_id 和 image_digests 映射（服务名称到 SHA256 摘要）
• 这些输出会自动传递给依赖步骤（release 会使用 build_id）
• 可独立检查构建：eve build show、eve build diagnose、eve build runs、eve build logs

Agent 步骤

当流水线阶段需要运行 AI Agent 作业时，使用 agent 步骤：

pipelines:
  remediation:
    steps:
      - name: analyze
        agent:
          prompt: "Analyze the failure and propose a fix"

规范的流水线流程

每个部署流水线都应遵循此模式：

pipelines:
  deploy:
    steps:
      - name: build
        action:
          type: build
          # Creates BuildSpec + BuildRun, outputs build_id + image_digests
      - name: release
        depends_on: [build]
        action:
          type: release
          # References build_id, derives digests from BuildArtifacts
      - name: deploy
        depends_on: [release]
        action:
          type: deploy
          env_name: staging
          # Uses digest-based image refs for immutable deploys

晋级工作流

先在测试环境中构建一次，然后将相同的构建制品晋级到预发布环境／生产环境：

• 构建步骤会创建包含制品（镜像摘要）的 BuildRun
• 发布会沿用 build_id，确保各环境使用相同的镜像
• 此模式可确保部署的内容与测试过的内容完全一致

跟踪流水线执行情况：

eve job list --phase active
eve job follow <job-id>
eve job result <job-id>

流水线日志和流式传输

实时监控流水线运行情况：

# Snapshot logs for a run
eve pipeline logs <pipeline> <run-id>

# Real-time SSE streaming
eve pipeline logs <pipeline> <run-id> --follow

# Stream specific step
eve pipeline logs <pipeline> <run-id> --follow --step <name>

步骤失败时会显示失败提示，并在适用时链接到构建诊断信息。

将环境部署作为流水线别名

当环境在清单中配置了 pipeline 时，eve env deploy <env> --ref <sha> 会自动触发该流水线，而不是直接部署。

基本用法

# Triggers the configured pipeline for test environment
eve env deploy test --ref 0123456789abcdef0123456789abcdef01234567

# Pass inputs to the pipeline
eve env deploy staging --ref 0123456789abcdef0123456789abcdef01234567 --inputs '{"release_id":"rel_xxx"}'

# Bypass pipeline and do direct deploy
eve env deploy staging --ref 0123456789abcdef0123456789abcdef01234567 --direct

晋级流程示例

# 1. Build and deploy to test environment
eve env deploy test --ref 0123456789abcdef0123456789abcdef01234567

# 2. Get release info from the test build
eve release resolve v1.2.3
# Output: rel_xxx

# 3. Promote to staging using the release_id
eve env deploy staging --ref 0123456789abcdef0123456789abcdef01234567 --inputs '{"release_id":"rel_xxx"}'

关键行为

• 如果设置了 environments.<env>.pipeline，eve env deploy <env> 就会触发该流水线
• 使用 --direct 标志可绕过流水线并直接部署
• 使用 --inputs '{"key":"value"}' 将输入传递给流水线运行
• 可通过清单中的 environments.<env>.pipeline_inputs 配置默认输入
• --ref 标志指定要部署的 git SHA（40 个字符的 SHA，或通过 --repo-dir 解析的 ref）
• 环境变量和密钥照常进行插值

此模式支持晋级工作流：在较低环境中构建一次，再将相同的制品逐级晋级到较高环境。

工作流

• 在清单的 workflows 下定义工作流。
• 存在 db_access 时会采用其设置（read_only、read_write）。
• 调用时的 resource_refs 默认对每个工作流步骤（包括依赖步骤）均可用。使用工作流级别的 resource_refs 设置默认策略，并使用步骤级别的 resource_refs 覆盖该策略：
  • inherit / all：传递所有调用 refs。
  • none：不传递任何 refs。
  • [brief, design-system]：仅传递与 name、label、mount_path、uri 或 metadata.name 匹配的 ref。
• 手动调用：
  • eve workflow list
  • eve workflow show <project> <name>
  • eve workflow run <project> <name> --input '{"k":"v"}'（发起后即返回）
  • eve workflow invoke <project> <name> --input '{"k":"v"}'（等待结果）
  • eve workflow logs <job-id>
• 调用会创建一个作业；使用常规作业命令跟踪该作业。

工作流提示

通过 hints 控制门控、超时和执行框架偏好：

workflows:
  remediate:
    hints:
      gates: ["remediate:proj_abc123:staging"]

条件步骤

根据上游步骤的结果跳过下游步骤。条件引用具名上游步骤，并在派发时解析：

workflows:
  triage-and-act:
    steps:
      - name: triage
        agent: { prompt: "Classify this incident" }
      - name: deep
        depends_on: [triage]
        condition: "triage.status == 'complex'"   # skip if false
        agent: { prompt: "Run deep analysis" }

条件支持针对上游步骤状态使用 == 和 !=。被引用的步骤必须出现在 depends_on 中——在清单同步时，验证会拒绝不存在的引用和不正确的条件语法。

步骤级 Harness 覆盖

为每个步骤固定或覆盖 Harness（工作流步骤和流水线步骤使用相同的结构）：

steps:
  - name: classify
    harness: claude
    harness_profile: claude-sonnet
    harness_options:
      model: claude-sonnet-4-7
      reasoning_effort: medium
      temperature: 0.2
    agent: { prompt: "Classify this" }

步骤级值优先于 Agent 解析出的默认值。harness_profile 可以包含 ${inputs.model} 这样的模板，以便调用方选择。

工作流 env_overrides

在工作流、步骤和调用三个层级设置环境变量；运行时按此顺序合并（后者优先）。使用 ${secret.KEY} 引用密钥；解析器会在日志中对其进行脱敏。

workflows:
  remediate:
    env_overrides:
      LOG_LEVEL: info
    steps:
      - name: act
        env_overrides:
          LOG_LEVEL: debug          # step wins over workflow
          API_KEY: ${secret.VENDOR_TOKEN}
        agent: { prompt: "Remediate" }

调用方可在调用时添加第三层：

eve workflow invoke <project> remediate --input '{"k":"v"}' --env-override DRY_RUN=true

流水线的 env 会向下传递到运行的 env_name，因此步骤无需重新声明即可使用正确的作用域。

按任务覆盖 Harness（临时任务）

触发临时任务（工作流之外）时，在创建调用中覆盖 Harness：

eve job create --description "Investigate" \
  --harness claude \
  --profile claude-sonnet

# Or pass a full override object:
eve job create --description "..." --harness-override-file ./override.json
# override.json: { "harness": "...", "model": "...", "reasoning_effort": "...", "variant": "...", "temperature": 0.2 }

此覆盖会贯穿派发和领取流程，并优先于 Agent 解析出的值。

Slack 通知、重试和文件引用

• 工作流的 hints.slack 会向配置的频道发送步骤开始、完成和失败通知。
• 重试上一次调用中失败的步骤及其后续步骤：
  • eve workflow retry <root-job-id> --failed
  • eve workflow retry <root-job-id> --from <step>
• 工作流步骤接受文件引用（指向路径的 resource_refs 条目）——这些文件会与其他引用一起写入步骤的工作区。