eve-orchestration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eve Orchestration

Eve Orchestration 作业编排

This skill explains how to orchestrate complex work in Eve Horizon by spawning child jobs, managing dependencies, and maximizing parallel execution while respecting depth limits.

本技能介绍了如何在Eve Horizon中通过生成子作业、管理依赖关系，并在遵守深度限制的前提下最大化并行执行，来编排复杂工作。

Core Principles

核心原则

Parent sets a target depth and passes it to children.
Each job decides its own decomposition based on scope and depth.
Parallelize by default when tasks can proceed independently.
Use relations to encode true dependencies, not preference.
Leaf jobs execute; parent jobs orchestrate and wait.

父作业设置目标深度并将其传递给子作业。
每个作业根据范围和深度决定自身的分解方式。
当任务可以独立进行时，默认采用并行处理。
使用关联关系来编码真实的依赖，而非偏好。
叶子作业负责执行；父作业负责编排并等待。

Always Start With Context

始终从上下文开始

Fetch the current job context before deciding anything:

bash

eve job current --json

在做任何决策前先获取当前作业上下文：

bash

eve job current --json

or explicit

或显式指定

eve job current $EVE_JOB_ID --json


Use the context to confirm:
- `job.depth` (current depth)
- `children` (existing sub-jobs)
- `relations` (dependencies)
- `blocked` / `waiting` / `effective_phase`

eve job current $EVE_JOB_ID --json


使用上下文确认以下信息：
- `job.depth`（当前深度）
- `children`（已存在的子作业）
- `relations`（依赖关系）
- `blocked` / `waiting` / `effective_phase`（阻塞/等待/有效阶段）

Environment and IDs

环境变量与ID

Use the environment to avoid guessing identifiers:

```
EVE_JOB_ID
```
: current job
```
EVE_PROJECT_ID
```
: owning project
```
EVE_ATTEMPT_ID
```
: current attempt
```
EVE_REPO_PATH
```
: workspace path
```
EVE_AGENT_ID
```
: agent identifier (optional)

使用环境变量避免猜测标识符：

```
EVE_JOB_ID
```
: 当前作业ID
```
EVE_PROJECT_ID
```
: 所属项目ID
```
EVE_ATTEMPT_ID
```
: 当前尝试ID
```
EVE_REPO_PATH
```
: 工作区路径
```
EVE_AGENT_ID
```
: Agent标识符（可选）

Depth Propagation

深度传播

The parent decides the target depth and passes it to children (in the child description or data). Each child must read and honor the same target depth.

Example snippet to include in child descriptions:

Target depth: 3 (EPIC). Current depth: 1.
If current depth < target, you may create child jobs and use waits_for relations to parallelize.
If current depth >= target, execute directly.

父作业决定目标深度并将其传递给子作业（在子作业描述或数据中）。每个子作业必须读取并遵循相同的目标深度。

子作业描述中可包含以下示例片段：

Target depth: 3 (EPIC). Current depth: 1.
If current depth < target, you may create child jobs and use waits_for relations to parallelize.
If current depth >= target, execute directly.

Default Depth Rules

默认深度规则

EPIC: target depth = 3
- Root orchestrates children
- Children may orchestrate grandchildren
- Grandchildren execute
Story: target depth = 2
- Root orchestrates children
- Children execute

If no target depth is provided, default to Story depth (2) unless the scope clearly indicates EPIC.

EPIC: 目标深度 = 3
- 根作业编排子作业
- 子作业可编排孙作业
- 孙作业执行
Story: 目标深度 = 2
- 根作业编排子作业
- 子作业执行

如果未提供目标深度，默认采用Story深度（2），除非范围明确表明是EPIC。

Per-Job Orchestration Flow

单作业编排流程

Fetch context (
```
eve job current --json
```
).
Determine depth:
- Read inherited target depth.
- If
```
current_depth >= target_depth
```
  , execute directly.
Decide whether to decompose:
- If the work is sizable or parallelizable, create child jobs.
- Each child inherits the same target depth.
Add relations:
- Use
```
waits_for
```
  for standard gating.
- Use
```
blocks
```
  only for strict ordering constraints.
Return waiting signal after relations exist.
Resume when children complete; re-check context and continue.

获取上下文（
```
eve job current --json
```
）。
确定深度：
- 读取继承的目标深度。
- 如果
```
current_depth >= target_depth
```
  ，直接执行。
决定是否分解：
- 如果工作规模较大或可并行化，创建子作业。
- 每个子作业继承相同的目标深度。
添加关联关系：
- 使用
```
waits_for
```
  进行标准门控。
- 仅在严格顺序约束下使用
```
blocks
```
  。
关联关系存在后返回等待信号。
子作业完成后恢复；重新检查上下文并继续。

Creating Child Jobs (CLI)

创建子作业（CLI）

Use

eve job create

with

--parent

to spawn sub-jobs. Provide clear, atomic descriptions and pass the target depth in the child description.

bash

undefined

使用

eve job create

并加上

--parent

参数来生成子作业。提供清晰、原子化的描述，并在子作业描述中传递目标深度。

bash

undefined

Create two child jobs in parallel

并行创建两个子作业

eve job create --project $EVE_PROJECT_ID
--parent $EVE_JOB_ID
--description $'Target depth: 3 (EPIC). Current depth: 1.\nScope: Research sources\nDeliverable: Annotated bibliography'
--phase ready

eve job create --project $EVE_PROJECT_ID
--parent $EVE_JOB_ID
--description $'Target depth: 3 (EPIC). Current depth: 1.\nScope: Draft outline\nDeliverable: Structured outline'
--phase ready


After creating children, add dependencies so the parent waits on them:

```bash
eve job dep add $EVE_JOB_ID $CHILD_A_ID --type waits_for
eve job dep add $EVE_JOB_ID $CHILD_B_ID --type waits_for

eve job create --project $EVE_PROJECT_ID
--parent $EVE_JOB_ID
--description $'Target depth: 3 (EPIC). Current depth: 1.\nScope: Research sources\nDeliverable: Annotated bibliography'
--phase ready

eve job create --project $EVE_PROJECT_ID
--parent $EVE_JOB_ID
--description $'Target depth: 3 (EPIC). Current depth: 1.\nScope: Draft outline\nDeliverable: Structured outline'
--phase ready


创建子作业后，添加依赖关系使父作业等待它们完成：

```bash
eve job dep add $EVE_JOB_ID $CHILD_A_ID --type waits_for
eve job dep add $EVE_JOB_ID $CHILD_B_ID --type waits_for

Parallel Decomposition Guidance

并行分解指南

Favor multiple small, independent children over one large child.
If tasks can run in parallel, create them and make the parent wait on all.
Avoid chaining children unless the outputs are truly sequential.
Every child repeats the same decision process and may create grandchildren if depth allows.

优先创建多个小型、独立的子作业，而非一个大型子作业。
如果任务可以并行运行，创建它们并让父作业等待所有子作业完成。
除非输出确实需要顺序执行，否则避免将子作业链式排列。
每个子作业重复相同的决策流程，如果深度允许，可创建孙作业。

Dependencies and Relations

依赖关系与关联

Use the CLI dependency commands to express relationships:

bash

eve job dep add $PARENT_JOB_ID $CHILD_JOB_ID --type waits_for
eve job dep add $CHILD_JOB_ID $OTHER_JOB_ID --type blocks
eve job dep list $JOB_ID

Relation guidance:

```
waits_for
```
: standard parent waits for child completion
```
blocks
```
: strict ordering constraint
```
conditional_blocks
```
: use only when the dependency is conditional

Add relations before returning a waiting control signal.

使用CLI依赖命令来表达关联关系：

bash

eve job dep add $PARENT_JOB_ID $CHILD_JOB_ID --type waits_for
eve job dep add $CHILD_JOB_ID $OTHER_JOB_ID --type blocks
eve job dep list $JOB_ID

关联关系指南：

```
waits_for
```
: 标准的父作业等待子作业完成
```
blocks
```
: 严格的顺序约束
```
conditional_blocks
```
: 仅在依赖为条件性时使用

添加关联关系后再返回等待控制信号。

Control Signals (json-result)

控制信号（json-result）

When you spawn children and set relations, pause the parent with a waiting signal:

json

{
  "eve": {
    "status": "waiting",
    "summary": "Spawned 3 parallel child jobs; waiting on waits_for relations"
  }
}

Rules:

Only return
```
waiting
```
after dependencies exist.
```
waiting
```
requeues the job to
```
ready
```
while it stays blocked by relations.
Returning
```
waiting
```
without blockers triggers a short backoff; avoid it.
Use
```
success
```
when the work is complete.
Use
```
failed
```
only for unrecoverable outcomes.

当你生成子作业并设置关联关系后，使用等待信号暂停父作业：

json

{
  "eve": {
    "status": "waiting",
    "summary": "Spawned 3 parallel child jobs; waiting on waits_for relations"
  }
}

规则：

仅在依赖关系存在后返回
```
waiting
```
。
```
waiting
```
会将作业重新加入
```
ready
```
队列，同时作业会因关联关系保持阻塞状态。
若没有阻塞器却返回
```
waiting
```
，会触发短暂退避；请避免这种情况。
工作完成时返回
```
success
```
。
仅在出现不可恢复的结果时返回
```
failed
```
。

Review Mechanics (Optional)

审核机制（可选）

Default: no review unless explicitly required by the parent or project settings.

If review is required:

Apply at the specified level (top only, all levels, or none).
Do not submit for review when returning
```
waiting
```
.
Submit for review only when the job is complete.

bash

eve job submit $EVE_JOB_ID --summary "Completed work and ready for review"

默认：除非父作业或项目设置明确要求，否则无需审核。

如果需要审核：

在指定级别应用审核（仅顶层、所有级别或无）。
返回
```
waiting
```
时不要提交审核。
仅在作业完成时提交审核。

bash

eve job submit $EVE_JOB_ID --summary "Completed work and ready for review"

Parent Review of Child Work

父作业审核子作业成果

When a parent resumes after children complete:

Read the child outputs and verify they meet the parent scope.
If review is required, submit the parent for review after verification.
If no review is required, summarize child outcomes and complete the parent.

父作业在子作业完成后恢复时：

读取子作业输出并验证是否符合父作业的范围要求。
如果需要审核，验证后提交父作业进行审核。
如果不需要审核，总结子作业成果并完成父作业。

Failure Handling

故障处理

If a child fails:

Re-check context and determine whether to retry, replace, or stop.
Remove or adjust relations if the plan changes.
Do not leave the parent waiting on a permanently failed child.

如果子作业失败：

重新检查上下文并决定是否重试、替换或停止。
如果计划变更，移除或调整关联关系。
不要让父作业一直等待永久失败的子作业。

Child Job Description Template

子作业描述模板

Use a consistent header so children inherit depth and decision rules:

Target depth: 3 (EPIC). Current depth: 1.
If current depth < target, you may create child jobs and use waits_for relations to parallelize.
If current depth >= target, execute directly.

Scope: <concise child objective>
Deliverable: <clear outcome>

使用一致的标题，让子作业继承深度和决策规则：

Target depth: 3 (EPIC). Current depth: 1.
If current depth < target, you may create child jobs and use waits_for relations to parallelize.
If current depth >= target, execute directly.

Scope: <concise child objective>
Deliverable: <clear outcome>

Knowledge-Work Examples (Non-SWE)

知识工作示例（非软件工程）

Research: parallel literature review, data gathering, synthesis
Writing: outline, draft sections in parallel, consolidate
Ops: parallel checks (metrics, logs, status), then summary
Strategy: parallel SWOT, stakeholder analysis, risk assessment

研究：并行文献综述、数据收集、综合分析
写作：大纲制定、并行撰写各章节、整合内容
运维：并行检查（指标、日志、状态），然后生成总结
战略：并行SWOT分析、利益相关者分析、风险评估

Quick Checklist

快速检查清单

Read context and depth
Determine target depth and level
Decide direct vs decompose
Create children in parallel where possible
Add relations
Return
```
json-result
```
waiting (if children exist)
Resume and complete

读取上下文和深度
确定目标深度和级别
决定直接执行还是分解
尽可能并行创建子作业
添加关联关系
返回
```
json-result
```
等待信号（如果存在子作业）
恢复并完成作业

Recursive skill distillation

递归技能提炼

Capture new orchestration patterns and edge cases here.
Split out a new skill when a focused pattern keeps repeating.
Update the eve-skillpacks README and ARCHITECTURE listings after changes.

在此处记录新的编排模式和边缘情况。
当某个聚焦模式不断重复时，拆分出一个新技能。
变更后更新eve-skillpacks的README和ARCHITECTURE列表。