eve-orchestration

Eve 编排

本技能介绍如何在 Eve Horizon 中通过生成子任务、管理依赖关系并最大限度地并行执行，同时遵守深度限制，来编排复杂工作。

核心原则

1. 父任务设定目标深度并传递给子任务。
2. 每个任务根据范围和深度决定如何拆分。
3. 默认并行处理可独立推进的任务。
4. 使用关系表示实际依赖，而非偏好。
5. 叶子任务负责执行；父任务负责编排和等待。
6. 编排者应保持轻量——分派工作，而不是累积工作。

何时编排，何时直接执行

并非每个任务都需要拆分。可参考以下原则：

• 直接执行：工作是原子性的、独立完整的，并且单个 Agent 的上下文和能力足以轻松胜任。例如：修复单个 Bug、撰写一个文档章节、运行诊断检查。
• 进行编排：工作包含适合并行处理的独立子部分；范围超出单个 Agent 一次能够在上下文中处理的内容；或者不同部分需要不同的技能或工具访问权限。
• 默认直接执行。 编排会产生额外开销（创建任务、等待、恢复）。只有在并行性或工作范围确实需要时，才进行拆分。

始终从上下文开始

在做出任何决定之前，先获取当前任务的上下文：

eve job current --json
# or explicit
eve job current $EVE_JOB_ID --json

利用上下文确认：

• job.depth（当前深度）
• children（现有子任务）
• relations（依赖关系）
• blocked / waiting / effective_phase

环境与 ID

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

• EVE_JOB_ID：当前任务
• EVE_PROJECT_ID：所属项目
• EVE_ATTEMPT_ID：当前尝试
• EVE_REPO_PATH：工作区路径
• EVE_AGENT_ID：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.

默认深度规则

• EPIC：目标深度 = 3

  • 根任务编排子任务
  • 子任务可以编排孙任务
  • 孙任务负责执行

• Story：目标深度 = 2

  • 根任务编排子任务
  • 子任务负责执行

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

上下文管理

编排者最宝贵的资源是上下文窗口。请妥善保护：

• 不要在编排者中读取大型文件或数据集。 如果需要分析，请创建子任务来读取并总结结果。
• 让编排者的职责仅限于规划、分派和综合。 编排者决定做什么以及如何拆分，然后委派实际工作。
• 避免在行内累积子任务输出。 子任务完成后恢复工作时，只读取验证完成所需的摘要或结果，而不是每个子任务完整的工作成果。
• 尽早考虑拆分方案。 将上下文用于规划拆分，而不是进行之后会由子任务重做的部分工作。

运行良好的编排者结束工作时，应当仍有大部分上下文预算未使用。

单任务编排流程

1. 获取上下文（eve job current --json）。
2. 确定深度：
   • 读取继承的目标深度。
   • 如果 current_depth >= target_depth，则直接执行。
3. 决定是否拆分：
   • 如果工作量较大或可并行处理，则创建子任务。
   • 每个子任务继承相同的目标深度。
4. 编写内容完整、可独立理解的子任务描述（见下方模板）。
5. 添加关系：
   • 标准门控使用 waits_for。
   • 仅在有严格顺序要求时使用 blocks。
6. 关系建立后，返回等待信号。
7. 子任务完成后恢复工作；阅读摘要、验证结果并继续。

创建子任务

使用 eve job create 和 --parent 创建子任务。每个子任务的描述必须 完全自包含——子 Agent 无法访问父任务的对话、上下文或推理过程。子任务执行所需的一切信息都必须包含在描述中。

# 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

创建子任务后，添加依赖项，让父任务等待它们完成：

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

并行任务拆分指南

• 优先创建多个规模较小、彼此独立的子任务，而非一个规模较大的子任务。
• 如果任务可以并行执行，就创建相应子任务，并让父任务等待所有子任务完成。
• 除非一个子任务的输出确实是下一个子任务的输入，否则不要将子任务串联起来。
• 每个子任务都会重复相同的决策流程；如果深度允许，还可以创建孙任务。
• 合理的任务拆分会缩小每个子任务的范围，使单个 Agent 无需耗尽其上下文窗口即可完成。

依赖项与关系

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

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：仅在依赖关系有条件时使用

返回等待控制信号之前，先添加关系。

控制信号（json-result）

创建子任务并设置关系后，使用等待信号暂停父任务：

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

规则：

• 仅在依赖关系存在后返回 waiting。
• waiting 会将任务重新排入 ready，同时任务仍会被关系阻塞。
• 在没有阻塞项时返回 waiting 会触发短暂退避；请避免这种情况。
• 工作完成后使用 success。
• 仅在遇到不可恢复的情况时使用 failed。

审核机制（可选）

默认情况下，除非父任务或项目设置明确要求，否则不进行审核。

如果需要审核：

• 按指定级别执行（仅顶层、所有层级或不审核）。
• 返回 waiting 时不要提交审核。
• 仅在任务完成后提交审核。

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

父任务审核子任务成果

子任务完成后，父任务恢复执行时：

• 阅读子任务摘要和结果，而非完整工作产物，以保护上下文。
• 验证所有子任务的输出是否共同满足父任务的范围要求。
• 如果需要审核，验证后提交父任务审核。
• 如果不需要审核，整合子任务结果到父任务摘要中，然后完成任务。

故障处理

如果子任务失败：

• 重新检查上下文，判断是重试、替换还是停止。
• 如果计划发生变化，移除或调整关系。
• 不要让父任务一直等待已永久失败的子任务。

子任务描述模板

每个子任务的描述都必须自包含。子 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>

子任务描述的关键规则：

• 指定具体文件和路径。“更新认证模块”含义模糊；“更新 /src/auth/handler.ts，添加令牌刷新逻辑”则可直接执行。
• **包含已做出的相关决策。**如果父任务已选定方案，请告知子任务，不要让它重新推导。
• 将交付内容表述为可验证的条件。“测试通过”或“路径 X 下存在文件”比“实现功能 Y”更明确。
• **绝不要假设子任务能读懂父任务的想法。**如有疑问，请尽量详细说明。

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

• 研究：并行开展文献综述、数据收集和综合分析
• 写作：拟定大纲、并行撰写各章节、整合内容
• 运维：并行检查指标、日志和状态，然后汇总
• 策略：并行开展 SWOT 分析、利益相关方分析和风险评估

快速检查清单

• 阅读上下文并判断工作量
• 确定目标工作量和级别
• 决定：直接执行还是进行编排？（如果任务是原子的，默认直接执行）
• 如果进行编排：规划任务分解，然后为子任务创建自包含的描述
• 优先选择并行子任务，而非顺序链
• 在发出信号前添加关系
• 返回 json-result 等待（如果存在子任务）
• 恢复时：阅读子任务摘要（而非完整输出），进行验证并完成