summon

Summon

概述

Summon 是 egregore 编排循环。 它读取清单（.egregore/manifest.json），选择 下一个活跃工作项，将当前流水线步骤映射到 专用技能，并调用该技能。 每个步骤完成后，它会推进流水线，检查上下文和 令牌预算，然后重复此过程，直到所有工作项完成或 预算耗尽。

编排器不会重新实现阶段逻辑。 流水线中的每个步骤都会通过 Skill() 调用委派给现有技能。 Summon 只管理状态转换、重试和预算限制。

适用场景

• 通过完整的 intake-build-quality-ship 流水线处理一个或多个工作项。
• 恢复中断的 egregore 会话（清单已存在且包含活跃工作项）。
• 在看门狗下自主运行，由看门狗在进程退出时重新启动。

不适用场景

• 单独运行某个技能（请直接调用该技能）。
• 流水线不适用的探索性工作。
• 每个步骤都需要人工审核的情况（请手动调用技能）。

启动编排器

始终在前台启动编排器 Agent。 不要使用 run_in_background: true。主会话 会成为 egregore：它会阻塞在编排器 Agent 上， 直到 egregore 完成或被停止。

Agent(
  subagent_type: "egregore:orchestrator",
  prompt: "<context about work items and current state>",
  run_in_background: false   // Required
)

如果在后台启动编排器，主会话就无事可做， 随后会停止。这会让 egregore 的整个目的落空。 停止钩子无法阻止这种情况，因为后台 Agent 会脱离会话运行。

无人值守的夜间运行

上面的编排器是会话中的一个 Agent。夜间运行则是 另一个入口：一个可由看门狗重启的普通进程；它会运行数小时， 且无法保证任何会话都能持续这么久。它会处理一个 已交接的工作项（gate、walk、proof）。如果工作项被拒绝且没有 任何操作运行，它会以 gate 自身的代码（1 到 4）退出； 如果 walk 在启动后中断，则以 5 退出：

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/night_run.py" \
  --item-dir .egregore/handoff/<item> --root .

会话内的任何内容都不会启动它。请手动运行，或通过 你配置的调度程序运行。来自 /egregore:install-watchdog 的看门狗不会启动它：该看门狗会 重新启动一个调用此技能的 claude -p 会话。关于冷却路径为何不同， 请参阅 modules/budget.md。

清单模式

启动编排器前，请确保清单设置了 正确的运行模式：

• 默认（不带 --bounded 标志）：在清单中设置 "indefinite": true。 egregore 会在完成所有工作项后扫描新工作，并持续运行，直到被停止。
• 使用 --bounded 标志时：在清单中设置 "mode": "bounded"。 egregore 会在所有工作项完成或失败后停止。

如果清单已存在，且设置了 "mode": "bounded"， 但用户未传入 --bounded，请在启动前将清单 更新为 "indefinite": true。

启动后，不要生成任何摘要、状态表 或“当前进展”输出。现在，会话本身就是编排器。 让它运行。

编排循环

严格按照以下步骤执行。 每次迭代都会处理一个工作项的一个流水线步骤。

1. 加载状态

manifest  = Read(".egregore/manifest.json")
config    = Read(".egregore/config.json")
budget    = Read(".egregore/budget.json")

如果 manifest.json 不存在，请报错并停止： “未找到清单。请先运行 egregore init。”

2. 选择下一个工作项

item = manifest.next_active_item()

如果 item 为 None，则所有工作均已完成。 保存清单，报告完成情况并退出。

3. 将当前步骤映射到技能

在下方的“流水线到技能映射”表中查找 item.pipeline_stage 和 item.pipeline_step。 确定要调用的技能名称或操作。

4. 调用技能

调用 Skill() 或执行映射的操作。 传入工作项所需的上下文（分支名称、问题引用等）。

5. 处理结果

成功时：

• 调用 manifest.advance(item.id) 进入下一步。
• 将 item.attempts 重置为 0。
• 保存清单。

失败时：

• 调用 manifest.fail_current_step(item.id, reason)。
• 如果 item.attempts < item.max_attempts，则在下一次迭代中重试同一步。
• 如果 item.status 现在为 "failed"，记录失败并转到下一个工作项。
• 保存清单。

6. 检查上下文预算

估算上下文窗口的使用量。 如果使用量超过 80%：

1. 将清单保存到磁盘。
2. 将续接说明写入 .egregore/continuation.json，其中包含当前项 ID、阶段和步骤。
3. 调用 Skill(conserve:clear-context)。
4. 看门狗或调用方会启动一个全新会话，从已保存的状态继续。

7. 检查令牌预算

如果上一次技能调用返回了速率限制错误：

1. 通过 budget.record_rate_limit(cooldown_minutes) 在 budget.json 中记录速率限制。
2. 保存 budget.json。
3. 通知监管程序（参见 notify.py）。
4. 安排会话内恢复（仅限有人值守的会话）：使用 CronCreate 安排一次性恢复任务，在冷却期结束时恢复。其任务只存在于运行中的会话里，因此只有当该会话仍在运行且在窗口续期时处于空闲状态，才能使用此方式。
5. 否则正常退出，这是无人值守运行时的默认方式。看门狗会读取记录的冷却期，并在窗口续期后重新启动。调用 window.plan_resume()，不要自行决定。

8. 重复

返回步骤 2。 持续执行，直到所有项均已完成、所有项均已失败，或达到预算上限。

流水线到技能的映射

阶段	步骤	技能/操作
intake	parse	解析提示词，或通过 gh issue view 获取 issue
intake	validate	验证需求是否可执行
intake	prioritize	按复杂度排序（只有一项时跳过）
build	brainstorm	Skill(attune:project-brainstorming)
build	specify	Skill(attune:project-specification)
build	blueprint	Skill(attune:project-planning)
build	execute	Skill(attune:project-execution)
quality	code-review	Skill(pensive:code-refinement)
quality	unbloat	Skill(conserve:bloat-detector)
quality	code-refinement	Skill(pensive:code-refinement)
quality	update-tests	Skill(sanctum:test-updates)
quality	update-docs	Skill(sanctum:doc-updates)
ship	prepare-pr	Skill(sanctum:pr-prep)
ship	pr-review	Skill(sanctum:pr-review)
ship	fix-pr	应用审查修复
ship	merge	gh pr merge（如果启用了 auto_merge）

intake 阶段的步骤（parse、validate、prioritize）由编排器内联处理。 详情请参阅 modules/intake.md。

循环内的委派

默认情况下，build 和 quality 阶段通过 Skill(conjure:delegation-core) 委派执行。 在无人值守的循环中，这种默认做法最能发挥作用：没有人在场注意到有可用的外部 CLI 却未被使用。

编排器不会针对每项任务单独做决定。 它会调用映射的技能，由该技能根据自身的 Keep Local 条款应用委派策略。

providers_exhausted 结果不属于步骤失败。 编排器不得重试该步骤，也不得因此将工作项标记为失败。根据 Skill(attune:project-execution) 模块 subagent-fallback.md，该技能会将工作交给基于会话模型的子 Agent，流水线随后继续推进。 如果将其视为失败，会在没有任何故障的机器上耗尽重试预算。

若要在不使用外部模型的情况下运行 egregore，请在启动它的环境中导出 CONJURE_DELEGATION=off。

上下文溢出协议

编排器运行在有限的上下文窗口中。 为避免窗口填满时丢失状态：

1. 监控使用情况。 每次调用技能后，估算 已消耗的上下文窗口容量。
2. 达到 80% 容量时，触发上下文保存：
   • 将完整清单持久化到磁盘。
   • 写入 .egregore/continuation.json，其中包含 当前进度的快照。
   • 调用 Skill(conserve:clear-context)。
3. 重新启动时，加载 continuation.json，并从 保存的位置继续。磁盘上的清单是管道进度的事实来源。
4. 每次发生上下文溢出交接时，将 manifest.continuation_count 加 1。

此协议可确保进度在上下文边界之间不会丢失。

进度监控与自我修复（2.1.71+）

加载状态后（步骤 1），安排定期心跳任务，同时报告状态并恢复停滞的管道：

CronCreate(
  cron: "*/5 * * * *",
  prompt: "Check .egregore/manifest.json. If there are pending or active items that are not being processed, resume the orchestration loop by invoking Skill(egregore:summon). Otherwise, report status via /egregore:status.",
  recurring: true
)

此举有两个目的：

1. 可见性：每 5 分钟发出一次状态摘要， 使自主运行过程可被观察。
2. 自我修复：如果用户提示词、上下文压缩 或意外错误中断了编排循环，下一次心跳会检测停滞项，并自动重新进入管道。

这两项功能都依赖会话保持运行：定期任务也仅存在于创建它的会话中，且只有在 REPL 空闲时才会触发。定期任务会在 7 天后自动过期，并在删除前最后触发一次，因此运行时间超过一周时，需要重新安排心跳任务。

durable: true 不会让任务在重启后继续存在。 虽然该参数会被接受，但工具说明指出它“没有效果”，且不提供持久化功能。使用 CronDelete 提前取消任务；对于任何必须跨会话持续运行的任务，请使用 watchdog。

令牌预算协议

Egregore 会话会在预算窗口内消耗 API 令牌（默认：5 小时）。 预算协议可防止费用失控：

1. 每次调用技能前，检查 budget.json 中是否存在 活跃的冷却期。如果 is_in_cooldown(budget) 返回 true，则退出并等待 watchdog 稍后重试。
2. 发生速率限制错误时，通过 budget.record_rate_limit(cooldown_minutes) 记录事件。 冷却时长等于 API 的 retry-after 标头值加上 config.budget.cooldown_padding_minutes。
3. 保存并退出。 写入 budget.json，通知 监督程序，然后以代码 0 退出。
4. watchdog 会在重新启动前检查 budget.json。 冷却期结束前，它不会启动新会话。

完整的计算方法和状态架构请参阅 modules/budget.md。

失败处理

每个工作项的每个步骤最多可重试 max_attempts 次 （默认：3，可在 config.json 中配置）。

• 重试：如果某个步骤失败且 attempts < max_attempts， 编排器会在下一次迭代中重试同一步骤。重试之间会保存清单。
• 标记为失败：如果 attempts >= max_attempts，该项 的状态将变为 "failed"，并设置 failure_reason。 编排器会转到下一个活跃工作项。
• 通知：发生失败时，通过配置的通知渠道通知监督程序。
• 绝不阻塞：编排器绝不能等待人工输入。如果某个步骤需要澄清，应记录一项决策（参见 modules/decisions.md），并采用当前最佳选项继续。

模块参考

• pipeline.md：阶段和步骤定义、转换规则、 幂等性保证。
• budget.md：令牌窗口管理、速率限制检测、 冷却计算、正常关闭。
• intake.md：提示词和 GitHub issues 的工作项解析、 跳过头脑风暴的逻辑。
• decisions.md：自主决策框架、 决策日志格式、示例。

退出条件

• 在编排循环开始前成功读取 .egregore/manifest.json；如果文件不存在，技能将停止并提示 "No manifest found. Run egregore init first."
• 每个已完成的流水线步骤都会推进清单中的 item.pipeline_stage，并将清单保存到磁盘
• 上下文达到 80% 时，在交接前写入 .egregore/continuation.json，其中包含当前条目 ID、阶段和步骤
• 遇到速率限制错误时，在会话以代码 0 退出前，用冷却时长更新 budget.json
• 所有条目均已完成或失败时，编排器退出并生成列出各条目状态的完成报告