omh-autopilot

OMH Autopilot — 端到端自主流水线

适用场景

• 从构想到经过验证和审查的代码，端到端实现功能
• 用户说：「autopilot」「帮我构建」「全部交给你处理」「端到端完成」

不适用场景

• 单文件修改或简单任务（直接处理即可）
• 希望在一个连续会话中完成（autopilot 会跨多个会话）
• 只需要规划（omh-ralplan）或执行（omh-ralph）

前提条件

• 必须已安装 omh 插件（~/.hermes/plugins/omh/）

架构：每次调用执行一个阶段步骤

每次调用 autopilot 时，都会读取状态、完成一项工作，然后退出。调用方需要再次调用。 这样可以确保每个阶段都使用全新的上下文，包括 ralph 循环期间。

Invocation 1:   Phase 0 — requirements (or skip)
Invocation 2:   Phase 1 — planning (or skip)
Invocations 3-N: Phase 2 — ralph iterations (one per call)
Invocation N+1: Phase 3 — QA cycle         [FRESH SESSION]
Invocation M:   Phase 4 — validation round  [FRESH SESSION]
Final:          Phase 5 — cleanup → complete

如何驱动此循环，请参阅 references/caller-examples.md。

流程

步骤 0：解析实例并获取锁

Autopilot 会通过 spec → plan → ralph → QA → validation 推进目标。 如果两个 autopilot 会话同时处理同一目标，就会同时争用 autopilot、ralph 和 ralph-tasks 状态。请使用按实例隔离的状态 和咨询锁。

1. 按以下顺序解析 instance_id：
   • 如果 .omh/specs/{name}-spec.md 中存在已确认的 spec，使用 instance_id = "{name}"。
   • 否则，如果 .omh/plans/ralplan-{slug}.md 中存在计划，使用 instance_id = "{slug}"。
   • 否则，根据目标生成：instance_id = kebab(goal)[:60]。
2. 获取 autopilot 锁：

   lock = omh_state(action="lock", mode="autopilot",
                    lock_key="{instance_id}",
                    session_id="{HERMES_SESSION_ID or uuid}",
                    holder_note="autopilot driving {goal_or_plan}")
   

   如果 acquired=false，报告 held_by，并提供等待、取消或更换目标的选项。 对陈旧 PID 会自动释放锁。
3. 在本次调用的每次 omh_state 调用中传入 instance_id （autopilot、ralph、ralph-tasks）。
4. 在 Phase 2 中分派给 ralph 时，在委派上下文中传入相同的 instance_id，以便 ralph 子 Agent 使用相同的 slug 获取 mode="ralph" 锁。
5. 在每个退出点释放 autopilot 锁（暂停、 阻塞、完成、异常）：

   omh_state(action="unlock", mode="autopilot",
             lock_key="{instance_id}",
             session_id="{HERMES_SESSION_ID or uuid}")
   

单例回退（旧版）。 省略 instance_id 会写入 .omh/state/autopilot-state.json，并跳过锁定。仅当一次只运行一个 autopilot 时才可接受。

每次调用时：分派

state = omh_state(action="read", mode="autopilot", instance_id="{instance_id}")

• 未找到：全新启动 → 智能检测（见下文）
• 已找到：检查 context_checkpoint 标志 → 如果为 true，则清除并退出（阶段边界）
• 检查是否过期：state.stale = true → 发出警告，并提供全新启动选项
• 检查暂停状态：如果 pause_after_phase 与当前已完成阶段匹配 → 设置 phase="paused"，然后退出
• 分派给当前阶段的处理程序

智能检测（全新启动）

如果不存在 autopilot 状态，则检测以下文件：

1. .omh/specs/*-spec.md 中存在已确认的 spec → 在 Phase 1 创建状态
2. .omh/plans/ralplan-*.md 中存在共识计划 → 在 Phase 2 创建状态
3. Ralph 已完成（omh_state(action="check", mode="ralph", instance_id="{instance_id}") → phase="complete"）→ 在 Phase 3 创建状态
4. 均不存在 → 在 Phase 0 创建状态

检查 ralph 是否正在运行：omh_state(action="check", mode="ralph", instance_id="{instance_id}") → 如果正在运行，提醒用户已有会话。

omh_state(action="write", mode="autopilot", instance_id="{instance_id}", data={
    "phase": "requirements", "goal": "...", "ralph_iteration": 0,
    "qa_cycle": 0, "max_qa_cycles": 5, "validation_round": 0,
    "max_validation_rounds": 3, "validation_verdicts": {},
    "skip_qa": false, "skip_validation": false, "pause_after_phase": null
})

Phase 0：需求

目标：确保存在已确认的 spec。

1. 检查 .omh/specs/*-spec.md 中是否有 status: confirmed → 如果找到，设置 spec_file，进入 Phase 1，然后退出
2. 未找到 — 评估输入：
   • 具体（文件路径、函数名、特定技术）：直接生成 spec，然后推进
   • 模糊：加载 omh-deep-interview 并遵循其流程。此阶段需要交互。
3. 更新状态：phase: "planning"、spec_file: "<path>"。然后退出。

对于完全自主的运行：先单独运行 omh-deep-interview。

Phase 1：规划

目标：确保存在共识计划。

1. 检查 .omh/plans/ralplan-*.md → 如果找到，设置 plan_file，进入 Phase 2，然后退出
2. 未找到：加载 omh-ralplan，以 spec 为输入并遵循其流程
3. 更新状态：phase: "execution"、plan_file、ralph_iteration: 0、context_checkpoint: true。然后退出。

阶段 2：执行（Ralph 迭代）

每次调用恰好执行一次 Ralph 迭代：

1. 使用 omh-ralph 技能上下文，通过 delegate_task 执行一次 Ralph 迭代：

   delegate_task(goal="[omh-role:executor] Follow the omh-ralph skill procedure:
     read state, pick the next incomplete task, execute it, verify, update state, exit.",
     context="<current ralph state + plan file contents>")
   

2. Ralph 完成步骤后，检查 Ralph 状态：

   ralph = omh_state(action="check", mode="ralph", instance_id="{instance_id}")
   

   • active=true → 递增 ralph_iteration，退出（调用方重新调用）
   • phase="complete" → 推进：phase: "qa"、context_checkpoint: true，退出
   • phase="blocked" → 将 autopilot 的 phase 设为 "blocked"，报告并退出

阶段 3：QA 循环

每次调用执行一次 QA 循环。在全新会话中启动（context_checkpoint）。

如果 skip_qa: true → 推进到阶段 4，退出。

1. 使用项目实际的构建／测试／lint 命令收集证据（检查 Makefile、package.json、Cargo.toml、pyproject.toml 等，以确定正确的命令）：

   evidence = omh_gather_evidence(commands=["<build>", "<test>", "<lint>"])
   

2. 如果 evidence.all_pass → 推进：phase: "validation"、context_checkpoint: true，退出
3. 如果有失败项：
   • 递增 qa_cycle。检查 qa_error_history 是否触发三次失败规则。如果触发 → phase="blocked"，退出
   • 如果 qa_cycle > max_qa_cycles（默认值为 5）→ phase="blocked"，退出
   • 委派只读的架构师子 Agent 进行诊断
   • 委派执行子 Agent 修复
   • 更新状态并退出（下一次调用重新运行 QA）

阶段 4：多审阅者验证

每次调用执行一轮验证。在全新会话中启动。

如果 skip_validation: true → 推进到阶段 5，退出。

1. 使用项目实际的构建／测试命令收集证据：

   evidence = omh_gather_evidence(commands=["<build>", "<test>"])
   

2. 委派 3 个并行审查（恰好 3 个 = Hermes 并发限制）：

   delegate_task(tasks=[
       {goal: "[omh-role:architect] Architectural review:\n{spec + plan}", context: "{evidence}"},
       {goal: "[omh-role:security-reviewer] Security review:\n{changed files list}", context: "{evidence}"},
       {goal: "[omh-role:code-reviewer] Code quality review:\n{changed files list}", context: "{evidence}"}
   ])
   

3. 在 validation_verdicts 中记录判定结果
4. 全部为 APPROVE → 推进到阶段 5，退出
5. 任一结果为 REQUEST_CHANGES → 委派执行子 Agent 修复，递增 validation_round 并退出
6. 如果 validation_round > max_validation_rounds（默认值为 3）→ phase="blocked"，退出

阶段 5：清理

1. 设置 phase: "complete"（安全措施 — 如果被中断，重新调用会重试清理）
2. 删除状态文件：

   omh_state(action="clear", mode="autopilot", instance_id="{instance_id}")
   omh_state(action="clear", mode="ralph", instance_id="{instance_id}")
   omh_state(action="clear", mode="ralph-tasks", instance_id="{instance_id}")
   

3. 保留：.omh/logs/、.omh/plans/、.omh/specs/
4. 报告完成摘要：目标、已完成阶段、Ralph 迭代次数、QA 循环次数、验证轮数

状态管理

所有状态均通过 omh_state 工具管理。原子写入和过期状态会自动处理。

哨兵约定

omh_state(action="check", mode="autopilot", instance_id="{instance_id}")
→ {exists, active, phase, stale}

注意事项

• 不要在单个会话中循环执行 Ralph。 每次 Ralph 迭代都是一次单独调用。上下文耗尽确实会发生。
• 不要重新实现 Ralph。 加载技能并遵循其流程。
• 阶段边界 = 全新会话。 遵守 context_checkpoint。
• 不要跳过 QA。 Ralph 会逐任务验证。QA 可以发现集成问题。
• 如果不存在规格，阶段 0 需要交互。 自动运行前请预先创建规格。
• 子 Agent 上限为 3 个。 阶段 4 会占用全部 3 个名额进行并行审查。