eve-orchestration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eve Orchestration

Eve 编排

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.
Orchestrators stay lightweight — dispatch work, don't accumulate it.

父作业设置目标深度并传递给子作业。
每个作业根据范围和深度决定自身的分解方式。
默认在任务可独立进行时并行处理。
使用关联关系编码真实依赖，而非偏好。
叶子作业执行任务；父作业负责编排并等待。
编排器保持轻量化——分派工作，而非累积工作。

When to Orchestrate vs Execute Directly

何时编排 vs 直接执行

Not every job needs decomposition. Use this heuristic:

Execute directly when the work is atomic, self-contained, and fits comfortably in a single agent's context and capability. Examples: fix a single bug, write one document section, run a diagnostic check.
Orchestrate when the work has independent sub-parts that benefit from parallelism, when the scope exceeds what a single agent should hold in context at once, or when different parts require different skills or tool access.
Default to direct execution. Orchestration has overhead (job creation, waiting, resumption). Only decompose when parallelism or scope genuinely demands it.

并非所有作业都需要分解。可遵循以下启发式规则：

直接执行：当工作是原子性、自包含的，且单个Agent的上下文和能力可轻松处理时。示例：修复单个bug、撰写文档的一个章节、运行诊断检查。
编排处理：当工作包含可从并行性中获益的独立子部分，或范围超出单个Agent可同时容纳的上下文，或不同部分需要不同技能或工具访问权限时。
默认直接执行：编排存在开销（作业创建、等待、恢复）。仅当并行性或范围确实需要时才进行分解。

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

环境变量与标识符

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
```
：当前作业
```
EVE_PROJECT_ID
```
：所属项目
```
EVE_ATTEMPT_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。

Context Management

上下文管理

The orchestrator's most precious resource is its context window. Protect it:

Do not read large files or datasets in the orchestrator. If analysis is needed, create a child job to do the reading and summarize the results.
Keep the orchestrator's role to planning, dispatching, and synthesizing. The orchestrator decides what to do and how to split it, then delegates the actual work.
Avoid accumulating child outputs inline. When resuming after children complete, read only the summaries or outcomes you need to verify completion — not the full content of every child's work product.
Front-load decomposition thinking. Spend context on planning the breakdown, not on doing partial work that will be redone by children.

A well-run orchestrator should finish with most of its context budget unspent.

编排器最宝贵的资源是其上下文窗口。请保护好它：

不要在编排器中读取大文件或数据集。如果需要分析，创建一个子作业来读取并总结结果。
将编排器的角色限制为规划、分派和综合。编排器决定做什么和如何拆分，然后将实际工作委托出去。
避免内联累积子作业输出。在子作业完成后恢复时，仅读取验证完成所需的摘要或结果——而非每个子作业工作产品的全部内容。
前置分解思考。将上下文用于规划拆分，而非做会被子作业重做的部分工作。

运行良好的编排器应在结束时保留大部分上下文预算。

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.
Write self-contained child descriptions (see template below).
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; read summaries, verify, and continue.

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

Creating Child Jobs

创建子作业

Create child jobs using

eve job create

with

--parent

. Each child description must be fully self-contained — the child agent has no access to the parent's conversation, context, or reasoning. Everything the child needs to act must be in the description itself.

bash

undefined

使用

eve job create

并加上

--parent

参数创建子作业。每个子作业描述必须完全自包含——子Agent无法访问父作业的对话、上下文或推理过程。子作业行动所需的一切都必须在描述本身中。

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 output of one is a genuine input to the next.
Every child repeats the same decision process and may create grandchildren if depth allows.
A good decomposition reduces each child's scope to something a single agent can complete without exhausting its context window.

优先创建多个小型、独立的子作业，而非一个大型子作业。
如果任务可并行运行，创建它们并让父作业等待所有子作业完成。
除非一个任务的输出是另一个任务的真实输入，否则避免链式连接子作业。
每个子作业重复相同的决策过程，如果深度允许，可创建孙作业。
良好的分解应将每个子作业的范围缩小到单个Agent可完成且不会耗尽其上下文窗口的程度。

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 child summaries and outcomes — not their full work products. Protect context.
Verify that child outputs collectively satisfy the parent's scope.
If review is required, submit the parent for review after verification.
If no review is required, synthesize child outcomes into a parent summary and complete.

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

读取子作业的摘要和结果——而非其完整工作产品。保护上下文。
验证子作业输出是否共同满足父作业的范围。
如果需要审核，验证后提交父作业进行审核。
如果不需要审核，将子作业结果综合为父作业摘要并完成。

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

子作业描述模板

Every child description must be self-contained. The child agent starts cold — no access to the parent's conversation, files read, or reasoning. Include everything it needs:

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.

Context: <why this work exists — enough background for the child to act without asking>
Scope: <concise child objective — what to do>
Inputs: <specific file paths, data references, or prior outputs the child needs>
Deliverable: <clear, verifiable outcome — what "done" looks like>
Constraints: <boundaries, standards, or requirements to honor>

Key rules for child descriptions:

Name specific files and paths. "Update the auth module" is ambiguous; "Update
```
/src/auth/handler.ts
```
to add token refresh logic" is actionable.
Include relevant decisions already made. If the parent chose an approach, tell the child — don't make it re-derive the decision.
State the deliverable as a verifiable condition. "Tests pass" or "File exists at path X" beats "implement feature Y."
Never assume the child can read the parent's mind. If in doubt, over-specify.

每个子作业描述必须自包含。子Agent从零开始——无法访问父作业的对话、读取的文件或推理过程。包含它所需的一切：

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.

Context: <why this work exists — enough background for the child to act without asking>
Scope: <concise child objective — what to do>
Inputs: <specific file paths, data references, or prior outputs the child needs>
Deliverable: <clear, verifiable outcome — what "done" looks like>
Constraints: <boundaries, standards, or requirements to honor>

子作业描述的关键规则：

指定具体文件和路径。“更新auth模块”表述模糊；“更新
```
/src/auth/handler.ts
```
以添加令牌刷新逻辑”则可直接执行。
包含已做出的相关决策。如果父作业已选择一种方法，告知子作业——不要让它重新推导决策。
将交付成果表述为可验证的条件。“测试通过”或“文件存在于路径X”比“实现功能Y”更清晰。
永远不要假设子作业能读懂父作业的想法。如有疑问，过度说明。

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: execute directly or orchestrate? (default to direct if work is atomic)
If orchestrating: plan the decomposition, then create children with self-contained descriptions
Favor parallel children over sequential chains
Add relations before signaling
Return
```
json-result
```
waiting (if children exist)
On resume: read child summaries (not full outputs), verify, and complete

读取上下文和深度
确定目标深度和级别
决定：直接执行还是编排处理？（如果工作是原子性的，默认直接执行）
如果编排处理：规划分解，然后创建带有自包含描述的子作业
优先并行子作业而非顺序链
发出信号前添加关联关系
返回
```
json-result
```
等待信号（如果存在子作业）
恢复时：读取子作业摘要（而非完整输出）、验证并完成