run

/ouroboros:run

通过 Ouroboros 工作流引擎执行 Seed 规范。

用法

/ouroboros:run [seed_file_or_content]

触发关键词：“ouroboros run”、“execute seed”

工作原理

1. **输入：**直接提供 Seed YAML 内容，或提供 .yaml 文件的路径
2. **验证：**解析并验证 Seed（目标、约束、验收标准、本体）
3. **执行：**编排器通过 PAL 路由运行工作流
4. **进度：**通过会话跟踪实时更新进度
5. **结果：**包含通过/失败状态的执行摘要
6. **验证状态：**仅运行所得的结果为 executed_unverified，直到 ooo evaluate <session_id> 执行正式的 3 阶段验证

说明

用户调用此技能时：

加载 MCP 工具（必须首先执行）

Ouroboros MCP 工具通常会注册为延迟工具，必须显式加载后才能使用。你必须先完成此步骤，再继续操作。

1. 使用当前运行时的工具发现功能，查找并加载执行 MCP 工具：

   tool discovery query: "+ouroboros execute"
   

2. 这些工具通常以 mcp__plugin_ouroboros_ouroboros__ 为前缀命名（例如，ouroboros_execute_seed、ouroboros_session_status）。运行时工具发现完成后，即可调用这些工具。
3. 如果这些工具可调用——无论是已公开还是通过发现加载的——都继续执行以下步骤。对于已公开的工具，发现结果为空是预期情况，并非失败。只有在工具确实不存在（没有 Ouroboros MCP 服务）时，才跳到后备方案部分。

**重要：**不要跳过此步骤。不要仅仅因为 MCP 工具没有出现在当前工具列表中，就认定它们不可用。它们几乎总是作为延迟工具提供，需要先加载。

关键——延迟架构防护（避免“Invalid tool parameters”）： 此技能会跨多个轮次调用执行 MCP 工具，而每个轮次都会在全新的工具上下文中运行。在某一轮加载的延迟工具架构，不保证在下一轮仍然加载。因此，如果在当前轮次未加载架构时调用任何执行 ouroboros_* MCP 工具，运行时会在请求到达服务端之前拒绝调用，并报错 “Invalid tool parameters”。 因此：在此技能中，每次调用执行 MCP 工具之前，都要立即重新运行 tool discovery query: "+ouroboros execute"，以重新加载执行工具系列，包括 ouroboros_start_execute_seed、ouroboros_job_wait、 ouroboros_ac_tree_hud 和 ouroboros_job_result（该操作具有幂等性——已加载时不会产生影响）。如果加载结果中没有匹配的工具（且该工具当前不可调用——已公开工具的加载结果为空属于预期情况，并非工具缺失），则切换到文档中说明的后备方案，不要重试失败的调用。

执行步骤

1. 检测 Git 工作流（在进行任何代码更改之前）：

   • 阅读项目的 CLAUDE.md，了解 Git 工作流偏好
   • 如果检测到基于 PR 的工作流，且当前位于 main/master 分支：
     • 创建功能分支：ooo/run/<session_id>
     • 所有代码更改都在此分支进行
   • 如果未指定偏好：使用当前分支（向后兼容）

2. 检查用户是否提供了 Seed 内容或文件路径：

   • 如果是文件路径：使用 Read 工具读取文件
   • 如果是内联 YAML：直接使用
   • 如果两者都没有：检查对话历史中最近生成的 Seed

   开始新的执行前，如果用户尚未选择效率策略，请用描述结果的语言询问：

   • 高效执行——经济地启动并行/拆分任务，仅在恢复需要时加强路由。发送 efficiency_mode="adaptive" 和 frugality_assurance="observe"。
   • 质量优先执行——让子任务保持在父任务的起始层级。发送 efficiency_mode="quality_first" 和 frugality_assurance="off"。 frugality_assurance="strict" 是一项单独的明确选择，因为它可能会为证明投入额外工作。切勿仅仅因为选择了高效执行就启用它。恢复时不要再次询问；服务端会恢复已持久化的策略，并拒绝在恢复时尝试更改策略。

3. 启动后台执行，使用 ouroboros_start_execute_seed：

   Tool: ouroboros_start_execute_seed
   Arguments:
     seed_content: <the seed YAML>
     efficiency_mode: <adaptive or quality_first>
     frugality_assurance: <observe, off, or explicit strict>
     max_iterations: 10    (or as specified by user)
   

   默认省略 model_tier，由运行时自动选择。只有用户明确指定层级时，才加入 model_tier: <user choice>。此操作会立即返回 job_id、session_id 和 execution_id。

4. 如果要恢复现有会话，请加入 session_id：

   Tool: ouroboros_start_execute_seed
   Arguments:
     seed_content: <the seed YAML>
     session_id: <existing session ID>
   

5. 建议的监控方式：委托一个子会话进行观察。

   作业开始时展示 TUI（RFC #1392）：

   返回 job_id、session_id 和 execution_id 后，在不延迟执行或观察者委派的情况下，展示一次实时视图：

   • 如果存在 response.meta.dashboard_url，将其作为主要实时视图展示。

   • 如果加载的 Ouroboros 配置中存在 execution.tui_autolaunch: true（或旧版顶层配置 tui_autolaunch: true），则无条件运行 ouroboros tui open，并用一行简短文字提及仪表板。

   • 否则，只提及一次可以在新终端中通过 ouroboros tui open 打开 TUI。询问是否要打开，但不要等待答复而阻塞运行。记住用户在本会话中的答复，不要重复询问。

   • 如果用户同意，则运行 ouroboros tui open。

   • 如果 ouroboros tui open 报告环境处于无头模式、SSH 环境或不受支持，因此需要手动执行命令，则转达该命令一次并继续。

   • 仪表板是外部观察者，不会改变哪个聊天会话负责 MCP 轮询。

   返回 ID 后，仅打印以下简短交接信息：

   Execution started in background.
   Job ID: <job_id>
   Session ID: <session_id>
   Execution ID: <execution_id>
   Live view: <dashboard_url, or `ouroboros tui open`>
   Runtime/harness: <response.meta.runtime_backend>
   LLM backend: <response.meta.llm_backend>
   Efficiency: <response.meta.efficiency_mode>
   Frugality assurance: <response.meta.frugality_assurance>
   
   Observation: <confirmed read-only child observer, or durable catch-up mode>.
   With a confirmed observer, meaningful progress, attention, and completion
   events will be posted here. Without one, the run still survives this turn
   and I will catch up from durable events on your next message or status request.
   This conversation stays available while the run continues.
   We can refine requirements, inspect or review code, or work on an unrelated
   task in an isolated worktree. I will check for active-worker conflicts before
   editing this run's workspace.
   For full details later: `ouroboros_ac_tree_hud(session_id=<session_id>)`
   

   如果存在 response.meta.job_observer，且宿主具有独立的子会话/子 Agent 原语，则恰好创建一个观察者会话，并原样传递该对象。Codex 要求显式委派给原生子 Agent；Claude Code 使用一个 Task/Agent 子会话。观察者必须：

   • 在 Codex 上，恰好调用一次原生 spawn_agent 原语，并设置 task_name="run_observer"，在子会话消息中原样包含 response.meta.job_observer。wait 调用不算创建子会话。

   • 要求创建子会话的结果返回有效的子会话 ID/路径，之后才能声称观察者已连接，或结束启动轮次。

   • 保持只读：不修改仓库、不控制执行，也不扇出工作任务；

   • 独占作业游标，并在每次调用观察者工具之前立即重新加载延迟加载的 MCP 架构；

   • 使用声明的参数调用声明的 wait.tool，根据响应元数据更新本地游标，并重复此操作，直到作业终止；

   • 状态终止后调用声明的 result.tool；

   • 遵循 follow_result_job_keys 中列出的所有作业 ID，包括链式正式评估，然后返回一份简洁的最终摘要；

   • 仅在宿主支持子会话到父会话的消息传递，且状态发生有意义变化时，发送简短的进度通知。

   观察者负责作业时，主会话不得轮询同一作业。主会话可以继续与用户交谈、完善需求、进行只读检查/审查、处理明确的状态/控制请求，或在隔离的工作树中处理无关任务。在向活动运行的工作区写入之前，先检查是否与工作 Agent 使用的文件冲突，或将工作隔离。如果由于插件模式已委派整个执行而不存在 job_id，则遵循该插件子会话的生命周期。 在 Codex 上，已确认的观察者还需要父级中继循环。spawn_agent 返回仍在运行的子级 ID/路径后，通过单次不超过 60 秒的 wait_agent 调用保持父级回合开启。子级的 send_message 只会将事件排入邮箱，无法唤醒已经结束的父级回合。转发有意义的观察者更新，然后再次等待，直到子级返回终结摘要。用户输入可能会中断等待；处理后，只要观察者仍处于活动状态，就恢复中继循环，除非用户要求停止实时观察或替换当前请求。此时只结束中继循环，让持久化作业继续运行，并提供在下一回合或通过明确的状态查询补报进展。如果观察者子级失败、被取消，或在返回终结摘要前退出，则使用相同的后备方案，而不是无限期等待。此等待循环绝不能调用 Ouroboros 作业工具，也不能与观察者争用游标。

   将观察者消息视为事件，而非记录稿：

   • phase_changed / progress_advanced：最多转发 1-2 行简洁信息。根据结构化子类型进行解读，而非照搬原始日志：
     • run_configuration：说明当前运行时/测试框架、已知的起始模型或等级、效率模式和节俭性保证。如果尚不知道确切模型，则说明将在首次路由事件中报告。
     • execution_plan：说明 AC 总数、依赖/并行级别总数、工作是否可以并行运行，以及首批已排期 AC 的摘要。
     • discovery_summary：说明 AC 正在检查哪些限定目标及其目的；绝不暴露搜索查询、原始命令或推理过程。
     • level_started / level_completed：说明当前或已完成的并行级别，以及有意义的成功/失败数量。
     • ac_routing / harness_changed：使用“目前正在使用”表述，并且只报告初始路由或实际的模型/等级/测试框架变更。
     • ac_verified：报告已完成的 AC 及其精简的保证证据。
   • attention_required：立即指出阻塞因素或待定决策，仅在需要人工判断时询问用户。
   • terminal：获取/呈现最终结果及任何链式评估。
   • Synapse .queued / .delivering：说明确切的 AC 有待处理或已认领的意图信号，并指出生效边界；不要声称已应用。
   • Synapse .applied / .completed：确认运行时已证实应用，并在有 AC 回复时转发该回复。
   • Synapse .rejected / .delivery_uncertain：立即指出，并绝不声称 AC 已改变方向。
   • 忽略未变化的心跳和原始工具输出。

   所有中继内容均使用用户当前对话的语言。仅当精确诊断信息有帮助时，才保留事件代码和有效模式值不变。这些是英文规范主机指令。使用当前对话语言自然地表述事实。

   对 SOL 类模型，此所有权划分为默认方式：主模型执行一次启动交接，由一个隔离的小型上下文负责重复的等待/结果状态机。

   如果无法创建子级、创建失败或未返回仍在运行的子级，则不要声称存在观察者，也不要承诺会主动实时发送消息。分离式工作进程会在 stdio MCP 回合结束后继续运行。告知用户进度会持久保存，并将在下一父级回合或明确的状态请求中补报。仅当用户明确要求实时监看时才保持回合开启；此时使用下方的后备方案。

6. 后备方案：在主会话中使用低令牌中继循环。 仅当 response.meta.job_observer 缺失、宿主没有独立的子会话原语，且用户明确要求在当前轮次继续观察时，才使用此方式。不要与委派的 observer 并行运行。否则安全结束当前轮次，并在下一个父轮次从同一游标继续跟进。

   对于常规监控，使用 ouroboros_job_wait，而不是反复调用 ouroboros_ac_tree_hud。从工具 meta 载荷中保留最新游标和先前进度计数器。

   此循环有意对 harness/模型友好：

   • 将 response.meta 视为唯一事实来源。
   • 不要从 response.text 解析计数、状态或游标。
   • 仅将 response.text 用作人类可读的当前消息提示。
   • 将所有本地监控状态保存在简单的标量变量中。
   • 每次响应变化时最多发出一条简短的中继消息。
   • 在出现终止状态后，始终继续获取最终的 ouroboros_job_result。

   cursor = <cursor from start/status response, or 0>
   prev_status = "running"
   prev_phase = null
   prev_ac_completed = 0
   prev_sub_ac_completed = 0
   prev_message = null
   
   loop:
     Tool: ouroboros_job_wait
     Arguments:
       job_id: <job_id from step 3>
       cursor: <cursor>
       timeout_seconds: 180
       view: "summary"
       stream: "linked"
       wait_for: "attention_or_ac_change"
   
     cursor = response.meta.cursor
   
     if response.meta.changed is false:
       # Do not narrate unless the user explicitly asked for heartbeat updates.
       continue
   
     status = response.meta.status
     phase = response.meta.current_phase
     ac_completed = response.meta.ac_completed
     ac_total = response.meta.ac_total
     sub_ac_completed = response.meta.sub_ac_completed
     sub_ac_total = response.meta.sub_ac_total
     # The metadata field names remain legacy-compatible; relay them to users as Task/Subtask progress.
     message_hint = first non-empty non-metadata line from response.text, or null
   
     # Build one short relay update from structured fields.
     if status in ["completed", "failed", "cancelled", "interrupted"]:
       print terminal_relay(status, phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total)
       break
   
     if ac_completed > prev_ac_completed:
       print task_progress_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
     elif sub_ac_completed > prev_sub_ac_completed:
       print subtask_progress_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
     elif phase != prev_phase or status != prev_status:
       print phase_or_status_relay(status, phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total)
     elif message_hint != prev_message:
       print current_work_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
   
     prev_status = status
     prev_phase = phase
     prev_ac_completed = ac_completed or prev_ac_completed
     prev_sub_ac_completed = sub_ac_completed or prev_sub_ac_completed
     prev_message = message_hint or prev_message
   

   注意：

   • timeout_seconds: 180 表示 MCP 调用最长可阻塞 3 分钟。 这样既能保持主会话足够频繁地可用以进行实时中继，又能避免产生大量轮询噪音。
   • 对于超长任务，或当用户只需要心跳时，使用 view: "compact"。原始工具仍可能返回诸如 job_x | running | AC 3/17 之类的旧式文本；请将其作为任务进度转达给用户。
   • 对于常规监控，使用 view: "summary"。它包含任务消息以及从旧式 ac_completed/sub_ac_completed 元数据字段派生的 Task/Subtask 计数。
   • 仅当用户要求详细任务状态时，才使用 view: "full"。

   中继风格示例：

   • 进行中：Deliver 处于 Task 1/3 和 Subtask 12/16。当前工作是 Subtask 3 回归测试。
   • 层级更新：并行层级 1/1 已完成，Task 进度推进至 3/3。
   • 已完成：执行已结束。现在正在获取最终任务结果。

   面向其他 harness/模型的中继输出约定：

   • 一次更新应为 1-2 句话或 1 行紧凑内容。
   • 存在时，包含 phase、Task 已完成/总数和 Subtask 已完成/总数。
   • 仅当当前工作提示发生变化时才包含它。
   • 常规中继输出中绝不要包含完整任务树。
   • 绝不要包含原始 JSON、原始 meta 转储或重复未变的游标行。
   • 终止状态必须明确：completed、failed、cancelled 或 interrupted。

   除非用户要求原始状态，否则不要粘贴完整的原始工具输出。 除非工具提供，否则不要添加推测性的 ETA。

   Synapse 意图细化： 当用户在活动运行期间给出增量实现意图时，由主会话负责目标选择；绝不要向用户询问内部的 AC/session ID。

   在每次 Synapse 调用之前，立即使用 tool discovery query: "+ouroboros session signal" 重新加载其延迟加载的 schema。

   1. 从启动结果或观察器契约中获取 execution_id，并调用 ouroboros_session_signal_targets(execution_id=...)。
   2. 根据各目标的 ac_content、显示路径，以及必要时当前 HUD 活动，将用户的意思与目标进行匹配。可直接选择一个活动目标。如果有多个目标，仅当其中一个明显更相关时才选择；只有确实难以区分时，才用简短的用户语言向用户澄清。
   3. 对于增量式实现细化，调用 ouroboros_session_signal，并使用所选目标的确切 scope/attempt/execution 守卫，设置 contract_effect="additive"、source="user"、mode="redirect" 和 fallback_mode="after_turn"。如果目标发现结果提供了 expected_contract_version，则照抄该值；并为本轮确切的用户请求创建一个稳定的幂等键。如果目标已过期，则重新发现一次，而不是询问 ID。
   4. 当用户向 AC 提出只读问题或请求确认，而非要求更改实现时，使用 mode="inform" 和 contract_effect="additive"，并完全省略 fallback_mode，因为它仅适用于 redirect。运行时支持时，Synapse 会运行一个不使用工具的回复轮次；请转达已完成事件中的有限回复。
   5. 告知用户选择了哪个 AC，并报告返回的有效模式。等待观察器的 .applied 或 .completed 后，再表示更改已生效。

   绝不要使用 Synapse 更改已批准的目标、AC、约束或非目标；这些更改需要经批准的共享后继契约或替代契约。

   活动 Conductor 注意事项处理： recommended_host_actions 是权威操作菜单。绝不要臆造会产生变更的工具调用。

   1. 使用提供的证据 ID，最多通过一个短时只读主机子任务进行 VERIFY。如果主机没有验证器原语，则告知用户该注意事项，并在执行变更前停止。
   2. 从按顺序排列的菜单操作中进行 DECIDE。考虑任何后继操作之前，必须先结束由引擎负责的重试/路由。
   3. 在执行 ACT 之前，通过 ouroboros_record_conductor_decision 记录 phase="selected"。对于运行模式下的规格变更，须获得用户明确批准并绑定其收据。
   4. 仅当菜单列出的是当前已注册的 MCP 工具时才执行 ACT。纠正性后继操作必须保留已批准的契约，除非用户已批准共享规格变更。
   5. 恰好记录一个终态结果：completed、failed 或 declined。不要悄悄重试失败的 conductor 操作。

7. 仅在手动逐层查看或检查异常时使用 ouroboros_ac_tree_hud。

   不要在正常轮询循环中调用完整树 HUD。

   使用以下定向调用：

   # Explicit short HUD, useful for a one-off check
   Tool: ouroboros_ac_tree_hud
   Arguments:
     session_id: <session_id>
     cursor: <cursor>
     view: "summary"
   
   # Lowest-token one-line HUD
   Tool: ouroboros_ac_tree_hud
   Arguments:
     session_id: <session_id>
     cursor: <cursor>
     view: "compact"
   
   # Full tree only when user asks "show details", progress looks stuck,
   # or debugging requires seeing the task/subtask structure.
   Tool: ouroboros_ac_tree_hud
   Arguments:
     session_id: <session_id>
     cursor: <cursor>
     view: "tree"
     max_nodes: 30
   

   将显式紧凑视图/摘要视图中的 unchanged cursor=<cursor> 视为无操作。除非用户明确询问心跳消息，否则不要向用户解释它。

8. 在轮询所有者中获取最终结果，使用 ouroboros_job_result。

   委派的观察器会在默认路径中执行此调用。主会话仅在第 6 步所述的后备路径中执行此调用。

   Tool: ouroboros_job_result
   Arguments:
     job_id: <job_id>
   

9. 向用户展示执行结果：

   • 显示成功/失败状态
   • 显示会话 ID（供之后查询状态使用）
   • 显示执行摘要

10. 执行后 QA 和正式评估（自动）： ouroboros_start_execute_seed 会在成功执行后自动运行 QA。 QA 判定结果包含在最终任务结果文本中。此 QA 检查不是正式的三阶段评估。对于返回 chained_evaluate_job_id 的服务，成功运行已将正式评估器作为单独的有界后台任务加入队列。 如需跳过：向工具传入 skip_qa: true。 如果最终运行结果的 meta 包含 chained_evaluate_job_id：

• 当前轮询所有者继续使用该任务 ID
• 终态后，使用 ouroboros_job_result 获取其判定结果
• 当 final_approved: true 时显示 APPROVED；否则显示未通过，并列出评估结果中的失败 AC 或失败原因
• 如果评估任务失败或超时，保持运行成功状态不变，并显示 Next: ooo evaluate <session_id> 作为手动重试方式

如果不存在 chained_evaluate_job_id，则原样保留旧路径：

• PASS：Next: ooo evaluate <session_id> for formal 3-stage verification
• REVISE：显示差异/建议，然后显示 Next: Fix the issues above, then ooo run to retry -- or ooo unstuck if blocked
• FAIL/ESCALATE：显示失败项，然后显示 Next: Review failures above, then ooo run to retry -- or ooo unstuck if blocked

回退方案（无 MCP 服务）

如果 MCP 服务不可用，请告知用户：

Ouroboros MCP server is not configured.
To enable full execution mode, run: /ouroboros:setup

Without MCP, you can still:
- Use /ouroboros:interview for requirement clarification
- Use /ouroboros:seed to generate specifications
- Manually implement the seed specification

示例

User: /ouroboros:run seed.yaml

[Reads seed.yaml, validates, starts background execution]

Background execution started.
Job ID: job_a1b2c3d4e5f6
Session ID: orch_x1y2z3
Execution ID: exec_m1n2o3

[Relay]
In progress: Deliver is at Task 1/3 and Subtask 12/16.
Current work is finishing the workflow routing Subtask.

[Relay]
Level update: parallel level 1/1 has finished, and Task progress advanced to 3/3.
Execution is complete. Fetching the final job result now.

[Fetching final result...]

Result:
  Seed Execution SUCCESS
  ========================
  Session ID: orch_x1y2z3
  Goal: Build a CLI task manager
  Duration: 45.2s
  Messages Processed: 12
  Verification Status: executed_unverified
  Formal Evaluation: NOT evaluated by the 3-stage evaluator

  Next: `ooo evaluate orch_x1y2z3` for formal 3-stage verification

  # Newer server path:
  Verification Status: evaluation_enqueued
  Chained Evaluation Job ID: job_eval987
  [Poll ouroboros_job_wait/job_status, then fetch ouroboros_job_result]
  Formal Evaluation Verdict: APPROVED

RFC #1392 状态面包屑页脚

你的最终回复必须以且仅以一行面包屑页脚结尾：

◆ <current state> → next: <recommended action>

当 MCP 投影可用时，通过 ouroboros_session_status 获取实时会话状态，以此确定 <current state>；否则根据此技能的实际结果确定。切勿使用线性的 Step N of M 页脚，因为 Ouroboros 是一个演进循环。当下一步确实存在多种选择时，在 next: 子句中列出 2–3 个真实选项。面包屑行必须是回复的最后一行。